MaxCompute:Tunnel コマンド

構文

tunnel <subcommand> [options] [args]

オプション

Available subcommands:
    upload (u)
    download (d)
    resume (r)
    show (s)
    purge (p)
    help (h)
    upsert(us)

パラメーター

• アップロード： MaxCompute テーブルにデータをアップロードします。一度に 1 つのテーブルまたは 1 つのパーティションにのみファイルをアップロードできます。パーティションテーブルの場合は、データをアップロードするパーティションを指定する必要があります。多段パーティション化テーブルの場合は、最下層のパーティションを指定する必要があります。

  -- MaxCompute クライアントの bin ディレクトリにある log.txt のデータを、プロジェクト test_project の 2 段パーティション化テーブル test_table のパーティション p1="b1",p2="b2" にアップロードします。
  tunnel upload log.txt test_project.test_table/p1="b1",p2="b2";
  
  -- log.txt のデータを test_table にアップロードします。 --scan=true パラメーターは、log.txt のデータを test_table のスキーマを使用して検証します。データがスキーマに準拠していない場合、エラーが報告され、アップロードは中止されます。
  tunnel upload  log.txt  test_table --scan=true;
  
  -- 別のディレクトリにある log.txt のデータを、プロジェクト test_project の 2 段パーティション化テーブル test_table のパーティション p1="b1",p2="b2" にアップロードします。
  tunnel upload D:\test\log.txt test_project.test_table/p1="b1",p2="b2";

• ダウンロード： MaxCompute テーブルからデータをダウンロードします。一度に 1 つのテーブルまたはパーティションから 1 つのローカルファイルにのみデータをダウンロードできます。パーティションテーブルの場合は、データをダウンロードするパーティションを指定する必要があります。多段パーティション化テーブルの場合は、最下層のパーティションを指定する必要があります。

  -- プロジェクト test_project の 2 段パーティション化テーブル test_table のパーティションから test_table.txt ファイルにデータをダウンロードします。
  tunnel download  test_project.test_table/p1="b1",p2="b2"  test_table.txt;
  -- プロジェクト test_project の 2 段パーティション化テーブル test_table のパーティションから、別のディレクトリのファイルにデータをダウンロードします。
  tunnel download  test_project.test_table/p1="b1",p2="b2"  D:\test\test_table.txt;

• レジューム：ファイルまたはディレクトリの転送を再開します。転送は、ネットワークが切断されたか、トンネルに障害が発生したために中断されます。このコマンドは、データアップロードの再開にのみ使用できます。1 回のデータダウンロードまたはアップロードをセッションと呼びます。このコマンドを実行する前に、レジュームコマンドでセッション ID を指定する必要があります。

  tunnel resume;

• ショー：タスクの履歴情報を表示します。

  -- 直近 5 回のデータアップロードまたはダウンロードで使用したコマンドを表示します。
  tunnel show history -n 5;
  -- 直近のデータアップロードまたはダウンロードのログを表示します。
  tunnel show log;

• パージ：セッションディレクトリからトンネルのログファイルをクリアします。デフォルトでは、過去 3 日間のログをクリアします。

  -- 過去 5 日間のログをクリアします。
  tunnel purge 5;

• ヘルプ：ヘルプ情報を取得します。

• アップサート： UPDATE と INSERT のセマンティクスを使用してデータを書き込みます。Transaction Table 2.0 テーブルのみが、UPSERT ステートメントを使用したデータ書き込みをサポートします。

  宛先テーブルに一致するデータが見つからない場合、新しいデータがテーブルに挿入されます。書き込むデータが既に存在する場合、テーブルのデータが更新されます。

  -- MaxCompute クライアントの bin ディレクトリにある log.txt ファイルのデータを、プロジェクト test_project の 2 段パーティション化テーブル test_table のパーティション p1="b1",p2="b2" にアップサートします。
  tunnel upsert log.txt test_project.test_table/p1="b1",p2="b2";

説明

構文

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

形式

Available options:
 -acp,-auto-create-partition <ARG>   auto create target partition if not
                                     exists, default false
 -bs,-block-size <ARG>               block size in MiB, default 100
 -c,-charset <ARG>                   specify file charset, default ignore.
                                     set ignore to download raw data
 -cf,-csv-format <ARG>               use csv format (true|false), default
                                     false. When uploading in csv format,
                                     file splitting not supported.
 -cp,-compress <ARG>                 compress, default true
 -dbr,-discard-bad-records <ARG>     specify discard bad records
                                     action(true|false), default false
 -dfp,-date-format-pattern <ARG>     specify date format pattern, default
                                     yyyy-MM-dd HH:mm:ss
 -fd,-field-delimiter <ARG>          specify field delimiter, support
                                     unicode, eg \u0001. default ","
 -h,-header <ARG>                    if local file should have table
                                     header, default false
 -mbr,-max-bad-records <ARG>         max bad records, default 1000
 -ni,-null-indicator <ARG>           specify null indicator string,
                                     default ""(empty string)
 -ow,-overwrite <true | false>       overwrite specified table or
                                     partition, default: false
 -rd,-record-delimiter <ARG>         specify record delimiter, support
                                     unicode, eg \u0001. default "\r\n"
 -s,-scan <ARG>                      specify scan file
                                     action(true|false|only), default true
 -sd,-session-dir <ARG>              set session dir, default
                                     D:\software\odpscmd_public\plugins\dship
 -ss,-strict-schema <ARG>            specify strict schema mode. If false,
                                     extra data will be abandoned and
                                     insufficient field will be filled
                                     with null. Default true
 -t,-threads <ARG>                   number of threads, default 1
 -te,-tunnel_endpoint <ARG>          tunnel endpoint
 -time,-time <ARG>                   keep track of upload/download elapsed
                                     time or not. Default false
 -tz,-time-zone <ARG>                time zone, default local timezone:
                                     Asia/Shanghai
Example:
    tunnel upload log.txt test_project.test_table/p1="b1",p2="b2"

パラメーター

• 必須パラメーター

  • パス

    アップロードするデータファイルのパスと名前を指定します。

    データファイルを MaxCompute クライアントの bin ディレクトリに保存できます。この場合、path パラメーターを File name.File name extension 形式の値に設定する必要があります。データファイルは、D ドライブの test フォルダーなど、別のディレクトリに保存することもできます。この場合、path パラメーターを D:\test\File name.File name extension 形式の値に設定する必要があります。

    説明

    macOS では、path パラメーターの値は絶対パスである必要があります。 たとえば、データファイルが MaxCompute クライアントの bin ディレクトリに保存されている場合、path パラメーターを /Users/username/MaxCompute/bin/file name.file name extension 形式の値に設定する必要があります。

  • [プロジェクト.]テーブル[/パーティション]

    データをアップロードするテーブルの名前を指定します。パーティションテーブルの場合は、最下位レベルのパーティションを指定する必要があります。テーブルが現在のプロジェクトに属していない場合は、テーブルが属するプロジェクトを指定する必要があります。

• 任意パラメーター

  • -acp

    データをアップロードするパーティションを指定します。指定されたパーティションが存在しない場合、パーティションが自動的に作成されます。デフォルト値：False。

  • -bs

    トンネルが毎回アップロードするデータブロックのサイズを指定します。デフォルト値：100 MiB (1 MiB = 1024 × 1024 バイト)。

  • -c

    データファイルの文字セットを指定します。デフォルトでは、このパラメーターは無視され、生データがダウンロードされます。

  • -cf

    ファイルが CSV ファイルであるかどうかを指定します。デフォルト値：False。

    説明

    Upload コマンドでは、TXT ファイルと CSV ファイルのみをアップロードできます。デフォルトでは TXT ファイルがアップロードされます。CSV ファイルをアップロードする場合は、-cf パラメーターを設定し、MaxCompute クライアントの最新バージョンをダウンロードする必要があります。

  • -cp

    ローカルデータファイルを MaxCompute にアップロードする前に圧縮して、ネットワークトラフィックを削減するかどうかを指定します。デフォルト値：True。

  • -dbr

    追加の列、欠落している列、または列データの型が一致しないなどのダーティデータを省略するかどうかを指定します。デフォルト値：False。

    • True: テーブルの定義に一致しないすべてのデータを省略します。デフォルトでは、1000 件のデータレコードが省略されます。省略するデータレコードの数を変更するには、-mbr パラメーターを指定します。

    • False：ダーティデータが検出された後にエラーが返されます。これにより、データをアップロードするテーブル内の生データが損なわれないことが保証されます。

  • -dfp

    DATETIME データの形式を指定します。 デフォルトの形式は yyyy-MM-dd HH:mm:ss です。 ミリ秒単位の精度で DATETIME データを指定する場合、yyyy-MM-dd HH:mm:ss.SSS 形式を使用できます。 DATETIME データ型の詳細については、「データ型バージョンガイド」をご参照ください。

  • -fd

    ローカルデータファイルで使用されるフィールド区切り文字を指定します。デフォルト値：カンマ (,)。

  • -h

    アップロードするデータファイルにテーブルヘッダーがあるかどうかを指定します。デフォルト値：False。この値は、データファイルにテーブルヘッダーが含まれていないことを示します。このパラメーターを True に設定すると、データファイルにテーブルヘッダーを含めることができます。この場合、システムはテーブルヘッダーをスキップして、2 行目からデータをアップロードします。

  • -mbr

    許容されるダーティデータレコードの最大数を指定します。このパラメーターは、-dbr パラメーターと併用する必要があり、-dbr パラメーターが True に設定されている場合にのみ有効です。ダーティデータレコードの数が指定された値を超えると、アップロードは停止します。デフォルト値: 1000。

  • -ni

    NULL インジケーターを指定します。デフォルト値：空文字列。

  • -ow

    アップロードされたデータがテーブルまたはパーティションを上書きするかどうかを指定します。デフォルト値：False。この値は、データが追加モードでアップロードされることを示します。以下にコード例を示します。

    -- パーティションテーブルを作成します。
    CREATE TABLE IF NOT EXISTS sale_detail(
          shop_name     STRING,
          customer_id   STRING,
          total_price   DOUBLE)
    PARTITIONED BY (sale_date STRING,region STRING);
    
    -- sale_detail テーブルにパーティションを追加します。
    ALTER TABLE sale_detail ADD PARTITION (sale_date='201312', region='hangzhou');
    
    -- D ドライブに次の内容のローカルデータファイル data.txt を準備します。
    shopx,x_id,100
    shopy,y_id,200
    
    -- パーティションテーブルにデータをアップロードします。
    tunnel upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou;
    
    -- sale_detail テーブルをクエリします。
    SELECT * FROM sale_detail;
    
    -- 次の結果が返されます。
    +------------+-------------+-------------+------------+------------+
    | 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;
    
    -- sale_detail テーブルをクエリします。
    SELECT * FROM sale_detail;
    
    -- 次の結果が返されます。
    +------------+-------------+-------------+------------+------------+
    | shop_name  | customer_id | total_price | sale_date  | region     |
    +------------+-------------+-------------+------------+------------+
    | shopx      | x_id        | 300.0       | 201312     | hangzhou   |
    | shopy      | y_id        | 400.0       | 201312     | hangzhou   |
    +------------+-------------+-------------+------------+------------+

  • -rd

    ローカルデータファイルで使用される行区切り文字を指定します。デフォルト値: \r\n。

  • -s

    ローカルデータファイルをスキャンするかどうかを指定します。デフォルト値：True。

    • True：システムはデータをスキャンし、データが正しい形式である場合にのみデータのインポートを開始します。

    • False：システムはスキャンせずにデータをインポートします。

    • Only：システムはローカルデータのみをスキャンします。スキャン後、データはインポートされません。

  • -sd

    セッションディレクトリを指定します。

  • -ss

    厳格なスキーマを指定します。デフォルト値：True。このパラメーターを False に設定すると、余分なデータは破棄され、不足しているフィールドは NULL で埋められます。

  • -t

    スレッド数を指定します。デフォルト値：1。

  • -te

    トンネルエンドポイントを指定します。

  • -time

    アップロード時間を追跡するかどうかを指定します。デフォルト値：False。

  • -tz

    タイムゾーンを指定します。デフォルト値：ローカルタイムゾーン (例：Asia/Shanghai)。タイムゾーンの詳細については、「タイムゾーンリスト」をご参照ください。

履歴レコードを表示します。

• 構文

  tunnel show history [-n <number>];

  -n <number>：表示する履歴レコード数を指定します。

• 例

  例 1：履歴レコードを表示します。デフォルトでは、500 件の履歴レコードが保存されます。

  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'
  ......

  例 2：直近 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 show log;

説明

履歴操作の実行を再開します。データアップロードのみ再開できます。

構文

tunnel resume <session_id> [-f];

パラメーター

• session_id

  アップロードが失敗したセッションの ID を指定します。このパラメーターは必須です。

• -f

  履歴操作の実行を強制的に再開するかどうかを指定します。このパラメーターはデフォルトで省略されます。

例

tunnel resume 20150610xxxxxxxxxxx70a002ec60c -f;

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

説明

MaxCompute テーブルデータ、または特定のインスタンスの実行結果をローカルディレクトリにダウンロードします。

Tunnel を使用してデータをダウンロードするには、ダウンロードのアクセス許可が必要です。ダウンロードのアクセス許可がない場合は、プロジェクトオーナーまたは Super_Administrator ロールが割り当てられているユーザーに連絡して、権限を付与してもらってください。ダウンロードのアクセス許可を付与する方法の詳細については、「ポリシーベースのアクセス制御」をご参照ください。

構文

odps@ project_name>tunnel help download;
usage: tunnel download [options] <[project.]table[/partition]> <path>

              download data to local file
 -c,-charset <ARG>                 specify file charset, default ignore.
                                   set ignore to download raw data
 -cf,-csv-format <ARG>             use csv format (true|false), default
                                   false. When uploading in csv format,
                                   file splitting not supported.
 -ci,-columns-index <ARG>          specify the columns index(starts from
                                   0) to download, use comma to split each
                                   index
 -cn,-columns-name <ARG>           specify the columns name to download,
                                   use comma to split each name
 -cp,-compress <ARG>               compress, default true
 -dfp,-date-format-pattern <ARG>   specify date format pattern, default
                                   yyyy-MM-dd HH:mm:ss
 -e,-exponential <ARG>             When download double values, use
                                   exponential express if necessary.
                                   Otherwise at most 20 digits will be
                                   reserved. Default false
 -fd,-field-delimiter <ARG>        specify field delimiter, support
                                   unicode, eg \u0001. default ","
 -h,-header <ARG>                  if local file should have table header,
                                   default false
    -limit <ARG>                   specify the number of records to
                                   download
 -ni,-null-indicator <ARG>         specify null indicator string, default
                                   ""(empty string)
 -rd,-record-delimiter <ARG>       specify record delimiter, support
                                   unicode, eg \u0001. default "\r\n"
 -sd,-session-dir <ARG>            set session dir, default
                                   D:\software\odpscmd_public\plugins\dship
 -t,-threads <ARG>                 number of threads, default 1
 -te,-tunnel_endpoint <ARG>        tunnel endpoint
 -time,-time <ARG>                 keep track of upload/download elapsed
                                   time or not. Default false
 -tz,-time-zone <ARG>              time zone, default local timezone:
                                   Asia/Shanghai
usage: tunnel download [options] instance://<[project/]instance_id> <path>

              download instance result to local file
 -c,-charset <ARG>                 specify file charset, default ignore.
                                   set ignore to download raw data
 -cf,-csv-format <ARG>             use csv format (true|false), default
                                   false. When uploading in csv format,
                                   file splitting not supported.
 -ci,-columns-index <ARG>          specify the columns index(starts from
                                   0) to download, use comma to split each
                                   index
 -cn,-columns-name <ARG>           specify the columns name to download,
                                   use comma to split each name
 -cp,-compress <ARG>               compress, default true
 -dfp,-date-format-pattern <ARG>   specify date format pattern, default
                                   yyyy-MM-dd HH:mm:ss
 -e,-exponential <ARG>             When download double values, use
                                   exponential express if necessary.
                                   Otherwise at most 20 digits will be
                                   reserved. Default false
 -fd,-field-delimiter <ARG>        specify field delimiter, support
                                   unicode, eg \u0001. default ","
 -h,-header <ARG>                  if local file should have table header,
                                   default false
    -limit <ARG>                   specify the number of records to
                                   download
 -ni,-null-indicator <ARG>         specify null indicator string, default
                                   ""(empty string)
 -rd,-record-delimiter <ARG>       specify record delimiter, support
                                   unicode, eg \u0001. default "\r\n"
 -sd,-session-dir <ARG>            set session dir, default
                                   D:\software\odpscmd_public\plugins\dshi
 -t,-threads <ARG>                 number of threads, default 1
 -te,-tunnel_endpoint <ARG>        tunnel endpoint
 -time,-time <ARG>                 keep track of upload/download elapsed
                                   time or not. Default false
 -tz,-time-zone <ARG>              time zone, default local timezone:
                                   Asia/Shanghai
Example:
    tunnel download test_project.test_table/p1="b1",p2="b2" log.txt // 指定したテーブルからデータをダウンロードします。
    tunnel download instance://test_project/test_instance log.txt   // 指定したインスタンスの実行結果をダウンロードします。

パラメーター

• 必須パラメーター

  • path

    ダウンロードしたデータファイルを保存するパスを指定します。

    データファイルは、MaxCompute クライアントの bin ディレクトリに保存できます。この場合、path には File name.File name extension 形式の値を設定する必要があります。また、データファイルは、たとえば D ドライブの test フォルダーなど、別のディレクトリに保存することもできます。この場合、path には D:\test\File name.File name extension 形式の値を設定する必要があります。

  • [project.]table[/partition]

    ダウンロードするテーブルの名前を指定します。パーティションテーブルの場合は、最下位レベルのパーティションを指定する必要があります。テーブルが現在のプロジェクトに属していない場合は、テーブルが存在するプロジェクトを指定する必要があります。

  • [project/]instance_id

    インスタンス ID を指定します。特定のインスタンスの実行結果をダウンロードできます。

• 任意パラメーター

  • -c

    ローカルデータファイルの文字セットを指定します。このパラメーターはデフォルトで省略されます。

  • -cf

    ファイルが CSV 形式かどうかを指定します。デフォルト値は false です。

    説明

    TXT ファイルと CSV ファイルのみダウンロードできます。デフォルトでは TXT ファイルがダウンロードされます。CSV ファイルをダウンロードする場合は、-cf パラメーターを true に設定し、MaxCompute クライアントの最新バージョンをダウンロードする必要があります。-cf パラメーターを true に設定すると、ファイルの区切り文字はコンマ (,) のみになります。この場合、-fd パラメーターで指定された区切り文字は有効になりません。

  • -ci

    ダウンロードする列のインデックスを指定します。列インデックスは 0 から始まります。列インデックスはカンマ (,) で区切ります。

  • -cn

    ダウンロードする列の名前を指定します。列名はカンマ (,) で区切ります。

  • -cp

    ダウンロード時にデータを圧縮してネットワークトラフィックを削減するかどうかを指定します。デフォルト値は true です。

  • -dfp

    DATETIME 型のデータの書式を指定します。デフォルトの形式は yyyy-MM-dd HH:mm:ss です。

  • -e

    ダウンロードする DOUBLE 型のデータを指数表現で表すかどうかを指定します。指数表現を使用しない場合は、最大 20 桁まで保持されます。デフォルト値は false です。

  • -fd

    ローカルデータファイルのフィールド区切り文字を指定します。デフォルト値はカンマ (,) です。

  • -h

    データファイルにテーブルヘッダーを含めるかどうかを指定します。デフォルト値は false で、この場合ヘッダーは含まれません。このパラメーターを true に設定すると、データファイルにテーブルヘッダーが含まれます。

    説明

    -h=true と threads>1 は併用できません。 threads>1 は、スレッド数が 1 より大きいことを意味します。

  • -limit

    ダウンロードするレコード数を指定します。

  • -ni

    NULL 値インジケーターを指定します。デフォルト値は空文字列です。

  • -rd

    ローカルデータファイルで使用される行区切り文字を指定します。デフォルト値: \r\n。

  • -sd

    セッションディレクトリを指定します。

  • -t

    スレッド数を指定します。デフォルト値は 1 です。

  • -te

    Tunnel のエンドポイントを指定します。

  • -time

    ダウンロードにかかる時間を計測するかどうかを指定します。デフォルト値は false です。

  • -tz

    タイムゾーンを指定します。デフォルトでは、Asia/Shanghai のようなローカルタイムゾーンが使用されます。

説明

セッションディレクトリからトンネルのログファイルをパージします。

構文

tunnel purge [n];

パラメーター

n ：トンネル履歴ログの保持期間 (日) です。デフォルト： 3。

次の表はデータ型について説明しています。

"yyyyMMddHHmmss"：例えば、"20140209101000" となります。
"yyyy-MM-dd HH:mm:ss" (デフォルト形式)：例えば、"2014-02-09 10:10:00" となります。
"MM/dd/yyyy"：例えば、"09/01/2014" となります。

tunnel upload log.txt test_table -dfp "yyyy-MM-dd HH:mm:ss"

NULL：各データ型で NULL 値が使用できます。

• デフォルトでは、空文字列は NULL 値とみなされます。

• NULL 文字列を指定するには、 -null-indicator パラメーターを使用します。

  tunnel upload log.txt test_table -ni "NULL"

エンコーディング形式：ファイルのエンコーディング形式を指定できます。デフォルト値： UTF-8。

tunnel upload log.txt test_table -c "gbk"

デリミタ： Tunnel コマンドでは、カスタムのファイルデリミタを使用できます。 -record-delimiter は行デリミタのカスタマイズに、 -field-delimiter は列デリミタのカスタマイズに使用します。

• 行デリミタまたは列デリミタには複数の文字を含めることができます。

• 列デリミタに行デリミタを含めることはできません。

• コマンドラインでは、次のエスケープ文字デリミタのみ使用できます： \r、\n、および \t。

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