Snowflake Document Processing · Topic 1 of 7

AI_PARSE_DOCUMENT - Document Parsing Functions, OCR and LAYOUT Modes

Pick the right Snowflake parsing mode: AI_PARSE_DOCUMENT with OCR, LAYOUT or AGENTIC, TO_FILE inputs, output shape and the CORTEX_USER role you need.

  • 5 min
In a nutshell
  • AI_PARSE_DOCUMENT is the current function and PARSE_DOCUMENT is the older name for it.
  • Input is a FILE from TO_FILE on a stage. Options are an OBJECT with mode, page_split, page_filter and extract_images.
  • Modes: OCR (default, plain text, no layout), LAYOUT (Markdown with tables and headings), AGENTIC (visuals, preview).

What it is

Document parsing turns a file on a stage (a PDF, a scan, a slide deck) into text a model can use. The Snowflake function for this is AI_PARSE_DOCUMENT, one of the Cortex AI functions. It is the updated version of the older PARSE_DOCUMENT function, so a question that names PARSE_DOCUMENT is asking about the same job.

The exam tests which mode fits a document and what the result looks like. The function does not answer questions about the file. It only returns content. To pull specific fields you use AI_EXTRACT, covered on a later page.

StagePDF filesTO_FILEFILE objectAI_PARSE_DOCUMENTJSONtext or Markdownnext stepChunk, classify or extract

How it works

The call

SELECT AI_PARSE_DOCUMENT(
  TO_FILE('@docs.public.contracts', 'msa_2026.pdf'),
  {'mode': 'LAYOUT'}
);

The first argument is a FILE object created with TO_FILE from a stage and a relative path. The second argument is an optional OBJECT of options. A third optional BOOLEAN, return_error_details, changes how failures come back (see the troubleshooting page).

The three modes

ModeWhat you getUse it for
OCRPlain text only. This is the defaultFast, high quality text from scanned or text heavy files where layout does not matter
LAYOUTText as Markdown plus structure such as tables and headersDocuments where tables, reading order and headings carry meaning
AGENTICLayout plus interpretation of visuals such as charts and diagramsDocuments whose meaning sits in figures. This mode is a preview feature

If you pass no mode, you get OCR. This default is a favorite trap: a table comes back as flat text unless you ask for LAYOUT.

OCR mode

OCR extracts the text and does not preserve layout. It suits scanned documents, forms read for plain content and text heavy files. Because the output is plain text, a table row becomes a run of words with no column boundaries.

LAYOUT mode

LAYOUT returns Markdown, so tables stay tables and headings stay headings. The guide recommends it when you need to preserve structure. This makes it the better input for chunking and search, because headings can guide where text is split.

LAYOUT also supports extract_images. Setting it to TRUE returns embedded images as base64 in the result, at no extra charge. The guide documents up to 50 images per document in LAYOUT mode, and tiny images (under 4 by 4 pixels) are skipped.

AGENTIC mode

AGENTIC goes further and classifies visuals (chart, table, diagram, screenshot, infographic and others), then writes a summary and structured details for each. Treat it carefully:

  • It is a preview feature, so do not describe it as generally available.
  • extract_images is not supported with it. Setting it to TRUE is an error.
  • Output is best effort and the schema is not guaranteed, so validate required fields and handle NULLs.
  • It handles up to 2,000 images per document.

Output shape

Without page splitting, the result has a content string and metadata.pageCount. The reference describes the value as a JSON formatted string, so wrap it in PARSE_JSON when you want to read fields in SQL. With page splitting you get a pages array instead (next page).

SELECT PARSE_JSON(
  AI_PARSE_DOCUMENT(TO_FILE('@docs.public.contracts','msa_2026.pdf'), {'mode':'LAYOUT'})
):content::STRING AS markdown_text;

Access

The caller needs a role with the SNOWFLAKE.CORTEX_USER database role. An ACCOUNTADMIN grants it. Native availability covers select regions, and other regions can use cross-region inference.

Need plain text fastscanspickOCR modeNeed tables and headingsstructurepickLAYOUT modeNeed charts and diagramsvisual contentpickAGENTIC modepreview
Exam tip

Default means OCR. If the scenario mentions tables, headings or preserving structure, the answer is LAYOUT. If it mentions charts or diagrams interpreted by the model, think AGENTIC and remember it is preview.

Common mistakes

Expecting tables from the default call. OCR is the default and it returns plain text. Set mode to LAYOUT.

Passing a path string instead of a FILE. The function takes a FILE object, so build it with TO_FILE.

Setting extract_images with OCR. Image extraction requires LAYOUT mode, and it is an error in AGENTIC mode.

Expecting AI_PARSE_DOCUMENT to answer questions. It returns content. Use AI_EXTRACT or AI_COMPLETE to ask about it.

Forgetting the role. Without SNOWFLAKE.CORTEX_USER the call fails even if the stage is readable.

Watch out

A failing row returns NULL by default rather than stopping the query. A result column full of NULLs usually means the file could not be processed, not that the document was empty.

What to remember for the exam

  • AI_PARSE_DOCUMENT is the current function and PARSE_DOCUMENT is the older name for it.
  • Input is a FILE from TO_FILE on a stage. Options are an OBJECT with mode, page_split, page_filter and extract_images.
  • Modes: OCR (default, plain text, no layout), LAYOUT (Markdown with tables and headings), AGENTIC (visuals, preview).
  • extract_images needs LAYOUT, is free of extra charge and is not supported in AGENTIC.
  • Access needs the SNOWFLAKE.CORTEX_USER database role.

Check yourself

  • A team parses a PDF with no options and the invoice table loses its columns. What is the fix?

    Set mode to LAYOUT, because the default OCR mode returns plain text without layout.

  • Which mode interprets charts and diagrams, and what is its status?

    AGENTIC, which is a preview feature.

  • What must you supply as the first argument?

    A FILE object built with TO_FILE from a stage and a file path.

Topic 1 of 7 in Snowflake Document Processing

Test yourself on Snowflake Document Processing

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.