Cortex Search Service 쿼리하기

Cortex Search Service를 생성하면 시스템은 낮은 대기 시간으로 쿼리를 처리하기 위해 API 엔드포인트를 프로비저닝합니다. Cortex Search Service에 대한 쿼리를 수행하려면 다음 세 가지 APIs를 사용할 수 있습니다.

매개 변수

APIs는 모두 동일한 쿼리 매개 변수 세트를 지원합니다.

매개 변수

설명

필수

query

서비스의 텍스트 열에서 검색할 검색어.

선택 사항

columns

응답에서 각 관련 결과에 대해 반환할 열의 쉼표로 구분된 목록입니다. 이 열들은 서비스의 소스 쿼리에 반드시 포함되어야 합니다. 이 매개 변수가 제공되지 않으면 응답에는 검색 열만 반환됩니다.

filter

ATTRIBUTES 열의 데이터를 기반으로 결과를 필터링하는 필터 오브젝트. 구문은 `구문 필터링`_을 참조하세요.

scoring_config

검색 순위 지정 동작을 사용자 지정하기 위한 구성 오브젝트입니다. 구문에 대해서는 Cortex Search Scoring 사용자 지정하기 섹션을 참조하세요.

scoring_profile

이전에 :doc:`ALTER CORTEX SEARCH SERVICE … ADD SCORING PROFILE </sql-reference/sql/alter-cortex-search>`로 정의된 쿼리와 함께 사용할 명명된 채점 프로필입니다. :code:`scoring_profile`이 제공되면 제공된 모든 :code:`scoring_config`가 무시됩니다.

limit

응답에서 반환할 최대 결과 수로, 최대 1000개입니다. 기본 제한은 10개입니다.

구문

다음 예제는 세 가지 표면 모두를 사용하여 Cortex Search Service를 쿼리하는 방법을 보여줍니다.

import os
from snowflake.core import Root
from snowflake.snowpark import Session

# connect to Snowflake
CONNECTION_PARAMETERS = { ... }
session = Session.builder.configs(CONNECTION_PARAMETERS).create()
root = Root(session)

# fetch service
my_service = (root
    .databases["<service_database>"]
    .schemas["<service_schema>"]
    .cortex_search_services["<service_name>"]
)

# query service
resp = my_service.search(
    query="<query>",
    columns=["<col1>", "<col2>"],
    filter={"@eq": {"<column>": "<value>"} },
    limit=5
)
print(resp.to_json())
Copy

설정 및 인증

Python API

Cortex Search Service는 Snowflake Python APIs 버전 0.8.0 이상을 사용하여 쿼리할 수 있습니다. Snowflake Python APIs에 대한 자세한 내용은 :doc:`Snowflake Python APIs: Python을 사용한 Snowflake 오브젝트 관리</developer-guide/snowflake-python-api/snowflake-python-overview>`를 참조하세요.

Snowflake Python API 라이브러리 설치하기

먼저, PyPI로부터 Snowflake Python APIs 패키지의 최신 버전을 설치하세요. 이 패키지를 PyPI로부터 설치하는 방법은 :doc:`Snowflake Python APIs 라이브러리 설치</developer-guide/snowflake-python-api/snowflake-python-installing>`를 참조하세요.

pip install snowflake -U
Copy

Snowflake에 연결하기

Snowpark Session 또는 Python Connector Connection 을 사용하여 Snowflake에 연결하고 Root 오브젝트를 생성합니다. Snowflake에 연결하는 방법에 대한 자세한 내용은 Snowflake Python APIs를 사용하여 Snowflake에 연결</developer-guide/snowflake-python-api/snowflake-python-connecting-snowflake>`을 참조하세요. 다음 예제에서는 Snowpark ``Session` 오브젝트와 Python 사전을 사용하여 구성합니다.

import os
from snowflake.core import Root
from snowflake.snowpark import Session

CONNECTION_PARAMETERS = {
    "account": os.environ["snowflake_account_demo"],
    "user": os.environ["snowflake_user_demo"],
    "password": os.environ["snowflake_password_demo"],
    "role": "test_role",
    "database": "test_database",
    "warehouse": "test_warehouse",
    "schema": "test_schema",
}

session = Session.builder.configs(CONNECTION_PARAMETERS).create()
root = Root(session)
Copy

참고

Cortex Search Service를 쿼리하려면 Snowflake Python APIs 라이브러리 버전 0.8.0 이상이 필요합니다.

REST API

Cortex Search는 Snowflake REST APIs 의 제품군에서 REST API 엔드포인트를 노출합니다. Cortex Search Service에 대해 생성된 REST 엔드포인트는 다음과 같은 구조로 되어 있습니다.

https://<account_url>/api/v2/databases/<db_name>/schemas/<schema_name>/cortex-search-services/<service_name>:query
Copy

여기서

  • <account_url>: 귀하의 Snowflake 계정 URL. 계정 URL을 찾는 방법에 대한 자세한 내용은 :ref:`계정의 조직 및 계정 이름 찾기<label-account_name_find>`를 참조하세요.

  • <db_name>: 서비스가 있는 데이터베이스입니다.

  • <schema_name>: 서비스가 있는 스키마입니다.

  • <service_name>: 서비스의 이름입니다.

  • :query: 서비스를 호출하는 메서드입니다. 이 경우에는 query 메서드입니다.

자세한 내용은 RESTCortex Search Service API` 에 대한 <https://docs.snowflake.com/developer-guide/snowflake-rest-api/reference/cortex-search-service> `_ 참조를 참조하십시오.

인증

Snowflake REST APIs는 프로그래매틱 액세스 토큰(PATs), JSON 웹 토큰을 사용한 키 페어 인증(JWTs), OAuth를 통한 인증을 지원합니다. 자세한 내용은 :doc:`Snowflake를 사용하여 Snowflake REST APIs 인증</developer-guide/snowflake-rest-api/authentication>`을 참조하세요.

SQL SEARCH_PREVIEW 함수

SNOWFLAKE.CORTEX.SEARCH_PREVIEW 함수를 사용하면 워크시트나 Snowflake Notebook 셀과 같은 SQL 환경 내에서 Cortex Search Service에 대한 개별 쿼리의 결과를 미리 볼 수 있습니다. 이 함수를 사용하면 서비스가 올바르게 채워지고 합리적인 결과가 제공되는지 대화형으로 유효성을 검사할 수 있습니다.

중요

SEARCH_PREVIEW 함수는 Cortex Search Service의 테스트 및 유효성 검사를 위해 제공됩니다. 최종 사용자 애플리케이션에서 검색 쿼리를 제공하기 위한 것이 아닙니다.

  • 이 함수는 문자열 리터럴에서만 작동합니다. 배치 텍스트 데이터는 허용하지 않습니다.

  • 이 함수의 지연 시간이 REST 및 Python APIs보다 깁니다.

필터 구문

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

Cortex Search는 다섯 가지 일치하는 연산자를 지원합니다.

이러한 일치 연산자는 다양한 논리 연산자로 구성될 수 있습니다.

  • @and

  • @or

  • @not

사용법 노트

  • 소스 쿼리에서 ``NaN``(‘숫자 아님’) 값에 대한 일치는 :ref:`label-data_type_float_special_values`에 설명된 대로 처리됩니다.

  • 19자리 이상(선행 0 제외)의 고정소수점 숫자 값은 @eq, @gte 또는 ``@lte``에서 작동하지 않으며, 이러한 연산자에서는 반환되지 않습니다(단, ``@not``을 사용하면 전체 쿼리에서 반환될 수는 있음).

  • TIMESTAMP 및 DATE 필터는 YYYY-MM-DD, 타임존 인식 날짜의 경우 YYYY-MM-DD+HH:MM 와 같은 형식의 값을 허용합니다. 시간대 오프셋을 지정하지 않으면 날짜는 UTC 로 해석됩니다.

  • @primarykey``는 :doc:`기본 키</sql-reference/constraints-overview>`로 구성된 서비스에 대해서만 지원됩니다. 필터의 값은 모든 기본 키 열을 해당 값(또는 ``NULL)에 매핑하는 JSON 오브젝트여야 합니다.

이러한 연산자를 1개의 필터 오브젝트로 결합할 수 있습니다.

예

  • 문자열과 같은 열 string_col 은 value 값과 같은 행을 필터링합니다.

    { "@eq": { "string_col": "value" } }
    Copy

  • region 열에 지정된 기본 키 값 us-west-1``이 있고, ``agent_id 열에 ``abc123``이 있는 행으로 필터링:

    { "@primarykey": { "region": "us-west-1", "agent_id": "abc123" } }
    Copy

  • ARRAY 열 array_col 에 값 value 가 포함된 행을 필터링합니다.

    { "@contains": { "array_col": "arr_value" } }
    Copy

  • NUMERIC 열 numeric_col 이 10.5에서 12.5(포함) 사이인 행을 필터링합니다.

    {
  "@and": [
    { "@gte": { "numeric_col": 10.5 } },
    { "@lte": { "numeric_col": 12.5 } }
  ]
}
    Copy

  • TIMESTAMP 열 timestamp_col 이 2024-11-19 과 2024-12-19 (포함) 사이에 있는 행을 필터링합니다.

    {
  "@and": [
    { "@gte": { "timestamp_col": "2024-11-19" } },
    { "@lte": { "timestamp_col": "2024-12-19" } }
  ]
}
    Copy

  • 논리 연산자를 사용하여 필터 구성:

    // Rows where the "array_col" column contains "arr_value" and the "string_col" column equals "value"
{
  "@and": [
    { "@contains": { "array_col": "arr_value" } },
    { "@eq": { "string_col": "value" } }
  ]
}

// Rows where the "string_col" column does not equal "value"
{
  "@not": { "@eq": { "string_col": "value" } }
}

// Rows where the "array_col" column contains at least one of "val1", "val2", or "val3"
{
  "@or": [
    { "@contains": { "array_col": "val1" } },
    { "@contains": { "array_col": "val2" } },
    { "@contains": { "array_col": "val3" } }
  ]
}
    Copy

액세스 제어 요구 사항

Cortex Search Service를 쿼리하는 역할은 결과를 검색하기 위해 다음 권한이 있어야 합니다.

권한

오브젝트

USAGE

Cortex Search Service

USAGE

Cortex Search Service가 있는 데이터베이스

USAGE

Cortex Search Service가 있는 스키마

소유자 권한으로 쿼리하기

Cortex Search Service는 소유자의 권한 으로 검색을 수행하며 소유자의 권한으로 실행되는 다른 Snowflake 오브젝트와 동일한 보안 모델을 따릅니다.

특히, 이는 서비스의 소스 쿼리에서 참조되는 기본 오브젝트(예: 테이블 및 뷰)에 대한 해당 역할의 권한에 관계없이 Cortex Search Service를 쿼리할 수 있는 충분한 권한을 가진 모든 역할이 서비스가 인덱싱한 모든 데이터를 쿼리할 수 있다는 것을 의미합니다.

예를 들어, 행 수준 마스킹 정책이 있는 테이블을 참조하는 Cortex Search Service의 경우, 해당 서비스의 쿼리 사용자는 쿼리 사용자의 역할이 소스 테이블에서 해당 행을 읽을 수 없더라도 소유자의 역할에 읽기 권한이 있는 행의 검색 결과를 볼 수 있습니다.

예를 들어, 다른 Snowflake 사용자에게 Cortex Search Service에서 USAGE 권한이 있는 역할을 부여할 때는 주의를 기울이십시오.

알려진 제한 사항

Cortex Search Service 쿼리에는 다음과 같은 제한이 적용됩니다.

예

이 섹션에서는 세 가지 API 메서드 모두에서 Cortex Search Service를 쿼리하는 포괄적인 예시를 제공합니다.

예제를 위한 설정

다음 예제에서는 다양한 기능을 시연하기 위해 타임스탬프 및 숫자 열이 있는 ``business_documents``라는 테이블을 사용합니다.

CREATE OR REPLACE TABLE business_documents (
    document_contents VARCHAR,
    last_modified_timestamp TIMESTAMP,
    created_timestamp TIMESTAMP,
    likes INT,
    comments INT
);

INSERT INTO business_documents (document_contents, last_modified_timestamp, created_timestamp, likes, comments)
VALUES
    ('Quarterly financial report for Q1 2024: Revenue increased by 15%, with expenses stable.',
     '2024-01-12 10:00:00', '2024-01-10 09:00:00', 10, 20),

    ('IT manual for employees: Instructions for usage of internal technologies, including hardware.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Employee handbook 2024: Updated policies on remote work, health benefits, and company culture.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Marketing strategy document: Target audience segmentation for upcoming product launch.',
     '2024-03-15 12:00:00', '2024-03-12 11:15:00', 150, 32),

    ('Product roadmap 2024: Key milestones for tech product development, including the launch.',
     '2024-04-22 17:30:00', '2024-04-20 16:00:00', 200, 45),

    ('Annual performance review process guidelines: Procedures for managers to conduct employee.',
     '2024-05-02 09:30:00', '2024-05-01 08:45:00', 60, 5);

CREATE OR REPLACE CORTEX SEARCH SERVICE business_documents_css
    ON document_contents
    WAREHOUSE = <warehouse_name>
    TARGET_LAG = '1 minute'
AS SELECT * FROM business_documents;
Copy

필터 예시

동일성 필터가 포함된 간단한 쿼리

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LIKES"],
    filter={"@eq": {"REGION": "US"}},
    limit=5
)
Copy

범위 필터

resp = business_documents_css.search(
    query="business",
    columns=["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
    filter={"@and": [
        {"@gte": {"LIKES": 50}},
        {"@lte": {"COMMENTS": 50}}
    ]},
    limit=10
)
Copy

점수 예시

숫자 부스트

좋아요와 댓글 열 모두에 숫자 부스트를 적용하되, 댓글 값에 대해 좋아요 값 대비 두 배의 부스트 가중치를 부여합니다.

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
    scoring_config={
        "functions": {
            "numeric_boosts": [
                {"column": "comments", "weight": 2},
                {"column": "likes", "weight": 1}
            ]
        }
    }
)
Copy

결과에서 참고하십시오.

  • 부스트가 적용되면 “제품 로드맵 2024:…” 문서는 “기술”이라는 검색어와의 관련성은 다소 낮지만, 많은 좋아요와 댓글 덕분에 최상위 결과로 노출됩니다.

  • 부스트가 적용되지 않으면 해당 쿼리의 최상위 결과는 “직원용 IT 매뉴얼:…”입니다.

시간 감쇠

다음과 같은 경우, LAST_MODIFIED_TIMESTAMP 열을 기준으로 시간 감쇠를 적용합니다.

  • 현재 타임스탬프를 기준으로 더 최근의 LAST_MODIFIED_TIMESTAMP 값을 가진 문서가 부스트됩니다.

  • 현재 타임스탬프로부터 LAST_MODIFIED_TIMESTAMP 값이 240시간을 초과하는 문서는 부스트가 거의 적용되지 않습니다.

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
    scoring_config={
        "functions": {
            "time_decays": [
                {"column": "LAST_MODIFIED_TIMESTAMP", "weight": 1, "limit_hours": 240, "now": "2024-04-23T00:00:00.000-08:00"}
            ]
        }
    }
)
Copy

결과에서 참고하십시오.

  • 감쇠가 적용되면 “제품 로드맵 2024:…” 문서는 현재 타임스탬프에 대한 최신성으로 인해 최상위 결과로 표시됩니다. 비록 “기술”이라는 쿼리에 대한 관련성은 약간 낮지만 말입니다.

  • 감쇠가 적용되지 않으면 해당 쿼리의 최상위 결과는 “직원용 IT 매뉴얼:…”입니다.

순위 재지정 비활성화

순위 재지정을 비활성화하려면 다음을 수행하세요.

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
    limit=5,
    scoring_config={
        "reranker": "none"
    }
)
Copy

팁

순위 재지정을 사용하여 서비스를 쿼리하려면 순위 재지정이 기본 동작이므로 scoring_config 오브젝트에서 "reranker": "none" 매개 변수를 생략하십시오.

언어: 한국어