Codatum CLI

Appearance

cdm sql ​

cdm sql サブコマンドで、コネクションに対して SQL を実行・検証します。

cdm sql <subcommand> [arguments] [options]
サブコマンド用途
sql runSQL を実行し、結果が出るまで待機して取得
sql dry-runSQL の dry-run（スキーマ/処理量の見積もり）
sql create-jobSQL の非同期ジョブを作成し、ジョブ ID を出力
sql get-job-metadataジョブの状態を取得
sql get-job-resultジョブの結果行を取得
sql cancel-jobジョブへのキャンセル要求を送信

SQL の渡し方 ​

SQL を入力とするサブコマンド（sql run, sql dry-run, sql create-job）では、位置引数 <sql> か標準入力のいずれかで SQL を渡します。

  • 位置引数 <sql>: SQL を直接指定します。位置引数を指定した場合、標準入力は読み込みません（パイプ・リダイレクトが接続されていても無視します）
  • 標準入力: 位置引数 <sql> を省略すると、標準入力から SQL を読み込みます。パイプやリダイレクトで渡してください（標準入力が TTY の場合は読み込めません）
  • 位置引数も標準入力も指定されなかった場合は、エラーメッセージを出力して exit 1 で終了します

位置引数で直接指定する例:

bash
cdm sql run "SELECT * FROM users" -c 671ef14b0d08cf6c657df7da

cdm notebook build-sql の出力をパイプで渡す例:

bash
cdm notebook build-sql my.cnb.md -k pageId:p1/sqlId:q1 | cdm sql run -c 671ef14b0d08cf6c657df7da

ファイルからリダイレクトで渡す例:

bash
cdm sql run -c 671ef14b0d08cf6c657df7da < query.sql

SQL の実行（同期） ​

cdm sql run [<sql>]
  -c, --connection-id <id>   コネクション ID（必須）
      --timeout <sec>        ジョブ完了を待つタイムアウト秒数（既定: 300）
      --limit <n>            取得する最大行数（既定: 1000、上限: 1000）
      --profile <name>       利用する profile を指定

SQL を実行し、結果が確定するまで待機して JSON で出力します。

  • sql create-job から sql get-job-result までの処理を一括で行います
  • SQL の渡し方は SQL の渡し方 を参照してください
  • ジョブが ERROR で終了した場合、エラーメッセージを出力して exit 1 で終了します
  • 以下の場合、ジョブのキャンセルを試みた上で、ジョブ ID を含むエラーメッセージを出力して exit 1 で終了します
    • --timeout を超えてもジョブが完了しない時
    • コマンド実行中に SIGINT（Ctrl+C）を受け取った時
  • 出力は sql get-job-result と同じ形式です
  • コネクションの閲覧・実行権限が必要です

出力の分離 ​

TTY 接続時は stderr に進捗情報を出力します。実行完了後の結果 JSON は stdout に出力します（非 TTY では進捗は出力しません）。

進捗表示（stderr） ​

ジョブの完了待ち中、スピナー付きの進捗行を出力します。

TTY 時の出力例 ​

実行中:

⠋ RUNNING (3s)

完了時:

✔ SUCCESS  duration=1.4s

結果（stdout） ​

sql get-job-result と同じ JSON 形式を stdout に出力します。

出力例:

json
{
  "jobResultStatus": "SUCCESS",
  "totalRows": 123,
  "totalBytesProcessed": 1048576,
  "columns": [
    { "name": "id", "type": "STRING" },
    { "name": "email", "type": "STRING" }
  ],
  "rows": [
    { "id": "u1", "email": "a@example.com" },
    { "id": "u2", "email": "b@example.com" }
  ]
}

SQL の dry-run ​

cdm sql dry-run [<sql>]
  -c, --connection-id <id>   コネクション ID（必須）
      --profile <name>       利用する profile を指定

SQL を実行せずに dry-run を行い、結果を JSON で取得します。

  • SQL の渡し方は SQL の渡し方 を参照してください
  • BigQuery では bqTotalBytesProcessed と bqFields が出力されます
  • BigQuery 以外の場合、問題がなければ空の JSON オブジェクト {} を出力します
  • dry-run 自体が失敗した場合（構文エラー等）、errorMessage を含む JSON をそのまま出力します（exit 0）
  • コネクションの閲覧権限が必要です

出力例（BigQuery）:

json
{
  "bqTotalBytesProcessed": 1048576,
  "bqFields": [
    { "name": "id", "type": "STRING" },
    { "name": "email", "type": "STRING" }
  ]
}

エラー時の出力例:

json
{ "errorMessage": "Function not found: hoge at [1:8]" }

ジョブの作成 ​

cdm sql create-job [<sql>]
  -c, --connection-id <id>   コネクション ID（必須）
      --profile <name>       利用する profile を指定

SQL の非同期ジョブを作成し、ジョブ ID を JSON で出力します。

出力例:

json
{ "jobId": "nFsupzWNxYUaDbSaSKcTqHvpOVU" }

出力された jobId を <job-id> 引数に指定する方法は ジョブ ID の指定 を参照してください。

ジョブ ID の指定 ​

sql get-job-metadata、sql get-job-result、sql cancel-job の <job-id> 引数には、次の 2 つの形式を指定できます。

形式例-c の指定
ジョブ IDnFsupzWNxYUaDbSaSKcTqHvpOVU必須
ジョブリソース IDbq/cn=<connectionId>/jb=<jobId>省略可
  • ジョブ ID: sql create-job が返すジョブ ID です。あわせて -c でコネクション ID を指定する必要があります
  • ジョブリソース ID: コネクション ID とジョブ ID が 1 つにまとまった形式です（詳細は ジョブリソース ID からの指定 を参照）。-c を省略できます

ジョブリソース ID からの指定 ​

ノートブック内の SQL ブロック・チャートや、cdm notebook run の出力に記録される jobId は、ジョブリソース ID（bq/cn=<connectionId>/jb=<jobId> 形式）です。これはコネクション ID とジョブ ID を 1 つの文字列にまとめたものです。

ジョブリソース ID は <job-id> 引数にそのまま渡せます。コネクション ID はジョブリソース ID 内の cn= の値が使われるため、-c の指定は不要です。

bash
# ジョブリソース ID をそのまま指定（-c は不要）
cdm sql get-job-result bq/cn=674d04aa723c39d549407a6c/jb=Y8HsQyld9k3j0WbUG4k7K64ah9u

-c をあわせて指定した場合は、cn= の値と一致していればそのまま処理を続行し、一致しない場合はエラーメッセージを出力して exit 1 で終了します。

また、ジョブリソース ID から cn= と jb= の値を取り出し、-c とジョブ ID に分けて指定することもできます。

bash
# cn= の値を -c に、jb= の値を <job-id> に分けて指定
cdm sql get-job-result Y8HsQyld9k3j0WbUG4k7K64ah9u -c 674d04aa723c39d549407a6c

ジョブ状態の取得 ​

cdm sql get-job-metadata <job-id>
  -c, --connection-id <id>   コネクション ID（ジョブ ID の場合は必須）
      --profile <name>       利用する profile を指定

指定したジョブの現在の状態を JSON で取得します。

  • <job-id> は 位置引数で必ず指定 します。ジョブ ID の場合は -c が必須、ジョブリソース ID の場合は -c を省略できます（ジョブ ID の指定 を参照）
  • ジョブが完了していない場合（PENDING / RUNNING）でも、その時点の状態をそのまま出力します（exit 0）
  • ジョブが見つからない場合など、取得に失敗した場合は、エラーメッセージを出力して exit 1 で終了します
  • コネクションの閲覧権限が必要です

出力例:

json
{
  "jobStatus": "SUCCESS",
  "sql": "SELECT * FROM users",
  "resultRowCount": 123,
  "spendTimeMsec": 1450,
  "resultBytes": 4096,
  "totalBytesProcessed": 1048576
}

ジョブ結果の取得 ​

cdm sql get-job-result <job-id>
  -c, --connection-id <id>   コネクション ID（ジョブ ID の場合は必須）
      --limit <n>            取得する最大行数（既定: 1000、上限: 1000）
      --profile <name>       利用する profile を指定

指定したジョブの結果行を JSON で取得します。

  • <job-id> は 位置引数で必ず指定 します。ジョブ ID の場合は -c が必須、ジョブリソース ID の場合は -c を省略できます（ジョブ ID の指定 を参照）
  • ジョブが完了していない場合や ERROR 状態の場合、jobResultStatus が "ERROR" の JSON をそのまま出力します（exit 0）
    • ジョブ完了を待ってから取得したい場合は、先に sql get-job-metadata で jobStatus を確認してください
  • 通信エラー等、結果の取得に失敗した場合は、エラーメッセージを出力して exit 1 で終了します
  • コネクションの閲覧権限が必要です

出力例:

json
{
  "jobResultStatus": "SUCCESS",
  "totalRows": 123,
  "totalBytesProcessed": 1048576,
  "columns": [
    { "name": "id", "type": "STRING" },
    { "name": "email", "type": "STRING" }
  ],
  "rows": [
    { "id": "u1", "email": "a@example.com" },
    { "id": "u2", "email": "b@example.com" }
  ]
}

ジョブのキャンセル ​

cdm sql cancel-job <job-id>
  -c, --connection-id <id>   コネクション ID（ジョブ ID の場合は必須）
      --profile <name>       利用する profile を指定

指定したジョブに対してキャンセル要求を送ります。

  • <job-id> は 位置引数で必ず指定 します。ジョブ ID の場合は -c が必須、ジョブリソース ID の場合は -c を省略できます（ジョブ ID の指定 を参照）
  • キャンセル要求を送り、エラーが返らなかった場合、空の JSON オブジェクト {} を出力して exit 0 で終了します
  • 要求の送信に失敗した場合、エラーメッセージを出力して exit 1 で終了します
  • ジョブの状態を確認する場合は sql get-job-metadata を利用してください
  • コネクションの実行権限が必要です

Codatum CLI AIエージェントのための分析環境

© Codatum Inc.