CertSafari
    Snowflake SnowPro Specialty: Gen AI (GES-C02)· Lessons

    Domain 4 · Lesson 12/15

    AI_PARSE_DOCUMENT: OCR vs LAYOUT mode, page_split and page_filter

    Use document parsing functions.

    11 min read
    3.75% of exam
    2 sources
    Published 21 Oct 2026
    Docs as of 4 Oct 2026

    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.

    The full signature: a file, then optional options, then an optional error-details flagsql
    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.

    Which mode to pick, by what the downstream step needs
    NeedModeWhat 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 stepsLAYOUTMarkdown-formatted text
    Embedded images for multimodal workLAYOUT with 'extract_images': TRUEMarkdown 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;

    Checkpoint 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?

    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?

    Sources12

    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.

    LAYOUT mode with page_split: each page of the research paper becomes its own element in the pages arraysql
    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.

    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?

    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?

    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?

    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.

    Sources12

    Sources

    (2)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 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
      “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 file size of 104857600 bytes exceeded.”
      ↩︎ Working within the page limit with page_filter, and reading errors
    2. 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
      “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

    Continue to part 2 of 2

    AI_EXTRACT: responseFormat, scores and writing extraction questions

    Spotted a mistake, or was something unclear? Tell us.