Snowflake Document Processing · Topic 4 of 7

Preparing and Uploading Documents - Stages, Formats and Size Limits

Prepare documents for Snowflake Cortex: stages, directory tables, upload methods, supported formats, the 100 MB size cap, and page and resolution limits.

  • 4 min
In a nutshell
  • Documents live on an internal or external stage and are passed as FILE objects through TO_FILE.
  • Create internal stages with SNOWFLAKE_SSE and DIRECTORY enabled for file access.
  • PUT runs from a client, with AUTO_COMPRESS set to FALSE. It cannot run in a Snowsight worksheet.

What it is

Before any Cortex function can read a document, the file must sit on a stage and meet the function's requirements. Preparing documents means choosing the stage, getting the files there, making them visible to SQL, and checking format, size and page limits. Most failed extraction questions trace back to one of these steps.

Local filesPDF, DOCX, imagesPUT or SnowsightStageinternal or externaldirectory tableFile listrelative_pathTO_FILECortex AI function

How it works

Choosing a stage

StageWhere files liveNotes
Internal named stageIn Snowflake storageYou upload files into it. Create it with ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE') for unstructured file access
External stageIn your S3, GCS or Azure containerSnowflake reads the files where they are. A storage integration is the preferred access method

Cortex document functions also accept stages with client side or server side encryption, including accounts that use PrivateLink or network policies that restrict public access.

CREATE OR REPLACE STAGE docs.public.contracts
  ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')
  DIRECTORY = (ENABLE = TRUE);

Uploading documents

  • Snowsight upload: use the stage's file upload in the web interface. This is the simplest option for a few files.
  • PUT command: run it from a client such as SnowSQL or the Snowflake CLI. PUT cannot run from a Snowsight worksheet. Use AUTO_COMPRESS = FALSE so documents are not gzipped.
  • External stage: drop files into the bucket or container with your own cloud tools. No PUT is needed.
PUT file:///data/contracts/msa_2026.pdf @docs.public.contracts AUTO_COMPRESS = FALSE;

Compressing a PDF defeats the purpose, because the function needs the original file.

Directory tables

A directory table is metadata about the files on a stage. You enable it with DIRECTORY = (ENABLE = TRUE) when you create the stage, or add it later with ALTER STAGE ... SET DIRECTORY. Query it with DIRECTORY(@stage) to get columns such as relative_path.

SELECT relative_path, TO_FILE('@docs.public.contracts', relative_path) AS doc
FROM DIRECTORY(@docs.public.contracts);

After you add files, run ALTER STAGE ... REFRESH to register them. Internal stages need that manual refresh. External stages can refresh automatically through cloud event notifications. On a large external stage you can limit a manual refresh with SUBPATH.

Format, size and page requirements

RequirementAI_PARSE_DOCUMENTAI_EXTRACT
FormatsPDF, PPTX, DOCX, JPEG, JPG, PNG, TIFF, TIF, HTML, TXTPDF, PNG, PPT and PPTX, EML, DOC and DOCX, JPEG, JPG, HTM and HTML, TXT, TIF and TIFF, BMP, GIF, WEBP, MD
File size100 MB100 MB
Pages2,000 per document1,000 with cross-region inference, 125 without
Font size8 points or larger for best resultsNot stated

AI_PARSE_DOCUMENT detects page orientation automatically and recognizes handwriting, while decorative or script fonts can cause trouble. Page resolution is capped, with the reference giving 10,000 by 10,000 pixels as the image limit. For AI_EXTRACT the pixel limit applies to images and converted pages.

Languages differ per function, so a document in an unsupported language is an error for AI_PARSE_DOCUMENT.

Access to the files

The role running the query needs USAGE on the database and schema and READ on an internal stage (or USAGE on an external stage), plus the SNOWFLAKE.CORTEX_USER database role. A file that cannot be read produces the error "Provided file cannot be accessed."

Exam tip

The two functions have different page ceilings. AI_PARSE_DOCUMENT allows 2,000 pages, while AI_EXTRACT depends on whether cross-region inference is on. Read which function the question names.

Watch out

GET_PRESIGNED_URL and unstructured file access depend on server side encryption. An internal stage created without SNOWFLAKE_SSE can return corrupted downloads.

Common mistakes

Uploading with PUT inside a Snowsight worksheet. PUT is not supported there. Use a client or the upload feature.

Leaving AUTO_COMPRESS on. The file is gzipped and the function sees a compressed copy.

Forgetting to refresh the directory table. New files do not appear until ALTER STAGE ... REFRESH runs on an internal stage.

Assuming every format works everywhere. AI_PARSE_DOCUMENT does not list EML, BMP, GIF or WEBP, while AI_EXTRACT does.

Exceeding 100 MB. The call errors and the fix is to split the document into smaller files before upload.

What to remember for the exam

  • Documents live on an internal or external stage and are passed as FILE objects through TO_FILE.
  • Create internal stages with SNOWFLAKE_SSE and DIRECTORY enabled for file access.
  • PUT runs from a client, with AUTO_COMPRESS set to FALSE. It cannot run in a Snowsight worksheet.
  • Internal stage directory tables need a manual REFRESH.
  • 100 MB per file for both functions. Pages: 2,000 for parsing, 125 or 1,000 for extraction.

Check yourself

  • Why use AUTO_COMPRESS = FALSE with PUT for a PDF?

    Otherwise the file is gzipped, and the document function needs the original file.

  • New PDFs were uploaded to an internal stage but do not show in DIRECTORY(). What is missing?

    An ALTER STAGE ... REFRESH, because internal stage directory tables are refreshed manually.

  • What is the file size limit for AI_PARSE_DOCUMENT and AI_EXTRACT?

    100 MB for both.

Topic 4 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.