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 を渡します。

  • 位置引数: cdm sql run -c <id> "SELECT * FROM users"
  • 標準入力: 標準入力が TTY でない場合（パイプ・リダイレクト時）、自動的に標準入力から SQL を読み込みます

両方が指定された場合（位置引数があり、かつ標準入力もパイプされている場合）は、エラーとして exit 1 で終了します。

cdm notebook build-sql と組み合わせる場合の例:

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

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 で終了します
  • 以下のいずれかが発生した場合、ジョブのキャンセルを試みた上で、エラーメッセージを出力して exit 1 で終了します。エラーメッセージにはジョブ ID を含めるので、後から sql get-job-metadata で状態を確認できます
    • --timeout を超えてもジョブが完了しません
    • コマンド実行中に SIGINT（Ctrl+C）を受け取ります
  • 上記でキャンセル自体が失敗した場合は、その旨を追記して exit 1 で終了します（ジョブの実行は継続している可能性があります）
  • 出力は sql get-job-result と同じ形式です

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" }

ジョブ状態の取得 ​

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

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

  • <job-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（必須）
      --limit <n>            取得する最大行数（既定: 1000、上限: 1000）
      --profile <name>       利用する profile を指定

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

  • <job-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（必須）
      --profile <name>       利用する profile を指定

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

  • <job-id> は 位置引数で必ず指定 します
  • キャンセル要求を送り、エラーが返らなかった場合、空の JSON オブジェクト {} を出力して exit 0 で終了します
  • 要求の送信に失敗した場合、エラーメッセージを出力して exit 1 で終了します
  • ジョブの状態を確認する場合は sql get-job-metadata を利用してください