Directory Tables
In shortA directory table is a catalog of the files in a stage: one row per file, with path, size, dates and a URL. It describes the files and never reads what's inside.
The problem
Safia's team scans supplier invoices as PDFs into a stage. They don't want rows parsed from the PDFs yet. They want a list of files they can query, join with other tables and link to.
How it works
| SHIPMENT_ID | WEIGHT_KG |
|---|---|
| S-1 | 12 |
| S-2 | 8 |
| S-3 | 30 |
ONE STAGE
FILEpart-0.
FILEpart-1.
FILEinv_01.pdfa document
| RELATIVE_PATH | SIZE |
|---|---|
| part-0.parquet | 2.1 MB |
| part-1.parquet | 1.4 MB |
| inv_01.pdf | 0.3 MB |
Enable it with DIRECTORY = (ENABLE = TRUE) on the stage. It shows what it knew at its last refresh. On an external stage, DIRECTORY = (ENABLE = TRUE AUTO_REFRESH = TRUE) keeps it in sync through the cloud's event notifications. On an internal stage, automatic refresh is a preview feature on AWS-hosted accounts; elsewhere, schedule ALTER STAGE … REFRESH. Two Information Schema table functions show the refresh history: STAGE_ (refreshes and their errors) and AUTO_ (files registered by automatic refresh and the credits charged).
Example: the invoice catalog
CREATE STAGE hr_db. docs. invoice_ stage DIRECTORY = (ENABLE = TRUE)ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE' ); -- server-side encryption: required for presigned URLsALTER STAGE hr_db. docs. invoice_ stage REFRESH; -- sync the catalog with the stage SELECT relative_path, size, last_ modified, GET_PRESIGNED_ URL( @hr_ db. docs. invoice_ stage, relative_ path, 3600) AS link_1h FROM DIRECTORY(@hr_ db. docs. invoice_ stage) WHERE last_modified > DATEADD('day', -7, CURRENT_ TIMESTAMP( ));
Expected resultOne row per invoice uploaded in the last week, with a link anyone can open for one hour. Put together with AI_EXTRACT (Part 7), the app can show the vendor and amount next to each link, and no binary was ever loaded into a table.
| External table | Directory table | |
|---|---|---|
| Describes | Records inside structured or semi-structured files | The files themselves |
| One row per | Record | File |
| Typical use | Query a data lake in place | Catalog unstructured files (PDF, images), generate URLs, feed AI extraction |
| Object | Its own schema object | A property of a stage, queried with DIRECTORY(@stage) |
| Stages | External stages only | Internal and external stages |
| Refresh | Event notifications or manual REFRESH | Event notifications (AUTO_ |
File URL functions
| Function | Who can use the URL | How long |
|---|---|---|
GET_ | Anyone holding the link, with no Snowflake login | 1 hour by default and up to 7 days, except that 1 hour is the maximum for a stage that reaches S3 through an IAM role |
BUILD_ | Only the user who generated it, through Snowflake | About 24 hours, the time Snowflake keeps a query result |
BUILD_ | Any authenticated user whose role has privileges on the stage | Permanent |
GET_ | Not a file URL: returns the stage's base location | n/ |
- Directory table = file catalog of a stage, enabled with DIRECTORY = (ENABLE = TRUE).
- It lists files and URLs; it never parses contents.
- Presigned = anyone, until expiry · scoped = only the generating user, about 24 h · file URL = permanent, needs privileges.

