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
In a nutshell
  • AI_EXTRACT answers questions or fills a schema; it returns error and response.
  • Limits: 100 MB file, 125 pages (1,000 with cross region inference), 100 entity or 10 table questions per call.
  • AI_PARSE_DOCUMENT modes: 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.

Staged filePDF, image, DOCXTO_FILEFILE valuefields wantedAI_EXTRACTJSON responseor full textAI_PARSE_DOCUMENTOCR or LAYOUT

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 type of object. Sub objects can be lists (type: array) or tables. string is 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

ItemLimit
File sizeUnder 100 MB
Pages per documentUp to 125 without cross region inference; up to 1,000 with it
Questions per callUp to 100 entity questions, or 10 table questions
Table question weightOne table question counts as 10 entity questions
Output per entity question512 tokens
Output for table answersUp 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.

OptionMeaning
mode'OCR' (default, text only), 'LAYOUT' (text plus layout, tables as Markdown), or 'AGENTIC' (also interprets charts and diagrams; preview)
extract_imagesTRUE extracts embedded images; needs LAYOUT mode and is not supported in AGENTIC mode
page_splitTRUE returns each page separately; default FALSE
page_filterArray 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.

Exam tip

For a long document that exceeds the token limit, turn on page_split so each page is handled separately.

Watch out

Do not use page_filter together with FL_FILTER_PAGES. Choose one way to select pages.

Choosing

ScenarioFunction
Pull invoice number and total into columnsAI_EXTRACT
Extract a line item tableAI_EXTRACT with a table schema
Feed contract text to a chunker and search serviceAI_PARSE_DOCUMENT in LAYOUT mode
Keep headings and tables as MarkdownAI_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_EXTRACT answers questions or fills a schema; it returns error and response.
  • Limits: 100 MB file, 125 pages (1,000 with cross region inference), 100 entity or 10 table questions per call.
  • AI_PARSE_DOCUMENT modes: OCR (default), LAYOUT, AGENTIC.
  • page_split returns a pages array and works for PDF, PPTX and DOCX.
  • AI_PARSE_DOCUMENT is billed per page; AI_EXTRACT by tokens.
  • Both take FILE values created with TO_FILE.

Check yourself

  • Which function returns text with tables as Markdown?

    AI_PARSE_DOCUMENT with mode set to 'LAYOUT'.

  • How many table questions fit in one AI_EXTRACT call?

    Ten, since a table question counts as ten entity questions out of 100.

  • What does scores => TRUE add to an AI_EXTRACT result?

    A scoring object 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.