What you will be able to do
- Create an internal or external stage that AI_PARSE_DOCUMENT and AI_EXTRACT can read, with SNOWFLAKE_SSE encryption and a directory table
- Choose between PUT, Snowsight and cloud object storage to get documents onto a stage
- Process every file on a stage by building TO_FILE references from the directory table's relative paths
- Check a document against the supported formats and the file-size, page-count and resolution limits before calling a document function, and fix one that fails
- Identify the access a role needs before it can run document functions on staged files
Key concept
Stage-resident document — Snowflake's document functions read a file that already sits on an internal or external stage. They receive it as a FILE reference, never as raw bytes in a table column. Getting a document ready means landing it on a suitable stage, inside the function's limits, so a FILE reference can point at it.
1.Why document functions read from a stage
Before you call a document function, the document has to be sitting on a stage. AI_PARSE_DOCUMENT takes a FILE object as its first argument. That object points at a document stored in a Snowflake stage. AI_EXTRACT accepts the same kind of FILE input. Most of the work of an extraction workflow therefore happens before the first SQL call: choose or create a stage, put the documents on it, and check that each one fits the function's limits.
The FILE object comes from TO_FILE, which takes a stage name and the path of a file on that stage. PROMPT() and TO_FILE() / FILE inputs covers that function. In a pipeline that receives new contracts, landing the files on a stage is the step nothing else can replace. Raw bytes in a VARIANT column, a Snowpark DataFrame, or an entry in a model registry give the function nothing to read. The model registry has a different job: it stores document extraction models that have been fine-tuned for an organisation's own use cases.
SELECT AI_PARSE_DOCUMENT (
TO_FILE('@docs.doc_stage','research-paper-example.pdf'),
{'mode': 'LAYOUT' , 'page_split': true}) AS research_paper_example;Because the functions read straight from the stage, documents can be processed directly from object storage. You don't have to copy them into tables first.
Checkpoint 1 of 9· Fill the gap
This query parses a PDF that sits on the stage @docs.doc_stage. Which function builds the FILE object that AI_PARSE_DOCUMENT needs as its first argument?
SELECT AI_PARSE_DOCUMENT (
? ('@docs.doc_stage','research-paper-example.pdf'),
{'mode': 'LAYOUT' , 'page_split': true}) AS research_paper_example;The first argument of AI_PARSE_DOCUMENT must be a FILE object that points at a document on a Snowflake stage. TO_FILE builds that object from a stage name and a file path. File bytes held as a VARIANT, as parsed JSON or as BINARY give the function nothing it can read.
Source: docs.snowflake.comCheckpoint 2 of 9· Exam question
Before a Snowpark pipeline can call AI_PARSE_DOCUMENT or AI_EXTRACT on newly arrived contracts, what must the engineering team do to make the files available to the function?
Correct answer: A — Load the files into a stage, then reference them via TO_FILE()
- A. Both functions operate on FILE objects created from documents sitting in an internal or external stage, and TO_FILE() is the mechanism used to reference a staged document in the call.
- B. Storing raw bytes in a VARIANT column bypasses the stage-based FILE reference these functions expect, so it is not a supported input path.
- C. A Snowpark DataFrame represents tabular query results, not a staged document reference, so it cannot substitute for a FILE object built from a stage.
- D. The model registry stores machine learning models and artifacts, not source documents awaiting parsing or extraction, so it is unrelated to this requirement.
2.Creating a stage with server-side encryption and a directory table
Two stage settings decide whether document processing works smoothly. The first is encryption. Most Cortex functions that read media files require the stage to use server-side encryption, so create the stage with ENCRYPTION = ( TYPE = 'SNOWFLAKE_SSE' ) and it will work with all of them. The second is a directory table. Without one you can still name a single file by its path, but you can't query the stage or loop over everything stored on it.
CREATE OR REPLACE STAGE input_stage
DIRECTORY = ( ENABLE = true )
ENCRYPTION = ( TYPE = 'SNOWFLAKE_SSE' );If the documents already live in cloud object storage such as Amazon S3, use an external stage instead of copying them. First create a storage integration for the cloud provider. Then create an external stage that uses the integration and whose URL points at the bucket or container. An internal and an external stage are equally valid inputs. The choice depends on where the files are, not on which function will read them.
Checkpoint 3 of 9· Check yourself
A team created an internal stage with ENCRYPTION = ( TYPE = 'SNOWFLAKE_SSE' ) and no other options, then uploaded 500 invoices to it. Calling AI_EXTRACT on one invoice by its path works. Their batch query, which runs AI_EXTRACT over every file on the stage, does not. What should they change?
Without a directory table you can still name a single file by its path. To query the stage or process everything on it, you need the directory table, which supplies the relative_path values passed to TO_FILE. Encryption isn't the cause, because AI_EXTRACT accepts both client-side and server-side encryption. page_split only splits a document into pages, and a VARIANT column gives the function no FILE to read.
“Ensure that the directory table is enabled.”Source: docs.snowflake.com
3.Uploading documents: PUT, Snowsight or cloud storage
How you upload depends on where the documents are and how many there are. PUT copies local files into an internal stage. You run it from the Snowflake CLI, the SnowSQL client, or a driver, so it fits scripts and repeatable loads. Snowsight's upload is meant for a few small files going into a named internal stage, such as one sample contract for testing an extraction question. For files that cloud tools or upstream systems already write to S3, Azure or Google Cloud Storage, you don't upload anything to Snowflake. An external stage over that location makes them readable where they are.
PUT file:///data/data.csv @my_stage;| Method | Target | Use it when |
|---|---|---|
| PUT from Snowflake CLI, SnowSQL or a driver | Internal stage: user stage @~, table stage @%, or named stage @my_stage | Local files are uploaded by a script or on a repeatable schedule |
| Snowsight upload | Named internal stage | A few small local files are added by hand |
| Cloud object storage plus a storage integration | External stage whose URL points at the bucket or container | Documents already arrive in S3, Azure or Google Cloud Storage |
PUT can target a user stage or a table stage, but for documents a named stage is usually the better choice. It is the stage you create yourself, so you control its encryption and directory table setting.
Checkpoint 4 of 9· Check yourself
Every night, a scanning server in the legal department writes several hundred new contract PDFs to its local disk. An automated job must get them onto the named internal stage that AI_EXTRACT reads from. Which approach fits?
PUT, run from the Snowflake CLI, SnowSQL or a driver, uploads local files into an internal stage and suits scripted, repeatable loads. Snowsight upload is meant for a few small files added by hand. A VARIANT column or the model registry gives the function no stage file to build a FILE reference from.
“Execute PUT using the Snowflake CLI client, the SnowSQL client, or Drivers to upload (stage) local data files into an internal stage.”Source: docs.snowflake.com
Sources5
4.Building TO_FILE references from the directory table
The directory table is what lets one query cover every file on the stage. DIRECTORY(@stage) returns a row per staged file, and its relative_path column holds each file's path within the stage. Pass that column to TO_FILE along with the stage name, and every row becomes a FILE reference. The query runs the extraction once per document. A file uploaded tomorrow is picked up the next time the query runs, with no change to the SQL.
SELECT AI_EXTRACT( file => TO_FILE('@db.schema.files', relative_path), responseFormat => [ 'What is the document ID?', 'What is the address of the company?' ] ) FROM DIRECTORY (@db.schema.files);If the stage was created without a directory table, this pattern fails. You are back to naming each file by hand. That is why the directory setting belongs in the original CREATE STAGE, not in a fix after the first batch run.
Checkpoint 5 of 9· Fill the gap
To run AI_EXTRACT on every document on the stage @db.schema.files without listing file names, the query builds one FILE reference per row of the directory table. Which column goes in the blank?
SELECT AI_EXTRACT( file => TO_FILE('@db.schema.files', ? ), responseFormat => [ 'What is the document ID?', 'What is the address of the company?' ] ) FROM DIRECTORY (@db.schema.files);DIRECTORY(@stage) returns one row for each staged file. Its relative_path column holds the file's path within the stage, and TO_FILE combines it with the stage name to build a FILE reference. This works only if the stage has a directory table enabled. The function needs a reference to a file on the stage, so a column of raw file bytes would give it nothing to read.
Source: docs.snowflake.comSources6
5.Document requirements: formats, file size, page count and resolution
Every document must pass the function's limits before it is parsed. A file that breaks a limit fails no matter which stage it sits on or which options the call uses. For AI_PARSE_DOCUMENT the limits are fixed per document.
| Requirement | Limit | If a document breaks it |
|---|---|---|
| Maximum file size | 100 MB | Split or compress the file so each staged document is under 100 MB |
| Maximum pages per document | 2,000 | Split the document into files of 2,000 pages or fewer |
| Maximum page resolution | 10000 x 10000 pixels; 33.3 x 33.3 inches (at 300 DPI) | Reduce the page dimensions before staging |
| Supported file type | PDF, PPTX, DOCX, JPEG, JPG, PNG, TIFF, TIF, HTML, TXT | Convert the file to a supported type |
| Stage encryption | Client-side or server-side encryption | Use a stage configured with one of these |
| Font size | 8 points or larger for best results | Expect weaker results on smaller text |
None of the parsing options lifts these ceilings. mode only chooses between text-only OCR and LAYOUT, which also keeps tables and structure. page_split returns output per page, and it exists for documents whose content would exceed the function's token limit, not its size or page limits. It also works only for PDF, PPTX and DOCX; other formats return an error. page_filter processes chosen page ranges. extract_images pulls embedded images out in LAYOUT mode, up to 50 per document. A 120 MB manual and a 3,000-page PDF fail for the same reason: the document itself is too big. The fix is to split or compress it before staging. Changing the options or moving the file to another stage does not help.
AI_EXTRACT has the same 100 MB file ceiling and 10000x10000-pixel page ceiling, but its page limit is much lower: 125 pages per document. Pages larger than 50x50 inches are also rejected. It accepts a wider set of formats than AI_PARSE_DOCUMENT: besides the common ones it reads PPT, DOC, EML, HTM, BMP, GIF, WEBP and MD. A 500-page contract that parses without trouble will therefore fail in AI_EXTRACT until you split it or extract from a subset of its pages.
Checkpoint 6 of 9· Check yourself
Your pipeline runs AI_PARSE_DOCUMENT and then AI_EXTRACT on the same staged 500-page, 40 MB PDF contract. AI_PARSE_DOCUMENT parses it without trouble, but AI_EXTRACT fails on it. What is the cause, and what is the fix?
AI_PARSE_DOCUMENT accepts up to 2,000 pages per document, but AI_EXTRACT rejects anything over 125 pages. Both functions have the same 100 MB file ceiling, both accept client-side or server-side encrypted stages, and page_split doesn't lift a page limit. The fix is to make the document smaller.
“Maximum number of 125 pages exceeded. The document has {actual_pages} pages.”Source: docs.snowflake.com
Checkpoint 7 of 9· Exam question
A team needs to run AI_PARSE_DOCUMENT against a scanned engineering manual that is 120 MB. The call fails immediately with a size-related error. What is the most direct fix consistent with the function's document requirements?
Correct answer: A — Split or compress the file so each upload stays under the 100 MB size limit
- A. AI_PARSE_DOCUMENT enforces a hard 100 MB maximum file size regardless of stage type or parsing mode, so splitting or compressing the source file is the only way to satisfy the limit.
- B. OCR and LAYOUT are text/table extraction modes, not size controls; switching modes has no effect on whether a file passes the size check.
- C. Internal and external stages are both valid places to store a document for parsing, but neither location changes the 100 MB ceiling the function enforces.
- D. page_split only restricts which document formats are accepted for that option; it does not raise or remove the underlying file size limit.
Checkpoint 8 of 9· Exam question
An operations team submits a single PDF containing 3,000 scanned pages to AI_PARSE_DOCUMENT and the call fails. Which change addresses the root cause?
Correct answer: A — Split the PDF into multiple documents so no single file exceeds 2,000 pages
- A. AI_PARSE_DOCUMENT caps a single document at 2,000 pages, so a 3,000-page PDF must be divided into smaller files before it can be processed.
- B. OCR and LAYOUT modes control how text, tables, and layout are extracted; neither mode changes the maximum page count a single document can contain.
- C. DPI relates to the page resolution limit, not the total page count, so lowering it does not address a document that exceeds the page ceiling.
- D. Turning on image extraction changes what content is pulled from each page but does not batch or reduce the number of pages the function must process at once.
6.Access a role needs to run document functions on staged files
Running a document function takes two kinds of access. The first is Cortex access. An ACCOUNTADMIN must grant the SNOWFLAKE.CORTEX_USER database role to whoever calls the function. Granting and revoking that role is covered in model access controls. The second is access to the file. A role that has Cortex access but cannot read the stage still fails, with an error that names the file rather than the function.
| Error message | What it means |
|---|---|
| Provided file cannot be found. | The file was not found: wrong stage name or relative path in TO_FILE |
| Provided file cannot be accessed. | The current user does not have sufficient privileges to access the file |
| The provided file format {file_extension} isn't supported. | The document is not in a supported format |
| Maximum file size of 104857600 bytes exceeded. | The document is larger than 100 MB |
| Maximum number of 125 pages exceeded. | The document exceeds the 125-page limit |
Checkpoint 9 of 9· Match them up
Match each AI_EXTRACT error to what you should fix in your stage preparation.
Tap a term, then the definition that fits it.
Each error points to a different preparation problem. 'Cannot be found' means the TO_FILE reference is wrong, and 'cannot be accessed' means the role lacks privileges on the file, even if it holds the Cortex role. The format, page and size errors are about the document itself, so you have to convert, split or compress it.
“Provided file cannot be accessed. | The current user does not have sufficient privileges to access the file.”Source: docs.snowflake.com
Practise it for real
Stage a set of documents and extract fields from every one of them in a single query.
1.Run CREATE OR REPLACE STAGE input_stage DIRECTORY = ( ENABLE = true ) ENCRYPTION = ( TYPE = 'SNOWFLAKE_SSE' );
Why: Server-side encryption suits the document functions, and the directory table makes the files queryable.
You should see: The stage is created with a directory table enabled.
2.Upload two or three PDFs under 100 MB and 125 pages, using PUT from SnowSQL or the Snowflake CLI, or the Snowsight upload for a handful of files.
Why: The files must be on the stage, and inside the AI_EXTRACT limits, before any function can read them.
You should see: The files appear on the stage.
3.Run SELECT relative_path FROM DIRECTORY(@input_stage);
Why: The relative paths are what TO_FILE needs to point at each document.
You should see: One row per uploaded file. If a file is missing, refresh the directory table and run the query again.
4.Run AI_EXTRACT with file => TO_FILE('@input_stage', relative_path) and a responseFormat of two questions, FROM DIRECTORY(@input_stage).
Why: Building a TO_FILE reference from each directory row processes every staged document in one statement.
You should see: One JSON result per document, each with a response object holding the answers.
Stuck? Get a nudge
If a row returns 'Provided file cannot be accessed.', the role running the query cannot read the stage. Check its grants on the stage, not the Cortex role.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“A FILE object that specifies the document to parse, stored in a Snowflake stage.”
↩︎ Why document functions read from a stage“This feature supports only PDF, PowerPoint (.pptx), and Word (.docx) documents.”
↩︎ Document requirements: formats, file size, page count and resolution“To process long documents that exceed the token limit of AI_PARSE_DOCUMENT, set this option to TRUE.”
↩︎ Exam trap 1“A FILE object that specifies the document to parse, stored in a Snowflake stage.”
↩︎ Exam trap 3 - 2.
“A model registry stores document extraction models fine-tuned for custom use cases specific to your organization.”
↩︎ Why document functions read from a stage - 3.
“Documents can be processed directly from object storage to avoid unnecessary data movement.”
↩︎ Why document functions read from a stage“AI_PARSE_DOCUMENT supports documents on stages that use client-side or server-side encryption”
↩︎ Creating a stage with server-side encryption and a directory table“Maximum file size | 100 MB”
↩︎ Document requirements: formats, file size, page count and resolution“Supported file type | PDF, PPTX, DOCX, JPEG, JPG, PNG, TIFF, TIF, HTML, TXT”
↩︎ Document requirements: formats, file size, page count and resolution“AI_PARSE_DOCUMENT can extract embedded images from documents (up to 50 images per document)”
↩︎ Document requirements: formats, file size, page count and resolution“a user with the ACCOUNTADMIN role must grant the SNOWFLAKE.CORTEX_USER database role to the user who will call the function.”
↩︎ Access a role needs to run document functions on staged files“Maximum pages per document | 2,000”
↩︎ Prediction - 4.
“Most of these functions require the stage to use server-side encryption”
↩︎ Creating a stage with server-side encryption and a directory table“If you want to be able to query the stage or programmatically process all the files stored there, the stage must have a directory table.”
↩︎ Creating a stage with server-side encryption and a directory table“create a storage integration, then create an external stage that uses the storage integration.”
↩︎ Creating a stage with server-side encryption and a directory table“Cortex AI Functions that process media files (documents, images, audio, or video) require the files to be stored on an internal or external stage.”
↩︎ Key concept“If you want to be able to query the stage or programmatically process all the files stored there, the stage must have a directory table.”
↩︎ Exam trap 4 - 5.
“Execute PUT using the Snowflake CLI client, the SnowSQL client, or Drivers to upload (stage) local data files into an internal stage.”
↩︎ Uploading documents: PUT, Snowsight or cloud storage“If you want to load a few small local data files into a named internal stage, you can also use Snowsight.”
↩︎ Uploading documents: PUT, Snowsight or cloud storage - 6.
“The following example extracts entities from all files in a directory on a stage”
↩︎ Building TO_FILE references from the directory table“The files must be less than 100 MB in size.”
↩︎ Document requirements: formats, file size, page count and resolution“Page size in inches exceeds 50x50 (3600x3600 pt).”
↩︎ Document requirements: formats, file size, page count and resolution“The current user does not have sufficient privileges to access the file.”
↩︎ Access a role needs to run document functions on staged files“Maximum number of 125 pages exceeded.”
↩︎ Exam trap 2“Ensure that the directory table is enabled.”
↩︎ Checkpoint“Maximum number of 125 pages exceeded. The document has {actual_pages} pages.”
↩︎ Checkpoint“Provided file cannot be accessed. | The current user does not have sufficient privileges to access the file.”
↩︎ Checkpoint