17.10 - WRITE_NOS構文 - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL演算子およびユーザー定義関数

Product
Advanced SQL Engine
Teradata Database
Release Number
17.10
Release Date
2021年7月
Content Type
プログラミング リファレンス
管理
Publication ID
B035-1210-171K-JPN
Language
日本語 (日本)
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 ( { [DatabaseName.]AuthorizationObjectName |
       '{"Access_ID":"identification", "Access_Key":"secret_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' } ) ]
)
'{"Access_ID":"identification", "Access_Key":"secret_key"}'に太字で示した波括弧を入力する必要があります。これらの特定の波括弧は、WRITE_NOS文の一部です。

構文要素

[ 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
以下の形式の外部ストレージ システムを識別するURI
/connector/endpoint/bucket_or_container/prefix
LOCATION文字列は2048文字を超えることはできません。
AUTHORIZATION
[オプション]外部ストレージにアクセスするための許可。
どのプラットフォームでも、許可オブジェクト([DatabaseName.]AuthorizationObjectName)を指定できます。AuthorizationObjectNameに対するEXECUTE権限が必要です。
Amazon S3、Azure BLOBストレージおよびAzure Data Lake Storage Gen2では、許可オブジェクトまたはJSON形式の文字列のいずれかを指定することができます。この文字列は、外部ストレージにアクセスするためのUSER (identification)とPASSWORD (secret_key)を指定します。次の表は、USERおよびPASSWORD (CREATE AUTHORIZATIONコマンドで使用)でサポートされる信頼証明を示します。
システム/スキーマ USER PASSWORD
AWS アクセス キーID アクセス キー シークレット
Azure/共有キー ストレージ アカウント名 ストレージ アカウント キー
Azure共有アクセス署名(SAS) ストレージ アカウント名 アカウントSASトークン
Google Cloud (S3相互運用モード) アクセス キーID アクセス キー シークレット
Google Cloud (ネイティブ) クライアントの電子メール 秘密鍵
オンプレミス オブジェクト ストア アクセス キーID アクセス キー シークレット
パブリック アクセス オブジェクト ストア <空の文字列>

空の文字列を左右の区別がない一重引用符で囲む: USER ''

<空の文字列>

空の文字列を左右の区別がない一重引用符で囲む: PASSWORD ''

関数マッピングを使用してREAD_NOSのラッパーを定義する場合は、関数マッピングで許可を指定できます。関数マッピングでは、システム全体の許可ではなく、[ INVOKER | DEFINER ] TRUSTED のみを使用できます。
AWS IAM信頼証明がアクセスを提供する場合は、AUTHORIZATION句を省略できます。
STOREDAS
WRITE_NOSによって外部ストレージに作成されたオブジェクトは、Parquet形式でのみ書き込まれます。
NAMING
これにより、データ行を含むオブジェクトに外部ストレージ内で名前を付ける方法が決まります。
  • 固有の命名は、外部ストレージ内のオブジェクト名の一部として順序付け列の値を使用します。例えば、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
マニフェスト ファイルが書き込まれる完全修飾パスとファイル名を指定します。以下の形式を使用します。
/connector/end point/bucket_or_container/prefix/manifest_file_name
例:
/S3/ceph-s3.teradata.com/xz186000/manifest/manifest.json
MANIFESTFILEパラメータを含めないと、マニフェスト ファイルは書き込まれません。
MANIFESTONLY
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
外部ストレージ内の既存のマニフェスト ファイルが、同じ名前の新しいマニフェスト ファイルで上書きされるかどうかを決定します。デフォルトのFALSEの場合、マニフェスト ファイルがMANIFESTFILEの値と同じ名前の外部ストレージに存在すれば、WRITE_NOSはエラーを返します。
OVERWRITEは、MANIFESTONLY('TRUE')とともに使用する必要があります。
INCLUDE_ORDERING
INCLUDE_HASHBY
ORDER BY列およびHASH BY列とそれらの値を外部ストレージに書き込むかどうかを決定します。
MAXOBJECTSIZE
最大出力オブジェクトのサイズをメガバイト単位で指定します(max_object_sizeは4から16の数値)。デフォルトは、DBS制御のDefaultRowGroupSizeフィールドの値です。DBS制御の詳細については、Teradata Vantage™ - データベース ユーティリティ、B035-1102を参照してください。
COMPRESSION
外部ストレージに書き込まれるオブジェクトの圧縮に使用する圧縮アルゴリズムを決定します。
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>を参照してください。