CREATE CORTEX SEARCH SERVICE¶

Sintaxe¶

CREATE [ OR REPLACE ] CORTEX SEARCH SERVICE [ IF NOT EXISTS ] <name>
  ON <search_column>
  ATTRIBUTES <col_name> [ , ... ]
  WAREHOUSE = <warehouse_name>
  TARGET_LAG = '<num> { seconds | minutes | hours | days }'
  [ EMBEDDING_MODEL = <embedding_model_name> ]
  [ INITIALIZE = { ON_CREATE | ON_SCHEDULE } ]
  [ COMMENT = '<comment>' ]
AS <query>;

CREATE [ OR REPLACE ] CORTEX SEARCH SERVICE <name>
  TEXT INDEXES <text_column_name> [ , ... ]
  VECTOR INDEXES <column_specification> [ , ... ]
  ATTRIBUTES <col_name> [ , ... ]
  WAREHOUSE = <warehouse_name>
  TARGET_LAG = '<num> { seconds | minutes | hours | days }'
  [ INITIALIZE = { ON_CREATE | ON_SCHEDULE } ]
  [ COMMENT = '<comment>' ]
AS <query>;

Parâmetros obrigatórios¶

name

A cadeia de caracteres que especifica o identificador (ou seja, o nome) para o Cortex Search Service; deve ser exclusivo para o esquema no qual o serviço é criado.

Além disso, o identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais informações, consulte Requisitos para identificadores.

ON search_column

Specifies the text column in the base table that you wish to search on, for single-index Cortex Search. This column must be a text value.

TEXT INDEXES text_column_name [, ... ]

Specifies comma-separated text columns in the base table to search on, for multi-index Cortex Search. Columns must be text values.

VECTOR INDEXES column_specification [ , ... ]

Especifica colunas para pesquisas de similaridade vetorial. As especificações de coluna incluem:

• Incorporações vetoriais gerenciadas: text_column_name (model='embedding_model'): especifica uma coluna de texto e o modelo de incorporação usado para geração de vetores. Deve usar um dos modelos de incorporação compatíveis. Se nenhum modelo for especificado, o modelo padrão snowflake-arctic-embed-m-v1.5 será usado.

• Incorporação vetoriais fornecidas pelo usuário: vector_column_name: especifica uma coluna de incorporação vetorial fornecida pelo usuário.

• Incorporações vetoriais fornecidas pelo usuário com incorporações de consulta gerenciada: vector_column_name(query_model='embedding_model'): especifica uma coluna de incorporação vetorial fornecida pelo usuário e o modelo de incorporação usado para incorporar texto no momento da consulta. O query_model deve ser um dos modelos de incorporação gerenciados pelo Snowflake compatíveis com o Cortex Search. Se nenhum query_model for especificado, a coluna vetorial fornecida pelo usuário só poderá ser usada com uma consulta de incorporação vetorial.

Para obter informações sobre o comportamento das incorporações vetoriais, consulte Notas de uso.

ATTRIBUTES col_name [ , ... ]

Especifica uma lista separada por vírgulas de colunas na tabela base que você deseja filtrar ao emitir consultas ao serviço. As colunas de atributos devem ser incluídas na consulta de origem, por meio de enumeração explícita ou curinga, (*).

WAREHOUSE = warehouse_name

Especifica o warehouse a ser usado para executar a consulta de origem, criar o índice de pesquisa e mantê-lo atualizado de acordo com o destino TARGET_LAG.

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

Especifica o tempo máximo que o conteúdo do Cortex Search Service deve ficar atrás das atualizações das tabelas base especificadas na consulta de origem.

Parâmetros opcionais¶

EMBEDDING_MODEL = <embedding_model_name>

Parâmetro opcional que especifica o modelo de incorporação a ser usado no Cortex Search Service. Essa propriedade não pode ser alterada depois que você criar o Cortex Search Service. Para modificar a propriedade, recrie o Cortex Search Service com um comando CREATE OR REPLACE CORTEX SEARCH SERVICE.

Alguns modelos de incorporação estão disponíveis apenas em determinadas regiões da nuvem para o Cortex Search. Para obter uma lista de disponibilidade por modelo e por região, consulte Disponibilidade regional do Cortex Search.

Cada modelo pode incorrer em um custo diferente por milhão de tokens de entrada processados. Consulte a Tabela de consumo do serviço Snowflake para o custo de cada função em créditos por milhão de tokens.

Se o endereço EMBEDDING_MODEL não for especificado, o modelo padrão será usado. O modelo padrão é snowflake-arctic-embed-m-v1.5.

INITIALIZE

Especifica o comportamento da atualização inicial do Cortex Search Service. Essa propriedade não pode ser alterada depois que você criar o serviço. Para modificar a propriedade, substitua o Cortex Search Service por um comando CREATE OR REPLACE CORTEX SEARCH SERVICE.

ON_CREATE

Atualiza o Cortex Search Service de forma síncrona na criação. Se essa atualização falhar, a criação do serviço falhará e será exibida uma mensagem de erro.

ON_SCHEDULE

Atualiza o Cortex Search Service na próxima atualização programada.

O Cortex Search Service é preenchido quando o processo do cronograma de atualização é executado. Nenhum dado é preenchido quando o Cortex Search Service é criado. Se você tentar consultar o serviço, poderá ver o seguinte erro, pois a primeira atualização programada ainda não ocorreu.

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

Padrão: ON_CREATE

COMMENT = 'comment'

Especifica um comentário para o serviço.

AS query

Especifica uma consulta que define a tabela base a partir da qual o serviço é criado.

Requisitos de controle de acesso¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

A operação em um objeto de esquema requer pelo menos um privilégio no banco de dados pai e um privilégio no esquema pai.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

• O tamanho do warehouse usado para executar a consulta de origem do Cortex Search Service afeta a velocidade e o custo de cada atualização. Um warehouse maior diminui o tempo de criação e atualização. No entanto, durante esta versão preliminar, a Snowflake recomenda usar um tamanho de warehouse não maior do que MEDIUM para os Cortex Search Services.

• A Snowflake recomenda usar um warehouse dedicado para cada Cortex Search Service para não interferir em outras cargas de trabalho.

• O índice de pesquisa é criado como parte da instrução create, o que significa que a instrução CREATE CORTEX SEARCH SERVICE pode demorar mais para ser concluída para conjuntos de dados maiores.

• Ao criar um serviço de pesquisa de vários índices, pelo menos uma coluna deve ser especificada na cláusula VECTOR INDEXES a fim de garantir a mais alta qualidade dos resultados da pesquisa. A tentativa de criar um serviço sem índices vetoriais retorna um erro.

• Uma coluna pode ser especificada na cláusula TEXT INDEXES, VECTOR INDEXES ou em ambas:

  • As colunas especificadas como índices de texto podem ser usadas para pesquisa de palavras-chave (lexical). Ao consultar um índice de texto, os resultados são pontuados com base no grau de similaridade lexical.

  • As colunas especificadas como índices vetoriais podem ser usadas para pesquisa vetorial (semântica). Ao consultar um índice vetorial, os resultados são pontuados com base no grau de similaridade semântica.

• As colunas especificadas como índices de texto e vetoriais são usadas para ambos os tipos de pesquisa.

• Cada coluna de índice vetorial emprega um dos três métodos para gerenciar incorporações:

  • Incorporações vetoriais gerenciadas: o Snowflake calcula as incorporações vetoriais quando uma coluna de texto é especificada nas cláusulas ON ou VECTOR INDEXES. Deve usar um dos modelos de incorporação compatíveis.

  • Incorporações vetoriais fornecidas pelo usuário: você é responsável por calcular as incorporações vetoriais com um modelo de incorporação vetorial fornecido pelo Snowflake ou um modelo de incorporação hospedado externamente antes da ingestão pelo Cortex Search Service, além das entradas de texto no momento da consulta.

  • Incorporações vetoriais fornecidas pelo usuário com incorporações de consulta gerenciada: você é responsável por calcular as incorporações vetoriais com um dos modelos de incorporação gerenciados pelo Snowflake compatíveis com o Cortex Search antes da ingestão pelo Cortex Search Service. No momento da consulta, o Cortex Search incorpora as consultas de texto usando o query_model especificado.

Requisitos de rastreamento de alterações¶

Ao criar um Cortex Search Service, se o rastreamento de alterações ainda não estiver habilitado nas tabelas que ele consulta, o Snowflake tentará automaticamente habilitar o rastreamento de alterações nelas. Para oferecer suporte a atualizações incrementais, o rastreamento de alterações deve ser habilitado com retenção do Time Travel diferente de zero em todos os objetos subjacentes usados por um Cortex Search Service.

O Cortex Search Service muda de acordo com as alterações nos objetos base. Se você recriar um objeto base, deverá habilitar novamente o rastreamento de alterações.

Para obter mais informações sobre como habilitar o rastreamento de alterações, consulte Habilitar o rastreamento de alterações.

• As cláusulas OR REPLACE e IF NOT EXISTS são mutuamente exclusivas. Os dois não podem ser usados na mesma instrução.

• Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.

Examples¶

Crie um serviço do Cortex Search chamado mysvc usando o modelo de incorporação snowflake-arctic-embed-l-v2.0:

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
);

Crie um serviço Cortex Search chamado mysvc, com a primeira atualização programada para ser executada após um período de TARGET_LAG (1 hora).

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;

Crie um serviço de pesquisa de vários índices chamado business_search_service que pesquisa a tabela business_directory, em que:

• name e address são especificados como índices de texto, portanto, são pesquisáveis apenas com pesquisa por palavra-chave.

• description é especificado como um índice vetorial, portanto, é qualificado para pesquisa vetorial (semântica) usando incorporações vetoriais gerenciadas e o modelo 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 );

Crie um Cortex Search Service de vários índices com incorporações vetoriais personalizadas chamado custom_vector_search_service. Esse serviço pesquisa uma tabela com uma coluna de texto (document_contents) e uma coluna de incorporação vetorial fornecida pelo usuário (document_embedding) separada, que contém incorporações correspondentes à coluna de texto.

-- 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;

Crie um serviço managed_vector_search_service com incorporações vetoriais gerenciadas pelo usuário e incorporações de consulta gerenciada:

-- 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;