Loading the documentation…

AI in SQL

AI in SQL lets a SQL query ask Kartlos about each row: classify a review, pull a field out of free text, translate, filter rows by a plain-language condition or redact personal data. It works through six ClickHouse functions, listed below. Every call uses Kartlos Standard and is billed to your company's standard bucket.

Turn AI in SQL on for your company

AI in SQL is off until an administrator turns it on.

Go to Admin > System Configuration > AI in SQL.
Switch AI in SQL on.
Click Confirm in the Turn on AI in SQL dialog.

While the setting is off, every query that calls an AI function is refused. See Scheduler, health, maps and connector safety.

Give people the permission

A person can call the functions only when the setting is on and their role holds Use AI in SQL (in the Data Layer category, group AI in SQL; the standard permission AI in SQL User covers it). Data Layer Administrator does not include it, so grant it on purpose. See Roles and permissions.

Which functions you can call

Function	Use it to
`aiGenerate`	Write free text from a prompt
`aiClassify`	Pick one of the labels you list
`aiExtract`	Pull the information you describe out of free text
`aiTranslate`	Translate text into another language
`aiFilter`	Keep the rows where a plain-language condition holds, in `WHERE`
`aiRedact`	Remove personal data from text

aiEmbed and aiSimilarity are not available.

sql

SELECT
    body,
    aiClassify(body, ['positive', 'negative', 'neutral']) AS sentiment
FROM reviews
LIMIT 100

Where they run

The Editor: queries run under your own account, so they work only when you hold the permission. While the setting is off the query fails with AI in SQL is turned off; without the permission it fails with AI in SQL needs the "Use AI in SQL" permission.
Minds, DataMind Oda and the MCP query tools: a Mind's query may call them when the person who asked holds the permission.
Warehouse transformations: create, check and save a transformation that calls them, and its runs write the AI results into the table. A scheduled run needs the person who started the run, or who last saved the transformation, to be an active user who holds the permission.

They never run inside a view, a materialized view, a dictionary, a function or a column expression: those would ask the model again on every read, insert or refresh. Write the results into a table with a Warehouse transformation instead.

Limits

A query makes at most 1,000 calls to the model by default, one per row. Raise it in the query with SETTINGS ai_function_max_api_calls_per_query = 5000, from 1 to 20,000. The Editor refuses a value outside that range; Minds, DataMind Oda and Warehouse transformations treat 0 or a higher value as 20,000. A Warehouse transformation run allows 20,000 calls; set the value in the transformation's query settings to lower it.
A query may also send and receive up to 5,000 tokens per allowed call in each direction: 5,000,000 for the default 1,000 calls, 100,000,000 at most. One answer is at most 8,192 tokens.
An answer comes back as plain text, without Markdown, unless your prompt asks for a format.
ai_function_max_api_calls_per_query is the only ai_function_* setting a query may change. The functions always use the company's datamind_ai credentials.
max_threads may be set from 1 to 16 in a query that calls an AI function.
DataMind Oda does not export a query that calls an AI function, because the export would ask the model again for every row. Write the results into a table with a Warehouse transformation and export that table.
The Editor returns the first page of an AI query only. It does not count the rows first, and it does not run the query again for the next page, a chart aggregation or a download, because each would ask the model again for the same rows. Narrow the query with WHERE or LIMIT, or keep the results in a table.

Questions, answered

Why does my query say AI in SQL is turned off?

An administrator has not turned it on. Ask them to switch AI in SQL on in Admin > System Configuration > AI in SQL.

Why does my query ask for the "Use AI in SQL" permission?

Your role does not hold it. Ask an administrator to add Use AI in SQL to your role.

How many rows can one query send to the model?

1,000 by default, because the functions make one call per row. Add SETTINGS ai_function_max_api_calls_per_query = <n> to raise it, up to 20,000. When the call or token limit is reached, the query stops with an error.

Why can't I open page 2 of an AI query in the Editor?

The next page would run the query again and ask the model again for the same rows. Narrow the query, or write the results into a table with a Warehouse transformation and query that table.

Can I create a view that calls aiClassify?

No. A view, materialized view, dictionary, function or column expression would call the model on every read, insert or refresh. Store the results with a Warehouse transformation, then build the view on that table.

Which model answers, and who pays?

Kartlos Standard answers every call. The usage is billed to your company's standard bucket.

Can a Mind use AI functions on its own?

A Mind's query may call them when the setting is on and the person who asked the Mind holds the permission. If not, the Mind is told the call is refused and answers without it.

Can I pick another model in the call?

No. Only Kartlos Standard serves AI in SQL; a call that names another model is refused.