What you will be able to do
- Choose OCR or LAYOUT mode for a given document workload
- Predict the JSON shape AI_PARSE_DOCUMENT returns with and without page_split
- Use page_filter and page_split to stay within the page limit and parse only the pages you need
- Read AI_PARSE_DOCUMENT failures through NULL returns or return_error_details
Key concept
Parsing mode and page splitting — Two options decide what AI_PARSE_DOCUMENT gives back. The mode sets how much structure is kept: plain text in OCR, Markdown with tables and headings in LAYOUT. page_split sets the shape: one content string for the whole file, or a pages array with one entry per page.
1.Calling AI_PARSE_DOCUMENT in OCR or LAYOUT mode
AI_PARSE_DOCUMENT turns a staged file into text you can query. It is the step that sits in front of most Snowflake document pipelines. It takes a FILE object, usually built with TO_FILE from a stage path. It also takes an optional OBJECT of options and an optional error-details flag, and it returns a JSON-formatted string. It replaces the older SNOWFLAKE.CORTEX.PARSE_DOCUMENT, so new work should call AI_PARSE_DOCUMENT to get the current features.
AI_PARSE_DOCUMENT( <file_object> [, <options> ] [, <return_error_details> ] )OCR mode extracts text only, and it is what you get if you set no mode. It is the recommended choice for fast, high-quality text extraction from scanned or text-heavy documents such as contracts, insurance claims and manuals. A stack of scanned claim forms that are mostly paragraphs needs nothing more. Asking for layout there only adds structure that nobody downstream will read.
LAYOUT mode extracts the layout as well as the text, including tables, headers and how elements relate to each other. It returns the content as Markdown, so a table in a 10-K filing comes back as a Markdown table instead of a run of numbers. Snowflake calls LAYOUT the preferred choice for most use cases, and especially for complex documents. It is also the only mode that can return embedded images: 'extract_images': TRUE requires LAYOUT and costs nothing extra.
| Need | Mode | What comes back |
|---|---|---|
| Quick text from scanned or text-heavy files (contracts, claims, manuals) | OCR (the default) | Plain text |
| Tables, headings and reading order kept for later steps | LAYOUT | Markdown-formatted text |
| Embedded images for multimodal work | LAYOUT with 'extract_images': TRUE | Markdown plus an images array of base64 data and bounding boxes |
Checkpoint 1 of 7· Fill the gap
This query parses a 10-K filing, and its tables must come back as Markdown tables rather than as a run of numbers. Which value completes the mode setting?
SELECT AI_PARSE_DOCUMENT (
TO_FILE('@docs.doc_stage','10K-example.pdf'),
{'mode': ' ? ', 'page_split': true}) AS sec_10k_example;Only LAYOUT keeps tables, headers and how elements relate, and it returns the content as Markdown. OCR is the default and returns plain text only. MARKDOWN and TABLE are not modes, and page_split only changes the output shape. It does not keep table structure.
Source: docs.snowflake.comCheckpoint 2 of 7· Exam question
A claims processing team receives scanned insurance claim PDFs that are dense with body text and have almost no tables. They need AI_PARSE_DOCUMENT to extract the text quickly and cost-effectively for downstream analysis. Which configuration best fits this requirement?
Correct answer: A — Call AI_PARSE_DOCUMENT with mode set to OCR, since it is built for fast, high-quality text extraction from scanned, text-heavy documents like claims
- A. OCR mode is recommended for fast, high-quality text extraction from scanned or text-heavy documents such as insurance claims, which matches this workload exactly.
- B. LAYOUT mode is optimized for preserving structural content like tables and headings, which is unnecessary overhead when the claim documents are mostly dense body text.
- C. Extracting embedded images is not the stated need, and the function's default mode is OCR rather than LAYOUT, so this description misstates the baseline behavior.
- D. The legacy PARSE_DOCUMENT function is being superseded by AI_PARSE_DOCUMENT and is not documented as offering better throughput; it is treated as the older form of the current function.
Checkpoint 3 of 7· Exam question
A finance analyst uploads a multi-page quarterly report PDF that contains several data tables and needs the parsed output to preserve table structure and section headings for downstream processing. Which AI_PARSE_DOCUMENT configuration best satisfies this requirement?
Correct answer: A — Set mode to LAYOUT, so the response markdown preserves tables and structural headings alongside the extracted text
- A. LAYOUT mode extracts layout as well as text, including structural content such as tables, which is exactly what preserving table and heading structure requires.
- B. OCR mode extracts text only and does not preserve layout, so it cannot reconstruct table borders or column alignment as this option claims.
- C. Splitting a document into individual pages changes how output is chunked but does not add structural table or heading preservation, which only LAYOUT mode provides.
- D. Extract_images pulls embedded picture content and requires LAYOUT mode to function, but it does not convert tabular text into structured output on its own.
2.What page_split does to the output
page_split changes the shape of the response, not its content. When it is FALSE or missing, which is the default, the result is a single object. Its content field holds the text of the whole document as one string: plain text in OCR mode, Markdown in LAYOUT mode. A 19-page research paper parsed this way comes back as one long string, with no marker for where one page ends and the next begins.
With 'page_split': TRUE, the result has a pages array instead. Each element has its own content and an index. The index counts from 0 by position in the file and ignores any page numbers printed on the pages. A one-page document still gets a pages array, holding one object, so code that reads pages does not need a special case for short files.
SELECT AI_PARSE_DOCUMENT (
TO_FILE('@docs.doc_stage','research-paper-example.pdf'),
{'mode': 'LAYOUT' , 'page_split': true}) AS research_paper_example;Splitting has two limits. It works only on PDF, PowerPoint (.pptx) and Word (.docx) files. Other formats return an error, so passing a PNG or a TXT file with page_split set fails instead of falling back. Splitting is also how you handle a long document that would otherwise go over the function's token limit, because each page is processed separately.
Neither shape contains document metadata such as pageCount. The output is a JSON string, so wrap it in PARSE_JSON before you reach into pages or content from SQL.
Re-run the parse with 'page_split': TRUE, or with a page_filter covering that page, and read pages[11]. Without splitting there is one content string, and nothing in the output shows where page 12 starts.
Checkpoint 4 of 7· Check yourself
A nightly job parses every staged PDF with {'mode': 'OCR', 'page_split': TRUE}. Most files are long, but some are only one page. What does AI_PARSE_DOCUMENT return for a one-page PDF?
With page_split set, the output is always a pages array, even for a one-page file. Each element has content and an index that counts from 0 by position in the file and ignores printed page numbers. Document metadata such as pageCount is not part of this output shape.
“If the document has only one page, the output still contains a "pages" array (which contains a single object).”Source: docs.snowflake.com
Checkpoint 5 of 7· Exam question
When AI_PARSE_DOCUMENT is called on a multi-page document without setting page_split (or with it left FALSE), which structure does the function return?
Correct answer: A — A single object with a content field holding the document's extracted text or markdown as one combined string
- A. Without page_split enabled, AI_PARSE_DOCUMENT returns a single content field containing the whole document's extracted text or markdown as one combined value.
- B. A pages array with per-page content and index fields is the response shape produced when page_split is set to TRUE, not the default behavior.
- C. PageCount only appears inside the metadata object when return_error_details is TRUE, and it is unrelated to whether page_split was configured.
- D. AI_PARSE_DOCUMENT does not return per-paragraph confidence scores in its response; that granularity and field are not part of the documented output.
Sources2
3.Working within the page limit with page_filter, and reading errors
Every document has a page limit. AI_PARSE_DOCUMENT accepts at most 2,000 pages per document, alongside the size and resolution rules covered in Document requirements: formats, file size, page count and resolution. page_filter is the option that keeps a call inside that limit, and it also keeps the bill down. It takes an array of ranges and processes only those pages.
Each range is an object with start and end fields. Pages are numbered from 0, start is included and end is not. So {'start': 0, 'end': 1} means only the first page, and the first ten pages are {'start': 0, 'end': 10}. Setting page_filter turns on page_split automatically, so the result always comes back as a pages array and you do not need to set both. Billing is per page processed, so filtering a 300-page annual report down to the five pages with the income statement means paying for five pages.
Failures do not stop a batch. By default, a file the function cannot process returns NULL, and the other rows of the query still finish. Pass TRUE as the third argument, return_error_details, and each row returns an OBJECT with top-level value, error and metadata fields. value holds the parsed document, or NULL if it failed. error holds the message, or NULL if it succeeded. metadata carries details such as the page count. That is also the only way to get pageCount back.
The messages say what went wrong. A file over the page limit returns Maximum number of 2000 pages exceeded. followed by its actual page count. A file over 100 MB returns Maximum file size of 104857600 bytes exceeded., and a format the function cannot read gets a message that the provided file format is not supported. Tracking these down across a whole stage is covered in Diagnosing document-function errors (error fields, GET_PRESIGNED_URL).
Checkpoint 6 of 7· Check yourself
Your team only needs the 21st through 25th pages of a long PDF, counted by position in the file. Which page_filter processes exactly those five pages?
Page indexes start at 0, so the 21st page is index 20. start is inclusive and end is exclusive, so end 25 stops after index 24, which is the 25th page. The other options assume 1-based numbering, an inclusive end, or both.
“specify the first (inclusive) and last (exclusive) page in the range. Page indexes start at 0.”Source: docs.snowflake.com
Checkpoint 7 of 7· Match them up
Match each part of an AI_PARSE_DOCUMENT result to what it holds. Assume TRUE was passed as the third argument unless the item says otherwise.
Tap a term, then the definition that fits it.
Passing return_error_details as TRUE wraps each result in an OBJECT with value, error and metadata at the top level. It is the only way to get pageCount back. Without the flag, a failed file returns NULL and the batch keeps running.
“The function then returns an OBJECT with top-level value, error, and metadata fields; metadata contains fields such as pageCount.”Source: docs.snowflake.com
Sources
(2)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“OCR mode is recommended for fast, high-quality text extraction from scanned or text-heavy documents such as contracts, insurance claims, and manuals.”
↩︎ Calling AI_PARSE_DOCUMENT in OCR or LAYOUT mode“LAYOUT mode is the preferred choice for most use cases, especially for complex documents.”
↩︎ Calling AI_PARSE_DOCUMENT in OCR or LAYOUT mode“There is no additional cost for using this parameter.”
↩︎ Calling AI_PARSE_DOCUMENT in OCR or LAYOUT mode“Maximum pages per document | 2,000”
↩︎ Working within the page limit with page_filter, and reading errors“Billing for AI_PARSE_DOCUMENT is based on the number of pages processed; a single image file is considered a page.”
↩︎ Working within the page limit with page_filter, and reading errors“Maximum number of 2000 pages exceeded.”
↩︎ Working within the page limit with page_filter, and reading errors“Maximum file size of 104857600 bytes exceeded.”
↩︎ Working within the page limit with page_filter, and reading errors - 2.
“The function extracts layout as well as text, including structural content such as tables.”
↩︎ Calling AI_PARSE_DOCUMENT in OCR or LAYOUT mode“AI_PARSE_DOCUMENT is the updated version of PARSE_DOCUMENT. For the latest functionality, use AI_PARSE_DOCUMENT.”
↩︎ Calling AI_PARSE_DOCUMENT in OCR or LAYOUT mode“The page index in the file, starting at 0. Page numbers and formats specified in the document are ignored.”
↩︎ What page_split does to the output“This feature supports only PDF, PowerPoint (.pptx), and Word (.docx) documents. Documents in other formats return an error.”
↩︎ What page_split does to the output“To process long documents that exceed the token limit of AI_PARSE_DOCUMENT, set this option to TRUE.”
↩︎ What page_split does to the output“To use the output in SQL, convert it to an OBJECT value using the PARSE_JSON function.”
↩︎ What page_split does to the output“Specifying page_filter implies page_split.”
↩︎ Working within the page limit with page_filter, and reading errors“rows with errors return NULL”
↩︎ Working within the page limit with page_filter, and reading errors“metadata: An OBJECT containing document metadata such as page count.”
↩︎ Working within the page limit with page_filter, and reading errors“Plain text (in OCR mode) or Markdown-formatted text (in LAYOUT mode).”
↩︎ Key concept“If set to TRUE, the function extracts images embedded in the document. Requires LAYOUT mode.”
↩︎ Exam trap 1“Document metadata such as pageCount is not included in the output structures above.”
↩︎ Exam trap 2“Each range is an object with start and end fields that specify the first (inclusive) and last (exclusive) page in the range.”
↩︎ Exam trap 3“The function extracts text only. This is the default mode.”
↩︎ Prediction“If the document has only one page, the output still contains a "pages" array (which contains a single object).”
↩︎ Checkpoint“specify the first (inclusive) and last (exclusive) page in the range. Page indexes start at 0.”
↩︎ Checkpoint“The function then returns an OBJECT with top-level value, error, and metadata fields; metadata contains fields such as pageCount.”
↩︎ Checkpoint