ai_decide function

Applies to: Databricks SQL Databricks Runtime

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

The ai_decide() function evaluates one or more questions against text or structured data. For each question, it returns either a probability, a choice from named criteria, or a score on an ordered scale. Use it to route support tickets, assess whether an event needs attention, or prioritize work using a rubric you define.

All questions in a call use the same input, called state. You can combine different question types in one call and use the returned answers in downstream SQL queries.

Data security

Your document data is processed within the Databricks security perimeter. Databricks does not store the parameters that are passed into the AI function calls, but does retain metadata run details, such as the Databricks Runtime version used.

Requirements

Apache 2.0 license

The underlying models that might be used at this time are licensed under the Apache 2.0 License, Copyright © The Apache Software Foundation. Customers are responsible for ensuring compliance with applicable model licenses.

Databricks recommends reviewing these licenses to ensure compliance with any applicable terms. If models emerge in the future that perform better according to Databricks's internal benchmarks, Databricks might change the model (and the list of applicable licenses provided on this page).

The model powering this function is made available using Model Serving Foundation Model APIs. See Applicable model terms for information about which models are available on Databricks and the licenses and policies that govern the use of those models.

If models emerge that perform better according to Databricks's internal benchmarks, Databricks might change the models and update the documentation.

• This function is only available in some regions, see AI function availability.
• For workspaces with the Enhanced Security and Compliance add-on,
  • See regional support for ai_decide for the appropriate compliance standard.
  • See Manage Databricks previews for how to enable it on your workspace.
• This function is not available on Databricks SQL Classic.
• Databricks Runtime 15.4 LTS or above is required. Databricks Runtime 18.2 or above is recommended for the best performance and access to the latest features.
• Check the Databricks SQL pricing page.

Syntax

SQL

ai_decide(state, questions [, options])

Arguments

• state: A VARIANT or STRING expression containing the content, context, and examples needed to answer the questions. The value can vary by row. Accepts either:

  • A STRING containing plain text or a JSON-encoded object or array. JSON objects and arrays are interpreted as structured data. Other strings are treated as text.
  • A VARIANT produced by another AI function (such as ai_parse_document or ai_extract)

• questions: A constant STRING expression containing a nonempty JSON object. Each key is a nonempty question ID, and each value is a question definition. The same definitions apply to every row. See Question definitions.

• options: An optional constant MAP<STRING, STRING> expression. The supported option is version, with the value '1.0'. Version 1.0 is the default. To specify it explicitly, use map('version', '1.0').

Question definitions

Each question definition requires type and instructions, plus criteria when required by the question type. Required fields cannot be null. Other fields are not supported.

• type: One of noul, choice, or score.
• instructions: Instructions for evaluating the state, expressed as a string, JSON object, or JSON array.
• criteria: The descriptions that define how to answer. The required shape depends on type.

Noul questions

Use noul to estimate the likelihood that a question is true. The result is a number from 0 to 1.

The optional criteria object can contain true and false keys to describe those outcomes. Each description can be a string, JSON object, or JSON array. Omit criteria when you do not need these descriptions. If supplied, criteria must be an object and cannot be null.

JSON

{
  "needs_escalation": {
    "type": "noul",
    "instructions": "Does this ticket need immediate escalation?",
    "criteria": {
      "true": "An active service outage blocks the customer from working.",
      "false": "The customer can continue working or has a workaround."
    }
  }
}

Choice questions

Use choice to select one label from a set of named criteria.

The required criteria object maps 1 to 255 nonempty labels to descriptions. Each description can be a string, JSON object, JSON array, or null. Use null when the label alone describes the choice.

JSON

{
  "team": {
    "type": "choice",
    "instructions": "Which team should handle this ticket?",
    "criteria": {
      "shipping": "Delivery or shipment issues",
      "billing": "Payment or invoice issues",
      "technical_support": "Product technical problems"
    }
  }
}

Score questions

Use score to evaluate the state against an ordered scale.

The required criteria array contains 2 to 10 descriptions, ordered from lowest to highest. Each description can be a string, JSON object, or JSON array. The first criterion has index 0, the next has index 1, and so on.

The result is the probability-weighted average of these indices. It can be fractional and ranges from 0 to the number of criteria minus one. For example, probabilities of 0.1, 0.3, and 0.6 across three criteria produce a score of 1.5.

JSON

{
  "urgency": {
    "type": "score",
    "instructions": "How urgent is this ticket?",
    "criteria": [
      "Routine request with no time pressure",
      "Time-sensitive issue with a workaround",
      "Critical issue that blocks the customer"
    ]
  }
}

Returns

Returns a VARIANT with the fields response, metadata, and error_message. The response field contains an answers object with one entry per question. Question IDs exactly match those provided in the questions parameter. Each answer includes a type field that matches the question type: noul, choice, or score. The following examples show the response field for each question type:

• Noul questions: A probability from 0 to 1 estimating the likelihood that the question is true.

  JSON

  {
    "answers": {
      "needs_escalation": {
        "type": "noul",
        "probability": 0.1
      }
    }
  }

• Choice questions: A choice containing the label with the highest probability and a probabilities object mapping every label to its probability. confidence is a number from 0 to 1 indicating how well the state supports the assessment. The probabilities values sum to 1. Label names exactly match those provided in criteria.

  JSON

  {
    "answers": {
      "team": {
        "type": "choice",
        "choice": "shipping",
        "probabilities": {
          "shipping": 0.8,
          "billing": 0.1,
          "technical_support": 0.1
        },
        "confidence": 0.9
      }
    }
  }

• Score questions: A score containing the probability-weighted average of the criterion indices, a legend mapping string indices (such as "0") to the original criterion descriptions, and a probabilities object mapping those indices to probabilities. confidence is a number from 0 to 1 indicating how well the state supports the assessment. The probabilities values sum to 1.

  JSON

  {
    "answers": {
      "urgency": {
        "type": "score",
        "score": 1.5,
        "legend": {
          "0": "Routine request with no time pressure",
          "1": "Time-sensitive issue with a workaround",
          "2": "Critical issue that blocks the customer"
        },
        "probabilities": {
          "0": 0.1,
          "1": 0.3,
          "2": 0.6
        },
        "confidence": 0.8
      }
    }
  }

On success, metadata.version identifies the function version used and error_message is null.

On failure, response is null and error_message describes the failure. Invalid argument types or nonconstant question definitions can also cause query errors.

Examples

The following example shows how to evaluate several questions in one call. Generated answers can vary between calls.

Evaluate multiple question types

This example evaluates a product listing for its category, use of recycled materials, and suitability for hiking in rainy weather:

SQL

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?"
    },
    "hiking_suitability": {
      "type": "score",
      "instructions": "How suitable is this product for hiking in rainy weather?",
      "criteria": [
        "Not suitable for outdoor use in rain",
        "Offers some protection from rain",
        "Designed for hiking with waterproof protection"
      ]
    }
  }',
  map('version', '1.0')
) AS decision;

Example response:

JSON

{
  "response": {
    "answers": {
      "category": {
        "type": "choice",
        "choice": "outerwear",
        "probabilities": { "outerwear": 0.95, "footwear": 0.01, "accessories": 0.04 },
        "confidence": 0.95
      },
      "recycled_materials": { "type": "noul", "probability": 0.98 },
      "hiking_suitability": {
        "type": "score",
        "score": 1.8,
        "legend": {
          "0": "Not suitable for outdoor use in rain",
          "1": "Offers some protection from rain",
          "2": "Designed for hiking with waterproof protection"
        },
        "probabilities": { "0": 0.05, "1": 0.1, "2": 0.85 },
        "confidence": 0.9
      }
    }
  },
  "metadata": { "version": "1.0" },
  "error_message": null
}

Related functions

• ai_classify function
• ai_extract function
• ai_query function
• Transform unstructured data using AI Functions