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

    Domain 4 · Lesson 13/15

    Staging, uploading and sizing documents for Cortex AI document functions

    Prepare and manage documents and implement extracting workflows.

    16 min read
    3.75% of exam
    6 sources
    Published 21 Oct 2026
    Docs as of 4 Oct 2026

    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.

    A staged PDF passed to AI_PARSE_DOCUMENT through TO_FILE(stage, path)sql
    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;

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

    Sources123

    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.

    An internal stage set up for AI document functions: directory table on, Snowflake server-side encryptionsql
    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?

    Sources43

    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 uploads a local file (Linux or macOS path) to a named internal stage; a bare @ identifies a named stagesql
    PUT file:///data/data.csv @my_stage;
    Ways to get documents onto a stage and when each fits
    MethodTargetUse it when
    PUT from Snowflake CLI, SnowSQL or a driverInternal stage: user stage @~, table stage @%, or named stage @my_stageLocal files are uploaded by a script or on a repeatable schedule
    Snowsight uploadNamed internal stageA few small local files are added by hand
    Cloud object storage plus a storage integrationExternal stage whose URL points at the bucket or containerDocuments 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?

    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.

    AI_EXTRACT over every file on a stage, with TO_FILE built from the directory table's relative_pathsql
    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);

    Sources6

    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.

    AI_PARSE_DOCUMENT input requirements
    RequirementLimitIf a document breaks it
    Maximum file size100 MBSplit or compress the file so each staged document is under 100 MB
    Maximum pages per document2,000Split the document into files of 2,000 pages or fewer
    Maximum page resolution10000 x 10000 pixels; 33.3 x 33.3 inches (at 300 DPI)Reduce the page dimensions before staging
    Supported file typePDF, PPTX, DOCX, JPEG, JPG, PNG, TIFF, TIF, HTML, TXTConvert the file to a supported type
    Stage encryptionClient-side or server-side encryptionUse a stage configured with one of these
    Font size8 points or larger for best resultsExpect 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?

    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?

    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?

    Sources316

    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.

    AI_EXTRACT errors that point back to stage preparation
    Error messageWhat 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.

    Sources36

    Practise it for real

    Stage a set of documents and extract fields from every one of them in a single query.

    1. 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. 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. 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. 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. 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. 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. 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
      “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. 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. 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. 6.
      “The following example extracts entities from all files in a directory on a stage”
      ↩︎ Building TO_FILE references from the directory table
      “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

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