SEARCH_PREVIEW

SEARCH_PREVIEW (SNOWFLAKE.CORTEX)

SEARCH_PREVIEW 함수는 Cortex Search 서비스 이름과 쿼리가 주어지면 지정된 서비스로부터 응답을 반환해요.

출처: 문서

본문

문법 (Syntax)

SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    '<service_name>',
    '<query_parameters_object>'
)

인자 (Arguments)

service_name — Cortex Search 서비스의 이름이에요. 서비스가 현재 세션과 다른 스키마에 있으면 정규화된 이름(fully qualified name)을 사용하세요.
query_parameters_object — 서비스를 호출하기 위한 쿼리 파라미터를 지정하는 JSON 객체를 담은 STRING이에요.
- query (String) — 서비스의 텍스트 열을 검색할 검색 쿼리예요. 필수예요.
- columns (Array) — 응답의 각 관련 결과에 대해 반환할 열의 쉼표로 구분된 목록이에요. 이 열들은 서비스의 소스 쿼리에 포함되어야 해요. 서비스 생성 시 지정한 검색 열.
- filter (Object) — ATTRIBUTES 열의 데이터를 기준으로 결과를 필터링하기 위한 필터 객체예요. 자세한 구문은 아래의 필터 구문(Filter syntax)을 참조하세요. 빈 객체.
- limit (Integer) — 응답에 반환할 최대 결과 수예요. 10.

필터 구문 (Filter syntax)

Cortex Search는 CREATE CORTEX SEARCH SERVICE 명령에 지정된 ATTRIBUTES 열에 대한 필터링을 지원해요.

Cortex Search는 다섯 가지 일치 연산자(matching operator)를 지원해요:

TEXT 또는 NUMERIC 같음: @eq
ARRAY 포함: @contains
NUMERIC 또는 DATE/TIMESTAMP 크거나 같음: @gte
NUMERIC 또는 DATE/TIMESTAMP 작거나 같음: @lte
기본 키 같음: @primarykey

이 일치 연산자들은 다양한 논리 연산자와 결합할 수 있어요:

@and
@or
@not

다음 사용 메모가 적용돼요:

소스 쿼리의 NaN('not a number') 값에 대한 일치는 Special values에 설명된 대로 처리돼요.
19자리 초과(앞의 0 제외) 고정 소수점 숫자 값은 @eq, @gte, @lte에서 동작하지 않으며 이 연산자들로 반환되지 않아요. 예를 들어 소스 쿼리에 큰 값이 있으면 @eq로 정확히 일치시키려 해도 결과가 없어요. 이런 큰 값은 @not을 사용하면 전체 필터로 여전히 반환될 수 있어요 (예: 어떤 큰 X에 대해 @eq X는 값을 반환하지 않지만 @not @eq Y는 반환할 수 있어요).
TIMESTAMP 및 DATE 필터는 YYYY-MM-DD 형식의 값과, 시간대를 아는 날짜의 경우 YYYY-MM-DD+HH:MM 형식의 값을 받아요. 시간대 오프셋을 지정하지 않으면 날짜는 UTC로 해석돼요.
@primarykey는 기본 키로 구성된 서비스에서만 지원돼요. 필터 값은 모든 기본 키 열을 해당 값(또는 NULL)에 매핑하는 JSON 객체여야 해요.

이 연산자들은 단일 필터 객체로 결합할 수 있어요.

예시

문자열형 열 string_col이 값 value와 같은 행 필터링: { "@eq": { "string_col": "value" } }
지정된 기본 키를 가진 행으로 필터링: { "@primarykey": { "region": "us-west-1", "agent_id": "abc123" } }
ARRAY 열 array_col이 값 value를 포함하는 행 필터링: { "@contains": { "array_col": "arr_value" } }
NUMERIC 열 numeric_col이 10.5와 12.5 사이(포함)인 행 필터링: { "@and": [ { "@gte": { "numeric_col": 10.5 } }, { "@lte": { "numeric_col": 12.5 } } ]}
TIMESTAMP 열 timestamp_col이 2024-11-19와 2024-12-19 사이(포함)인 행 필터링: { "@and": [ { "@gte": { "timestamp_col": "2024-11-19" } }, { "@lte": { "timestamp_col": "2024-12-19" } } ]}
논리 연산자로 필터 결합: // "array_col" 열이 "arr_value"를 포함하고 "string_col" 열이 "value"와 같은 행: { "@and": [ { "@contains": { "array_col": "arr_value" } }, { "@eq": { "string_col": "value" } } ] } // "string_col" 열이 "value"와 같지 않은 행 { "@not": { "@eq": { "string_col": "value" } } } // "array_col" 열이 "val1", "val2", "val3" 중 적어도 하나를 포함하는 행 { "@or": [ { "@contains": { "array_col": "val1" } }, { "@contains": { "array_col": "val1" } }, { "@contains": { "array_col": "val1" } } ] }

반환 (Returns)

Cortex Search 서비스로부터의 쿼리 결과와 고유한 요청 ID를 담은 OBJECT를 반환해요. 예제 출력은 예제(Examples) 섹션을 참조하세요.

사용 메모 (Usage notes)

이 함수는 테스트 및 검증을 위해 설계됐으며 REST 또는 Python API를 사용하는 것보다 지연 시간(latency)이 더 커요. 낮은 지연 시간이 필요한 최종 사용자 애플리케이션에서는 검색 쿼리를 제공하기 위해 다른 방법을 사용하세요.
이 함수는 상수 인자에 대해서만 동작해요. 테이블 열은 입력으로 받지 않아요.
이 함수는 검색 결과가 300kB를 초과하면 잘라내요. REST 표면에서는 최대 10MB의 응답을 허용해요.

예제 (Examples)

이 예제는 sample_service라는 서비스를 테스트 쿼리로 조회해요. 예제는 최대 5개의 결과를 반환하며 col1과 col2 열의 데이터를 포함해요.

SELECT
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW (
      'mydb.mysch.sample_service',
      '{
          "query": "test query",
          "columns": ["col1", "col2"],
          "limit": 3
      }'
  );

{
  "results":[
      {"col1":"text", "col2":"text"},
      {"col1":"text", "col2":"text"},
      {"col1":"text", "col2":"text"}
  ],
  "request_id":"a27d1d85-e02c-4730-b320-74bf94f72d0d"
}

더 알아보기 (Learn more)

Cortex Search