AI

aiClassify

Classifies the given text into one of the provided categories using an LLM provider.

The function sends the text together with a fixed classification prompt and a JSON-schema response format constraining the model to return exactly one of the supplied labels. When the response is returned as a JSON object of the form {"category": "..."}, the label is unwrapped and the label string is returned.

Credentials (a named collection specifying the provider, model, endpoint, and optionally an API key) are taken from the credentials key of the optional parameter map, or from the ai_function_text_default_credentials setting when the map omits it.

Syntax

aiClassify(text, categories[, params])

Arguments

• text — Text to classify. String
• categories — Constant list of candidate category labels. Array(String)
• params — Optional constant Map(String, String) of parameters. Function-specific keys: temperature (sampling temperature controlling randomness; default 0.0), max_tokens (maximum output tokens per call; default 1024). The common parameters credentials and model also apply (see AI Functions). Map(String, String)

Returned value

One of the provided category labels, or the default value for the column type (empty string) if the request failed and ai_function_throw_on_error is disabled. String

Examples

Classify sentiment

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

positive

Classify a column with explicit credentials

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

Introduced in version 26.4.0.

aiEmbed

Generates an embedding vector for the given text using the configured AI provider.

The function sends the text to the configured embedding endpoint and returns the resulting vector as Array(Float32). Within a single block of rows, inputs are grouped into batches of up to ai_function_embedding_max_batch_size entries per HTTP request to reduce per-call overhead.

Credentials (a named collection specifying the provider, endpoint, and optionally an API key) are taken from the credentials key of the parameter map, or from the ai_function_embedding_default_credentials setting when the map omits it. Note that aiEmbed uses a separate default-credentials setting from the text functions, since an embeddings endpoint differs from a chat one.

The model is a required positional argument (a constant String). Unlike the text functions, aiEmbed does not read model from the named collection or the parameter map. A named collection that defines model is rejected.

The optional dimensions parameter, when supported by the model (e.g. OpenAI's text-embedding-3-*), requests a vector of the given size; otherwise the model's native size is returned.

Syntax

aiEmbed(text, model[, params])

Arguments

• text — Text to embed. String
• model — Embedding model name. const String
• params — Optional constant Map(String, String) of parameters. Function-specific key: dimensions (target dimensionality of the output vector; 0 or omitted means the model's native size). The common parameter credentials also applies (see AI Functions). Map(String, String)

Returned value

The embedding vector, or an empty array if the input is NULL or empty, the request failed and ai_function_throw_on_error is disabled, or a quota was exceeded with ai_function_throw_on_quota_exceeded disabled. Array(Float32)

Examples

Embed a single string (credentials can be omitted if the ai_function_embedding_default_credentials setting is set)

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

With explicit dimensions

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

Embed a column of texts

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

Introduced in version 26.6.0.

aiExtract

Extracts structured information from unstructured text using an LLM provider.

The third argument may be either a free-form natural-language instruction (e.g. 'the main complaint') or a JSON-encoded schema of the form '{"field_a": "description of field a", "field_b": "description of field b"}'.

In instruction mode, the function returns the extracted value as a plain string, or an empty string if nothing was found. In schema mode, the function returns a JSON object string whose keys match the requested schema; missing fields are null.

Credentials (a named collection specifying the provider, model, endpoint, and optionally an API key) are taken from the credentials key of the optional parameter map, or from the ai_function_text_default_credentials setting when the map omits it.

Syntax

aiExtract(text, instruction_or_schema[, params])

Arguments

• text — Text to extract information from. String
• instruction_or_schema — Free-form extraction instruction, or a constant JSON object describing the fields to extract. const String
• params — Optional constant Map(String, String) of parameters. Function-specific keys: temperature (sampling temperature controlling randomness; default 0.0), max_tokens (maximum output tokens per call; default 1024). The common parameters credentials and model also apply (see AI Functions). Map(String, String)

Returned value

A single extracted value (instruction mode) or a JSON object string (schema mode). Returns the default value for the column type (empty string) if the request failed and ai_function_throw_on_error is disabled. String

Examples

Free-form instruction

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

late and damaged package

Schema extraction

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

Introduced in version 26.4.0.

aiGenerate

Generates free-form text content from a prompt using an LLM provider.

The function sends the prompt to the configured AI provider and returns the generated text.

Credentials (a named collection specifying the provider, model, endpoint, and optionally an API key) are taken from the credentials key of the optional parameter map, or from the ai_function_text_default_credentials setting when the map omits it.

The optional parameter map may also set system_prompt (an instruction that guides the model's behavior, e.g. tone, format, role), temperature, max_tokens, and model. If system_prompt is not set, the default is: You are a helpful assistant. Provide a clear and concise response.

Syntax

aiGenerate(prompt[, params])

Arguments

• prompt — The user prompt or question to send to the model. String
• params — Optional constant Map(String, String) of parameters. Function-specific keys: temperature (sampling temperature controlling randomness; default 0.7), max_tokens (maximum output tokens per call; default 1024), system_prompt (constant system-level instruction guiding the model's behavior; default a generic assistant prompt). The common parameters credentials and model also apply (see AI Functions). Map(String, String)

Returned value

The generated text response, or the default value for the column type (empty string) if the request failed and ai_function_throw_on_error is disabled. String

Examples

Simple question

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

4

With explicit credentials and system prompt

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

Summarize column values

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

Introduced in version 26.4.0.

aiTranslate

Translates the given text into the specified target language using an LLM provider.

Additional style or dialect instructions may be passed via the instructions key of the parameter map (e.g. 'keep technical terms untranslated').

Credentials (a named collection specifying the provider, model, endpoint, and optionally an API key) are taken from the credentials key of the optional parameter map, or from the ai_function_text_default_credentials setting when the map omits it.

Syntax

aiTranslate(text, target_language[, params])

Arguments

• text — Text to translate. String
• target_language — Target language name or BCP-47 code (e.g. 'French', 'es-MX'). String
• params — Optional constant Map(String, String) of parameters. Function-specific keys: temperature (sampling temperature controlling randomness; default 0.3), max_tokens (maximum output tokens per call; default 1024), instructions (additional style or dialect instructions for the translator). The common parameters credentials and model also apply (see AI Functions). Map(String, String)

Returned value

The translated text, or the default value for the column type (empty string) if the request failed and ai_function_throw_on_error is disabled. String

Examples

Translate to French

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

Bonjour le monde!

Translate to Japanese with style instructions

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

Introduced in version 26.4.0.