WRITE_NOS構文 - Advanced SQL Engine - Teradata Database

Write_NOS (
  ON { [database_name.]table_name | (subquery) } 
     [ PARTITION BY column_name [,...] ORDER BY column_name [,...] |
       HASH BY column_name [,...] LOCAL ORDER BY column_name [,...] |
       LOCAL ORDER BY column_name [,...]]
  USING
    LOCATION('external_storage_path')
    AUTHORIZATION(' { "Access_ID":"your_access_id",
                      "Access_Key":"your_access_key" } ')
    STOREDAS('PARQUET')
    [NAMING('DISCRETE' | 'RANGE')]
    [MANIFESTFILE('manifest_name') ]
    [MANIFESTONLY('TRUE')]
    [OVERWRITE('TRUE' | 'FALSE')]
    [INCLUDE_ORDERING('TRUE' | 'FALSE')]
    [INCLUDE_HASHBY('TRUE' | 'FALSE')]
    [MAXOBJECTSIZE('max_object_size')]
    [COMPRESSION( { 'GZIP' | 'SNAPPY'} ) ]
)

[database_name.]table_name

外部ストレージに書き込むデータの取得先となるテーブルの名前。

subquery

外部ストレージに書き込むデータを返すクエリー。

PARTITION BY column_name [,...] ORDER BY column_name [,...]

HASH BY column_name [,...] LOCAL ORDER BY column_name [,...]

LOCAL ORDER BY column_name [,...]

これらの句によって、Vantageが、table_nameの行、またはsubqueryによって返された行をAMP間でソートおよび分割してからこれらの行を外部ストレージに書き込む方法を制御できます。これらの句は、外部ストレージ オブジェクト名(この名前には、それぞれのストアド オブジェクトに含まれる値がNAMINGオプションに即して反映される)に影響します。

• PARTITON BYは、各AMPで複数回(パーティションごとに1回) WRITE_NOSを呼び出し、パーティションごとに少なくとも1つのファイルを外部ストレージに書き込みます。PARTITION BYを指定する場合は、パーティション列をORDER BYリストに含める必要があります。
• HASH BYは、AMPごとに1回のみWRITE_NOSを呼び出し、AMPごとに少なくとも1つのファイルを外部ストレージに書き込みます。
• PARTITION BYまたはHASH BYの列リスト中にあるいずれかの列に含まれる値の種類が少なく、すべてのテーブル データを1つまたは少数のAMPにハッシュし、それがデータ スキュー発生の原因となる場合は、LOCAL ORDER BYのみを使用します。LOCAL ORDER BYは、パーティション化またはハッシュを行なう列に基づいてデータを再分散しないようにすることで、データ スキューを最小限に抑えます。代わりに、データはそれぞれのAMPで所定の位置に順序付けられた後に、外部ストレージに書き込まれます。

PARTITION BY、HASH BY、またはLOCAL ORDER BYに、最大10の列を指定できます。

結果をパーティション列でグループ化するクエリーを使用することで、外部ストレージへの書き込み前に、テーブルまたはサブクエリーに対して作成されるパーティションの数を確認できます。以下に例を示します。

SELECT COUNT(*) 
FROM (SELECT * FROM table 
      GROUP BY column1,column2)
 derived_table_name;

ORDER BYおよびLOCAL ORDER BYに使用される列に対する、次の制限に注意してください。

• データ型は、BYTEINT、SMALLINT、INTEGER、BIGINT、DATE、VARCHARに制限されます。
• VARCHAR列には、英数字と以下の特殊文字のみを含めることができます。

   - _ ! * ' ( ) 

• VARCHAR列は128文字に制限されています。

LOCATION('external_storage_path')

以下の形式の外部ストレージ システムを識別するURI

/connector/endpoint/bucket_or_container/prefix

LOCATION文字列は2048文字を超えることはできません。

AUTHORIZATION('

{ "Access_ID":"your_access_id","Access_Key":"your_access_key" } ')

外部ストレージ システムのアクセス情報を含む、JSON形式の名前と値のペア(NVP)のセット。

許可情報を保護するために、IAMロールを使用するか(Amazon S3リポジトリに定義されている場合)、許可の信頼証明を含むWRITE_NOSの関数マッピングを作成することを推奨します。以下に例を示します。

CREATE FUNCTION MAPPING WRITE_NOS_fm
FOR WRITE_NOS
AUTHORIZATION (' 
{ "Access_ID":"your_access_id","Access_Key":"your_access_key" } ');

関数マッピングを定義した後、WRITE_NOSを使用する代わりに、許可情報を明示的に渡さずにWRITE_NOS_fmを使用することができます。<Teradata Vantage™ - SQLデータ定義言語-構文規則および例、B035-1144>の「CREATE FUNCTION MAPPING」を参照してください。

STOREDAS('PARQUET')

WRITE_NOSによって外部ストレージに作成されたオブジェクトは、Parquet形式でのみ書き込まれます。

NAMING('DISCRETE' | 'RANGE')

これにより、データ行を含むオブジェクトに外部ストレージ内で名前を付ける方法が決まります。

• 固有の命名は、外部ストレージ内のオブジェクト名の一部として順序付け列の値を使用します。例えば、PARTITION BY句にORDER BY dateColumn, intColumnがある場合、外部ストレージに書き込まれるオブジェクトの固有の形式の名前には、オブジェクト名の一部としてそれらの列の値が含まれ、次のようになります。

  S3/ceph-s3.teradata.com/xz186000/2019-03-01/13/object_33_0_1.parquet

  2019-03-01は、最初の順序付け列であるdateColumnの値、13は2番目の順序付け列であるintColumnの値になります。このParquet形式の外部オブジェクトに格納されているすべての行には、これら2つの値が含まれます。
• 範囲の命名(デフォルト)には、オブジェクト名の一部として、順序付け列ごとのパーティションに含まれる値の範囲が含まれます。例えば、上記と同じORDER BYを使用すると、オブジェクト名は次のようになります。

  S3/ceph-s3.teradata.com/xz186000/2019-01-01/2019-03-02/9/10000/object_33_0_1.parquet

  ここで2019-01-01は、最初の順序付け列dateColumnのオブジェクトの最小値、2019-03-02はこのParquet形式の外部オブジェクトに格納されている行の最大値です。値9は、2番目の順序付け列intColumnの最小値、10000はその列の最大値です。

MANIFESTFILE('manifest_name')

マニフェスト ファイルが書き込まれる完全修飾パスとファイル名を指定します。以下の形式を使用します。

/connector/end point/bucket_or_container/prefix/manifest_file_name

以下に例を示します。

/S3/ceph-s3.teradata.com/xz186000/manifest/manifest.json

MANIFESTFILEパラメータを含めないと、マニフェスト ファイルは書き込まれません。

MANIFESTONLY('TRUE')

1つのマニフェスト ファイルのみを外部ストレージに書き込みます。

MANIFESTONLY('TRUE')を使用すると、実際のデータ オブジェクトは外部ストレージに書き込まれません。

また、外部ストレージにマニフェスト ファイルを作成するには、MANIFESTFILE('manifest_name')オプションを使用する必要があります。

このオプションを使用すると、データベースのアボートまたは再起動によってWRITE_NOS操作が失敗した場合、または全データが外部ストレージに書き込まれる前にネットワーク接続の問題によってWRITE_NOS操作が中断、停止した場合に、新しいマニフェスト ファイルを作成できます。

マニフェストは、WRITE_NOSに入力されるテーブルまたはクエリー結果セットから作成されます。この入力は、ストレージ オブジェクトの名前とサイズのリストであり、オブジェクトごとに1行が含まれる必要があります。

MANIFESTONLYを含むWRITE_NOSへの入力は、次のようにREAD_NOSを組み込むことができ、ここではWRITE_NOSおよびREAD_NOSに対する関数マッピングを使用しています。

SELECT * FROM WRITE_NOS_fm 
(ON 
  (SELECT Location, ObjectLength 
   FROM READ_NOS_fm 
   (ON 
     (SELECT CAST(NULL AS JSON CHARACTER SET UNICODE) )
     USING
       LOCATION('your_location')
       RETURNTYPE('NOSREAD_KEYS') 
  ) AS d1 )
USING
 MANIFESTFILE('your_location/orders_manifest.json')
 MANIFESTONLY('TRUE')
 OVERWRITE('TRUE')
) AS d;

このようなクエリーは、WRITE_NOS操作がマニフェスト ファイルを作成する前に失敗した場合に使用できます。READ_NOSを使用して作成される新しいマニフェスト ファイルは、現在外部ストレージ場所にある全データ オブジェクトを反映し、また不完全なWRITE_NOS操作によって生じたデータ オブジェクトの判断にも役立ちます。詳細については、<Teradata Vantage™- Native Object Store入門ガイド、B035-1214>を参照してください。

OVERWRITE({'TRUE' | 'FALSE'})

外部ストレージ内の既存のマニフェスト ファイルが、同じ名前の新しいマニフェスト ファイルで上書きされるかどうかを決定します。デフォルトのFALSEの場合、マニフェスト ファイルがMANIFESTFILEの値と同じ名前の外部ストレージに存在すれば、WRITE_NOSはエラーを返します。

OVERWRITEは、MANIFESTONLY('TRUE')とともに使用する必要があります。

INCLUDE_ORDERING('TRUE' | 'FALSE')

INCLUDE_HASHBY('TRUE' | 'FALSE')

ORDER BY列およびHASH BY列とそれらの値を外部ストレージに書き込むかどうかを決定します。

MAXOBJECTSIZE('max_object_size')

最大出力オブジェクトのサイズをメガバイト単位で指定します(max_object_sizeは4から16の数値)。デフォルトは、DBS制御のDefaultRowGroupSizeフィールドの値です。DBS制御の詳細については、<Teradata Vantage™ - データベース ユーティリティ、B035-1102>を参照してください。

COMPRESSION('GZIP' | 'SNAPPY')

外部ストレージに書き込まれるオブジェクトの圧縮に使用する圧縮アルゴリズムを決定します。

Parquetファイルの圧縮は、ファイル全体ではなくParquetファイルの部分的な内部で行なわれるため、外部オブジェクトでのファイル拡張子は.parquetのままです。

戻り値

WRITE_NOSは、渡されたオプションに従ってデータベースのデータを外部ストレージに書き込み、外部ストレージに書き込んだオブジェクトに関する情報を返します。返される値は、次の列を含むテーブルです。

NodeId

外部オブジェクトに書き込まれたデータを含むSQL Engineノードを識別するINTEGER値。

AmpId

外部オブジェクトに書き込まれたデータを含むAMPを識別するINTEGER値。

シーケンス

同じパスと名前を持つ複数のオブジェクトが存在すると名前が競合するので、それを避けるため外部オブジェクトを一意に特定するBIGINT値。

ObjectName

次の形式による完全なオブジェクト ファイル名としての、VARCHAR(1024) UNICODE値。

/connector/endpoint/bucket_or_container/prefix/object_file_name

• connector
• endpoint
• bucket_or_container
• prefixは、NAMINGオプション、固有の命名または範囲の命名に依存します。
• object_file_nameは次の形式になります。

  <Location Path>/[<Discrete Naming or Range Naming>]/object_<Node_ID>_<AMP_ID>_<Sequence>.parquet

例:

/S3/ceph-s3.mycompany.com/test-bucket/2020-06-01/object_33_0_1.parquet

ObjectSize

外部オブジェクトのサイズ(バイト単位)であるBIGINT値。

RecordCount

外部オブジェクト内のSQL Engineレコード数を示すBIGINT値。

使用上の注意

WRITE_NOSは、外部ストレージのデータ オブジェクトを上書きしません。WRITE_NOS操作で、パスと名前が正確に一致する書き込み対象のオブジェクトが検出されると、操作が停止しエラーが生成されます。

この場合、WRITE_NOS操作は停止し、エラーを返し、MANIFESTFILEオプションを使用した場合でもマニフェスト ファイルを作成しません。書き込み操作で、何らかのデータ オブジェクトが外部ストレージの場所に書き込まれた場合は、同じWRITE_NOS操作を繰り返す前に手動でそれらを削除する必要があります。同じWRITE_NOS操作を繰り返す前に、外部ストレージから除去する必要があるデータ オブジェクトを判別する方法については、<Teradata Vantage™- Native Object Store入門ガイド、B035-1214>を参照してください。