> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Documentação sobre Funções de IA # 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`](/pt-BR/reference/settings/session-settings/allow-experimental#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 prompt** O 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`](/pt-BR/reference/settings/session-settings/ai-function#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/pt-BR/reference/settings/session-settings/ai-function#ai_function_max_output_tokens_per_query)) e chamadas de API ([`ai_function_max_api_calls_per_query`](/pt-BR/reference/settings/session-settings/ai-function#ai_function_max_api_calls_per_query)). * **Retentativas com backoff**: Falhas transitórias são repetidas ([`ai_function_max_retries`](/pt-BR/reference/settings/session-settings/ai-function#ai_function_max_retries)) com backoff exponencial ([`ai_function_retry_initial_delay_ms`](/pt-BR/reference/settings/session-settings/ai-function#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: ```sql theme={null} 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: 1. a chave `credentials` do seu mapa de parâmetros, quando presente; 2. caso contrário, a configuração padrão de credenciais aplicável: * [`ai_function_text_default_credentials`](/pt-BR/reference/settings/session-settings/ai-function#ai_function_text_default_credentials) para as funções de texto (`aiGenerate`, `aiClassify`, `aiFilter`, `aiExtract`, `aiTranslate`, `aiRedact`); * [`ai_function_embedding_default_credentials`](/pt-BR/reference/settings/session-settings/ai-function#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. ```sql theme={null} 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`: ```sql theme={null} 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. ```sql theme={null} 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](/pt-BR/reference/settings/session-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`](/pt-BR/reference/settings/server-settings/settings/remote#remote_url_allow_hosts) na configuração do servidor, por exemplo: ```xml theme={null} api.openai.com api.anthropic.com ``` 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`](/pt-BR/reference/settings/session-settings/ai-function#ai_function_allow_insecure_endpoint) como `1`. Essa verificação é independente de [`remote_url_allow_hosts`](/pt-BR/reference/settings/server-settings/settings/remote#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](/pt-BR/reference/system-tables/query_log) 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: ```sql theme={null} 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** ```sql theme={null} aiClassify(text, categories[, params]) ``` **Aliases**: `AIClassify` **Argumentos** * `text` — Texto a ser classificado. [`String`](/pt-BR/reference/data-types/string) * `categories` — Lista constante de rótulos de categorias possíveis. [`Array(String)`](/pt-BR/reference/data-types/array) * `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](/pt-BR/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/pt-BR/reference/data-types/map) **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`](/pt-BR/reference/data-types/string) **Exemplos** **Classificar o sentimento** ```sql title=Query theme={null} SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral']) ``` ```response title=Response theme={null} positive ``` **Classificar uma coluna com credenciais explícitas** ```sql title=Query theme={null} 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`](/pt-BR/reference/settings/session-settings/ai-function#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** ```sql theme={null} aiEmbed(text, model[, params]) ``` **Aliases**: `AIEmbed` **Argumentos** * `text` — Texto para gerar o embedding. [`String`](/pt-BR/reference/data-types/string) * `model` — Nome do modelo de embedding. [`const String`](/pt-BR/reference/data-types/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](/pt-BR/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/pt-BR/reference/data-types/map) **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)`](/pt-BR/reference/data-types/array) **Exemplos** **Gerar o embedding de uma única string (`credentials` pode ser omitido se a configuração `ai_function_embedding_default_credentials` estiver definida)** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **Com dimensões explícitas** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) ``` **Gere embeddings para uma coluna de textos** ```sql title=Query theme={null} 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** ```sql theme={null} aiExtract(text, instruction_or_schema[, params]) ``` **Aliases**: `AIExtract` **Argumentos** * `text` — Texto do qual extrair informações. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/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](/pt-BR/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/pt-BR/reference/data-types/map) **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`](/pt-BR/reference/data-types/string) **Exemplos** **Instrução em formato livre** ```sql title=Query theme={null} SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint') ``` ```response title=Response theme={null} late and damaged package ``` **Extração de esquema** ```sql title=Query theme={null} 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** ```sql theme={null} aiFilter(text, condition[, params]) ``` **Aliases**: `AIFilter` **Argumentos** * `text` — Texto a ser avaliado. [`String`](/pt-BR/reference/data-types/string) * `condition` — Condição constante em linguagem natural que o texto deve atender. [`String`](/pt-BR/reference/data-types/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](/pt-BR/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/pt-BR/reference/data-types/map) **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`](/pt-BR/reference/data-types/int-uint) **Exemplos** **Filtrar avaliações irritadas** ```sql title=Query theme={null} SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping') ``` **Filtre uma coluna usando credenciais explícitas** ```sql title=Query theme={null} 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** ```sql theme={null} aiGenerate(prompt[, params]) ``` **Aliases**: `AIGenerate` **Argumentos** * `prompt` — O prompt ou a pergunta do usuário a ser enviada ao modelo. [`String`](/pt-BR/reference/data-types/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](/pt-BR/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/pt-BR/reference/data-types/map) **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`](/pt-BR/reference/data-types/string) **Exemplos** **Pergunta simples** ```sql title=Query theme={null} SELECT aiGenerate('What is 2 + 2? Reply with just the number.') ``` ```response title=Response theme={null} 4 ``` **Com credenciais explícitas e prompt de sistema** ```sql title=Query theme={null} SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.')) ``` **Resumir valores da coluna** ```sql title=Query theme={null} 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** ```sql theme={null} aiRedact(text, categories[, params]) ``` **Aliases**: `AIRedact` **Argumentos** * `text` — Texto a ser ocultado. [`String`](/pt-BR/reference/data-types/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)`](/pt-BR/reference/data-types/array) * `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](/pt-BR/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/pt-BR/reference/data-types/map) **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`](/pt-BR/reference/data-types/string) **Exemplos** **Ocultar categorias específicas** ```sql title=Query theme={null} SELECT aiRedact('Purchase was done by customer John Doe with email test@test.org', ['email', 'credit_card', 'name']) ``` ```response title=Response theme={null} Purchase was done by customer [REDACTED] with email [REDACTED] ``` **Oculte as categorias de PII predefinidas com um token personalizado** ```sql title=Query theme={null} 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](https://en.wikipedia.org/wiki/Cosine_similarity). 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** ```sql theme={null} aiSimilarity(text1, text2, model[, params]) ``` **Aliases**: `AISimilarity` **Argumentos** * `text1` — Primeiro texto. [`String`](/pt-BR/reference/data-types/string) * `text2` — Segundo texto. [`String`](/pt-BR/reference/data-types/string) * `model` — Nome do modelo de embedding. [`const String`](/pt-BR/reference/data-types/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](/pt-BR/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/pt-BR/reference/data-types/map) **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)`](/pt-BR/reference/data-types/nullable) **Exemplos** **Compare duas strings (`credentials` pode ser omitido se a configuração `ai_function_embedding_default_credentials` estiver definida)** ```sql title=Query theme={null} SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **Classifique as avaliações por similaridade com uma consulta** ```sql title=Query theme={null} 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** ```sql title=Query theme={null} 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** ```sql theme={null} aiTranslate(text, target_language[, params]) ``` **Aliases**: `AITranslate` **Argumentos** * `text` — Texto a ser traduzido. [`String`](/pt-BR/reference/data-types/string) * `target_language` — Nome do idioma de destino ou código BCP-47 (por exemplo, `'French'`, `'es-MX'`). [`String`](/pt-BR/reference/data-types/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](/pt-BR/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/pt-BR/reference/data-types/map) **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`](/pt-BR/reference/data-types/string) **Exemplos** **Traduzir para o francês** ```sql title=Query theme={null} SELECT aiTranslate('Hello, world!', 'French') ``` ```response title=Response theme={null} Bonjour le monde! ``` **Traduza para o japonês seguindo as instruções de estilo** ```sql title=Query theme={null} SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5 ```