Cortex Search Service 쿼리하기¶

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>`를 참조하세요.

pip install snowflake -U

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)

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

여기서

• <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> `_ 참조를 참조하십시오.

SQL SEARCH_PREVIEW 함수¶

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

사용법 노트¶

• 소스 쿼리에서 ``NaN``(‘숫자가 아님’) 값에 대한 일치는 :doc:`특수한 값</sql-reference/data-types-numeric>`에 설명된 대로 처리됩니다.

• 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 생성 시 사용된 소스 테이블의 열에서 가져옵니다. 쿼리 생성 시 부스트 또는 감쇠에 사용할 메타데이터 열을 지정할 수 있지만, 해당 열들은 Cortex Search Service 생성 시 반드시 포함되어야 합니다.

부스트 또는 감쇠 신호를 이용한 서비스 쿼리

Cortex Search Service를 쿼리할 때 scoring_config.functions 필드의 numeric_boosts 및 time_decays 필드에서 부스팅 또는 감쇠에 사용할 열을 선택 사항으로 지정합니다. 각 부스트 또는 쇠퇴에 대한 가중치를 지정할 수도 있습니다.

{
  "scoring_config": {
    "functions": {
      "numeric_boosts": [
        {
          "column": "<column_name>",
          "weight": <weight>
        },
        // ...
      ],
      "time_decays": [
        {
          "column": "<column_name>",
          "weight": <weight>,
          "limit_hours": <limit_hours>
        },
        // ...
      ]
    }
  }
}

속성:

• numeric_boosts (array, 선택 사항):

  • <numeric_boost_object> (object, 선택 사항):

    • column_name (string): 부스트가 적용될 숫자 열을 지정합니다.

    • weight (float): 순위 프로세스에서 부스트된 열에 할당된 가중치 또는 중요도를 지정합니다. 여러 열을 지정한 경우 가중치가 높을수록 필드의 영향력이 커집니다.

• time_decays (array, 선택 사항):

  • <time_decay_object> (object, 선택 사항):

    • column_name (string): 감쇠를 적용할 시간 또는 날짜 열을 지정합니다.

    • weight (float): 순위 프로세스에서 쇠퇴한 열에 할당된 가중치 또는 중요도를 지정합니다. 여러 열을 지정한 경우 가중치가 높을수록 필드의 영향력이 커집니다.

    • limit_hours (float): 문서의 관련성이나 중요도에 영향을 미치기 시작하는 경계를 설정합니다. 예를 들어, limit_hours 값이 240이면 now 타임스탬프에서 과거 240시간(10일) 이상의 타임스탬프가 있는 문서는 크게 부스트되지 않는 반면, 최근 240시간 이내의 타임스탬프가 있는 문서는 더 크게 부스트되어야 함을 나타냅니다.

    • now (string, 선택 사항): ISO-8601 형식 yyyy-MM-dd'T'HH:mm:ss.SSSXXX 로 감쇠를 계산하는 선택적 참조 타임스탬프. 예: "2025-02-19T14:30:45.123-08:00". 지정하지 않으면 기본값은 현재 타임스탬프입니다.

순위 재조정¶

기본적으로 Cortex Search Service에 대한 쿼리는 의미 체계 순위 재지정 을 활용하여 검색 결과 관련성을 개선합니다. 순위 재지정은 결과 관련성을 측정 가능하게 높일 수 있지만, 쿼리 대기 시간도 눈에 띄게 증가할 수 있습니다. 비즈니스 사용 사례에서 더 빠른 쿼리 속도를 위해 순위 재지정이 제공하는 품질 이점을 희생할 수 있다고 판단되면 모든 Cortex Search 쿼리에서 순위 재지정 기능을 사용하지 않도록 설정할 수 있습니다.

순위 재지정 없이 Cortex Search Service 쿼리

다음 형식의 scoring_config.reranker 필드에서 쿼리 시 개별 쿼리에 대한 순위 재지정을 비활성화할 수 있습니다.

{
  "scoring_config": {
      "reranker": "none"
}

속성:

• reranker (string, 선택 사항): 순위 재지정을 꺼야 하는 경우 “없음”으로 설정할 수 있는 매개 변수입니다. 제외되거나 null인 경우 기본 순위 재지정이 사용됩니다.

소유자 권한으로 쿼리하기¶

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

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

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

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

예제를 위한 설정¶

다음 예제에서는 다양한 기능을 시연하기 위해 타임스탬프 및 숫자 열이 있는 ``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;

필터 예시¶

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES"],
  "filter": {"@eq": {"REGION": "US"}},
  "limit": 5
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LIKES"],
         "filter": {"@eq": {"REGION": "US"}},
         "limit": 5
      }'
  )
)['results'] as results;

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "business",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "filter": {"@and": [
    {"@gte": {"LIKES": 50}},
    {"@lte": {"COMMENTS": 50}}
  ]},
  "limit": 10
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "business",
         "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
         "filter": {"@and": [
           {"@gte": {"LIKES": 50}},
           {"@lte": {"COMMENTS": 50}}
         ]},
         "limit": 10
      }'
  )
)['results'] as results;

점수 예시¶

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}
            ]
        }
    }
)

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "scoring_config": {
    "functions": {
      "numeric_boosts": [
        {"column": "comments", "weight": 2},
        {"column": "likes", "weight": 1}
      ]
    }
  }
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
         "scoring_config": {
           "functions": {
             "numeric_boosts": [
               {"column": "comments", "weight": 2},
               {"column": "likes", "weight": 1}
             ]
           }
         }
      }'
  )
)['results'] as results;

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"}
            ]
        }
    }
)

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "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"}
      ]
    }
  }
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "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"}
             ]
           }
         }
      }'
  )
)['results'] as results;

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
  "scoring_config": {
    "reranker": "none"
  }
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
         "scoring_config": {
           "reranker": "none"
         }
      }'
  )
)['results'] as results;