자동화 조회 문법 레퍼런스

list 단계에서는 하나의 query 안에 검색, 필터, 정렬과 조회 범위를 함께 설정합니다. 시스템은 이 설정을 모두 결합하여 워크플로우가 처리할 행을 선택합니다.

query:
  search: "김"
  where:
    status: { in: [confirmed] }
    starts_at: { lt: "now-30m" }
  order: { column: starts_at, ascending: true }
  limit: 25
  offset: 0

이 예시는 검색 가능한 텍스트에 김이 있고, 상태가 confirmed이며, 시작 시각이 30분 이상 지난 행을 선택합니다. 오래된 시작 시각부터 최대 25건을 선택합니다.

검색

search는 기능이 검색 가능하도록 등록한 텍스트와 번역된 이름에서 용어를 찾습니다. 검색할 컬럼을 직접 지정할 필요는 없습니다. 검색 가능한 컬럼은 기능마다 다릅니다.

query:
  search: "VIP"

검색과 where, or, embed를 함께 사용하면 모든 항목이 적용됩니다.

필터

where 안의 조건은 모두 만족해야 합니다. 한 컬럼에 두 연산자를 사용하면 두 조건이 모두 적용됩니다. 예를 들어 { gte: "now", lt: "now+2h" }는 실행 시각부터 두 시간 후까지의 범위를 선택합니다.

기능마다 필터할 수 있는 컬럼과 사용할 수 있는 연산자가 다릅니다. 기능 레퍼런스에서 해당 기능의 필터 가능 컬럼을 확인하세요.

사용자 필드

고객, 예약 또는 대화의 사용자 필드는 custom.<key> 경로로 조회합니다. 폼, 표와 자동화에서 같은 사용자 필드 키를 사용합니다.

query:
  where:
    "custom.student_grade": { eq: middle }
    "custom.interest_area": { contains: [coding] }

문자열 사용자 필드에는 like 또는 ilike를 사용할 수 있습니다. 선택값 한 개, 숫자, 날짜와 켜기 값에는 eq, neq 또는 in을 사용하세요. 여러 선택값에는 contains를 사용하세요. 사용자 필드 키와 종류는 현재 조직의 사용자 필드에서 확인하세요.

대체 조건

or의 한 항목 안에서는 조건 중 하나만 만족해도 됩니다. where와 여러 or 항목을 함께 사용하면 각 항목의 결과를 모두 만족해야 합니다. or 안에서는 in을 사용할 수 없습니다.

query:
  where:
    status: { eq: open }
  or:
    - last_message_at: { lt: "now-2d" }
      updated_at: { lt: "now-7d" }

상대 시간

시간 값에는 now 또는 now에 분, 시간, 일을 더하거나 뺀 값을 사용할 수 있습니다.

상대 시간은 워크플로우가 실행될 때 해석됩니다.

관계 조건

embed는 연결된 기록의 값을 조회 조건에 사용합니다. 연결된 기록이 조건을 만족하는 행만 선택하려면 inner: true를 함께 설정하세요. 다음 예시는 활성 고객의 진행 중 대화만 선택합니다.

query:
  where:
    status: { in: [open] }
    last_message_at: { lt: "now-1d" }
  embed:
    customer_id:
      inner: true
      where:
        status: { eq: active }

관계 조건은 기능이 제공하는 관계만 사용합니다. 연결된 행에도 워크플로우 실행자의 데이터 범위와 권한이 적용됩니다.

정렬

order.column은 정렬할 컬럼을 지정합니다. ascending을 생략하거나 true로 설정하면 오름차순으로 정렬합니다. 내림차순이 필요하면 false로 설정하세요.

query:
  order:
    column: created_at
    ascending: false

기능이 조회에 제공하는 컬럼만 정렬에 사용할 수 있습니다. 조회 범위를 나눌 때에는 같은 정렬을 계속 사용하세요.

조회 범위

limit는 한 실행에서 선택할 최대 행 수입니다. 값을 생략하면 list 단계는 최대 20건을 선택합니다. 직접 설정할 수 있는 최대값은 50입니다.

offset은 건너뛸 행 수이며 0부터 시작합니다. 조회 범위를 직접 나눌 때에는 limit와 함께 설정하세요.

query:
  order: { column: created_at, ascending: true }
  limit: 25
  offset: 25

위 예시는 같은 정렬 결과의 두 번째 25건을 선택합니다. 조회 중에 데이터가 바뀔 수 있다면 offset으로 작업 대상을 소진하지 마세요. 처리한 행의 상태를 변경하여 다음 실행의 조회 조건에서 빠지게 만드세요.

큰 조회는 작은 limit로 시작하세요. 실행 시간과 결과를 확인한 뒤 값을 조정하세요. 한 단계가 반복 처리할 수 있는 횟수에는 별도의 안전 제한도 적용됩니다.