Snowflake Directory Tablesでステージ内ファイルのメタデータを管理する方法

Directory Tables（ディレクトリテーブル）は、Snowflakeのステージ上にあるファイルの メタデータ（パス・サイズ・更新日時・チェックサムなど）をSQLで照会できる機能です。 データレイク上のファイル管理をSnowflakeのSQL操作に統合でき、 ファイル一覧の取得・差分検出・Streamによるファイル到着イベント駆動処理を実現します。

Directory Tablesの有効化

-- 既存ステージにDirectory Tablesを有効化
ALTER STAGE raw_data_stage SET DIRECTORY = (ENABLE = TRUE);

-- 新規ステージ作成時に有効化（External Stage / S3の例）
CREATE OR REPLACE STAGE landing_stage
  URL = 's3://my-bucket/landing/'
  STORAGE_INTEGRATION = s3_integration
  DIRECTORY = (ENABLE = TRUE);

-- 自動リフレッシュも同時に有効化
CREATE OR REPLACE STAGE landing_stage
  URL = 's3://my-bucket/landing/'
  STORAGE_INTEGRATION = s3_integration
  DIRECTORY = (
    ENABLE = TRUE
    AUTO_REFRESH = TRUE
  );

-- Internal Stageの場合
CREATE OR REPLACE STAGE internal_landing
  DIRECTORY = (ENABLE = TRUE);

Directory Tablesのメタデータ列

Directory Tablesへのクエリ

-- ステージ内の全ファイル一覧を取得
SELECT * FROM DIRECTORY(@landing_stage);

-- 特定の拡張子でフィルタ
SELECT relative_path, size, last_modified
FROM DIRECTORY(@landing_stage)
WHERE relative_path LIKE '%.parquet';

-- 過去24時間以内に追加されたファイル
SELECT relative_path, size, last_modified
FROM DIRECTORY(@landing_stage)
WHERE last_modified >= DATEADD(HOUR, -24, CURRENT_TIMESTAMP());

-- ファイル数とサイズの集計
SELECT
  SPLIT_PART(relative_path, '.', -1) AS file_extension,
  COUNT(*) AS file_count,
  SUM(size) / (1024 * 1024) AS total_size_mb
FROM DIRECTORY(@landing_stage)
GROUP BY file_extension
ORDER BY total_size_mb DESC;

メタデータの手動リフレッシュ

-- ステージ全体のメタデータをリフレッシュ
ALTER STAGE landing_stage REFRESH;

-- 特定のサブパスのみリフレッシュ（大量ファイル時に効率的）
ALTER STAGE landing_stage REFRESH SUBPATH = '/2026/03/';

自動リフレッシュ（AUTO_REFRESH = TRUE）が有効な場合、 クラウドストレージ側のイベント通知をトリガーにメタデータが自動更新されます。 Internal Stageでは自動リフレッシュが利用できないため、手動リフレッシュが必須です。

自動リフレッシュのクラウド別設定

Streamとの連携でファイル到着駆動処理

-- Directory TableにStreamを作成
CREATE OR REPLACE STREAM landing_file_stream
  ON STAGE landing_stage;

-- Streamから新着ファイルを検出
SELECT *
FROM landing_file_stream
WHERE METADATA$ACTION = 'INSERT';

-- Taskと連携して新着ファイルを自動処理
CREATE OR REPLACE TASK process_new_files
  WAREHOUSE = etl_wh
  SCHEDULE = '5 MINUTE'
  WHEN SYSTEM$STREAM_HAS_DATA('landing_file_stream')
AS
  COPY INTO raw_data
  FROM @landing_stage
  FILES = (
    SELECT RELATIVE_PATH
    FROM landing_file_stream
    WHERE METADATA$ACTION = 'INSERT'
  )
  FILE_FORMAT = (TYPE = 'PARQUET');

ファイルURL関数

-- スコープ付きURL（セッション内で有効な一時URL）
SELECT BUILD_SCOPED_FILE_URL(@landing_stage, relative_path)
FROM DIRECTORY(@landing_stage)
WHERE relative_path LIKE '%.pdf';

-- ステージURL（Snowflake内部参照用）
SELECT BUILD_STAGE_FILE_URL(@landing_stage, relative_path)
FROM DIRECTORY(@landing_stage);

-- 署名付きURL（外部共有用、有効期限付き）
SELECT GET_PRESIGNED_URL(@landing_stage, relative_path, 3600)
FROM DIRECTORY(@landing_stage)
WHERE relative_path = 'reports/2026-Q1.pdf';

コスト見積もり

-- 自動リフレッシュのコスト見積もり
SELECT SYSTEM$ESTIMATE_AUTOMATIC_REFRESH_COST('landing_stage');

ベストプラクティス

• 自動リフレッシュはExternal Stageでのみ有効化：Internal Stageでは手動リフレッシュを定期Taskで実行するパターンが一般的
• サブパス別リフレッシュで効率化：日付パーティション単位でREFRESH SUBPATHを指定し、不要なスキャンを回避する
• Streamと組み合わせてCDCパターンを構築：Directory Table上のStreamでファイル到着を検知し、Taskで自動ロードを実行する
• LIST @stageとの使い分け：LIST @stageはリアルタイムの一覧取得だがキャッシュされない。Directory Tablesはメタデータがキャッシュされ高速だが、リフレッシュまでのラグがある

問題で確認

よくある質問