CREATE CORTEX SEARCH SERVICE¶

新しい Cortex Search サービスを作成するか、既存のものを置き換えます。

構文¶

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> ]
  [ 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> ]
  [ COMMENT = '<comment>' ]
AS <query>;

必須パラメーター¶

name

Cortex Search Service用のノートブックの識別子（つまり、名前）を指定する文字列。ノートブックが作成されるスキーマに対して一意にする必要があります。

また、識別子はアルファベット文字で始まる必要があり、識別子文字列全体が二重引用符で囲まれていない限り、スペースや特殊文字を含めることはできません（例: "My object"）。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

詳細については、識別子の要件をご参照ください。

ON search_column

シングルインデックスCortex Searchのために、検索したいベーステーブルのテキスト列を指定します。この列はテキスト値である必要があります。

TEXT INDEXES text_column_name [, ... ]

マルチインデックスCortex Searchのために、検索するベーステーブルのコンマ区切りのテキスト列を指定します。列はテキスト値である必要があります。

VECTOR INDEXES column_specification [ , ... ]

ベクトル類似性検索の列を指定します。列の仕様には次が含まれます。

管理されたベクトル埋め込み: text_column_name (model='embedding_model'):ベクトル生成に使用するテキスト列と埋め込みモデルを指定します。サポートされている埋め込みモデルのいずれかを使用する必要があります。モデルが指定されていない場合、デフォルトのモデル snowflake-arctic-embed-m-v1.5 が使用されます。
ユーザー提供のベクトル埋め込み: vector_column_name:ユーザーが提供するベクトル埋め込み列を指定します。
管理されたクエリ埋め込みを持つユーザー提供のベクトル埋め込み: vector_column_name(query_model='embedding_model'):ユーザーが提供するベクトル埋め込み列と、クエリ時にテキスト埋め込みに使用される埋め込みモデルを指定します。query_model は Cortex SearchでサポートされるSnowflake管理埋め込みモデルのいずれかである必要があります。query_model が指定されていない場合、ユーザー提供のベクトル列はベクトル埋め込みクエリと一緒にのみ使用できます。

ベクトル埋め込みの動作については、使用上の注意をご参照ください。

ATTRIBUTES col_name [ , ... ]

サービスにクエリを発行する際にフィルタリングしたいベーステーブルの列のリストをカンマ区切りのリストで指定します。属性列は、明示的な列挙またはワイルドカード（*）を使用して、ソース・クエリに含める必要があります。

WAREHOUSE = warehouse_name

ソースクエリを実行し、検索インデックスを構築し、 TARGET_LAG ターゲットに従って更新し続けるために使用するウェアハウスを指定します。

TARGET_LAG = 'num { seconds | minutes | hours | days }'

Cortex Search Serviceのコンテンツがソースクエリで指定されたベーステーブルの更新から遅れる最大時間を指定します。

オプションのパラメーター¶

PRIMARY KEY ( col_name [, ... ] )

ソースクエリの各行を一意に識別する列のセットを指定します。指定された列の値の組み合わせは、行ごとに一意である必要があります。主キー値が重複している行は、結果の検索インデックスでは無視されます。主キー列は:doc:TEXT</sql-reference/data-types-text>`データタイプである必要があります。主キーを持つサービスは、基になるデータが変更されたときに最適化されたリフレッシュパスを利用できるため、リフレッシュのコストとレイテンシを大幅に削減できます。詳細については、 :ref:`label-cortex_search_primary_keys をご参照ください。

EMBEDDING_MODEL = <embedding_model_name>

Cortex Search Serviceで使用する埋め込みモデルを指定するオプションパラメーター。このプロパティは、Cortex Search Serviceを作成した後に変更することはできません。プロパティを変更するには、 CREATE OR REPLACE CORTEX SEARCH SERVICE コマンドでCortex Search Serviceを再作成します。

一部の埋め込みモデルは、Cortex Searchの特定のクラウドリージョンでのみ利用可能です。リージョン/モデル別の可用性リストについては、 Cortex Searchリージョン別可用性をご参照ください。

入力トークンが100万件処理されるごとに、各モデルに異なるコストが発生する場合があります。100万トークンあたりのクレジット単位での各コストについては、 Snowflakeサービス利用テーブルをご参照ください。

EMBEDDING_MODEL が指定されていない場合は、デフォルトのモデルが使用されます。デフォルトモデルは Snowflake-arctic-embed-m-v1.5 です。

REFRESH_MODE = { FULL | INCREMENTAL }

Cortex Search Serviceのリフレッシュモードを指定します。

このプロパティは、Cortex Search Serviceを作成した後に変更することはできません。プロパティを変更するには、 CREATE OR REPLACE CORTEX SEARCH SERVICE コマンドでCortex Search Serviceを再作成します。

FULL
Cortex Search Serviceのフルリフレッシュを強制します。フルリフレッシュはすべての埋め込みを再計算し、基になるソースデータに変更を加えるたびにインデックスを再構築します。埋め込みを再計算するコストを考えると、ワークロードでインクリメンタルリフレッシュがサポートされていない場合にのみ、フルリフレッシュを検討する必要があります。

INCREMENTAL
Cortex Search Serviceのインクリメンタルリフレッシュを強制します。インクリメンタルリフレッシュは、前回のリフレッシュ以降の変更のみを適用し、小さな更新を伴う大規模なデータセットに対してより効率的です。Cortex Search Serviceがインクリメンタルリフレッシュを実行できない場合、サービスの作成は失敗し、エラーメッセージが表示されます。

インクリメンタルリフレッシュでは、基になるすべてのオブジェクトで変更追跡を有効にする必要があります。詳細については、変更追跡の要件をご参照ください。

デフォルト: INCREMENTAL

INITIALIZE

Cortex Search Serviceの初期更新の動作を指定します。このプロパティは、サービス作成後に変更することはできません。プロパティを変更するには、Cortex Search Serviceを CREATE OR REPLACE CORTEX SEARCH SERVICE コマンドで置き換えます。

ON_CREATE
Cortex Search Serviceの作成時に同期的に更新します。この更新に失敗すると、サービスの作成に失敗し、エラーメッセージが表示されます。

ON_SCHEDULE
次のスケジュールでCortex Search Serviceを更新します。

Cortex Search Serviceは、更新スケジュール処理が実行されたときに入力されます。Cortex Search Serviceの作成時にはデータは入力されません。サービスをクエリしようとすると、最初のスケジュール更新がまだ発生していないため、次のようなエラーが表示されることがあります。
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

:ref:`主キー<label-cortex_search_primary_keys>`が定義されたCortex Search Serviceについて、フルインデックス再構築の間隔を日単位で指定します。このプロパティは、主キーが設定されているサービスにのみ適用されます。

この値はソフトターゲットです。サービスのターゲットラグ、サービスソースデータの変更率、サービス全体のサイズなどの要因に基づいて提供パフォーマンスを最適化するため、フルインデックスの再構築は指定された間隔よりも頻繁に発生する可能性があります。

デフォルト:0

COMMENT = 'comment'

サービスのコメントを指定します。

AS query

サービスが作成されるベース・テーブルを定義するクエリを指定します。

アクセス制御の要件¶

この操作の実行に使用されるロールには、少なくとも次の権限が必要です。


権限	オブジェクト
CREATE CORTEX SEARCH SERVICE	検索サービスを作成しているスキーマ。
SELECT	サービスがクエリするテーブルとビュー。
USAGE	サービスをリフレッシュするウェアハウス。

スキーマ内のオブジェクトを操作するには、親データベースの少なくとも1つの権限と、親スキーマの少なくとも1つの権限が必要です。

指定された権限のセットを使用してカスタムロールを作成する手順については、カスタムロールの作成をご参照ください。

セキュリティ保護可能なオブジェクトに対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、アクセス制御の概要をご参照ください。

注意

Cortex Search Serviceを作成するには、ロールがCortex埋め込み関数を使用するために必要な権限を持っている必要があります。これには、SNOWFLAKE.CORTEX_USER データベースロールか、 SNOWFLAKE.CORTEX_EMBED_USER データベースロールをサービス作成者ロールに付与する必要があります。

使用上の注意¶

注意

Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールドをご参照ください。

Cortex Searchサービスのソースクエリを実行するために使用されるウェアハウスのサイズは、各リフレッシュの速度とコストに影響します。より大きなウェアハウスは、ビルドとリフレッシュの時間を短縮します。ただし、このプレビュー期間中、Snowflake は Cortex Search サービスに MEDIUM 以下のウェアハウスサイズを使用することを推奨します。
Snowflake では、他のワークロードと干渉しないように、Cortex Search サービスごとに専用のウェアハウスを使用することを推奨しています。
検索インデックスはcreate文の一部として構築されるため、 CREATE CORTEX SEARCH SERVICE 文は大きなデータセットの場合、完了までに時間がかかることがあります。
マルチインデックスの検索サービスを作成する場合は、検索結果の最高の品質を確保するために VECTORINDEXES 句で少なくとも1つの列を指定する必要があります。ベクトルインデックスを持たないサービスを作成しようとすると、エラーが返されます。
TEXTINDEXES 句、 VECTORINDEXES 句、またはその両方で列を指定できます。
- テキストインデックスとして指定された列は、キーワード（レキシカル）検索に使用できます。テキストインデックスをクエリすると、結果はレキシカル類似度に基づいてスコアリングされます。
- ベクトルインデックスとして指定された列は、ベクトル（セマンティック）検索に使用できます。ベクトルインデックスをクエリすると、結果はセマンティック類似度に基づいてスコアリングされます。
テキストインデックスとベクトルインデックスの両方として指定された列は、どちらのタイプの検索にも使用されます。
各ベクトルインデックス列は、埋め込みを管理するために3つのメソッドのいずれかを使用します。
- 管理されたベクトル埋め込み:Snowflakeは、テキスト列が ON または VECTOR INDEXES 句で指定された場合に、ベクトル埋め込みを計算します。サポートされている埋め込みモデルのいずれかを使用する必要があります。
- ユーザー提供のベクトル埋め込み:あなたは Snowflakeが提供するベクトル埋め込みモデルまたはCortex Search Serviceによる取り込み前の外部ホスト埋め込みモデルを使ったベクトル埋め込みの計算と、クエリ時のテキスト入力に責任があります。
- 管理されたクエリ埋め込みを持つユーザー提供のベクトル埋め込み:あなたは、Cortex Search Serviceによる取り込みの前に Cortex SearchでサポートされるSnowflake管理埋め込みモデルのいずれかを使ってベクトル埋め込みを計算する責任があります。クエリ時に、Cortex Searchは指定された query_model を使用してテキストクエリを埋め込みます。

変更追跡の要件¶

Cortex Search Serviceを作成する際、クエリするテーブルで変更追跡が有効になっていない場合、Snowflakeは自動的にそれらのテーブルで変更追跡を有効にしようとします。増分リフレッシュをサポートするには、Cortex Search Serviceで使用されるすべての基本オブジェクトに対して、ゼロ以外のTime Travel保持期間で変更追跡を有効にする必要があります。

ベースオブジェクトが変更されると、Cortex Search Serviceも変更されます。ベースオブジェクトを再作成する場合は、変更追跡を再度有効にする必要があります。

変更追跡の有効化の詳細については、変更の追跡を有効にするをご参照ください。

OR REPLACE 句と IF NOT EXISTS 句は互いに排他的です。この2つを同じステートメントで使うことはできません。
CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。

例¶

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 Serviceを作成します。このサービスは、テキスト列（document_contents）と、テキスト列に対応する埋め込みを含むユーザー提供の別のベクトル埋め込み列（document_embedding）を持つテーブルを検索します。

注釈

この例では、簡単にするためにモック埋め込みを使用しています。実稼働のユースケースでは、 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;