CREATE CORTEX SEARCH SERVICE

CREATE CORTEX SEARCH SERVICE

새 Cortex Search 서비스를 만들거나 기존 서비스를 교체하는 명령이에요. Cortex Search 서비스는 기본 테이블의 데이터를 인덱싱해 빠른 검색(키워드 및 벡터 검색)을 제공하는 객체예요.

출처: 문서

본문

새 Cortex Search 서비스를 만들거나 기존 서비스를 교체해요.

구문 (Syntax)

CREATE [ OR REPLACE ] CORTEX SEARCH SERVICE [ IF NOT EXISTS ] <name>
  ON <search_column>
  [ PRIMARY KEY ( <col_name> [, ... ] ) ]
  ATTRIBUTES <col_name> [ , ... ]
  WAREHOUSE = <warehouse_name>
  TARGET_LAG = '<num> { seconds | minutes | hours | days }'
  [ EMBEDDING_MODEL = <embedding_model_name> ]
  [ REFRESH_MODE = { FULL | INCREMENTAL } ]
  [ INITIALIZE = { ON_CREATE | ON_SCHEDULE } ]
  [ FULL_INDEX_BUILD_INTERVAL_DAYS = <num> ]
  [ REQUEST_LOGGING = { TRUE | FALSE } ]
  [ AUTO_SUSPEND = <num_seconds> ]
  [ COMMENT = '<comment>' ]
AS <query>;

CREATE [ OR REPLACE ] CORTEX SEARCH SERVICE <name>
  TEXT INDEXES <text_column_name> [ , ... ]
  VECTOR INDEXES <column_specification> [ , ... ]
  [ PRIMARY KEY ( <col_name> [, ... ] ) ]
  ATTRIBUTES <col_name> [ , ... ]
  WAREHOUSE = <warehouse_name>
  TARGET_LAG = '<num> { seconds | minutes | hours | days }'
  [ REFRESH_MODE = { FULL | INCREMENTAL } ]
  [ INITIALIZE = { ON_CREATE | ON_SCHEDULE } ]
  [ FULL_INDEX_BUILD_INTERVAL_DAYS = <num> ]
  [ REQUEST_LOGGING = { TRUE | FALSE } ]
  [ AUTO_SUSPEND = <num_seconds> ]
  [ COMMENT = '<comment>' ]
AS <query>;

필수 매개변수 (Required parameters)

name Cortex Search 서비스의 식별자(즉 이름)를 지정하는 문자열로, 서비스가 만들어지는 스키마 안에서 고유해야 해요.

또한 식별자는 반드시 알파벳 문자로 시작해야 하며, 전체 식별자 문자열이 큰따옴표로 묶이지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 묶인 식별자는 대소문자를 구분해요.

자세한 내용은 식별자 요구 사항(Identifier requirements)을 참고해요.

ON search_column 단일 인덱스 Cortex Search에서 검색할 기본 테이블의 텍스트 컬럼을 지정해요. 이 컬럼은 텍스트 값이어야 해요.

TEXT INDEXES text_column_name [, ... ] 다중 인덱스 Cortex Search에서 검색할 기본 테이블의 쉼표로 구분된 텍스트 컬럼을 지정해요. 컬럼은 텍스트 값이어야 해요.

VECTOR INDEXES column_specification [ , ... ] 벡터 유사성 검색을 위한 컬럼을 지정해요. 컬럼 사양에는 다음이 포함돼요.

• 관리형 벡터 임베딩(Managed vector embeddings): text_column_name (model='embedding_model') — 텍스트 컬럼과 벡터 생성을 위한 임베딩 모델을 지정해요. 지원되는 임베딩 모델 중 하나를 사용해야 해요. 모델을 지정하지 않으면 기본 모델 snowflake-arctic-embed-m-v1.5가 사용돼요.
• 사용자 제공 벡터 임베딩(User-provided vector embeddings): vector_column_name — 사용자가 제공한 벡터 임베딩 컬럼을 지정해요.
• 관리형 쿼리 임베딩이 있는 사용자 제공 벡터 임베딩: vector_column_name(query_model='embedding_model') — 사용자가 제공한 벡터 임베딩 컬럼과 쿼리 시 텍스트 임베딩에 사용할 임베딩 모델을 지정해요. query_model은 Cortex Search에서 지원하는 Snowflake 관리 임베딩 모델 중 하나여야 해요. query_model을 지정하지 않으면 사용자 제공 벡터 컬럼은 벡터 임베딩 쿼리에만 사용할 수 있어요.

벡터 임베딩의 동작에 대한 정보는 사용 메모(Usage Notes)를 참고해요.

ATTRIBUTES col_name [ , ... ] 서비스에 쿼리를 발행할 때 필터링할 기본 테이블의 컬럼의 쉼표로 구분된 목록을 지정해요. 속성 컬럼은 명시적 열거 또는 와일드카드(*)를 통해 소스 쿼리에 포함되어야 해요.

WAREHOUSE = warehouse_name TARGET_LAG 대상을 기준으로 소스 쿼리 실행, 검색 인덱스 빌드, 새로 고침 유지를 위한 웨어하우스를 지정해요.

TARGET_LAG = 'num { seconds | minutes | hours | days }' Cortex Search 서비스 내용이 소스 쿼리에 지정된 기본 테이블의 업데이트보다 뒤처질 수 있는 최대 시간을 지정해요.

참고: 대상 지연(target lag)이 소스 테이블의 데이터 보존 기간보다 짧도록 해요. 대상 지연이 데이터 보존 기간을 초과하면 서비스가 소스 데이터의 변경을 감지하지 못할 수 있고 재생성이 필요할 수 있어요. 자세한 내용은 DATA_RETENTION_TIME_IN_DAYS를 참고해요.

선택 매개변수 (Optional parameters)

PRIMARY KEY ( col_name [, ... ] ) 소스 쿼리에서 각 행을 고유하게 식별하는 컬럼 집합을 지정해요. 지정된 컬럼의 값 조합은 각 행에 대해 고유해야 하며, 중복 기본 키 값을 가진 행은 결과 검색 인덱스에서 무시돼요. 기본 키 컬럼은 TEXT 데이터 유형이어야 해요. 기본 키가 있는 서비스는 기본 데이터가 변경될 때 최적화된 새로 고침 경로를 사용할 수 있어 새로 고침 비용과 지연 시간을 크게 줄여요. 자세한 내용은 기본 키(Primary keys)를 참고해요.

EMBEDDING_MODEL = <embedding_model_name> Cortex Search 서비스에서 사용할 임베딩 모델을 지정하는 선택적 매개변수예요. 이 속성은 Cortex Search 서비스를 만든 뒤에는 변경할 수 없어요. 속성을 수정하려면 CREATE OR REPLACE CORTEX SEARCH SERVICE 명령으로 서비스를 다시 만들어요.

일부 임베딩 모델은 Cortex Search에 특정 클라우드 리전에서만 사용할 수 있어요. 모델별·리전별 가용성 목록은 Cortex Search 리전별 가용성(Cortex Search Regional Availability)을 참고해요.

각 모델은 처리되는 입력 토큰 100만 개당 비용이 다를 수 있어요. 각 함수의 백만 토큰당 크레딧 비용은 Snowflake 서비스 소비 표(Service Consumption Table)를 참고해요.

EMBEDDING_MODEL을 지정하지 않으면 기본 모델이 사용돼요. 기본 모델은 snowflake-arctic-embed-m-v1.5예요.

REFRESH_MODE = { FULL | INCREMENTAL } Cortex Search 서비스의 새로 고침 모드를 지정해요.

이 속성은 Cortex Search 서비스를 만든 뒤에는 변경할 수 없어요. 속성을 수정하려면 CREATE OR REPLACE CORTEX SEARCH SERVICE 명령으로 서비스를 다시 만들어요.

• FULL: Cortex Search 서비스의 전체 새로 고침을 강제해요. 전체 새로 고침은 기본 소스 데이터의 모든 변경에 대해 모든 임베딩을 다시 계산하고 인덱스를 다시 빌드해요. 임베딩 재계산 비용을 고려할 때, 워크로드에서 증분 새로 고침이 지원되지 않는 경우에만 전체 새로 고침을 고려해야 해요.
• INCREMENTAL: Cortex Search 서비스의 증분 새로 고침을 강제해요. 증분 새로 고침은 마지막 새로 고침 이후의 변경만 적용하므로, 작은 업데이트가 있는 대규모 데이터셋에 더 효율적이에요. 증분 새로 고침을 수행할 수 없으면 서비스 생성이 실패하고 오류 메시지를 표시해요.

증분 새로 고침은 모든 기본 객체에서 변경 추적(change tracking)이 활성화되어 있어야 해요. 자세한 내용은 변경 추적 요구 사항(Change Tracking Requirements)을 참고해요.

INITIALIZE = { ON_CREATE | ON_SCHEDULE } Cortex Search 서비스의 초기 새로 고침 동작을 지정해요. 이 속성은 서비스를 만든 뒤에는 변경할 수 없어요. 속성을 수정하려면 CREATE OR REPLACE CORTEX SEARCH SERVICE 명령으로 서비스를 교체해요.

• ON_CREATE: 생성 시 Cortex Search 서비스를 동기적으로 새로 고쳐요. 이 새로 고침이 실패하면 서비스 생성이 실패하고 오류 메시지를 표시해요.
• ON_SCHEDULE: 다음 예정된 새로 고침에서 Cortex Search 서비스를 새로 고쳐요.

Cortex Search 서비스는 새로 고침 스케줄 프로세스가 실행될 때 채워져요. Cortex Search 서비스가 만들어질 때는 데이터가 채워지지 않아요. 서비스를 쿼리하려고 하면 첫 번째 예정된 새로 고침이 아직 발생하지 않아 다음 오류가 표시될 수 있어요.

Your service has not yet been loaded into our serving system. Please retry your request in a few minutes.

• 기본값: ON_CREATE

FULL_INDEX_BUILD_INTERVAL_DAYS = num 기본 키가 정의된 Cortex Search 서비스에서 전체 인덱스 다시 빌드 사이의 대상 간격(일)을 지정해요. 이 속성은 기본 키가 설정된 서비스에만 적용돼요.

기본 키가 있는 서비스는 최적화된 새로 고침 경로를 사용하며, 각 새로 고침 주기(TARGET_LAG로 제어)는 모든 데이터를 다시 임베딩하는 대신 마지막 새로 고침 이후 변경된 행만 처리해요. 시간이 지남에 따라 이러한 증분 업데이트는 단편화된 인덱스 세그먼트를 축적해요. 전체 인덱스 다시 빌드는 이러한 세그먼트를 단일 최적화된 인덱스로 압축해요. 다시 빌드는 변경되지 않은 데이터를 다시 임베딩하지 않아요.

이 값은 소프트 대상(soft target)이에요. 서비스 대상 지연, 서비스 소스 데이터의 변경률, 전체 서비스 크기 같은 요인에 따라 서빙 성능을 최적화하기 위해 지정된 간격보다 더 자주 전체 인덱스 다시 빌드가 발생할 수 있어요.

• 기본값: 1

REQUEST_LOGGING = { TRUE | FALSE } Cortex Search 서비스의 요청 로깅을 활성화하거나 비활성화해요. 활성화하면 서비스가 검색 요청에 대한 정보를 기록하며, 이를 모니터링과 분석 목적으로 쿼리할 수 있어요. 자세한 내용은 Cortex Search 요청 모니터링(Monitor Cortex Search requests)을 참고해요.

• 기본값: FALSE

AUTO_SUSPEND = num_seconds 지정된 시간(초) 동안 쿼리 비활성화 후 서비스의 서빙 컴퓨트를 자동으로 일시 중지해요. 서비스는 쿼리를 받으면 자동으로 재개돼요.

• 최소값: 1800 (30분). 자세한 내용은 비활동 시 서빙 자동 일시 중지(Auto-suspend serving on inactivity)를 참고해요.
• 기본값: NULL (자동 일시 중지 비활성화)

COMMENT = 'comment' 서비스에 대한 설명(comment)을 지정해요.

AS query 서비스가 생성되는 기본 테이블을 정의하는 쿼리를 지정해요.

접근 제어 요구 사항 (Access Control Requirements)

권한 (Privilege)	객체 (Object)
CREATE CORTEX SEARCH SERVICE	서비스를 만드는 스키마
SELECT	서비스가 쿼리하는 테이블과 뷰
USAGE	서비스를 새로 고치는 웨어하우스

⚠️ 주의: Cortex Search 서비스를 만들려면 역할이 Cortex 임베딩 함수를 사용하는 데 필요한 권한을 가져야 해요. 이를 위해서는 서비스 생성자 역할에 SNOWFLAKE.CORTEX_USER 데이터베이스 역할 또는 SNOWFLAKE.CORTEX_EMBED_USER 데이터베이스 역할을 부여해야 해요.

사용 메모 (Usage Notes)

⚠️ 주의: 고객은 Snowflake 서비스를 사용할 때 (User 객체를 제외하고) 개인 데이터·민감 데이터·수출 통제 데이터·기타 규제 데이터를 메타데이터로 입력하지 않도록 해야 해요. 자세한 내용은 Snowflake의 메타데이터 필드를 참고해요.

Cortex Search 서비스 소스 쿼리를 실행하는 데 사용하는 웨어하우스의 크기는 각 새로 고침의 속도와 비용에 영향을 미쳐요. 더 큰 웨어하우스는 빌드·새로 고침 시간을 줄여요. 다만 이 미리보기 동안 Snowflake는 Cortex Search 서비스에 MEDIUM보다 큰 웨어하우스 크기를 사용하지 않을 것을 권장해요.

Snowflake는 각 Cortex Search 서비스에 대해 전용 웨어하우스를 사용해 다른 워크로드를 방해하지 않을 것을 권장해요.

검색 인덱스는 create 문의 일부로 만들어지므로, 데이터셋이 클수록 CREATE CORTEX SEARCH SERVICE 문을 완료하는 데 시간이 더 걸릴 수 있어요.

다중 인덱스 검색 서비스를 만들 때는 검색 결과의 최고 품질을 보장하기 위해 VECTOR INDEXES 절에 컬럼을 최소 하나 지정해야 해요. 벡터 인덱스 없이 서비스를 만들려고 하면 오류가 반환돼요.

컬럼은 TEXT INDEXES 절, VECTOR INDEXES 절, 또는 둘 다에 지정할 수 있어요.

• 텍스트 인덱스로 지정된 컬럼은 키워드(어휘) 검색에 사용할 수 있어요. 텍스트 인덱스를 쿼리하면 결과가 어휘 유사성의 정도에 따라 점수가 매겨져요.
• 벡터 인덱스로 지정된 컬럼은 벡터(의미) 검색에 사용할 수 있어요. 벡터 인덱스를 쿼리하면 결과가 의미 유사성의 정도에 따라 점수가 매겨져요.
• 텍스트와 벡터 인덱스 둘 다로 지정된 컬럼은 두 가지 유형의 검색에 모두 사용돼요.

각 벡터 인덱스 컬럼은 임베딩을 관리하는 세 가지 방법 중 하나를 사용해요.

• 관리형 벡터 임베딩: 텍스트 컬럼이 ON 또는 VECTOR INDEXES 절에 지정되면 Snowflake가 벡터 임베딩을 계산해요. 지원되는 임베딩 모델 중 하나를 사용해야 해요.
• 사용자 제공 벡터 임베딩: Cortex Search 서비스에 의한 수집 전, 그리고 쿼리 시 텍스트 입력에 대해 Snowflake 제공 벡터 임베딩 모델 또는 외부 호스팅 임베딩 모델로 벡터 임베딩을 계산하는 것은 사용자 책임이에요.
• 관리형 쿼리 임베딩이 있는 사용자 제공 벡터 임베딩: Cortex Search 서비스에 의한 수집 전에 Cortex Search에서 지원되는 Snowflake 관리형 임베딩 모델 중 하나로 벡터 임베딩을 계산하는 것은 사용자 책임이에요. 쿼리 시에는 Cortex Search가 지정된 query_model로 텍스트 쿼리를 임베딩해요.

변경 추적 요구 사항 (Change Tracking Requirements)

Cortex Search 서비스를 만들 때, 그것이 쿼리하는 테이블에서 변경 추적이 아직 활성화되지 않았다면 Snowflake가 자동으로 변경 추적을 활성화하려고 시도해요. 증분 새로 고침을 지원하려면 Cortex Search 서비스가 사용하는 모든 기본 객체에서 0이 아닌 Time Travel 보존으로 변경 추적이 활성화되어 있어야 해요.

기본 객체가 변경되면 Cortex Search 서비스도 변경돼요. 기본 객체를 다시 만들면 변경 추적을 다시 활성화해야 해요.

변경 추적 활성화에 대한 자세한 내용은 기본 테이블에서 변경 추적이 활성화되지 않음(Change tracking not enabled on base tables)을 참고해요.

참고: Cortex Search 서비스의 경우 CREATE OR REPLACE의 원자성은 메타데이터 트랜잭션에만 적용돼요. 새 서비스를 위한 검색 인덱스는 트랜잭션이 커밋된 뒤에 빌드되므로, 문이 커밋되는 순간부터 새 인덱스 빌드가 끝날 때까지 이전 서비스의 데이터는 더 이상 사용할 수 없어요.

OR REPLACE와 IF NOT EXISTS 절은 서로 배타적이에요. 같은 문에서 둘 다 사용할 수 없어요.

CREATE OR REPLACE <object> 문은 원자적(atomic)으로 동작해요. 즉, 객체를 교체할 때 기존 객체는 삭제되고 새 객체는 단일 트랜잭션 안에서 생성돼요.

예시 (Examples)

snowflake-arctic-embed-l-v2.0 임베딩 모델을 사용해 mysvc라는 Cortex Search 서비스를 만들어요.

CREATE OR REPLACE CORTEX SEARCH SERVICE mysvc
  ON transcript_text
  ATTRIBUTES region,agent_id
  WAREHOUSE = mywh
  TARGET_LAG = '1 hour'
  EMBEDDING_MODEL = 'snowflake-arctic-embed-l-v2.0'
AS (
  SELECT
      transcript_text,
      date,
      region,
      agent_id
  FROM support_db.public.transcripts_etl
);

mysvc라는 Cortex Search 서비스를 만들되, 첫 번째 새로 고침이 하나의 TARGET_LAG 기간(1시간)이 지난 뒤 실행되도록 예약해요.

CREATE OR REPLACE CORTEX SEARCH SERVICE mysvc
  ON transcript_text
  ATTRIBUTES region
  WAREHOUSE = mywh
  TARGET_LAG = '1 hour'
  INITIALIZE = ON_SCHEDULE
AS SELECT * FROM support_db.public.transcripts_etl;

테이블 business_directory를 검색하는 business_search_service라는 다중 인덱스 검색 서비스를 만들어요. 여기서:

• name과 address는 텍스트 인덱스로 지정되므로 키워드 검색으로만 검색할 수 있어요.
• description은 벡터 인덱스로 지정되므로 관리형 벡터 임베딩과 snowflake-arctic-embed-m-v1.5 모델로 벡터(의미) 검색에 사용할 수 있어요.

-- Generate sample data
CREATE OR REPLACE TABLE business_directory (name TEXT, address TEXT, description TEXT);
INSERT INTO business_directory VALUES
    ('Joe''s Coffee', '123 Bean St, Brewtown','A cozy café known for artisan espresso and baked goods.'),
    ('Sparkle Wash', '456 Clean Ave, Sudsville', 'Eco-friendly car wash with free vacuum service.'),
    ('Tech Haven', '789 Circuit Blvd, Siliconia', 'Computer store offering the latest gadgets and tech repair services.'),
    ('Joe''s Wash n'' Fold', '456 Apple Ct, Sudsville', 'Laundromat offering coin laundry and premium wash and fold services.'),
    ('Circuit Town', '459 Electron Dr, Sudsville', 'Technology store selling used computer parts at discounted prices.')
;

-- Create the Cortex Search Service
CREATE OR REPLACE CORTEX SEARCH SERVICE business_search_service
    TEXT INDEXES name, address
    VECTOR INDEXES description (model='snowflake-arctic-embed-m-v1.5')
    WAREHOUSE = mywh
    TARGET_LAG = '1 hour'
    AS ( SELECT * FROM business_directory );

사용자 지정 벡터 임베딩이 있는 custom_vector_search_service라는 다중 인덱스 Cortex Search 서비스를 만들어요. 이 서비스는 텍스트 컬럼(document_contents)과, 텍스트 컬럼에 대응하는 별도의 사용자 제공 벡터 임베딩 컬럼(document_embedding)이 있는 테이블을 검색해요.

참고: 이 예시는 단순화를 위해 목(mock) 임베딩을 사용해요. 실제 사용 사례에서는 Snowflake 벡터 임베딩 모델 또는 외부 호스팅 임베딩 모델을 통해 벡터를 생성해야 해요.

-- Generate sample data
CREATE OR REPLACE TABLE business_documents (
  document_contents VARCHAR,
  document_embedding VECTOR(FLOAT, 3)
);
INSERT INTO business_documents VALUES
  ('Quarterly financial report for Q1 2024: Revenue increased by 15%, with expenses stable. Highlights include strategic investments in marketing and technology.', [1, 1, 1]::VECTOR(float, 3)),
  ('IT manual for employees: Instructions for usage of internal technologies, including hardware and software guides and commonly asked tech questions.', [2, 2, 2]::VECTOR(float, 3)),
  ('Employee handbook 2024: Updated policies on remote work, health benefits, and company culture initiatives.', [2, 3, 2]::VECTOR(float, 3)),
  ('Marketing strategy document: Target audience segmentation for upcoming product launch.', [1, -1, -1]::VECTOR(float, 3))
;

-- Create the Cortex Search Service
CREATE OR REPLACE CORTEX SEARCH SERVICE custom_vector_search_service
  TEXT INDEXES (document_contents)
  VECTOR INDEXES (document_embedding)
  WAREHOUSE = mywh
  TARGET_LAG = '1 minute'
  AS SELECT * FROM business_documents;

사용자 관리 벡터 임베딩과 관리형 쿼리 임베딩이 있는 managed_vector_search_service 서비스를 만들어요.

-- Generate sample data
CREATE OR REPLACE TABLE business_documents (
  document_contents VARCHAR
);

INSERT INTO business_documents VALUES
  ('Quarterly financial report for Q1 2024: Revenue increased by 15%, with expenses stable. Highlights include strategic investments in marketing and technology.'),
  ('IT manual for employees: Instructions for usage of internal technologies, including hardware and software guides and commonly asked tech questions.'),
  ('Employee handbook 2024: Updated policies on remote work, health benefits, and company culture initiatives.'),
  ('Marketing strategy document: Target audience segmentation for upcoming product launch.');

-- Add managed vector embeddings
ALTER TABLE business_documents ADD COLUMN document_embeddings VECTOR(FLOAT, 768);
UPDATE business_documents SET document_embeddings = AI_EMBED('snowflake-arctic-embed-m-v1.5', document_contents);

-- Create the Cortex Search Service
CREATE OR REPLACE CORTEX SEARCH SERVICE managed_vector_search_service
  TEXT INDEXES document_contents
  VECTOR INDEXES document_embedding(query_model='snowflake-arctic-embed-m-v1.5')
  WAREHOUSE = mywh
  TARGET_LAG = '1 minute'
  AS SELECT * FROM business_documents;

더 알아보기 (Learn more)

• Cortex Search 개요 — 검색 서비스 소개
• ALTER CORTEX SEARCH SERVICE — 검색 서비스 수정
• SHOW CORTEX SEARCH SERVICES — 검색 서비스 조회