Funções de IA

Funções de IA são funções integradas do ClickHouse que você pode usar para chamar IA ou gerar embeddings para trabalhar com seus dados, extrair informações, classificar dados etc…

As funções de IA são experimentais. Defina allow_experimental_ai_functions para ativá-las.As funções de IA podem retornar saídas imprevisíveis. O resultado dependerá muito da qualidade do prompt e do modelo usado.

Injeção de promptO texto de entrada é enviado ao modelo e pode direcionar sua saída (injeção de prompt). Textos de fontes externas, não verificadas ou não sanitizadas podem conter instruções que fazem o modelo retornar conteúdo controlado por um invasor, ignorar o formato solicitado ou emitir payloads maliciosos. Trate a saída da função de IA como não confiável: valide-a ou sanitize-a antes de usá-la em etapas posteriores, como na criação de SQL, em comandos de shell, consultas adicionais ou decisões de controle de acesso.

Todas as funções compartilham uma infraestrutura comum que fornece:

Aplicação de cotas: Limites por consulta para tokens (ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query) e chamadas de API (ai_function_max_api_calls_per_query).
Retentativas com backoff: Falhas transitórias são repetidas (ai_function_max_retries) com backoff exponencial (ai_function_retry_initial_delay_ms).

Configuração

As funções de IA usam uma coleção nomeada que armazena as credenciais do provedor e a configuração. É possível criar e usar diferentes coleções nomeadas para funções distintas ou chamadas de função específicas. Por exemplo, talvez você queira definir uma coleção nomeada diferente para usar com as funções de texto (aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact) em vez das funções de embedding (aiEmbed, aiSimilarity), que requerem endpoints diferentes e geralmente usam modelos diferentes. Exemplo de instrução para criar uma coleção nomeada com credenciais do provedor: uma com endpoint de chat e outra com endpoint de embedding:

CREATE NAMED COLLECTION ai_text_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/chat/completions',
    model = 'gpt-4o-mini',
    api_key = 'sk-...';

-- The embedding functions (`aiEmbed`, `aiSimilarity`) do not read `model` from the named collection,
-- pass it as a positional argument instead. Defining `model` in an embedding collection is an error,
-- not silently ignored.
CREATE NAMED COLLECTION ai_embedding_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/embeddings',
    api_key = 'sk-...';

Parâmetros da coleção nomeada

Parâmetro	Tipo	Padrão	Descrição
`provider`	String	—	Provedor do modelo. Compatível com: `'openai'`, `'anthropic'`. Veja a observação abaixo.
`endpoint`	String	—	URL do endpoint da API.
`model`	String	—	Nome do modelo (por exemplo, `'gpt-4o-mini'`). Usado pelas funções de texto; as funções de embedding (`aiEmbed`, `aiSimilarity`) requerem `model` como argumento posicional e geram um erro se `model` for especificado na coleção nomeada.
`api_key`	String	—	Chave de autenticação do provedor. Opcional: quando omitida, o header de autenticação não é enviado, o que permite apontar para servidores compatíveis com OpenAI que não exigem autenticação.
`max_tokens`	UInt64	`1024`	Número máximo de tokens de saída por chamada à API.
`api_version`	String	—	String de versão da API. Usada pelo Anthropic (`'2023-06-01'`).

Qualquer API compatível com OpenAI (por exemplo, vLLM, Ollama, LiteLLM) pode ser usada definindo provider = 'openai' e apontando o endpoint para o seu serviço.

Selecionando credenciais

Uma função determina a coleção nomeada a ser usada na seguinte ordem:

a chave credentials do seu mapa de parâmetros, quando presente;
caso contrário, a configuração padrão de credenciais aplicável:
- ai_function_text_default_credentials para as funções de texto (aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact);
- ai_function_embedding_default_credentials para as funções de embedding (aiEmbed, aiSimilarity).

Se nenhum dos dois estiver definido, a chamada falhará. As funções de texto e de embedding usam configurações padrão separadas porque um endpoint de conclusões de chat é diferente de um usado para embeddings.

SET ai_function_text_default_credentials = 'ai_text_credentials';

-- Uses ai_text_credentials from the setting:
SELECT aiGenerate('What is 2 + 2? Reply with just the number.');

-- Overrides the default for this call:
SELECT aiGenerate('Bonjour', map('credentials', 'other_credentials'));

Filtre linhas com uma condição em linguagem natural usando aiFilter, que retorna UInt8 e pode ser usada diretamente em WHERE:

SELECT * FROM reviews
WHERE aiFilter(body, 'the customer is angry about shipping');

Mapa de parâmetros

Cada função aceita, ao final, um Map(String, String) opcional de parâmetros. Todos os valores são strings (coloque os números entre aspas, por exemplo, '0.2'). Chaves desconhecidas são rejeitadas. Uma chave presente substitui o valor correspondente da coleção nomeada; uma chave ausente recorre à coleção nomeada (para model/max_tokens) ou ao padrão interno. A exceção são as funções de embedding (aiEmbed, aiSimilarity), que recebem model como um argumento posicional obrigatório (por exemplo, aiEmbed(text, model[, params]), aiSimilarity(text1, text2, model[, params])) e geram erro se ele for definido no mapa de parâmetros ou na coleção nomeada. Isso serve para garantir embeddings reproduzíveis. Os parâmetros a seguir são comuns a todas as funções de IA:

Key	Description
`credentials`	Coleção nomeada a ser usada (veja acima).
`model`	Substitui o `model` da coleção (somente funções de texto; as funções de embedding (`aiEmbed`, `aiSimilarity`) recebem `model` como um argumento posicional obrigatório, não como uma chave do mapa).

Funções individuais aceitam parâmetros adicionais específicos de cada função (como max_tokens, temperature, system_prompt, instructions e dimensions). Consulte a referência de cada função abaixo para ver quais parâmetros ela aceita e seus valores padrão.

SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles;

Configurações no nível da consulta

Todas as configurações relacionadas à IA estão listadas em Settings com o prefixo ai_function_.

Restringindo hosts de endpoint

A URL de endpoint em uma coleção nomeada de IA é um destino de saída ao qual o servidor se conecta com sua própria identidade, potencialmente enviando (se especificada) a api_key da coleção nomeada no cabeçalho da requisição. Por padrão, o ClickHouse permite qualquer host. Para restringir as funções a um conjunto específico de provedores, configure remote_url_allow_hosts na configuração do servidor, por exemplo:

<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>

Observe que essa configuração vale para todo o servidor e se aplica a todas as funcionalidades que usam HTTP.

Segurança de transporte (HTTP vs HTTPS)

O transporte é determinado exclusivamente pelo esquema da URL do endpoint. Não há criptografia do payload da requisição no nível da aplicação; a proteção dos dados em trânsito depende inteiramente do esquema:

https:// — a conexão usa TLS. O corpo da requisição (texto de entrada, prompts) e a api_key no cabeçalho da requisição são criptografados em trânsito, e o certificado do provedor é validado. Use isto para qualquer provedor remoto.
http:// — a conexão não é criptografada. O corpo da requisição e a api_key são enviados em texto claro. Use isto somente com um provedor confiável em uma rede privada (por exemplo, uma instância local de vLLM ou Ollama).

Por padrão, as funções de IA rejeitam um endpoint que enviaria dados em texto claro para um host remoto: qualquer endpoint que não seja HTTPS e cujo host não seja de loopback gera uma exceção. Hosts de loopback (localhost, 127.0.0.0/8, ::1) estão isentos, portanto um servidor de modelo local em http://localhost funciona imediatamente. Para permitir um endpoint http:// em texto claro em um host remoto, defina ai_function_allow_insecure_endpoint como 1. Essa verificação é independente de remote_url_allow_hosts: essa configuração é uma lista de permissões de hosts e não inspeciona o esquema da URL, portanto um endpoint http:// direcionado a um host permitido ainda passa por ela. Observe que, em ambos os casos, o provedor recebe os dados de entrada em texto claro após a terminação de TLS; o TLS protege os dados apenas no caminho de rede entre o servidor e o provedor.

Provedores compatíveis

Provedor	valor de `provider`	Funções de chat	Observações
OpenAI	`'openai'`	Sim	Provedor padrão.
Anthropic	`'anthropic'`	Sim	Usa o endpoint `/v1/messages`.

Observabilidade

A atividade da função de IA é rastreada pelos ProfileEvents do ClickHouse:

ProfileEvent	Description
`AIAPICalls`	Número de solicitações HTTP feitas ao provedor de IA.
`AIInputTokens`	Total de tokens de entrada consumidos.
`AIOutputTokens`	Total de tokens de saída consumidos.
`AIRowsProcessed`	Número de linhas que receberam um resultado.
`AIRowsSkipped`	Número de linhas ignoradas (cota excedida ou erro com `ai_function_throw_on_error = 0`).

Consulte estes eventos:

SELECT
    ProfileEvents['AIAPICalls'] AS api_calls,
    ProfileEvents['AIInputTokens'] AS input_tokens,
    ProfileEvents['AIOutputTokens'] AS output_tokens
FROM system.query_log
WHERE query_id = 'query_id'
AND type = 'QueryFinish'
ORDER BY event_time DESC;

aiClassify

Introduzido em: v26.4.0 Classifica o texto fornecido em uma das categorias informadas usando um provedor de LLM. As credenciais (uma coleção nomeada que especifica o provedor, o modelo, o endpoint e, opcionalmente, uma chave de API) são obtidas da chave credentials do mapa de parâmetros opcional, ou da configuração ai_function_text_default_credentials quando o mapa a omite. Sintaxe

aiClassify(text, categories[, params])

Aliases: AIClassify Argumentos

text — Texto a ser classificado. String
categories — Lista constante de rótulos de categorias possíveis. Array(String)
params — Map(String, String) constante opcional de parâmetros. Chaves específicas da função: temperature (temperatura de amostragem que controla a aleatoriedade; padrão 0.0), max_tokens (número máximo de tokens de saída por chamada; padrão 1024). Os parâmetros comuns credentials e model também se aplicam (consulte Funções de IA). Map(String, String)

Valor retornado Um dos rótulos de categoria fornecidos ou o valor padrão do tipo da coluna (string vazia), caso a requisição falhe e ai_function_throw_on_error esteja desabilitado. String Exemplos Classificar o sentimento

Query

SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral'])

Response

positive

Classificar uma coluna com credenciais explícitas

Query

SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5

aiEmbed

Introduzido em: v26.6.0 Gera um vetor de embedding para o texto fornecido usando o provedor de IA configurado. A função envia o texto para o endpoint de embedding configurado e retorna o vetor resultante como Array(Float32). Dentro de um único bloco de linhas, as entradas são agrupadas em lotes de até ai_function_embedding_max_batch_size entradas por requisição HTTP para reduzir a sobrecarga por chamada. As credenciais (uma coleção nomeada que especifica o provedor, o endpoint e, opcionalmente, uma chave de API) são obtidas da chave credentials no mapa de parâmetros ou da configuração ai_function_embedding_default_credentials quando o mapa a omite. Observe que aiEmbed usa uma configuração de credenciais padrão separada das funções de texto, já que um endpoint de embeddings é diferente de um endpoint de chat. O model é um argumento posicional obrigatório (um String constante). Diferentemente das funções de texto, aiEmbed não lê model da coleção nomeada nem do mapa de parâmetros. Uma coleção nomeada que define model é rejeitada. O parâmetro opcional dimensions, quando compatível com o modelo (por exemplo, text-embedding-3-* da OpenAI), solicita um vetor do tamanho especificado; caso contrário, o tamanho nativo do modelo é retornado. Sintaxe

aiEmbed(text, model[, params])

Aliases: AIEmbed Argumentos

text — Texto para gerar o embedding. String
model — Nome do modelo de embedding. const String
params — Map(String, String) constante opcional de parâmetros. Chave específica da função: dimensions (dimensionalidade de destino do vetor de saída; 0 ou omitido significa o tamanho nativo do modelo). O parâmetro comum credentials também se aplica (consulte Funções de IA). Map(String, String)

Valor retornado O vetor de embedding, ou um array vazio se a entrada for NULL ou vazia, se a solicitação falhar e ai_function_throw_on_error estiver desabilitado, ou se uma cota for excedida com ai_function_throw_on_quota_exceeded desabilitado. Array(Float32) Exemplos Gerar o embedding de uma única string (credentials pode ser omitido se a configuração ai_function_embedding_default_credentials estiver definida)

Query

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

Com dimensões explícitas

Query

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256'))

Gere embeddings para uma coluna de textos

Query

SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10

aiExtract

Introduzido em: v26.4.0 Extrai informações estruturadas de texto não estruturado usando um provedor de LLM. O terceiro argumento pode ser uma instrução em linguagem natural de forma livre (por exemplo, 'a principal reclamação') ou um esquema codificado em JSON no formato '{"field_a": "description of field a", "field_b": "description of field b"}'. No modo de instrução, a função retorna o valor extraído como uma string simples, ou uma string vazia se nada for encontrado. No modo de esquema, a função retorna uma string contendo um objeto JSON cujas chaves correspondem ao esquema solicitado; os campos ausentes são null. As credenciais (uma coleção nomeada que especifica o provedor, o modelo, o endpoint e, opcionalmente, uma chave de API) são obtidas da chave credentials do mapa de parâmetros opcional ou da configuração ai_function_text_default_credentials quando o mapa a omite. Sintaxe

aiExtract(text, instruction_or_schema[, params])

Aliases: AIExtract Argumentos

text — Texto do qual extrair informações. String
instruction_or_schema — Instrução de extração em formato livre ou um objeto JSON constante que descreve os campos a serem extraídos. const String
params — Map(String, String) constante opcional de parâmetros. Chaves específicas da função: temperature (temperatura de amostragem que controla a aleatoriedade; padrão 0.0), max_tokens (número máximo de tokens de saída por chamada; padrão 1024). Os parâmetros comuns credentials e model também se aplicam (consulte AI Functions). Map(String, String)

Valor retornado Um único valor extraído (modo de instrução) ou uma string contendo um objeto JSON (modo de esquema). Retorna o valor padrão para o tipo da coluna (string vazia) se a requisição falhar e ai_function_throw_on_error estiver desativado. String Exemplos Instrução em formato livre

Query

SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint')

Response

late and damaged package

Extração de esquema

Query

SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

aiFilter

Introduzido em: v26.8.0 Avalia uma condição em linguagem natural em relação ao texto fornecido usando um provedor de LLM e retorna um valor booleano (UInt8) adequado para WHERE, PREWHERE e JOIN ... ON. A função solicita que o modelo responda apenas com true ou false em letras minúsculas. Solicitações com falha (quando ai_function_throw_on_error está desabilitado) e respostas não reconhecidas são mapeadas para 0, portanto a linha é filtrada. Aviso: Não confie nos resultados de aiFilter sem analisá-los cuidadosamente. Predicados baseados em LLM podem estar incorretos ou ser inconsistentes; use-os apenas quando falsos positivos e falsos negativos forem aceitáveis. As credenciais (uma coleção nomeada que especifica o provedor, o modelo, o endpoint e, opcionalmente, uma chave de API) são obtidas da chave credentials do mapa de parâmetros opcional ou da configuração ai_function_text_default_credentials quando o mapa não a inclui. Observação: usar aiFilter em JOIN ... ON avalia a LLM uma vez para cada par candidato e pode ser caro. Sintaxe

aiFilter(text, condition[, params])

Aliases: AIFilter Argumentos

text — Texto a ser avaliado. String
condition — Condição constante em linguagem natural que o texto deve atender. String
params — Map(String, String) constante e opcional de parâmetros. Chaves específicas da função: temperature (temperatura de amostragem que controla a aleatoriedade; padrão 0.0), max_tokens (máximo de tokens de saída por chamada; padrão 1024). Os parâmetros comuns credentials e model também se aplicam (consulte Funções de IA). Map(String, String)

Valor retornado 1 se o texto atender à condição; caso contrário, 0. Retorna o valor padrão (0) se a solicitação falhar e ai_function_throw_on_error estiver desabilitado. UInt8 Exemplos Filtrar avaliações irritadas

Query

SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping')

Filtre uma coluna usando credenciais explícitas

Query

SELECT body, aiFilter(body, 'describes a bug', map('credentials', 'ai_text_credentials')) AS is_bug FROM issues LIMIT 5

aiGenerate

Introduzido em: v26.4.0 Gera texto livre a partir de um prompt usando um provedor de LLM. A função envia o prompt ao provedor de IA configurado e retorna o texto gerado. As credenciais (uma coleção nomeada que especifica o provedor, o modelo, o endpoint e, opcionalmente, uma chave de API) são obtidas da chave credentials do mapa de parâmetros opcional ou da configuração ai_function_text_default_credentials quando o mapa a omite. O mapa de parâmetros opcional também pode definir system_prompt (uma instrução que orienta o comportamento do modelo, por exemplo, tom, formato e papel), temperature, max_tokens e model. Se system_prompt não for definido, o valor padrão é: You are a helpful assistant. Provide a clear and concise response. Sintaxe

aiGenerate(prompt[, params])

Aliases: AIGenerate Argumentos

prompt — O prompt ou a pergunta do usuário a ser enviada ao modelo. String
params — Map(String, String) constante opcional de parâmetros. Chaves específicas da função: temperature (temperatura de amostragem que controla a aleatoriedade; padrão 0.7), max_tokens (máximo de tokens de saída por chamada; padrão 1024), system_prompt (instrução constante em nível de sistema que orienta o comportamento do modelo; por padrão, um prompt genérico de assistente). Os parâmetros comuns credentials e model também se aplicam (consulte funções de IA). Map(String, String)

Valor retornado A resposta de texto gerada, ou o valor padrão do tipo de coluna (string vazia) se a solicitação falhar e ai_function_throw_on_error estiver desabilitado. String Exemplos Pergunta simples

Query

SELECT aiGenerate('What is 2 + 2? Reply with just the number.')

Response

Com credenciais explícitas e prompt de sistema

Query

SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.'))

Resumir valores da coluna

Query

SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

aiRedact

Introduzido em: v26.8.0 Detecta e oculta informações de identificação pessoal (PII) no texto fornecido usando um provedor de LLM.

aiRedact detecta e oculta PII de acordo com as melhores práticas possíveis usando um LLM, mas sua saída não é confiável. A detecção e remoção de PII dependem do modelo escolhido, do prompt e da entrada: o modelo pode deixar de identificar dados, ocultá-los apenas parcialmente ou alterar o texto ao redor. Funciona melhor com texto em inglês bem escrito; os resultados podem ser piores em outros idiomas ou em textos com muitos erros de ortografia, pontuação ou gramática. aiRedact não garante que sua saída esteja livre de PII e não deve ser considerado, por si só, um mecanismo de anonimização seguro ou suficiente. Sempre revise a saída para garantir que ela esteja em conformidade com as políticas de privacidade de dados e compliance da sua organização antes de expor dados a partes não confiáveis.

Cada span de PII detectado é substituído por um token de ocultação ([REDACTED] por padrão, configurável pelo parâmetro replacement). O array categories restringe quais tipos de PII são ocultados; um array vazio recorre a um conjunto padrão de categorias comuns (nome, e-mail, número de telefone, endereço, cartão de crédito, endereço IP). aiRedact instrui o modelo a alterar apenas os spans de PII detectados, mas a preservação do texto ao redor é feita conforme as melhores práticas possíveis, e o modelo ainda pode alterá-lo (consulte o aviso acima). Caracteres de controle diferentes de tabulação, quebra de linha e retorno de carro também são normalizados para espaços antes da solicitação; portanto, a saída não é idêntica em bytes a entradas que os contêm. Como aiRedact retorna todo o texto de entrada com PII substituída, a saída tem aproximadamente o mesmo tamanho da entrada. Defina max_tokens (padrão 1024) como um valor maior que o comprimento da entrada em tokens; uma resposta truncada por um limite muito baixo ficará incompleta. Sintaxe

aiRedact(text, categories[, params])

Aliases: AIRedact Argumentos

text — Texto a ser ocultado. String
categories — Lista constante de categorias de PII a serem ocultadas (por exemplo, ['name', 'ssn', 'credit_card']). Um array vazio usa um conjunto padrão de categorias comuns (nome, e-mail, número de telefone, endereço, cartão de crédito, endereço IP). Array(String)
params — Map(String, String) constante opcional de parâmetros. Chaves específicas da função: temperature (temperatura de amostragem que controla a aleatoriedade; padrão 0.0), max_tokens (número máximo de tokens de saída por chamada; padrão 1024 — como aiRedact retorna o texto completo, defina-o como maior que o comprimento da entrada em tokens; caso contrário, a resposta poderá ser truncada e incompleta), replacement (token que substitui cada span de PII detectado; padrão [REDACTED]). Os parâmetros comuns credentials e model também se aplicam (consulte Funções de IA). Map(String, String)

Valor retornado O texto com as PII detectadas substituídas pelo token de ocultação ou o valor padrão do tipo da coluna (string vazia), caso a solicitação falhe e ai_function_throw_on_error esteja desabilitado. String Exemplos Ocultar categorias específicas

Query

SELECT aiRedact('Purchase was done by customer John Doe with email test@test.org', ['email', 'credit_card', 'name'])

Response

Purchase was done by customer [REDACTED] with email [REDACTED]

Oculte as categorias de PII predefinidas com um token personalizado

Query

SELECT aiRedact(body, [], map('replacement', '***')) FROM tickets LIMIT 5

aiSimilarity

Introduzido em: v26.8.0 Calcula a similaridade semântica entre dois textos usando o provedor de embeddings configurado. Calcula os embeddings vetoriais de ambos os textos e retorna a similaridade de cosseno. Uma pontuação de -1 é atribuída a vetores de embedding opostos; semanticamente, isso significa que textos com pontuações próximas de -1 têm significados opostos. Uma pontuação de 0 significa que os vetores são ortogonais: semanticamente não relacionados. Por fim, uma pontuação de 1 significa que os vetores de embedding apontam na mesma direção; textos com pontuações próximas de 1 têm significados semelhantes. É o complemento de cosineDistance para os mesmos embeddings (aiSimilarity = 1 - cosineDistance(embedding1, embedding2)). O processamento em lotes, as credenciais e o parâmetro dimensions são iguais aos de aiEmbed, incluindo a configuração de credenciais padrão ai_function_embedding_default_credentials. Assim como em aiEmbed, model é um argumento posicional obrigatório (uma String constante) e não é lido da coleção nomeada nem do mapa de parâmetros. Sintaxe

aiSimilarity(text1, text2, model[, params])

Aliases: AISimilarity Argumentos

text1 — Primeiro texto. String
text2 — Segundo texto. String
model — Nome do modelo de embedding. const String
params — Map(String, String) constante opcional de parâmetros. Chave específica da função: dimensions (dimensionalidade de destino dos embeddings; 0 ou a omissão do parâmetro indica o tamanho nativo do modelo). O parâmetro comum credentials também se aplica (consulte Funções de IA). Map(String, String)

Valor retornado A similaridade de cosseno em [-1, 1] ou NULL se um dos textos for NULL ou estiver vazio, se uma solicitação de embedding falhar e ai_function_throw_on_error estiver desabilitado ou se uma cota for excedida com ai_function_throw_on_quota_exceeded desabilitado. Nullable(Float32) Exemplos Compare duas strings (credentials pode ser omitido se a configuração ai_function_embedding_default_credentials estiver definida)

Query

SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

Classifique as avaliações por similaridade com uma consulta

Query

SELECT review FROM product_reviews ORDER BY aiSimilarity(review, 'It works well under rain', 'text-embedding-3-small') DESC LIMIT 100

Deduplicação semântica com uma autorjunção

Query

SELECT a.id, b.id FROM docs a, docs b WHERE a.id < b.id AND aiSimilarity(a.title, b.title, 'text-embedding-3-small') > 0.9

aiTranslate

Disponível desde: v26.4.0 Traduz o texto fornecido para o idioma de destino especificado usando um provedor de LLM. Instruções adicionais de estilo ou dialeto podem ser passadas pela chave instructions do mapa de parâmetros (por exemplo, 'mantenha os termos técnicos sem tradução'). As credenciais (uma coleção nomeada que especifica o provedor, o modelo, o endpoint e, opcionalmente, uma chave de API) são obtidas da chave credentials do mapa de parâmetros opcional, ou da configuração ai_function_text_default_credentials quando o mapa não a inclui. Sintaxe

aiTranslate(text, target_language[, params])

Aliases: AITranslate Argumentos

text — Texto a ser traduzido. String
target_language — Nome do idioma de destino ou código BCP-47 (por exemplo, 'French', 'es-MX'). String
params — Map(String, String) constante opcional de parâmetros. Chaves específicas da função: temperature (temperatura de amostragem que controla a aleatoriedade; padrão 0.3), max_tokens (número máximo de tokens de saída por chamada; padrão 1024), instructions (instruções adicionais de estilo ou dialeto para o tradutor). Os parâmetros comuns credentials e model também se aplicam (consulte Funções de IA). Map(String, String)

Valor retornado O texto traduzido, ou o valor padrão do tipo da coluna (string vazia) se a requisição falhar e ai_function_throw_on_error estiver desabilitado. String Exemplos Traduzir para o francês

Query

SELECT aiTranslate('Hello, world!', 'French')

Response

Bonjour le monde!

Traduza para o japonês seguindo as instruções de estilo

Query

SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5

Referência SQL

Tipos de dados

Motores

Funções

Formatos

Interfaces

Configurações

Tabelas do sistema

Lagos de dados

Configuração

Parâmetros da coleção nomeada

Selecionando credenciais

Mapa de parâmetros

Configurações no nível da consulta

Restringindo hosts de endpoint

Segurança de transporte (HTTP vs HTTPS)

Provedores compatíveis

Observabilidade

aiClassify

aiEmbed

aiExtract

aiFilter

aiGenerate

aiRedact

aiSimilarity

aiTranslate

​Configuração

​Parâmetros da coleção nomeada

​Selecionando credenciais

​Mapa de parâmetros

​Configurações no nível da consulta

​Restringindo hosts de endpoint

​Segurança de transporte (HTTP vs HTTPS)

​Provedores compatíveis

​Observabilidade

​aiClassify

​aiEmbed

​aiExtract

​aiFilter

​aiGenerate

​aiRedact

​aiSimilarity

​aiTranslate

Configuração

Parâmetros da coleção nomeada

Selecionando credenciais

Mapa de parâmetros

Configurações no nível da consulta

Restringindo hosts de endpoint

Segurança de transporte (HTTP vs HTTPS)

Provedores compatíveis

Observabilidade

aiClassify

aiEmbed

aiExtract

aiFilter

aiGenerate

aiRedact

aiSimilarity

aiTranslate