ai_decide() is a Databricks SQL function that evaluates one or more questions against text or structured data and returns a probability, a choice from named criteria, or a score on an ordered scale. Databricks describes it as a way to route support tickets, assess whether an event needs attention, or prioritize work using a rubric you define. Every question in a call runs against the same input, which the documentation calls state, and the answers come back as a VARIANT you can read in the rest of the query. The documentation, last updated on 29 September 2026, says "This feature is in Beta."
The shape of the output is the point. Instead of prose you parse later, you get labelled answers with probabilities attached, so a WHERE clause or a CASE expression can act on them directly.
Syntax #
ai_decide(state, questions [, options])state is a VARIANT or STRING expression holding the content, context and examples needed to answer the questions, and it can vary by row. A STRING is read as plain text unless it is a JSON object or array, in which case it is interpreted as structured data. A VARIANT produced by another AI function, such as ai_parse_document or ai_extract, is also accepted.
questions is a constant STRING containing a nonempty JSON object. Each key is a question ID and each value is a question definition, and the same definitions apply to every row. A definition needs type and instructions, plus criteria where the type requires it. The three types are noul, which estimates the likelihood a question is true and returns a number from 0 to 1; choice, which picks one label from 1 to 255 named criteria; and score, which rates the state against an ordered array of 2 to 10 descriptions and returns the probability-weighted average of their indices.
options is an optional constant MAP<STRING, STRING>. The one supported option is version, whose value is '1.0', which is also the default.
A worked example #
SELECT ai_decide(
'{"name": "TrailShell jacket", "description": "Lightweight waterproof hiking jacket made from recycled polyester. Packs into its own pocket."}',
'{
"category": {
"type": "choice",
"instructions": "Which product category best fits this item?",
"criteria": {
"outerwear": "Jackets, coats, and other protective outer layers",
"footwear": "Shoes, boots, and sandals",
"accessories": "Bags, hats, and other accessories"
}
},
"recycled_materials": {
"type": "noul",
"instructions": "Does the listing state that the product uses recycled materials?"
}
}',
map('version', '1.0')
) AS decision;The documentation's example response returns outerwear for the choice question with probabilities of 0.95, 0.01 and 0.04 across the three labels and a confidence of 0.95, and a probability of 0.98 for the recycled materials question. The full return is a VARIANT with response, metadata and error_message; on success metadata.version names the function version and error_message is null, and on failure response is null and error_message describes what went wrong. Databricks notes that generated answers can vary between calls.
Limits and availability #
The documentation, last updated on 29 September 2026, lists these requirements. Databricks Runtime 15.4 LTS or above is required, with 18.2 or above recommended for the best performance and access to the latest features. The function isn't available on Databricks SQL Classic, and it runs only in some regions. Workspaces carrying the Security and Compliance add-on have a separate regional support list of their own. Being in Beta, the function has to be enabled through the workspace preview settings. Pricing is on the Databricks SQL pricing page. The model behind it is served through Model Serving Foundation Model APIs under the Apache 2.0 licence, and Databricks says it might change the model if one performs better on its internal benchmarks.
On data handling, Databricks says document data is processed inside its security perimeter and that it doesn't store the parameters passed into AI function calls, though it retains run metadata such as the runtime version.
When to use it #
Reach for ai_decide when the decision has a fixed shape and the output feeds another query: triage, routing, a rubric score that sorts a queue. The probabilities are the reason to prefer it over a free-text call, because you can set a threshold and send only the uncertain rows to something slower or to a human. Our reading of what it displaces sits in Foundation Models and the AI Gateway and in the margin note ai_decide is the cheap model you put in front of the expensive one. The Beta stage is a reason to pin behaviour with tests, and no reason at all to wait.
Questions people ask #
What does ai_decide return in Databricks? #
It returns a VARIANT with the fields response, metadata and error_message. Inside response is an answers object with one entry per question ID, each carrying a type of noul, choice or score along with the probability, chosen label or score.
Is ai_decide generally available? #
No. Databricks' documentation, last updated on 29 September 2026, says the feature is in Beta, and it has to be enabled through the workspace preview settings.
What are the three question types in ai_decide? #
noul estimates the likelihood a question is true as a number from 0 to 1. choice selects one label from a set of named criteria and returns probabilities for every label. score rates the input against an ordered list of 2 to 10 descriptions and returns the probability-weighted average of their indices.