Tunnel コマンドを使用してデータのアップロードとダウンロードを行う - MaxCompute

ご利用のローカル環境と MaxCompute 間でデータをアップロードおよびダウンロードするには、トンネルコマンドを使用します。トンネルは、大規模なデータインジェストおよび抽出向けに、バッチ転送および増分データ転送をサポートしています。

サブコマンド

tunnel <subcommand> [options] [args]

サブコマンド	エイリアス	説明
`upload`	`u`	ローカルデータを MaxCompute テーブルにアップロードします。
`download`	`d`	MaxCompute テーブルからデータをローカルファイルにダウンロードします。
`upsert`	`us`	UPDATE および INSERT セマンティクスを使用してデータを書き込みます（Transaction Table 2.0 のみ）。
`resume`	`r`	中断されたアップロードセッションを再開します。
`show`	`s`	転送履歴およびログを表示します。
`purge`	`p`	セッションディレクトリをクリアします。
`help`	`h`	ヘルプ情報を表示します。

コマンド間の関係：データ転送には upload、download、または upsert を使用します。アップロードが中断された場合は、resume を使用して停止した位置から続行します。show を使用して転送履歴を確認し、purge を使用して古いセッションログをクリーンアップします。

アップロード

ローカルデータを MaxCompute テーブルに追加モードでアップロードします。テーブル内の既存データは上書きされず、既存データと新しくアップロードされたデータが共存します。

各アップロード操作は、1 つのテーブルまたは 1 つのパーティションを対象とします。パーティションテーブルの場合、最下位レベルのパーティションを指定してください。

構文

tunnel upload [options] <path> <[project.]table[/partition]>

例：

# 2 レベルのパーティションテーブルに log.txt をアップロード（ファイルは MaxCompute クライアントの bin ディレクトリ内）
tunnel upload log.txt test_project.test_table/p1="b1",p2="b2"

# 絶対パスからアップロード（Windows）
tunnel upload D:\test\log.txt test_project.test_table/p1="b1",p2="b2"

# アップロード前にファイルをスキャンしてテーブルスキーマに対して検証
tunnel upload log.txt test_table --scan=true

# 追加ではなくパーティションを上書き
tunnel upload -ow true data.txt sale_detail/sale_date=201312,region=hangzhou

macOS では、path は /Users/username/MaxCompute/bin/file.txt のような絶対パスである必要があります。

アップロードはデフォルトで TXT ファイルをサポートしています。CSV ファイルをアップロードするには、-cf true を設定し、最新のMaxCompute クライアントを使用してください。CSV 形式ではファイル分割はサポートされていません。

パラメーター

必須

パラメーター	説明
`path`	ローカルデータファイルへのパス。MaxCompute クライアントの `bin` ディレクトリ内のファイルはファイル名のみで参照できます。他のディレクトリのファイルには完全なパスが必要です。
`[project.]table[/partition]`	対象テーブル。テーブルが別のプロジェクトにある場合はプロジェクト名を含めてください。パーティションテーブルの場合は、最下位レベルのパーティションを指定してください。

オプション — フォーマット

オプション	デフォルト	説明
`-c`、`-charset`	（未設定）	ファイルの文字コード。未設定の場合、生データが変換なしでアップロードされます。デフォルトのエンコーディングは UTF-8 です。
`-cf`、`-csv-format`	`false`	`true` に設定すると、CSV ファイルをアップロードします。有効にすると、ファイル分割はサポートされません。
`-fd`、`-field-delimiter`	`,`	列区切り文字。複数文字および `\u0001` のような Unicode エスケープをサポートします。行区切り文字を含めることはできません。
`-rd`、`-record-delimiter`	`\r\n`	行区切り文字。複数文字、Unicode エスケープ、およびエスケープシーケンス `\r`、`\n`、`\t` をサポートします。
`-h`、`-header`	`false`	ファイルにヘッダー行がある場合は `true` に設定します。ヘッダー行はアップロード時にスキップされます。
`-ni`、`-null-indicator`	`""`（空文字列）	ソースファイル内で NULL を表す文字列。未設定の場合、空文字列は NULL として扱われます。
`-dfp`、`-date-format-pattern`	`yyyy-MM-dd HH:mm:ss`	DATETIME のフォーマットパターン。ミリ秒精度の場合は `yyyy-MM-dd HH:mm:ss.SSS` を使用します。「データの型エディション」をご参照ください。

オプション — エラー処理

オプション	デフォルト	説明
`-s`、`-scan`	`true`	アップロード前のファイルスキャンを制御します。`true`：最初にスキャンし、有効な場合にアップロードします。`false`：スキャンをスキップして直接アップロードします。`only`：アップロードせずにスキャンのみ実行します。
`-ss`、`-strict-schema`	`true`	`false` に設定すると、緩やかなスキーママッチングが許可されます。余分な列は破棄され、不足している列は NULL で埋められます。
`-dbr`、`-discard-bad-records`	`false`	`true` に設定すると、不良レコード（余分な列、不足している列、または型の不一致）をスキップして失敗を回避します。`false` の場合、最初に検出された不良レコードでアップロードが停止し、エラーが返されます。`-mbr` と併用して、スキップする不良レコードの最大数を設定します。
`-mbr`、`-max-bad-records`	`1000`	スキップする不良レコードの最大数。`-dbr true` が設定されている場合にのみ有効です。不良レコードの数がこの制限を超えると、アップロードは停止します。

オプション — パフォーマンス

オプション	デフォルト	説明
`-t`、`-threads`	`1`	同時アップロードスレッド数。大きなファイルのスループットを向上させるには、この値を増やしてください。
`-bs`、`-block-size`	`100` MiB	各アップロードブロックのサイズ。1 MiB = 1,048,576 バイト。
`-cp`、`-compress`	`true`	ネットワーク使用量を削減するために、アップロード前にデータを圧縮します。

オプション — セッション

オプション	デフォルト	説明
`-acp`、`-auto-create-partition`	`false`	対象パーティションが存在しない場合、自動的に作成します。
`-ow`、`-overwrite`	`false`	対象テーブルまたはパーティションを追加ではなく上書きするには、`true` に設定します。
`-sd`、`-session-dir`	クライアントプラグインディレクトリ	セッション状態を保存するディレクトリ。
`-te`、`-tunnel_endpoint`	（未設定）	トンネルエンドポイント。「エンドポイント」をご参照ください。
`-tz`、`-time-zone`	ローカルタイムゾーン	DATETIME データのタイムゾーン。デフォルトはローカルタイムゾーン（例：`Asia/Shanghai`）です。「タイムゾーン」をご参照ください。
`-time`	`false`	アップロード完了後に経過時間を追跡して表示します。

例：パーティションの上書き

パーティションテーブルを作成し、初期パーティションを追加します。

CREATE TABLE IF NOT EXISTS sale_detail(
      shop_name     STRING,
      customer_id   STRING,
      total_price   DOUBLE)
PARTITIONED BY (sale_date STRING, region STRING);

ALTER TABLE sale_detail ADD PARTITION (sale_date='201312', region='hangzhou');

初期データをアップロードします（data.txt には shopx,x_id,100 および shopy,y_id,200 が含まれています）。

tunnel upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou

クエリ結果：

+------------+-------------+-------------+------------+------------+
| shop_name  | customer_id | total_price | sale_date  | region     |
+------------+-------------+-------------+------------+------------+
| shopx      | x_id        | 100.0       | 201312     | hangzhou   |
| shopy      | y_id        | 200.0       | 201312     | hangzhou   |
+------------+-------------+-------------+------------+------------+

data.txt を更新して shopx,x_id,300 および shopy,y_id,400 を含めるようにし、パーティションを上書きします。

tunnel upload -ow true data.txt sale_detail/sale_date=201312,region=hangzhou

上書き後のクエリ結果：

+------------+-------------+-------------+------------+------------+
| shop_name  | customer_id | total_price | sale_date  | region     |
+------------+-------------+-------------+------------+------------+
| shopx      | x_id        | 300.0       | 201312     | hangzhou   |
| shopy      | y_id        | 400.0       | 201312     | hangzhou   |
+------------+-------------+-------------+------------+------------+

ダウンロード

MaxCompute テーブルまたは特定のインスタンスの実行結果からデータをローカルファイルにダウンロードします。

各ダウンロード操作は、1 つのテーブルまたは 1 つのパーティションを対象とします。パーティションテーブルの場合、最下位レベルのパーティションを指定してください。

前提条件

ダウンロードする前に、対象テーブルに対するダウンロード権限があることを確認してください。権限がない場合は、プロジェクトオーナーまたは Super_Administrator ロールを持つユーザーにアクセス権の付与を依頼してください。「ポリシーに基づくアクセスの制御」をご参照ください。

構文

# テーブルまたはパーティションからダウンロード
tunnel download [options] <[project.]table[/partition]> <path>

# インスタンスの実行結果をダウンロード
tunnel download [options] instance://<[project/]instance_id> <path>

例：

# 2 レベルのパーティションテーブルをローカルファイルにダウンロード
tunnel download test_project.test_table/p1="b1",p2="b2" test_table.txt

# 特定のディレクトリにダウンロード（Windows）
tunnel download test_project.test_table/p1="b1",p2="b2" D:\test\test_table.txt

# 特定のインスタンスの実行結果をダウンロード
tunnel download instance://test_project/test_instance log.txt

ダウンロードはデフォルトで TXT ファイルをサポートしています。CSV ファイルをダウンロードするには、-cf true を設定し、最新のMaxCompute クライアントを使用してください。-cf true が設定されている場合、デリミタはカンマ（,）に固定され、-fd 設定は無視されます。

パラメーター

必須

パラメーター	説明
`path`	ダウンロードファイルを保存するパス。MaxCompute クライアントの `bin` ディレクトリ内のファイルはファイル名のみで参照できます。他のディレクトリのファイルには完全なパスが必要です。
`[project.]table[/partition]`	ソーステーブル。テーブルが別のプロジェクトにある場合はプロジェクト名を含めてください。パーティションテーブルの場合は、最下位レベルのパーティションを指定してください。
`[project/]instance_id`	インスタンスの実行結果をダウンロードするためのインスタンス ID。

オプション — フォーマット

オプション	デフォルト	説明
`-c`、`-charset`	（未設定）	ファイルの文字コード。未設定の場合、生データが変換なしでダウンロードされます。
`-cf`、`-csv-format`	`false`	CSV ファイルとしてダウンロードするには `true` に設定します。有効にすると、デリミタは `,` に固定され、`-fd` 設定は無視されます。
`-ci`、`-columns-index`	（すべての列）	ダウンロードする列インデックスのカンマ区切りリスト（0 ベース）。
`-cn`、`-columns-name`	（すべての列）	ダウンロードする列名のカンマ区切りリスト。
`-fd`、`-field-delimiter`	`,`	列区切り文字。複数文字および `\u0001` のような Unicode エスケープをサポートします。`-cf true` が設定されている場合は無視されます。
`-rd`、`-record-delimiter`	`\r\n`	行区切り文字。複数文字、Unicode エスケープ、およびエスケープシーケンス `\r`、`\n`、`\t` をサポートします。
`-h`、`-header`	`false`	ダウンロードファイルにヘッダー行を含めるには `true` に設定します。`-t` が `1` より大きい場合は使用できません。
`-ni`、`-null-indicator`	`""`（空文字列）	出力ファイル内で NULL 値を表す文字列。未設定の場合、NULL 値は空文字列として表示されます。
`-dfp`、`-date-format-pattern`	`yyyy-MM-dd HH:mm:ss`	DATETIME のフォーマットパターン。
`-e`、`-exponential`	`false`	DOUBLE 値に指数表記を使用するには `true` に設定します。`false` の場合、最大 20 桁が保持されます。
`-limit`	（未設定）	ダウンロードするレコードの最大数。未設定の場合、すべてのレコードがダウンロードされます。

オプション — パフォーマンス

オプション	デフォルト	説明
`-t`、`-threads`	`1`	同時ダウンロードスレッド数。`-h true` が設定されている場合は `1` より大きくすることはできません。
`-cp`、`-compress`	`true`	ネットワーク使用量を削減するために、ダウンロード中にデータを圧縮します。

オプション — セッション

オプション	デフォルト	説明
`-sd`、`-session-dir`	クライアントプラグインディレクトリ	セッション状態を保存するディレクトリ。
`-te`、`-tunnel_endpoint`	（未設定）	トンネルエンドポイント。「エンドポイント」をご参照ください。
`-tz`、`-time-zone`	ローカルタイムゾーン	DATETIME データのタイムゾーン（例：`Asia/Shanghai`）。「タイムゾーン」をご参照ください。
`-time`	`false`	ダウンロード完了後に経過時間を追跡して表示します。

アップサート

UPDATE および INSERT セマンティクスを使用して、Transaction Table 2.0 テーブルにデータを書き込みます。一致するレコードが存在しない場合は新しいレコードを挿入し、見つかった場合は既存のレコードを更新します。

前提条件

MaxCompute クライアント（odpscmd）バージョン V0.47 以降
対象テーブルが Transaction Table 2.0 テーブルであること

構文

tunnel upsert [options] <path> <[project.]table[/partition]>

例：

tunnel upsert log.txt test_project.test_table/p1="b1",p2="b2"

アップサートはデフォルトで TXT ファイルをサポートしています。CSV ファイルからアップサートするには、-cf true を設定し、最新のMaxCompute クライアントを使用してください。

パラメーター

必須

パラメーター	説明
`path`	ローカルデータファイルへのパス。MaxCompute クライアントの `bin` ディレクトリ内のファイルはファイル名のみで参照できます。他のディレクトリのファイルには完全なパスが必要です。macOS の場合は絶対パスである必要があります。
`[project.]table[/partition]`	対象テーブル。テーブルが別のプロジェクトにある場合はプロジェクト名を含めてください。パーティションテーブルの場合は、最下位レベルのパーティションを指定してください。

オプション — フォーマット

オプション	デフォルト	説明
`-c`、`-charset`	（未設定）	ファイルの文字コード。未設定の場合、生データが変換なしでアップロードされます。
`-cf`、`-csv-format`	`false`	CSV ファイルからアップサートするには `true` に設定します。
`-fd`、`-field-delimiter`	`,`	列区切り文字。複数文字および Unicode エスケープをサポートします。行区切り文字を含めることはできません。
`-rd`、`-record-delimiter`	`\n`	行区切り文字。アップサートのデフォルトは `\n` であり、アップロード（`\r\n`）とは異なります。
`-h`、`-header`	`false`	ファイルにヘッダー行がある場合は `true` に設定します。ヘッダー行はスキップされます。
`-ni`、`-null-indicator`	`""`（空文字列）	ソースファイル内で NULL を表す文字列。未設定の場合、空文字列は NULL として扱われます。
`-dfp`、`-date-format-pattern`	`yyyy-MM-dd HH:mm:ss`	DATETIME のフォーマットパターン。ミリ秒精度の場合は `yyyy-MM-dd HH:mm:ss.SSS` を使用します。「データの型エディション」をご参照ください。

オプション — エラー処理

オプション	デフォルト	説明
`-ss`、`-strict-schema`	`true`	`false` に設定すると、余分な列は破棄され、不足している列は NULL で埋められます。
`-dbr`、`-discard-bad-records`	`false`	`true` に設定すると、失敗せずに不良レコードをスキップします。`-mbr` と併用して、スキップするレコード数を制限します。
`-mbr`、`-max-bad-records`	`1000`	スキップする不良レコードの最大数。`-dbr true` が設定されている場合にのみ有効です。不良レコードの数がこの制限を超えると、操作は停止します。

オプション — パフォーマンス

オプション	デフォルト	説明
`-bs`、`-block-size`	`100` MiB	各アップロードブロックのサイズ。1 MiB = 1,048,576 バイト。
`-cp`、`-compress`	`true`	ネットワーク使用量を削減するために、アップロード前にデータを圧縮します。

オプション — セッション

オプション	デフォルト	説明
`-acp`、`-auto-create-partition`	`false`	対象パーティションが存在しない場合、自動的に作成します。
`-qn`、`-quota_name`	（未設定）	MaxCompute にアクセスする際に使用するトンネルクォータ。MaxCompute コンソールのワークスペース > クォータでクォータ名を確認できます。「新しい MaxCompute コンソールでのクォータ管理」をご参照ください。
`-sd`、`-session-dir`	クライアントプラグインディレクトリ	セッション状態を保存するディレクトリ。
`-te`、`-tunnel_endpoint`	（未設定）	トンネルエンドポイント。「エンドポイント」をご参照ください。
`-tz`、`-time-zone`	ローカルタイムゾーン	DATETIME データのタイムゾーン（例：`Asia/Shanghai`）。「タイムゾーン」をご参照ください。
`-time`	`false`	操作完了後に経過時間を追跡して表示します。

履歴書

中断されたアップロードセッションを再開します。再開できるのはアップロードのみで、ダウンロードは再開できません。

構文

tunnel resume [session_id] [-force]

パラメーター	説明
`session_id`	必須。失敗したアップロードセッションの ID。`tunnel show history` から取得します。
`-f`、`-force`	確認なしでセッションを強制的に再開します。

例

odps@ project_name>tunnel resume 20150610xxxxxxxxxxx70a002ec60c -force;
start resume
20150610xxxxxxxxxxx70a002ec60c
Upload session: 20150610xxxxxxxxxxx70a002ec60c
Start upload:d:\data.txt
Resume 1 blocks
2015-06-10 16:46:42     upload block: '1'
2015-06-10 16:46:42     upload block complete, blockid=1
upload complete, average speed is 0 KB/s
OK

表示

転送履歴およびログを表示します。

構文

# 転送履歴を表示
tunnel show history [-n <number>]

# 最近の転送のログを表示
tunnel show log

-n <number>：表示する履歴エントリの数。デフォルトでは最大 500 件のエントリが保存されます。

セッションステータス値

各履歴エントリには、セッション ID、ステータス、実行されたコマンドが表示されます。ステータス値は次のとおりです。

ステータス	説明
`success`	転送がエラーなく完了しました。
`bad`	転送は完了しましたが、一部のレコードがスキップされました（`-dbr true` が必要）。
`failed`	転送が失敗し、データは書き込まれませんでした。

例

保存されているすべての履歴を表示します。

tunnel show history

出力：

20230505xxxxxxxxxxxxxx0b0d5b3c  bad     'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -dbr true -time true'
20230505xxxxxxxxxxxxxx0ad720a3  failed  'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -time true'
20230505xxxxxxxxxxxxxx0ad5ca68  bad     'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -dbr true'
......

最新の 5 件を表示します。

tunnel show history -n 5

出力：

20230505xxxxxxxxxxxxxx0aa48c4b  success 'download sale_detail/sale_date=201312,region=hangzhou result.txt'
20230505xxxxxxxxxxxxxx0aa6165c  success 'download sale_detail/sale_date=201312,region=hangzhou result.txt'
20230505xxxxxxxxxxxxxx0af11472  failed  'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -s false'
20230505xxxxxxxxxxxxxx0b464374  success 'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -s false'
20230505xxxxxxxxxxxxxx02dbb6bd  failed  'upload d:\data.txt sale_detail/sale_date="201312",region="hangzhou" -s false'

パージ

セッションディレクトリからセッション履歴をクリアします。

構文

tunnel purge [n]

n：クリアする履歴の日数。デフォルト：3（過去 3 日間のログをクリア）。

例：過去 5 日間のログをクリアします。

tunnel purge 5

注意事項

サポートされるデータの型

データの型	アップロード時の動作	ダウンロード時の動作
STRING	最大長：8 MB	最大長：8 MB
BOOLEAN	`True`、`False`、`0`、または `1`（大文字小文字を区別しない）を受け入れます。	`True` または `False`
BIGINT	範囲：-9,223,372,036,854,775,807 ～ 9,223,372,036,854,775,807	同じ範囲
DOUBLE	16 桁の数値。指数表記で表現されます。	数値として表現されます（最大 20 桁）。正の無限大：`Infinity`。負の無限大：`-Infinity`。最大値：`1.7976931348623157E308`。最小値：`4.9E-324`。
DATETIME	デフォルトタイムゾーン：GMT+8。`-dfp` を使用してフォーマットを設定します。「データの型エディション」をご参照ください。	—

サポートされる DATETIME のフォーマットパターン：

パターン	例
`yyyyMMddHHmmss`	`20140209101000`
`yyyy-MM-dd HH:mm:ss`（デフォルト）	`2014-02-09 10:10:00`
`MM/dd/yyyy`	`09/01/2014`

NULL 値

デフォルトでは、空文字列は NULL として扱われます。カスタムの null インジケーターを使用するには、次のようにします。

tunnel upload log.txt test_table -ni "NULL"

ファイルエンコーディング

デフォルトのエンコーディングは UTF-8 です。別のエンコーディングを指定するには、次のようにします。

tunnel upload log.txt test_table -c "gbk"

デリミタ

行区切り文字と列区切り文字の両方とも複数文字をサポートします。列区切り文字には行区切り文字を含めることはできません。サポートされるエスケープシーケンス：\r、\n、\t。

tunnel upload log.txt test_table -fd "||" -rd "\r\n"

サブコマンド

アップロード

構文

パラメーター

必須

オプション — フォーマット

オプション — エラー処理

オプション — パフォーマンス

オプション — セッション

例：パーティションの上書き

ダウンロード

前提条件

構文

パラメーター

必須

オプション — フォーマット

オプション — パフォーマンス

オプション — セッション

アップサート

前提条件

構文

パラメーター

必須

オプション — フォーマット

オプション — エラー処理

オプション — パフォーマンス

オプション — セッション

履歴書

構文

例

表示

構文

セッションステータス値

例

パージ

構文

注意事項

サポートされるデータの型

NULL 値

ファイルエンコーディング

デリミタ

次のステップ