入出力ファイル形式
TiDB Cloud Lake は、データのロードやアンロードのソースおよびターゲットとして、さまざまなファイル形式を受け入れます。このページでは、サポートされているファイル形式と利用可能なオプションについて説明します。
構文
ステートメントでファイル形式を指定するには、次の構文を使用します。
-- Specify a standard file format
... FILE_FORMAT = ( TYPE = { CSV | TSV | NDJSON | PARQUET | LANCE | ORC | AVRO } [ formatTypeOptions ] )
-- Specify a custom file format
... FILE_FORMAT = ( FORMAT_NAME = '<your-custom-format>' )
TiDB Cloud Lake は、COPY または Select ステートメントで使用するファイル形式を、次の優先順位で決定します。
- まず、ステートメント内で FILE_FORMAT が明示的に指定されているかを確認します。
- 操作で FILE_FORMAT が指定されていない場合は、stage 作成時にその stage に対して最初に定義されたファイル形式を使用します。
- stage 作成時にファイル形式が定義されていない場合、TiDB Cloud Lake はデフォルトで PARQUET 形式を使用します。
formatTypeOptions
formatTypeOptions には、ファイルに関するその他の形式の詳細を記述するための 1 つ以上のオプションが含まれます。オプションはファイル形式によって異なります。サポートされている各ファイル形式で利用可能なオプションについては、以下のセクションを参照してください。
formatTypeOptions ::=
RECORD_DELIMITER = '<character>'
FIELD_DELIMITER = '<character>'
SKIP_HEADER = <integer>
QUOTE = '<character>'
ESCAPE = '<character>'
NAN_DISPLAY = '<string>'
ROW_TAG = '<string>'
COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | XZ | NONE
CSV オプション
TiDB Cloud Lake の CSV は RFC 4180 に準拠しており、次の条件に従います。
- 文字列に QUOTE、ESCAPE、RECORD_DELIMITER、または FIELD_DELIMITER の文字が含まれる場合、その文字列は引用符で囲む必要があります。
- 引用符で囲まれた文字列内では、QUOTE を除き、どの文字もエスケープされません。
- FIELD_DELIMITER と QUOTE の間に空白を入れてはいけません。
RECORD_DELIMITER
ファイル内でレコードを区切る区切り文字です。
利用可能な値:
\r\n#や|などの、1 バイトの非英数字文字- エスケープ文字付きの文字:
\b,\f,\r,\n,\t,\0,\xHH
デフォルト: \n
FIELD_DELIMITER
レコード内でフィールドを区切る区切り文字です。
利用可能な値:
#や|などの、1 バイトの非英数字文字- エスケープ文字付きの文字:
\b,\f,\r,\n,\t,\0,\xHH
デフォルト: , (カンマ)
QUOTE (ロードのみ)
値を引用符で囲むために使用する文字です。
データのロードでは、文字列に QUOTE、ESCAPE、RECORD_DELIMITER、または FIELD_DELIMITER の文字が含まれていない限り、引用符は必須ではありません。
利用可能な値: '\'', '"', または '`'(バッククォート)
デフォルト: '"'
ESCAPE
QUOTE 自体に加えて、引用符で囲まれた値の中で引用符文字をエスケープするために使用する文字です。
CSV の一部のバリアントでは、引用符を二重にしてエスケープする代わりに、\ のような特別なエスケープ文字を使って引用符をエスケープします。
利用可能な値: '\\' または '' (空。二重引用のみを使用することを意味します)
デフォルト: ''
SKIP_HEADER (ロードのみ)
ファイルの先頭からスキップする行数です。
デフォルト: 0
TRIM_SPACE (ロードのみ)
型変換の前に、各フィールド値の先頭および末尾から ASCII 空白文字を削除します。
削除対象の文字セットは ASCII 空白文字に固定されており、スペース、タブ、LF、CR、VT、FF が含まれます。
CSV では、csv-core がフィールドを抽出した後にトリミングが行われるため、引用符で囲まれたフィールド内容もトリミングされます。
デフォルト: false
OUTPUT_HEADER (アンロードのみ)
カラム名を含むヘッダー行を出力に含めます。
デフォルト: false
QUOTE_STYLE (アンロードのみ)
出力時に CSV の値をどのように引用符で囲むかを制御します。
デフォルト: QUOTE_NOT_NULL
NAN_DISPLAY
"NaN" (Not-a-Number) を表す文字列です。
利用可能な値: リテラル 'nan' または 'null' のみ (大文字小文字は区別されません)
デフォルト: 'NaN'
NULL_DISPLAY
NULL 値を表す文字列です。
データのロード時、引用符なしで一致した値は常に NULL になります。引用符付きで一致した値は、ALLOW_QUOTED_NULLS=true の場合にのみ NULL に変換されます。
デフォルト: '\N'
ALLOW_QUOTED_NULLS (ロードのみ)
引用符付き文字列を NULL 値に変換できるようにします。
NULL_DISPLAY に一致する引用符付き文字列は、このフラグが true の場合にのみ NULL になります。引用符なしで一致した値は、このオプションに関係なく NULL になります。
デフォルト: false
ERROR_ON_COLUMN_COUNT_MISMATCH (ロードのみ)
データファイル内のカラム数が宛先テーブルのカラム数と一致しない場合にエラーを返します。
デフォルト: true
EMPTY_FIELD_AS (ロードのみ)
引用符なしの空フィールド (つまり ,,) を変換する値です。
デフォルト: NULL
QUOTED_EMPTY_FIELD_AS (ロードのみ)
引用符付きの空フィールド (つまり ,"",) を変換する値です。
利用可能な値: EMPTY_FIELD_AS と同じ
デフォルト: STRING
BINARY_FORMAT
Binary カラムのエンコード形式です。
利用可能な値: HEX または BASE64
デフォルト: HEX
GEOMETRY_FORMAT
Geometry カラムのエンコード形式です。
利用可能な値: EWKT, WKT, WKB, EWKB, GEOJSON
デフォルト: EWKT
ENCODING (ロードのみ)
ソースファイルの文字セットエンコーディングです。UTF-8 以外のエンコーディングに設定した場合、フィールド解析の前にファイル内容は UTF-8 に変換されます。
Encoding Standard で認識される任意のラベルを使用できます（例: UTF-8, GBK, SHIFT_JIS, EUC-KR, ISO-8859-1）。このラベルは、ファイル形式 / stage の作成時に検証されます。
デフォルト: UTF-8
ENCODING_ERROR_MODE (ロードのみ)
宣言されたエンコーディングで無効なバイト列（またはエンコーディングが UTF-8 の場合は無効な UTF-8）をどのように処理するかを指定します。
デフォルト: STRICT
COMPRESSION
圧縮アルゴリズムです。
デフォルト: NONE
TSV オプション
TiDB Cloud Lake TSV（v1.2.891-nightly 以降では TEXT とも呼ばれます）は、どちらの名前でも同じ形式とオプションを使用します。このページでは、古いサーバーバージョンとの互換性のため、主要な用語として TSV を使用します。
TiDB Cloud Lake TSV には次の条件があります。
- RECORD_DELIMITER、FIELD_DELIMITER は、区切り文字の衝突 を解決するために
\でエスケープされます - 区切り文字に加えて、次の文字もエスケープされます:
\b,\f,\r,\n,\t,\0,\\,\'。 - QUOTE は形式の一部ではありません。
- NULL は
\Nとして表されます。
RECORD_DELIMITER
ファイル内でレコードを区切る文字です。
利用可能な値:
\r\n#や|などの任意の文字。- エスケープ文字付きの文字:
\b,\f,\r,\n,\t,\0,\xHH
デフォルト: \n
FIELD_DELIMITER
レコード内でフィールドを区切る文字です。
利用可能な値:
#や|などの英数字以外の文字。- エスケープ文字付きの文字:
\b,\f,\r,\n,\t,\0,\xHH
デフォルト: \t (TAB)
SKIP_HEADER (ロードのみ)
CSV の SKIP_HEADER オプションと同じです。
TRIM_SPACE (ロードのみ)
CSV の TRIM_SPACE オプションと同じです。
OUTPUT_HEADER (アンロードのみ)
CSV の OUTPUT_HEADER オプションと同じです。
NAN_DISPLAY
CSV の NAN_DISPLAY オプションと同じです。
NULL_DISPLAY
CSV の NULL_DISPLAY オプションと同じです。
EMPTY_FIELD_AS (ロードのみ)
CSV の EMPTY_FIELD_AS オプションと同じです。
Note: TSV のデフォルトは FIELD_DEFAULT です（デフォルトが NULL の CSV とは異なります）。
デフォルト: FIELD_DEFAULT
ERROR_ON_COLUMN_COUNT_MISMATCH (ロードのみ)
CSV の ERROR_ON_COLUMN_COUNT_MISMATCH オプションと同じです。
ENCODING (ロードのみ)
CSV の ENCODING オプションと同じです。
ENCODING_ERROR_MODE (ロードのみ)
CSV の ENCODING_ERROR_MODE オプションと同じです。
COMPRESSION
CSV の COMPRESSION オプションと同じです。
NDJSON オプション
NULL_FIELD_AS (ロードのみ)
null を変換する値です。
MISSING_FIELD_AS (ロードのみ)
欠落しているフィールドを変換する値です。
NULL_IF (ロードのみ)
文字列のリストです。ソースファイル内のフィールド値がこれらの文字列のいずれかと一致する場合、その値は NULL としてロードされます。一致は完全一致かつ大文字小文字を区別します。
Syntax: NULL_IF = ('value1', 'value2', ...)
デフォルト: 空 (追加の NULL マーカーなし)
COMPRESSION
CSV の COMPRESSION オプションと同じです。
PARQUET オプション
MISSING_FIELD_AS (ロードのみ)
欠落しているフィールドを変換する値です。
NULL_IF (ロードのみ)
NDJSON の NULL_IF オプションと同じです。
USE_LOGIC_TYPE (ロードのみ)
有効にすると、ロード時に Parquet の論理型（例: DATE、TIMESTAMP、DECIMAL などのアノテーション）を使用して対象カラム型を決定します。無効にすると、物理ストレージ型のみが考慮されます。
デフォルト: true
COMPRESSION (アンロードのみ)
parquet ファイル内部ブロックの圧縮アルゴリズムです。
LANCE オプション
LANCE は、COPY INTO <location> を使用したアンロードでのみサポートされます。
CSV、TSV、NDJSON、Parquet と比較すると、Lance エクスポートでは、TiDB Cloud Lake が直接読み戻せる単独ファイルは 1 つも、または複数も生成されません。代わりに、TiDB Cloud Lake は .lance データファイルと、_versions/ などのデータセットメタデータを含むデータセットディレクトリを書き込みます。
このため、Lance は、Python lance (pip install pylance) などの Lance ツールを使ってデータセットを利用する、下流の機械学習、ベクトル、Arrow ベースのワークフローにより適しています。
フォーマット固有のオプション
Lance にはフォーマット固有のオプションはありません。次を使用します。
FILE_FORMAT = (TYPE = LANCE)
動作上の違い
ORC オプション
MISSING_FIELD_AS (ロードのみ)
欠落しているフィールドが変換される値です。
AVRO オプション
MISSING_FIELD_AS (ロードのみ)
欠落しているフィールドが変換される値です。
NULL_IF (ロードのみ)
NDJSON の NULL_IF オプションと同じです。
USE_LOGIC_TYPE (ロードのみ)
有効にすると、ロード時に対象カラム型を決定するために Avro の論理型（例: date、timestamp-millis、decimal）が使用されます。無効にすると、基になる Avro 型のみが考慮されます。
デフォルト: true