MaxCompute:Tunnel コマンド

構文

tunnel <subcommand> [options] [args]

オプション

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

パラメーター

• upload: MaxComputeテーブルにデータをアップロードします。 ファイルは、毎回1つのテーブルまたはテーブル内の1つのパーティションにのみアップロードできます。 パーティションテーブルの場合、データのアップロード先のパーティションを指定する必要があります。 マルチレベルパーティションテーブルの場合、最低レベルのパーティションを指定する必要があります。

  -- Upload data in the log.txt file to the p1="b1" and p2="b2" partitions of the test_table table that has two levels of partitions in the test_project project. The log.txt file is saved in the bin directory of the MaxCompute client. 
  tunnel upload log.txt test_project.test_table/p1="b1",p2="b2";
  
  -- Upload data in the log.txt file to the test_table table. The scan parameter is used to check whether data in the log.txt file complies with the schema of the test_table table. If the data does not comply, the system reports an error and stops the upload. 
  tunnel upload  log.txt  test_table --scan=true;
  
  -- Upload data in the log.txt file from another directory to the p1="b1" and p2="b2" partitions of the test_table table that has two levels of partitions in the test_project project. 
  tunnel upload D:\test\log.txt test_project.test_table/p1="b1",p2="b2";

• download: MaxComputeテーブルからデータをダウンロードします。 一度に1つのテーブルまたはパーティションから1つのローカルファイルにデータをダウンロードできます。 パーティションテーブルの場合、データをダウンロードするパーティションを指定する必要があります。 マルチレベルパーティションテーブルの場合、最低レベルのパーティションを指定する必要があります。

  -- Download data from the test_project.test_table table, which has two levels of partitions, to the test_table.txt file in the bin directory of the MaxCompute client. 
  tunnel download  test_project.test_table/p1="b1",p2="b2"  test_table.txt;
  -- Download data from the test_project.test_table table, which has two levels of partitions, to the test_table.txt file in another directory. 
  tunnel download  test_project.test_table/p1="b1",p2="b2"  D:\test\test_table.txt;

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

  tunnel resume;

• show: 履歴タスク情報を表示します。

  -- Display the commands used in the last five data uploads or downloads. 
  tunnel show history -n 5;
  -- Display the logs of the last data upload or download. 
  tunnel show log;

• purge: セッションディレクトリをクリアします。 過去3日間のログはデフォルトで消去されます。

  -- Clear logs from the last five days. 
  tunnel purge 5;

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

• upsert: UPDATEおよびINSERTセマンティクスを使用してデータを書き込みます。 UPSERTステートメントを使用して、トランザクションテーブル2.0テーブルのみがデータ書き込みをサポートします。

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

  -- Upload data in the log.txt file to the p1="b1" and p2="b2" partitions of the test_table table that has two levels of partitions in the test_project project. The log.txt file is saved in the bin directory of the MaxCompute client. 
  tunnel upsert log.txt test_project.test_table/p1="b1",p2="b2";

説明

構文

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

Format

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"

パラメーター

• 必要なパラメーター

  • path

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

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

    説明

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

  • [project.] テーブル [/partition]

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

• オプションパラメーター

  • -acp

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

  • -bs

    Tunnelによって毎回アップロードされるデータブロックのサイズを指定します。 デフォルト値: 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データ型の詳細については、「data type editions」をご参照ください。

  • -fd

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

  • -h

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

  • -mbr

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

  • -ni

    NULLデータ識別子を指定します。 デフォルト値: 空の文字列。

  • -ow

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

    -- Create a partitioned table.
    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');
    
    -- Prepare the local data file data.txt. The file contains the following content:
    shopx,x_id,100
    shopy,y_id,200
    
    -- Upload data to the partitioned table.
    tunnel upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou;
    
    -- Query the sale_detail table.
    select * from sale_detail;
    
    -- The following result is returned:
    +------------+-------------+-------------+------------+------------+
    | shop_name  | customer_id | total_price | sale_date  | region     |
    +------------+-------------+-------------+------------+------------+
    | shopx      | x_id        | 100.0       | 201312     | hangzhou   |
    | shopy      | y_id        | 200.0       | 201312     | hangzhou   |
    +------------+-------------+-------------+------------+------------+
    
    -- Modify the data in the file data.txt. The file contains the following content:
    shopx,x_id,300
    shopy,y_id,400
    
    -- Upload the file after the data in the file is modified. The new file overwrites the existing file.
    tunnel upload -ow true data.txt sale_detail/sale_date=201312,region=hangzhou;
    
    -- Query the sale_detail table.
    select * from sale_detail;
    
    -- The following result is returned:
    +------------+-------------+-------------+------------+------------+
    | 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: システムはスキャンせずにデータをインポートします。

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

  • -sd

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

  • -ss

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

  • -t

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

  • -te

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

  • -時間

    アップロード時刻を追跡するかどうかを指定します。 デフォルト値：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;

説明

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

構文

odps@  project_name>tunnel help resume;
usage: tunnel resume [session_id] [-force]
              resume an upload session
 -f,-force   force resume
Example:
       tunnel resume

パラメーター

• session_id

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

• -f

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

例：

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

説明

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 // Download data from a specific table.
    tunnel download instance://test_project/test_instance log.txt   // Download the execution result of a specific instance.

パラメーター

• 必要なパラメーター

  • パス

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

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

  • [project.] テーブル [/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のエンドポイントを指定します。

  • -時間

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

  • -tz

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

説明

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

構文

odps@ project_name>tunnel help purge;
usage: tunnel purge [n]
              force session history to be purged.([n] days before, default
              3 days)
Example:
       tunnel purge 5

パラメーター

n: 履歴ログが消去される日数を指定します。 デフォルト値: 3。

次の表に、データ型を示します。

"yyyyMMddHHmmss": For example, "20140209101000" is used.
"yyyy-MM-dd HH:mm:ss" (default format): For example, "2014-02-09 10:10:00" is used.
"MM/dd/yyyy": For example, "09/01/2014" is used.

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

Null: 各データ型はnull値を持つことができます。

• デフォルトでは、空白の文字列はnull値を示します。

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

  tunnel upload log.txt test_table -ni "NULL"

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

tunnel upload log.txt test_table -c "gbk"

Delimiter: Tunnelコマンドは、カスタムファイル区切り文字をサポートします。 -record-delimiterは行区切り文字のカスタマイズに使用され、-field-delimiterは列区切り文字のカスタマイズに使用されます。

• 行または列の区切り文字には複数の文字を含めることができます。

• 列の区切り文字に行の区切り文字を含めることはできません。

• コマンドラインでサポートされているエスケープ文字の区切り文字は、\r、\n、および \tのみです。

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