Snowflake AI SQL User Guide: AI_PARSE_DOCUMENT

What is AI_PARSE_DOCUMENT?

AI_PARSE_DOCUMENT is a Snowflake Cortex AI function that extracts text, structure, and images from documents. It supports OCR for plain text extraction and LAYOUT mode for structured Markdown output with tables.

Listen to a quick technical breakdown of the Snowflake AI_PARSE_DOCUMENT function. In this short 5-minute audio overview, we explore what the function does, how its parameters work, and when you would use it in real-world Snowflake workloads.

[embed]

What we’ll cover

1. OCR Mode: Quick plain text extraction from a document
2. Layout Mode: Structured Markdown extraction preserving tables and formatting
3. Page Filtering: Process only specific pages from a document
4. Image Extraction: Extract and analyse embedded images

Key takeaway: AI_PARSE_DOCUMENT returns JSON. We’ll show both the raw JSON output and how to parse it into clean columns and rows using Snowflake’s semi-structured data features.

Setup

Before using AI_PARSE_DOCUMENT, we need to create the database, schemas, stage, and warehouse. We’ll use the ACCOUNTADMIN role for this setup.

Create Database and Schemas

USE ROLE ACCOUNTADMIN;
CREATE DATABASE IF NOT EXISTS DEMO_AI;
CREATE SCHEMA IF NOT EXISTS DEMO_AI.RAW;

Create Warehouse

CREATE WAREHOUSE IF NOT EXISTS SUPERHERO_GEN1_XS_WH
    WAREHOUSE_SIZE = 'XSMALL'
    AUTO_SUSPEND = 60
    AUTO_RESUME = TRUE;

Create Internal Stage

CREATE OR REPLACE STAGE DEMO_AI.RAW.STAGE_FILES
    ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')
    DIRECTORY = (ENABLE = TRUE)
    COMMENT = 'Internal stage for audio, video, images and documents used with AI functions';

Upload Document

For these demos we’ve create a folder in our STAGE called DOCUMENT and added the following document:

Download: Sample File

AI_PARSE_DOCUMENT supports the following formats:

• Documents: PDF, DOCX, PPTX
• Images: PNG, JPEG, GIF, BMP, TIFF, WEBP

Verify Document

USE ROLE ACCOUNTADMIN;
USE DATABASE DEMO_AI;
USE SCHEMA RAW;
USE WAREHOUSE SUPERHERO_GEN1_XS_WH;

LIST @DEMO_AI.RAW.STAGE_FILES;

1. OCR Mode (Quick Text Extraction)

OCR mode extracts plain text from a document without preserving formatting or structure. This is the fastest option when you just need the raw text content.

How it works:

• Use TO_FILE('@stage', 'path') to reference the file
• Pass {'mode': 'OCR'} as the options argument
• AI_PARSE_DOCUMENT returns JSON with content (the extracted text) and metadata (including page count)

SELECT 
    AI_PARSE_DOCUMENT
    (
        TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
        {'mode': 'OCR'}
    ) AS OUTPUT_JSON;

Parsing OCR JSON into Columns

The raw JSON is useful, but for reporting or downstream use, we want clean columns. We use Snowflake’s : notation to extract values from the JSON output.

Key pattern: OUTPUT_JSON:key_name::TYPE

• :content gets the full extracted text
• :metadata:pageCount gets the total number of pages
• ::VARCHAR and ::INT cast to the desired types

SELECT 
    OUTPUT_JSON:content::VARCHAR AS EXTRACTED_TEXT,
    OUTPUT_JSON:metadata:pageCount::INT AS PAGE_COUNT
FROM 
(
    SELECT 
        AI_PARSE_DOCUMENT
        (
            TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
            {'mode': 'OCR'}
        ) AS OUTPUT_JSON
);

2. Layout Mode (Structured Markdown with Tables)

Layout mode extracts both text and document structure. Tables are represented in Markdown format, and formatting elements are preserved. This is the preferred mode for documents with rich structure.

How it works:

• Pass {'mode': 'LAYOUT'} as the options argument
• AI_PARSE_DOCUMENT returns structured Markdown in the content field
• Tables, headers, and formatting are preserved in Markdown syntax

SELECT 
    AI_PARSE_DOCUMENT
    (
        TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
        {'mode': 'LAYOUT'}
    ) AS OUTPUT_JSON;

Layout Mode with Page Splitting

For long documents, enable page_split to process each page separately. This returns an array of page objects instead of a single content string, and is recommended to avoid token limits.

How it works:

• Pass {'mode': 'LAYOUT', 'page_split': TRUE} as the options argument
• The output pages field contains an array of objects, each with content and index

SELECT 
    AI_PARSE_DOCUMENT
    (
        TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
        {'mode': 'LAYOUT', 'page_split': TRUE}
    ) AS OUTPUT_JSON;

Parsing Pages into Rows

To turn the pages array into individual rows, we use LATERAL FLATTEN. Each page becomes its own row with its index and content.

Key pattern:

LATERAL FLATTEN(INPUT => OUTPUT_JSON:pages) PAGE

• Each array element becomes a row
• PAGE.VALUE:index gives the 0-based page number
• PAGE.VALUE:content gives the page's Markdown content

SELECT 
    PAGE.VALUE:index::INT AS PAGE_NUMBER,
    PAGE.VALUE:content::VARCHAR AS PAGE_CONTENT
FROM 
(
    SELECT 
        AI_PARSE_DOCUMENT
        (
            TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
            {'mode': 'LAYOUT', 'page_split': TRUE}
        ) AS OUTPUT_JSON
),
LATERAL FLATTEN(INPUT => OUTPUT_JSON:pages) PAGE;

3. Page Filtering (Process Specific Pages Only)

Page filtering lets you target specific page ranges within a multi-page document. This is useful when you only need data from certain pages, saving processing time and cost.

How it works:

• Pass {'mode': 'LAYOUT', 'page_filter': [{'start': 0, 'end': 1}]} as the options argument
• The page_filter uses a zero-based index (start: 0, end: 1 targets only the first page)
• Specifying a page_filter automatically enables page_split functionality

SELECT 
    AI_PARSE_DOCUMENT
    (
        TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
        {'mode': 'LAYOUT', 'page_filter': [{'start': 0, 'end': 1}]}
    ) AS OUTPUT_JSON;

Parsing Filtered Pages into Rows

We use the same LATERAL FLATTEN pattern to produce one row per filtered page.

Key pattern:

LATERAL FLATTEN(INPUT => OUTPUT_JSON:pages) PAGE

• Only the filtered pages appear in the output
• PAGE.VALUE:index and PAGE.VALUE:content give page details

SELECT 
    PAGE.VALUE:index::INT AS PAGE_NUMBER,
    PAGE.VALUE:content::VARCHAR AS PAGE_CONTENT
FROM 
(
    SELECT
        AI_PARSE_DOCUMENT
        (
            TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
            {'mode': 'LAYOUT', 'page_filter': [{'start': 0, 'end': 1}]}
        ) AS OUTPUT_JSON
),
LATERAL FLATTEN(INPUT => OUTPUT_JSON:pages) PAGE;

4. Image Extraction (Extract Embedded Images)

Image extraction identifies and extracts images embedded within a document. Each image is returned with its bounding box coordinates and base64-encoded data. This requires LAYOUT mode.

How it works:

• Pass {'mode': 'LAYOUT', 'extract_images': TRUE} as the options argument
• AI_PARSE_DOCUMENT returns an images array with id, bounding box coordinates, and image_base64 for each image
• You can combine extracted images with AI_EXTRACT to describe or analyze image content

SELECT 
    AI_PARSE_DOCUMENT
    (
        TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
        {'mode': 'LAYOUT', 'extract_images': TRUE}
    ) AS OUTPUT_JSON;

Listing All Extracted Images

Use LATERAL FLATTEN on the images array to produce one row per image with its metadata and base64 data.

Key pattern:

LATERAL FLATTEN(INPUT => OUTPUT_JSON:images) IMG

• IMG.VALUE:id gives a unique image identifier
• IMG.VALUE:top_left_x, top_left_y, bottom_right_x, bottom_right_y give bounding box coordinates
• IMG.VALUE:image_base64 gives the raw image data as a base64 string

SELECT 
    IMG.VALUE:id::VARCHAR AS IMAGE_ID,
    IMG.VALUE:top_left_x::FLOAT AS TOP_LEFT_X,
    IMG.VALUE:top_left_y::FLOAT AS TOP_LEFT_Y,
    IMG.VALUE:bottom_right_x::FLOAT AS BOTTOM_RIGHT_X,
    IMG.VALUE:bottom_right_y::FLOAT AS BOTTOM_RIGHT_Y,
    IMG.VALUE:image_base64::VARCHAR AS IMAGE_BASE64_PREVIEW
FROM 
(
    SELECT 
        AI_PARSE_DOCUMENT
        (
            TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
            {'mode': 'LAYOUT', 'extract_images': TRUE}
        ) AS OUTPUT_JSON
),
LATERAL FLATTEN(INPUT => OUTPUT_JSON:images) IMG;

Describe an Extracted Image with AI_EXTRACT

Combine AI_PARSE_DOCUMENT with AI_EXTRACT to analyze extracted images. This example takes the first image from the document and asks AI_EXTRACT to describe it.

How it works:

• Extract the first image’s base64 data from the images array
• Strip the data URI prefix with REGEXP_REPLACE
• Decode the base64 string with BASE64_DECODE_BINARY
• Pass the binary data to AI_EXTRACT with a response format requesting a description

SELECT 
    AI_EXTRACT
    (
        file_data => BASE64_DECODE_BINARY
        (
            REGEXP_REPLACE
            (
                (
                    SELECT 
                    (
                        AI_PARSE_DOCUMENT
                        (
                            TO_FILE('@DEMO_AI.RAW.STAGE_FILES', 'DOCUMENT/AI_PARSE_DOCUMENT.pdf'),
                            {'mode': 'LAYOUT', 'extract_images': TRUE}
                        ):images[0]['image_base64']
                    )::STRING
                ),
                '^data:image/[^;]+;base64,', ''
            )
        ),
        responseFormat => {'description': 'Describe the image in detail'}
    ) AS IMAGE_DESCRIPTION;

Summary

Try:

• Combine AI_PARSE_DOCUMENT with AI_EXTRACT to pull structured data from parsed documents
• Use page splitting output to build document summaries with AI_COMPLETE
• Store parsed content in a table and use Cortex Search for full-text search over document content

Next Steps

• Learn more on docs.snowflake.com
• Sign up for a Snowflake Trial

If you found this useful, follow me on LinkedIn for more Cortex AI SQL and Snowflake AI Data Cloud use cases.