CREATE TABLE - Amazon Athena
概要パラメータ例

CREATE TABLE

指定した名前とパラメータでテーブルを作成します。

注記

このページには、要約されたリファレンス情報が含まれています。Athena でのテーブルの作成と CREATE TABLE ステートメントの例に関する詳細については、「Athena でテーブルを作成する」を参照してください。データベースの作成、テーブルの作成、および Athena のテーブルに対する SELECT クエリの実行の例については、「使用を開始する」を参照してください。

概要

CREATE EXTERNAL TABLE [IF NOT EXISTS]
 [db_name.]table_name [(col_name data_type [COMMENT col_comment] [, ...] )]
 [COMMENT table_comment]
 [PARTITIONED BY (col_name data_type [COMMENT col_comment], ...)]
 [CLUSTERED BY (col_name, col_name, ...) INTO num_buckets BUCKETS]
 [ROW FORMAT row_format]
 [STORED AS file_format] 
 [WITH SERDEPROPERTIES (...)]
 [LOCATION 's3://amzn-s3-demo-bucket/[folder]/']
 [TBLPROPERTIES ( ['has_encrypted_data'='true | false',] ['classification'='aws_glue_classification',] property_name=property_value [, ...] ) ]

パラメータ

EXTERNAL

ユーザー指定の LOCATION で、テーブルが Amazon S3 に存在する基盤データに基づいていることを指定します。Iceberg テーブルの作成時を除いて、常に EXTERNAL キーワードが使用されます。Iceberg 以外のテーブルで、EXTERNAL キーワードを指定せずに CREATE TABLE を使用すると、Athena でエラーが発生します。外部テーブルを作成する場合、参照先のデータはデフォルト形式に準拠しているか、ユーザーが ROW FORMAT、STORED AS、および WITH SERDEPROPERTIES で指定する形式に準拠している必要があります。

[IF NOT EXISTS]

このパラメータは、同じ名前のテーブルが既に存在するかどうかを確認します。その場合、パラメータは TRUE を返し、Amazon Athena は CREATE TABLE アクションをキャンセルします。キャンセルは Athena がデータカタログを呼び出す前に行われるため、AWS CloudTrail イベントは発生しません。

[db_name.]table_name

作成するテーブルの名前を指定します。オプションの db_name パラメータは、テーブルを作成する先のデータベースを指定します。この引数を省略すると、現在のデータベースが使用されます。テーブル名に数字を含める場合は、table_name を引用符で囲みます (例: "table123")。table_name をアンダースコアで始める場合は、バックティックを使用します (例: `_mytable`)。特殊文字 (アンダースコア以外) はサポートされていません。

Athena のテーブル名では大文字と小文字が区別されませんが、Apache Spark を使用する場合、Spark ではテーブル名を小文字にする必要があります。Athena のテーブル名の制限については、「データベース、テーブル、列に名前を付ける」を参照してください。

[ ( col_name data_type [COMMENT col_comment] [, ...] ) ]

作成する各列の名前とデータ型を指定します。列名に特殊文字 (アンダースコア (_) を除く) を使用することはできません。col_name をアンダースコアで始める場合は、列名をバックティックで囲みます (例: `_mycolumn`)。Athena の列名の制限については、「データベース、テーブル、列に名前を付ける」を参照してください。

data_type 値には次のいずれかを指定できます。

  • boolean – 値は true もしくは false です。

  • tinyint – 2 の補数形式の 8 ビット符号付き整数で、最小値は -2^7、最大値は 2^7-1 です。

  • smallint – 2 の補数形式の 16 ビット符号付き整数で、最小値は -2^15、最大値は 2^15-1 です。

  • int – CREATE TABLE のようなデータ定義言語 (DDL) のクエリでは、整数を表すために int キーワードを使用します。他のクエリでは、integer キーワードを使用します。ここで integer は 2 の補数形式の 32 ビット符号付き値で表され、最小値は -2^31、最大値は 2^31-1 です。JDBC ドライバーでは、ビジネス分析アプリケーションとの互換性を確保するために integer が返されます。

  • bigint – 2 の補数形式の 64 ビット符号付き整数で、最小値は -2^63、最大値は 2^63-1 です。

  • double – 64 ビットの符号付き倍精度浮動小数点数です。これは、4.94065645841246544e-324d から 1.79769313486231570e+308d の範囲の正または負の値です。double は、IEEE Standard for Floating-Point Arithmetic (IEEE 754) に準拠しています。

  • float – 32 ビットの符号付き単精度浮動小数点数です。これは、1.40129846432481707e-45 から 3.40282346638528860e+38 の範囲の正または負の値です。floatは、IEEE Standard for Floating-Point Arithmetic (IEEE 754) に準拠しています。Presto の real に相当します。Athena では、CREATE TABLE のような DDL ステートメントで float、SELECT CAST のような SQL 関数で real を使用します。AWS Glue クローラは float で値を返し、Athena は real 型と float 型を内部で変換します (2018 年 5 月 6 日 リリースノートを参照)。

  • decimal [ (precision, scale) ]。ここで precision は桁の合計数であり、scale (オプション) は小数点以下の桁数です。デフォルトは 0 です。たとえば、decimal(11,5)、decimal(15) のタイプ定義を使用します。precision の最大値は 38 で、scale の最大値も 38 です。

    たとえばクエリ DDL 式で特定の小数値を含む行を選択する場合など、小数値をリテラルとして指定するには、decimal 型の定義を指定し、クエリ内で小数値をリテラル (一重引用符) としてリストします。例としては decimal_value = decimal '0.12' のようになります。

  • char – 固定長の文字データです。char(10) のように、1 から 255 の長さを指定します。詳細については、「CHAR Hive データ型」を参照してください。

  • varchar – 可変長の文字データです。varchar(10) のように、1 から 65535 の長さを指定します。詳細については、「VARCHAR Hive データ型」を参照してください。

  • string – 一重引用符または二重引用符で囲まれた文字列リテラルです。

    注記

    文字列以外のデータ型を Athena の string にキャストすることはできません。その代わりに varchar にキャストします。

  • binary – (Parquet のデータ用)

  • date – YYYY-MM-DD などの ISO 形式の日付です。例えば、date '2008-09-15' と指定します。例外として、1970 年 1 月 1 日以降の経過日数を使用する OpenCSVSerDe があります。詳細については、「CSV を処理するための Open CSV SerDe」を参照してください。

  • timestamp – 分解能をミリ秒単位まで指定可能な、java.sql.Timestamp 互換形式での日付と時刻のインスタント (例、yyyy-MM-dd HH:mm:ss[.f...]) です。例えば、timestamp '2008-09-15 03:04:05.324' と指定します。例外として、UNIX の数値形式 (1579059880000 など) の TIMESTAMP データを使用する OpenCSVSerDe があります。詳細については、「CSV を処理するための Open CSV SerDe」を参照してください。

  • array < data_type >

  • map < primitive_type, data_type >

  • struct< col_name : data_type [comment col_comment] [, ...]>

[COMMENT table_comment]

comment テーブルプロパティを作成し、指定した table_comment を追加します。

[PARTITIONED BY (col_name data_type [ COMMENT col_comment ], ... ) ]

col_name、data_type および col_comment が指定された 1 つ以上の列を持つ、パーティションされたテーブルを作成します。テーブルは、個別の列名と値の組み合わせで構成されるパーティションを 1 つ以上持つことができます。指定した組み合わせごとに別個のデータディレクトリが作成されます。これにより、クエリパフォーマンスが向上する場合があります。パーティション化された列はテーブルデータ内には存在しません。テーブル列と同じ col_name の値を使用する場合は、エラーになります。詳細については、「データのパーティション」を参照してください。

注記

パーティションされたテーブルを作成したら、MSCK REPAIR TABLE 句で構成されるクエリを続けて実行し、パーティションメタデータ (MSCK REPAIR TABLE cloudfront_logs; など) を更新します。Hive と互換性のないパーティションの場合、ALTER TABLE ADD PARTITION を使用してパーティションをロードすることで、データをクエリできるようにします。

[CLUSTERED BY (col_name, col_name, ...) INTO num_buckets BUCKETS]

パーティションの有無にかかわらず、指定された col_name 列のデータをバケットと呼ばれるデータサブセットに分割します。num_buckets パラメータは、作成するバケットの数を指定します。バケット化は、大規模なデータセットでの一部のクエリのパフォーマンスを向上させることができます。

[ROW FORMAT row_format]

テーブルの行形式と基になるソースデータ (該当する場合) を指定します。row_format として、DELIMITED 句で 1 つ以上の区切り記号を指定できます。または、以下に説明するように、SERDE 句を使用できます。ROW FORMAT を省略するか、ROW FORMAT DELIMITED を指定すると、ネイティブ SerDe が使用されます。

  • [DELIMITED FIELDS TERMINATED BY char [ESCAPED BY char]]

  • [DELIMITED COLLECTION ITEMS TERMINATED BY char]

  • [MAP KEYS TERMINATED BY char]

  • [LINES TERMINATED BY char]

  • [NULL DEFINED AS char]

    Hive 0.13 で、STORED AS ファイル形式が TEXTFILE である場合にのみ使用できます。

--または--

  • SERDE 'serde_name' [WITH SERDEPROPERTIES ("property_name" = "property_value", "property_name" = "property_value" [, ...] )]

    serde_name は、使用する SerDe を示します。WITH SERDEPROPERTIES 句を使用すると、SerDe で許可される 1 つ以上のカスタムプロパティを指定できます。

[STORED AS file_format]

テーブルデータのファイル形式を指定します。省略すると、デフォルトの TEXTFILE が使用されます。file_format のオプションは以下のとおりです。

  • SEQUENCEFILE

  • TEXTFILE

  • RCFILE

  • ORC

  • PARQUET

  • AVRO

  • ION

  • INPUTFORMAT input_format_classname OUTPUTFORMAT output_format_classname

[LOCATION 's3://amzn-s3-demo-bucket/[folder]/']

テーブルが作成される Amazon S3 内の基盤データの場所を指定します。ロケーションパスは、バケット名、またはバケット名と 1 つ以上のフォルダである必要があります。パーティションを使用する場合は、パーティションされたデータのルートを指定します。テーブルのロケーションの詳細については、「Amazon S3 でテーブルの場所を指定する」を参照してください。データ形式と許可については、「Amazon S3 に関する考慮事項」を参照してください。

フォルダやバケットの後にはスラッシュを使用します。ファイル名や glob 文字を使用しないでください。

を使用します。

s3://amzn-s3-demo-bucket/

s3://amzn-s3-demo-bucket/folder/

s3://amzn-s3-demo-bucket/folder/anotherfolder/

使用不可:

s3://amzn-s3-demo-bucket

s3://amzn-s3-demo-bucket/*

s3://amzn-s3-demo-bucket/mydatafile.dat

[TBLPROPERTIES ( ['has_encrypted_data'='true | false',] ['classification'='classification_value',] property_name=property_value [, ...] ) ]

定義済みのテーブルプロパティ ("comment" など) に加えて、テーブル定義のカスタムメタデータとしてキーと値のペアを指定します。

has_encrypted_data — Athena には、has_encrypted_data という組み込みプロパティがあります。このプロパティを true に設定し、LOCATION で指定する基になるデータを暗号化することを指定します。省略するか、そのワークグループの設定がクライアント側の設定を上書きしない場合、false が設定されます。省略するか、false に設定して基になるデータを暗号化すると、クエリはエラーになります。詳細については、「保管中の暗号化」を参照してください。

分類 — CloudTrail コンソールで Athena 用に作成されたテーブルは、classification プロパティの値として cloudtrail を追加されます。ETL ジョブを実行する場合、AWS Glue では、テーブルの作成時に classification プロパティを設定し、AWS Glue のデータ型を csv、parquet、orc、avro、json のいずれかに指定する必要があります。例えば、'classification'='csv' と指定します。このプロパティを指定しないと、ETL ジョブは失敗します。AWS Glue コンソール、API、または CLI を使用して後で指定できます。詳細については、「ETL ジョブのテーブルを作成する」と、「AWS Glue デベロッパーガイド」の「AWS Glue でジョブを作成する」を参照してください。

compression_level — compression_level プロパティは使用する圧縮レベルを指定します。このプロパティは、ZSTD 圧縮にのみ適用されます。有効な値は 1 から 22 です。デフォルト値は 3 です。詳細については、「ZSTD 圧縮レベルを使用する」を参照してください。

その他のテーブルプロパティの詳細については、「ALTER TABLE SET TBLPROPERTIES」を参照してください。

例

次のサンプル CREATE TABLE ステートメントは、Amazon S3 に保存されているタブ区切りの惑星データに基づいてテーブルを作成します。

CREATE EXTERNAL TABLE planet_data (
  planet_name string,
  order_from_sun int,
  au_to_sun float,
  mass float,
  gravity_earth float,
  orbit_years float,
  day_length float
  )
ROW FORMAT DELIMITED
FIELDS TERMINATED BY '\t'
STORED AS TEXTFILE
LOCATION 's3://amzn-s3-demo-bucket/tsv/'

以下の点に注意してください。

  • ROW FORMAT DELIMITED 句は、データが特定の文字で区切られていることを示します。

  • FIELDS TERMINATED BY '\t' 句は、TSV データ内のフィールドがタブ文字 ('\t') で区切られることを指定します。

  • STORED AS TEXTFILE 句は、データがプレーンテキストファイルとして Amazon S3 に保存されることを示します。

データをクエリするには、次のようなシンプルな SELECT ステートメントを使用できます。

SELECT * FROM planet_data

この例を使用して Athena で独自の TSV テーブルを作成するには、テーブル名と列名を独自のテーブルと列の名前とデータ型に置き換えてから、TSV ファイルが保存されている Amazon S3 パスをポイントするように LOCATION 句を更新します。

テーブル作成の詳細については、「Athena でテーブルを作成する」を参照してください。