AI_PARSE_DOCUMENT: OCR vs LAYOUT, page_split and page limits

1.The shape of an AI_PARSE_DOCUMENT call

AI_PARSE_DOCUMENT is the Cortex AI function that turns a document into text Snowflake can work with. It reads files on internal or external stages and keeps the reading order and structural elements such as tables and headers. Its output can then feed other Cortex AI functions for extraction, classification or enrichment. The function takes one required argument and two optional ones:

AI_PARSE_DOCUMENT( <file_object> [, <options> ] [, <return_error_details> ] )

The first argument is a FILE object pointing to a document on a Snowflake stage, normally built with TO_FILE('@stage', 'path'). The second is an OBJECT of options. Every key in it is optional, and the keys you will meet most are 'mode', 'page_split', 'page_filter' and 'extract_images'. The function returns a JSON-formatted string, so the documentation suggests passing it through PARSE_JSON before using the result in SQL.

The older function, SNOWFLAKE.CORTEX.PARSE_DOCUMENT, was called differently: it took a stage name and a relative path as two separate string arguments. Its reference page is kept only for backward compatibility and points new work to AI_PARSE_DOCUMENT.

Sources12

2.OCR mode vs LAYOUT mode

The 'mode' key picks one of two extraction types. OCR extracts text only and is the default. LAYOUT extracts layout as well as text, including structural content such as tables. The two modes also return different formats: content is plain text in OCR mode and Markdown in LAYOUT mode. Headings come back as # lines, and tables come back as Markdown tables.

The defaults and the recommendations point in different directions. The user guide calls LAYOUT the preferred choice for most use cases, especially complex documents, and it is required for image extraction. It recommends OCR for fast, high-quality text extraction from scanned or text-heavy documents such as contracts, insurance claims and manuals. So if you want tables or headings to survive, you have to ask for LAYOUT explicitly.

Image extraction is only available in LAYOUT. Setting 'extract_images' to TRUE adds an "images" array to the output. Each entry has an id, bounding-box coordinates (top_left_x, top_left_y, bottom_right_x, bottom_right_y) and the image itself as image_base64. The extracted images can then go to AI_EXTRACT or AI_COMPLETE for tagging and analysis.

Sources31

3.page_split: one result per page

By default, AI_PARSE_DOCUMENT returns the whole document as a single "content" field. When 'page_split' is TRUE, the document is split into pages and each page is processed separately. The output then becomes a "pages" array, and each element has a "content" field and an "index" field. The index starts at 0, and any page numbering printed in the document is ignored. A one-page document still comes back as a "pages" array with one element, so downstream code can rely on the same shape every time.

This is the documented way to handle long documents. The reference tip says to set the option to TRUE for documents that exceed the function's token limit. The user guide's examples combine it with LAYOUT mode, as below:

SELECT AI_PARSE_DOCUMENT (
    TO_FILE('@docs.doc_stage','research-paper-example.pdf'),
    {'mode': 'LAYOUT' , 'page_split': true}) AS research_paper_example;

There is one restriction to remember: page_split works only with paginated formats. PDF, PowerPoint (.pptx) and Word (.docx) are supported. Any other format returns an error, even though AI_PARSE_DOCUMENT can parse those formats without splitting.

Sources1

4.Limiting pages: page_filter and the per-document ceiling

The exam guide lists a 'page_limit' topic, but the documentation available here defines no option with that name. Two documented mechanisms limit which pages are processed. The first is the 'page_filter' option, which you control. The second is a fixed limit on document size: 100 MB per file and 2,000 pages per document.

'page_filter' takes an array of ranges. Each range is an object with 'start' and 'end' fields, page indexes start at 0, start is inclusive and end is exclusive. So {'start': 0, 'end': 1} selects only the first page. Setting page_filter implies page_split, so you do not need to set both, and the result comes back as a "pages" array. The documentation suggests this when you already know which pages hold the information you need.

SELECT AI_PARSE_DOCUMENT(
  TO_FILE('@my_documents', 'ResearchArticle.pdf'),
  {'mode': 'LAYOUT', 'page_filter': [{'start': 0, 'end': 1}]} );

SELECT AI_PARSE_DOCUMENT(
  TO_FILE('@my_documents', 'ResearchArticle.pdf'),
  {'mode': 'LAYOUT', ' ? ': [{'start': 0, 'end': 1}]} );

Sources3

5.When parsing fails

By default, AI_PARSE_DOCUMENT returns NULL for a document it cannot process. In a multi-row query, the failing rows return NULL and the other rows still complete. To find out why a row failed, pass TRUE as the third argument, return_error_details. The function then returns an OBJECT with three top-level fields: value holds the parsed data, error holds the message (or NULL on success), and metadata holds document metadata such as pageCount.

Sources1

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Because the documentation recommends LAYOUT for most use cases, AI_PARSE_DOCUMENT uses LAYOUT unless told otherwise.Why is that wrong?

   OCR is the default. To get tables and headings back as Markdown, you have to set 'mode': 'LAYOUT' explicitly.

   Covered in OCR mode vs LAYOUT mode

2. 2.'extract_images': TRUE works in any mode.Why is that wrong?

   Image extraction is available only in LAYOUT mode.

   Covered in OCR mode vs LAYOUT mode

3. 3.To use page_filter you must also set 'page_split': TRUE.Why is that wrong?

   page_filter implies page_split, so setting both is redundant.

   Covered in Limiting pages: page_filter and the per-document ceiling