Snowflake Document Processing · Topic 3 of 7
AI_EXTRACT - Response Format and Prompt Engineering
Use AI_EXTRACT to pull fields, lists and tables from documents: responseFormat forms, JSON schema, returned object, scores, limits and prompt tips.
- 5 min
- Includes a diagram
- AI_EXTRACT succeeds EXTRACT_ANSWER and returns an object with
errorandresponse. - responseFormat: object map, array of strings, array of pairs, or JSON schema for lists and tables.
- Limits: 100 entity questions, 10 table questions, 100 MB files.
What it is
AI_EXTRACT answers questions about a document or a piece of text and returns the answers as structured JSON. You give it a file (or text) and a responseFormat that says what to find. It replaces the older EXTRACT_ANSWER function and is the Cortex AI function to pick when the goal is fields such as an invoice number, a list of parties or a line item table.
It is different from AI_PARSE_DOCUMENT. Parsing returns all the content. Extraction returns only what you ask for.
How it works
Calling it
SELECT AI_EXTRACT(
file => TO_FILE('@docs.public.invoices', 'inv_0042.pdf'),
responseFormat => {
'invoice_no': 'What is the invoice number?',
'total': 'What is the total amount due?'
}
);
There are text and file versions, in positional and named form. You cannot pass text and file in the same call. The optional scores argument exists only in the named argument form.
Supported inputs
Files must be under 100 MB. Supported formats include PDF, PNG, JPEG and JPG, TIFF and TIF, BMP, GIF, WEBP, DOC and DOCX, PPT and PPTX, EML, HTML and HTM, TXT and MD. To process only some pages of a paged file, pass FL_FILTER_PAGES as the file argument.
The four responseFormat forms

| Form | Example idea | Result keys |
|---|---|---|
| Object map | {'name': 'What is the last name?'} | Your labels |
| Array of strings | ['What is the last name?'] | No labels of your own |
| Array of two element arrays | [['name', 'What is the last name?']] | Your labels |
| JSON schema | {'schema': {...}} | Property names from the schema |
The first three give you entity questions: one answer per question. The JSON schema form is the only way to ask for lists and tables in a typed way.
JSON schema details
- The top level must be an object, placed under the
schemakey. - An entity is a sub-object with
'type': 'string'. String is the only supported scalar type. - A list is a sub-object with
'type': 'array'. - A table is a sub-object with
'type': 'object', acolumn_orderingarray and nestedproperties. Each column is an array typed property whosedescriptionmatches the column name in the document. column_orderingis case sensitive, must match the property names and should follow the document's column order.- You cannot mix a schema with the other forms. All questions go inside the schema and no extra keys are allowed.
What comes back
A JSON object with two keys, error and response. Entities return key and value pairs, lists return arrays, and tables return an object of column arrays. One call can return all three. On success error is NULL.
With scores => TRUE a scoring object is added, with a number from 0 to 1 per entity (higher means more confident). Lists and tables get one aggregate score each. Requesting scores adds no cost, and a typical use is routing low confidence results to human review.
Limits per call
| Item | Limit |
|---|---|
| Entity questions | 100 |
| Table questions | 10, and each counts as 10 entity questions |
| Output per entity question | 512 tokens |
| Output for table extraction | 4,096 tokens |
| Pages, cross-region inference on | 1,000 |
| Pages, cross-region inference off | 125 |
Prompt engineering
AI_EXTRACT is steered by the wording of your questions and labels.
- Ask in natural language. "What is the effective date?" works. A field description such as "City, street, ZIP" also works.
- Keep labels unique. A duplicate feature name returns the error "Duplicate feature name found."
- Describe tables. Put the table's name or header in
descriptionand listcolumn_orderingin document order. - One fact per question. Split compound questions so each answer maps to one field.
- Limit pages. Pass FL_FILTER_PAGES so the model sees only the relevant pages.
- Use scores. Set a threshold and route low scoring values to review instead of trusting every answer.
- Large or dense pages. Without cross-region inference,
scale_factor(1.0 to 4.0, default 1.0) scales pages before extraction and can help with small text.
A table question costs ten entity questions of your 100 entity budget. If you need many tables, split them over several calls.
Common mistakes
Mixing a JSON schema with a plain question list. Everything must sit inside the schema.
Using a type other than string in a schema. String is the only supported scalar type.
Passing both text and file. Choose one input.
Using scores with positional arguments. The scores argument needs the named form.
Reusing a label. Duplicate names fail the request.
Assuming per cell scores for tables. Lists and tables get one aggregate score.
What to remember for the exam
- AI_EXTRACT succeeds EXTRACT_ANSWER and returns an object with
errorandresponse. - responseFormat: object map, array of strings, array of pairs, or JSON schema for lists and tables.
- Limits: 100 entity questions, 10 table questions, 100 MB files.
- Scores run from 0 to 1, cost nothing extra and work with fine-tuned models.
- Good prompts use clear natural language, unique labels, table descriptions and a page filter.
Check yourself
Which responseFormat form lets you extract a table?
The JSON schema form, with an object type sub-object, column_ordering and array typed column properties.
A request fails with "Duplicate feature name found." What is wrong?
Two questions share the same label, so each label must be unique.
How do you send low confidence answers to a reviewer?
Set scores to TRUE (named arguments) and route results whose score falls below your threshold.
Topic 3 of 7 in Snowflake Document Processing
Test yourself on Snowflake Document Processing
The full Snowflake GES-C02 question bank has 585 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by Snowflake. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.