Ai Functions

View as Markdown

Transform and enrich data with AI on Databricks.

Classify text into labelsPOST /api/2.0/ai-functions/ai-classifyExtract structured data from textPOST /api/2.0/ai-functions/ai-extractParse documents into structured contentPOST /api/2.0/ai-functions/ai-parse-document

Classify text into labels GA

POST /api/2.0/ai-functions/ai-classify

Classifies content according to a set of provided labels.

API scopes: ai-functions

Request body

contentobjectRequired

The content to classify. It accepts a plain string or the response object of ai_parse_document.

labelsobjectRequired

The label set to classify as. Either a JSON array of label strings (e.g. ["spam", "not_spam"]), or a JSON object mapping each label to a description (e.g. {"spam": "unsolicited bulk message", "not_spam": "a legitimate message"}). Accepts 2 to 500 labels, each 1 to 100 characters.

optionsobject

Function options. Omitted fields fall back to their documented defaults.

Show child attributesHide child attributes

instructionsstring

Natural-language guidance that steers how the text is classified (up to 20,000 characters).

versionstring

The function version to invoke. Defaults to the latest version. Supported versions: ["2.1"].

multilabelboolean

When true, allows more than one label to be returned per input.

enable_confidence_scoresboolean

When true, includes a per-label confidence score in the response.

enable_rationalesboolean

When true, includes a rationale explaining each classification in the response.

Response

responseobject

The function result as a JSON value. An array of per-label objects: one element in single-label mode (the default), or multiple elements when multilabel is true. When enable_confidence_scores and enable_rationales are true, confidence_score and rationale are included in each response value, respectively.

metadataobject

Additional metadata returned by AI Classify.

Show child attributesHide child attributes

versionstring

The resolved function version.

View as Markdown

Request

{
  "content": {},
  "labels": {},
  "options": {
    "instructions": "string",
    "version": "string",
    "multilabel": true,
    "enable_confidence_scores": true,
    "enable_rationales": true
  }
}

Response

{
  "response": {},
  "metadata": {
    "version": "string"
  }
}

Extract structured data from text GA

POST /api/2.0/ai-functions/ai-extract

Extracts structured data from text and documents according to a provided schema.

API scopes: ai-functions

Request body

contentobjectRequired

The text to extract from. It accepts a plain string or the response object of ai_parse_document.

schemaobjectRequired

The extraction schema defining the fields to extract. Either a JSON array of field names, assumed to be strings (e.g. ["company", "valuation"]), or a JSON object mapping each field to its type/description/nullability (e.g. {"company": {"type": "string", "description": "the company name"}}). Accepts up to 256 fields, 12 levels of nesting, and 500 enum values. Supported field types are string, integer, number, boolean, and enum.

optionsobject

Function options. Omitted fields fall back to their documented defaults.

Show child attributesHide child attributes

instructionsstring

Natural-language guidance that steers how data is extracted (up to 20,000 characters).

versionstring

The function version to invoke. Defaults to the latest version. Supported versions: ["2.1"].

modestring

Extraction mode. Supported modes: "precision" — more powerful extraction for complex schemas, long documents, and reasoning-heavy extractions. Defaults to none (standard extraction).

enable_citationsboolean

When true, includes citation metadata locating each extracted value in the source. Depending on the type of input, citations can be one of two types:

For raw text (STRING) inputs, a citation is a span of text in the original input. Each object in metadata.citations has an id (integer matching a citation_ids entry on a field), a start (inclusive 0-based character offset into the input string), and a stop (exclusive 0-based character offset into the input string).

For PDF documents and images (when using ai_extract downstream of ai_parse_document), a citation is a bounding box in the original input. Each object in metadata.citations has an id (integer matching a citation_ids entry on a field) and a bbox (array of {coord, page_id} objects, identical in shape to element.bbox in ai_parse_document output; coord is pixel coordinates on the page image as [x0, y0, x1, y1], and page_id is a 0-based page index).

enable_confidence_scoresboolean

When true, includes a per-field confidence score in the response.

Response

responseobject

The function result as a JSON value. When enable_confidence_scores and enable_citations are true, confidence and citation_ids are included in each response field, respectively.

metadataobject

Additional metadata returned by AI Extract.

Show child attributesHide child attributes

versionstring

The resolved function version.

modestring

The resolved extraction mode; present when a non-default mode was used.

chunk_typestring

How the source was chunked for citation offsets (span for text input, bbox for parsed-document input); present when citations are enabled.

citationsarray of object

Citation objects locating each result in the source; present when citations are enabled.

Show child attributesHide child attributes

idint64

Integer matching a citation_ids entry on an extracted field.

startint64

Inclusive 0-based character offset into the input string; set for span citations.

stopint64

Exclusive 0-based character offset into the input string; set for span citations.

bboxarray of object

Bounding boxes locating the citation on the source pages; set for bbox citations.

Show child attributesHide child attributes

coordarray of int64

Pixel coordinates on the page image as [x0, y0, x1, y1].

page_idint64

0-based page index the box is on.

View as Markdown

Request

{
  "content": {},
  "schema": {},
  "options": {
    "instructions": "string",
    "version": "string",
    "mode": "string",
    "enable_citations": true,
    "enable_confidence_scores": true
  }
}

Response

{
  "response": {},
  "metadata": {
    "version": "string",
    "mode": "string",
    "chunk_type": "string",
    "citations": [
      {}
    ]
  }
}

Parse documents into structured content GA

POST /api/2.0/ai-functions/ai-parse-document

Parse structured content from unstructured documents.

API scopes: ai-functions

Request body

contentstringRequired

The document to parse, given as a Unity Catalog volume path to the source file (the REST API accepts only a UC volume path, not inline binary data). Supported formats: PDF, DOCX, DOC, PPTX, PPT, JPG, JPEG, PNG, TIFF. Accepts up to 100 pages and 100 MB per document.

optionsobject

Function options. Omitted fields fall back to their documented defaults.

Show child attributesHide child attributes

versionstring

The ai_parse_document output schema version. Supported value: "2.0".

description_element_typesstring

Element types for which an AI-generated description is produced. Use "" (default) to generate descriptions for all supported element types, "figure" to generate them for figures only, or "" (empty string) to generate none. Only figure descriptions are supported for version "2.0", so "" and "figure" produce the same behavior.

image_output_pathstring

Unity Catalog volume path where rendered page and element images are written.

page_rangestring

Pages to parse (1-indexed), as a comma-separated list of page numbers or ranges (e.g. "1,3,5-10").

Response

documentobject

The parsed document as a JSON value, containing the extracted pages and elements.

error_statusarray of object

Per-page partial-failure details; present when the request succeeds (2xx) but individual pages fail.

Show child attributesHide child attributes

error_messagestring

Message describing why the page failed.

page_idint64

0-based index of the page that failed.

metadataobject

Additional metadata returned by AI Parse Document.

Show child attributesHide child attributes

idstring

Unique identifier for the parse request.

versionstring

The resolved function version.

file_metadataobject

Describes the source file; present only for file-path input.

Show child attributesHide child attributes

file_pathstring

Unity Catalog volume path of the source file.

file_namestring

Base name of the source file.

file_sizeint64

Size of the source file in bytes.

file_modification_timestring

Last-modified timestamp of the source file, as an HTTP date string.

View as Markdown

Request

{
  "content": "string",
  "options": {
    "version": "string",
    "description_element_types": "string",
    "image_output_path": "string",
    "page_range": "string"
  }
}

Response

{
  "document": {},
  "error_status": [
    {
      "error_message": "string",
      "page_id": 0
    }
  ],
  "metadata": {
    "id": "string",
    "version": "string",
    "file_metadata": {}
  }
}