Cortex Search Service 쿼리하기¶

Snowflake Python APIs 라이브러리 설치¶

먼저 PyPI에서 최신 버전의 Snowflake Python APIs 패키지를 설치 관리자에 설치합니다. PyPI에서 이 패키지를 설치하는 방법에 대한 지침은 Snowflake Python APIs 라이브러리 설치 섹션을 참조하십시오.

pip install snowflake -U

Snowflake에 연결하기¶

Snowpark Session 또는 Python Connector Connection 을 사용하여 Snowflake에 연결하고 Root 오브젝트를 생성합니다. Snowflake에 연결하는 방법에 대한 자세한 지침은 Snowflake Python APIs 을 사용하여 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)

서비스 쿼리¶

다음 구문을 사용하여 서비스를 쿼리합니다.

# 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())

매개 변수¶

REST API 인증 구성¶

Snowflake REST APIs 는 프로그래밍 방식의 액세스 토큰(PATs), JSON 웹 토큰(JWTs)을 사용한 키 페어 인증, OAuth 를 통한 인증을 지원합니다. 자세한 내용은 Snowflake를 사용하여 Snowflake REST APIs 인증하기 섹션을 참조하십시오.

서비스 쿼리의 예¶

curl: 을 사용하여 서비스를 쿼리하려면

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": "<search_query>",
  "columns": ["col1", "col2"],
  "filter": <filter>
  "limit": <limit>
}'

예¶

다음 예제에서는 preview query 쿼리 문자열로 서비스를 미리 보고 결과를 VARIANT 오브젝트로 구문 분석합니다.

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'my_search_service',
      '{
         "query": "preview query",
         "columns":[
            "col1",
            "col2"
         ],
         "filter": {"@eq": {"col1": "filter value"} },
         "limit":10
      }'
  )
)['results'] as results;

예¶

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

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

  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": "val1" } },
        { "@contains": { "array_col": "val1" } }
    ]
  }
  

  Copy

부스트 또는 감쇠 신호로 서비스 쿼리하기¶

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 만들기

이 예제에서는 business_documents 라는 테이블에 타임스탬프 열 2개(last_modified, created_timestamp)와 정수 열 2개(likes, columns)를 사용하여 검색 결과의 부스트 및 감쇠에 사용할 수 있습니다.

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. Highlights include strategic investments in marketing and technology.',
     '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 and software guides and commonly asked tech questions.',
     '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 initiatives. Includes new guidelines on hybrid working models.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Marketing strategy document: Target audience segmentation for upcoming product launch. Detailed plans for social media, influencer partnerships, and content creation.',
     '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 of new features, bug fixes, and performance improvements.',
     '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 evaluations, set goals, and provide constructive feedback.',
     '2024-05-02 09:30:00', '2024-05-01 08:45:00', 60, 5);

그런 다음, business_documents 테이블의 document_contents 열에 business_documents_css 이라는 이름의 Cortex Search Service를 만듭니다.

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

숫자 부스트로 서비스 쿼리하기

아래 쿼리는 likes 및 comments 열 모두에 숫자 부스트를 적용하며, comments 값에 부스트 가중치를 likes 값에 비해 두 배로 적용합니다. 이 쿼리는 SQL SEARCH_PREVIEW 함수 를 사용하여 “technology”를 검색합니다.

SELECT
    index,
    value['DOCUMENT_CONTENTS']::string as DOCUMENT_CONTENTS,
    value['LIKES']::int as LIKES,
    value['COMMENTS']::int as COMMENTS,
FROM TABLE(FLATTEN(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'] ))

결과에서 참고하십시오.

• 부스트를 사용하면 "Product roadmap 2024:..." 문서가 쿼리 "technology" 와의 관련성이 약간 낮지만 좋아요와 설명이 많기 때문에 최상위 결과가 됩니다

• 부스트가 없는 경우 쿼리의 최상위 결과는 "IT manual for employees:..." 입니다

시간 감쇠를 사용하여 서비스 쿼리하기

다음 쿼리는 LAST_MODIFIED_TIMESTAMP 열을 기준으로 시간 감쇠를 적용합니다. 여기서,

• now 타임스탬프에 비해 더 최근의 LAST_MODIFIED_TIMESTAMP 값을 가진 문서가 부스트됩니다

• now 타임스탬프에서 240시간보다 큰 LAST_MODIFIED_TIMESTAMP 값을 가진 문서는 약간의 부스팅을 받습니다

SELECT
  value['DOCUMENT_CONTENTS']::string as DOCUMENT_CONTENTS,
  value['LAST_MODIFIED_TIMESTAMP']::timestamp as LAST_MODIFIED_TIMESTAMP
FROM TABLE(FLATTEN(PARSE_JSON(SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    'business_documents_css',
    '{
      "query": "technology",
      "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP", "CREATED_TIMESTAMP", "LIKES", "COMMENTS"],
      "scoring_config": {
          "functions": {
              "time_decays": [
                {"column": "LAST_MODIFIED_TIMESTAMP", "weight": 1, "limit_hours": 240, "now": "2024-04-23T00:00:00.000-08:00"}
              ]
            }
        }
    }'
))['results'] ));

결과에서 참고하십시오.

• 감쇠를 사용하면 "Product roadmap 2024:..." 문서는 "technology" 쿼리와의 관련성이 약간 낮지만, now 타임스탬프에 가장 최근의 것이므로 최상위 결과가 됩니다

• 감쇠가 없는 경우 쿼리의 최상위 결과는 "IT manual for employees:..." 입니다

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

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

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

속성:

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

예¶

순위 재지정 없이 검색 서비스 쿼리하기(Python)

다음 코드는 Python API 을 사용하여 순위 재지정 단계 없이 서비스를 쿼리합니다.

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

순위 재지정 없이 서비스 쿼리하기 (SQL)

다음 SQL 문은 SEARCH_PREVIEW 함수 를 사용하여 순위 재지정 단계 없이 서비스를 쿼리합니다.

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

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

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

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

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

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