Snowflake Gen AI Functions · Topic 5 of 26
AI_EXTRACT and AI_PARSE_DOCUMENT - Pull Data Out of Text and Files
Know when to use AI_EXTRACT for questions and tables and AI_PARSE_DOCUMENT for OCR, LAYOUT and AGENTIC parsing, with arguments, limits and return shapes.
- 5 min
AI_EXTRACTanswers questions or fills a schema; it returnserrorandresponse.- Limits: 100 MB file, 125 pages (1,000 with cross region inference), 100 entity or 10 table questions per call.
AI_PARSE_DOCUMENTmodes:OCR(default),LAYOUT,AGENTIC.
What it is
AI_EXTRACT pulls specific values out of text, images or documents by answering questions you define. AI_PARSE_DOCUMENT converts a document into text, with or without layout, so that something else can read, chunk or search it.
The simple rule: if you know the fields you want, use AI_EXTRACT. If you want the whole document as text first, use AI_PARSE_DOCUMENT. Snowflake describes AI_EXTRACT as the updated version of EXTRACT_ANSWER, and AI_PARSE_DOCUMENT as the updated version of PARSE_DOCUMENT.
How it works
AI_EXTRACT syntax
AI_EXTRACT(<text>, <responseFormat>)
AI_EXTRACT(<file>, <responseFormat>)
AI_EXTRACT(file => <file>, responseFormat => <responseFormat> [, scores => TRUE])
The first argument is either a string or a FILE value from TO_FILE, never both. responseFormat describes what to extract and has several accepted shapes:
- An object mapping a label to a question.
- An array of question strings.
- An array of
[label, question]pairs. - A JSON schema with a top level
typeofobject. Sub objects can be lists (type: array) or tables.stringis the only scalar type, and a JSON schema cannot be mixed with the other formats.
SELECT AI_EXTRACT(
file => TO_FILE('@docs', 'invoice_1042.pdf'),
responseFormat => {
'invoice_no': 'What is the invoice number?',
'total': 'What is the total amount due?'
});
For tables, a table schema uses column_ordering, which is case sensitive and must match the property names. List the columns in the order they appear in the document, and add a description to help the model find the right table.
AI_EXTRACT output
The result is a JSON object with error and response keys. Entity questions return key value pairs, lists return arrays, and tables return an object of column arrays. If you pass scores => TRUE (named syntax only, default FALSE), a scoring object adds a score from 0 to 1 per field, with one aggregate score for each list or table. Scores are supported for fine tuned models.
To read only chosen pages, wrap the file in FL_FILTER_PAGES inside the call. A fine tuned model can be used by adding model => 'db.schema.model_name'.
AI_EXTRACT limits
| Item | Limit |
|---|---|
| File size | Under 100 MB |
| Pages per document | Up to 125 without cross region inference; up to 1,000 with it |
| Questions per call | Up to 100 entity questions, or 10 table questions |
| Table question weight | One table question counts as 10 entity questions |
| Output per entity question | 512 tokens |
| Output for table answers | Up to 4,096 tokens |
Without cross region inference, one failing file fails the whole statement. With it, the failure is reported in that document's error field and the statement continues.
Supported types include PDF, PNG, JPEG, TIFF, BMP, GIF, WEBP, DOC, DOCX, PPT, PPTX, HTML, EML, TXT and MD. Billing counts input and output tokens, the responseFormat counts as input, and each page counts as 970 tokens.
AI_PARSE_DOCUMENT syntax
AI_PARSE_DOCUMENT(<file_object> [, <options>] [, <return_error_details>])
The file object is a staged FILE made with TO_FILE. The options object has these keys.
| Option | Meaning |
|---|---|
mode | 'OCR' (default, text only), 'LAYOUT' (text plus layout, tables as Markdown), or 'AGENTIC' (also interprets charts and diagrams; preview) |
extract_images | TRUE extracts embedded images; needs LAYOUT mode and is not supported in AGENTIC mode |
page_split | TRUE returns each page separately; default FALSE |
page_filter | Array of {start, end} ranges; zero based, end exclusive; implies page_split |
SELECT AI_PARSE_DOCUMENT(
TO_FILE('@docs', 'report.pdf'),
{'mode': 'LAYOUT', 'page_split': TRUE}) AS parsed;
The result is a JSON string, so wrap it in PARSE_JSON to read fields. It always includes metadata.pageCount. With page splitting off you get one content string (plain text for OCR, Markdown for LAYOUT). With it on you get a pages array whose entries hold index, content and dimensions.
Page splitting supports PDF, PPTX and DOCX only. Page filtering needs a paginated document, so plain text files error. AI_PARSE_DOCUMENT is billed per document page and is available natively in select regions and through cross region inference everywhere.
For a long document that exceeds the token limit, turn on page_split so each page is handled separately.
Do not use page_filter together with FL_FILTER_PAGES. Choose one way to select pages.
Choosing
| Scenario | Function |
|---|---|
| Pull invoice number and total into columns | AI_EXTRACT |
| Extract a line item table | AI_EXTRACT with a table schema |
| Feed contract text to a chunker and search service | AI_PARSE_DOCUMENT in LAYOUT mode |
| Keep headings and tables as Markdown | AI_PARSE_DOCUMENT in LAYOUT mode |
Common mistakes
Passing both text and a file to AI_EXTRACT. Only one input is allowed per call.
Asking more than 10 table questions in one call. The limit is 10 table questions or 100 entity questions in total, counting a table as 10.
Expecting layout from the default mode. OCR returns text only; use LAYOUT for tables and structure.
Setting extract_images in OCR mode. It needs LAYOUT.
Reading the parse result as a column. It is a JSON string; use PARSE_JSON.
What to remember for the exam
AI_EXTRACTanswers questions or fills a schema; it returnserrorandresponse.- Limits: 100 MB file, 125 pages (1,000 with cross region inference), 100 entity or 10 table questions per call.
AI_PARSE_DOCUMENTmodes:OCR(default),LAYOUT,AGENTIC.page_splitreturns apagesarray and works for PDF, PPTX and DOCX.AI_PARSE_DOCUMENTis billed per page;AI_EXTRACTby tokens.- Both take
FILEvalues created withTO_FILE.
Check yourself
Which function returns text with tables as Markdown?
AI_PARSE_DOCUMENTwithmodeset to'LAYOUT'.How many table questions fit in one
AI_EXTRACTcall?Ten, since a table question counts as ten entity questions out of 100.
What does
scores => TRUEadd to anAI_EXTRACTresult?A
scoringobject with a 0 to 1 score per field.
Topic 5 of 26 in Snowflake Gen AI Functions
Test yourself on Snowflake Gen AI Functions
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.