AWS CDK Glueに型安全なパーティション射影設定機能を追加

新機能の背景

AWS Glue のパーティション射影（Partition Projection）は、Amazon Athena でのクエリ処理を高速化する重要な機能です。パーティション射影を使用すると、Athena はメタデータルックアップを行わずに、テーブルプロパティから直接パーティション値を計算できるため、特に大量のパーティションを持つテーブルで大幅なパフォーマンス向上が期待できます。

しかし、CDK でのパーティション射影の設定は文字列ベースで行われており、以下の問題がありました：

• 型チェックの欠如: 文字列ベースの設定では、TypeScript の型システムによる検証が行われないため、タイプミスや不正な値を実行時まで検出できませんでした
• プロパティの必須性が不明確: パーティション射影のタイプ（INTEGER、DATE、ENUMなど）によって必須プロパティが異なりますが、型定義で強制されていませんでした
• 実行時エラーのリスク: 設定ミスがデプロイ後に初めて発覚し、クエリ実行時のエラーにつながる可能性がありました

この問題を解決するため、型安全なファクトリメソッドパターンを採用した新しいAPIが導入されました。

新機能の概要

CDK の AWS Glue アルファモジュールに、型安全なパーティション射影設定用の新しい PartitionProjectionConfiguration クラスが追加されました。

主な特徴

1. 4種類のパーティション射影タイプをサポート:

   • INTEGER: 連続する整数値のパーティション
   • DATE: 日付・タイムスタンプのパーティション
   • ENUM: 明示的な値のリストによるパーティション
   • INJECTED: クエリ時に注入されるカスタムパーティション

2. ファクトリメソッドによる型安全な設定:

   • 各タイプ専用のファクトリメソッド（integer(), date(), enum(), injected()）
   • 各メソッドに専用の Props インターフェースがあり、TypeScript の型システムが必須プロパティを強制
   • コンパイル時に設定ミスを検出可能

3. 包括的なバリデーション:

   • 範囲の妥当性検証（min ≤ max）
   • 日付フォーマットの検証（Java SimpleDateFormat パターン）
   • ENUM 値の検証（空文字列やカンマを含む値の禁止）
   • 適切なエラーメッセージの提供

使い方

INTEGER パーティション射影

連続する整数値を持つパーティションキーの場合：

import * as glue from '@aws-cdk/aws-glue-alpha';

declare const myDatabase: glue.Database;

new glue.S3Table(this, 'MyTable', {
  database: myDatabase,
  columns: [{
    name: 'data',
    type: glue.Schema.STRING,
  }],
  partitionKeys: [{
    name: 'year',
    type: glue.Schema.INTEGER,
  }],
  dataFormat: glue.DataFormat.JSON,
  partitionProjection: {
    year: glue.PartitionProjectionConfiguration.integer({
      min: 2020,        // 最小値（必須）
      max: 2023,        // 最大値（必須）
      interval: 1,      // オプション、デフォルトは1
      digits: 4,        // オプション、先頭ゼロ埋めの桁数（例: 0001, 0002）
    }),
  },
});

DATE パーティション射影

日付やタイムスタンプ値を持つパーティションキーの場合：

// 固定日付の範囲を指定
new glue.S3Table(this, 'MyTable', {
  database: myDatabase,
  columns: [{
    name: 'data',
    type: glue.Schema.STRING,
  }],
  partitionKeys: [{
    name: 'date',
    type: glue.Schema.STRING,
  }],
  dataFormat: glue.DataFormat.JSON,
  partitionProjection: {
    date: glue.PartitionProjectionConfiguration.date({
      min: '2020-01-01',                      // 開始日（必須）
      max: '2023-12-31',                      // 終了日（必須）
      format: 'yyyy-MM-dd',                   // 日付フォーマット（必須、Java SimpleDateFormat）
      interval: 1,                            // オプション、デフォルトは1
      intervalUnit: glue.DateIntervalUnit.DAYS, // オプション: YEARS, MONTHS, WEEKS, DAYS, HOURS, MINUTES, SECONDS
    }),
  },
});

// NOW を使った相対日付の指定
new glue.S3Table(this, 'MyTable', {
  database: myDatabase,
  columns: [{
    name: 'data',
    type: glue.Schema.STRING,
  }],
  partitionKeys: [{
    name: 'date',
    type: glue.Schema.STRING,
  }],
  dataFormat: glue.DataFormat.JSON,
  partitionProjection: {
    date: glue.PartitionProjectionConfiguration.date({
      min: 'NOW-3YEARS',  // 現在から3年前
      max: 'NOW',         // 現在
      format: 'yyyy-MM-dd',
    }),
  },
});

ENUM パーティション射影

既知の値のセットを持つパーティションキーの場合：

new glue.S3Table(this, 'MyTable', {
  database: myDatabase,
  columns: [{
    name: 'data',
    type: glue.Schema.STRING,
  }],
  partitionKeys: [{
    name: 'region',
    type: glue.Schema.STRING,
  }],
  dataFormat: glue.DataFormat.JSON,
  partitionProjection: {
    region: glue.PartitionProjectionConfiguration.enum({
      values: ['us-east-1', 'us-west-2', 'eu-west-1'], // 許可する値のリスト（必須）
    }),
  },
});

INJECTED パーティション射影

クエリ時にカスタムパーティション値を注入する場合：

new glue.S3Table(this, 'MyTable', {
  database: myDatabase,
  columns: [{
    name: 'data',
    type: glue.Schema.STRING,
  }],
  partitionKeys: [{
    name: 'custom',
    type: glue.Schema.STRING,
  }],
  dataFormat: glue.DataFormat.JSON,
  partitionProjection: {
    custom: glue.PartitionProjectionConfiguration.injected(),
  },
});

複数パーティションの射影設定

複数のパーティションキーに対して異なる射影タイプを設定できます：

new glue.S3Table(this, 'MyTable', {
  database: myDatabase,
  columns: [{
    name: 'data',
    type: glue.Schema.STRING,
  }],
  partitionKeys: [
    {
      name: 'year',
      type: glue.Schema.INTEGER,
    },
    {
      name: 'month',
      type: glue.Schema.INTEGER,
    },
    {
      name: 'region',
      type: glue.Schema.STRING,
    },
  ],
  dataFormat: glue.DataFormat.JSON,
  partitionProjection: {
    year: glue.PartitionProjectionConfiguration.integer({
      min: 2020,
      max: 2023,
    }),
    month: glue.PartitionProjectionConfiguration.integer({
      min: 1,
      max: 12,
      digits: 2,  // 01, 02, ..., 12 のようにゼロ埋め
    }),
    region: glue.PartitionProjectionConfiguration.enum({
      values: ['us-east-1', 'us-west-2'],
    }),
  },
});

注意点

バリデーションと制約

1. INTEGER 型の制約:

   • min と max は整数でなければなりません
   • min は max 以下である必要があります
   • interval は正の整数である必要があります
   • digits は 1 以上の整数である必要があります

2. DATE 型の制約:

   • format は Java SimpleDateFormat の有効なパターンでなければなりません（例: yyyy-MM-dd, yyyy-MM-dd HH:mm:ss）
   • 無効なパターン文字が含まれている場合、コンパイル時にエラーが発生します
   • interval は正の整数である必要があります
   • 相対日付（NOW, NOW-3YEARS など）と固定日付の両方をサポート

3. ENUM 型の制約:

   • values は空の配列であってはいけません
   • 値に空文字列を含めることはできません
   • 値にカンマ（,）を含めることはできません（内部的にカンマ区切りリストとしてシリアライズされるため）

4. INJECTED 型:

   • 追加のプロパティは必要ありません
   • クエリ実行時にパーティション値を SQL で指定する必要があります

既存コードへの影響

• この機能は新規追加であり、既存の文字列ベースの設定方法との後方互換性があります
• 破壊的変更はありません
• 新しい型安全な API への移行を推奨しますが、既存コードの修正は必須ではありません

パフォーマンスと使用シナリオ

• パーティション射影は、以下のケースで特に効果的です：

  • 大量のパーティションを持つテーブル（数千〜数百万のパーティション）
  • 定期的に新しいパーティションが追加されるテーブル
  • パーティションが予測可能なパターンに従う場合（整数、日付、列挙値など）

• パーティション射影を使用する場合：

  • AWS Glue Data Catalog のパーティションメタデータは無視されます
  • 射影されたパーティションが S3 に存在しない場合、クエリはエラーを返さずに0行を返します
  • 射影されたパーティションの半分以上が空の場合は、従来のパーティション管理を使用することを推奨します

モジュールのバージョン

• この機能は @aws-cdk/aws-glue-alpha モジュール（アルファ版）で提供されています
• AWS CDK v2.238.0 以降で利用可能です
• アルファモジュールのため、API は将来的に変更される可能性があります

補完情報の出典

• AWS CDK v2.238.0 リリースノート
• AWS CDK PR #35660: feat(glue): typed partition projection
• AWS Athena ドキュメント: パーティション射影の使用
• AWS Athena ドキュメント: パーティション射影のサポートされるタイプ