特徴量エンジンKaskadaリファレンス〜CLIによるクエリ実行

# はじめに

先日、以下の記事を発表しました。

https://qiita.com/yoshiyuki_kono/items/7dc7bdad5e02ff986f5d

公式ドキュメントの学習過程の記録として、以下の記事をまとめてみました。

本稿情報のソースとして、下記ドキュメントを参照ください。

https://kaskada.io/docs-site/kaskada/main/developing/queries.html#querying-with-the-cli

## CLIによるクエリ実行

CLI を利用する場合、`kaskada-cli query run`でクエリを実行できます。

CLI実行では、クエリ文字列は、`STDIN`に対して指定します。
クエリを定義する簡単な方法は、クエリを含むテキストファイルを作成することです。

**query.fenl**
```javascript
{
  time: Purchase.purchase_time,
  entity: Purchase.customer_id,
  max_amount: last(Purchase.amount) | max(),
  min_amount: Purchase.amount | min()
}
```

そして、以下のように、クエリを CLI にパイプして実行します。

```javascript
cat query.fenl | kaskada-cli query run
```

クエリを実行すると、プロンプトに、以下のように、JSON 形式のクエリ応答オブジェクトが返されます。
デフォルトでは、クエリ結果は Parquet ファイルに書き込まれます。ファイルの場所やファイル名は、他のクエリメタデータとともにクエリ応答に含まれます。
```javascript
{
	"state": "STATE_SUCCESS",
	"config": {
		"dataTokenId": "b5bc4597-47d4-4770-a772-0b94e0d12483"
	},
  // ...
}
```
結果のファイルについての情報は、パスの配列としてクエリ応答オブジェクトJSONのパス`outputTo.objectStore.outputPaths.paths`に格納されています。

例えば、以下のように、`jq`コマンドを使用して、JSON 出力をフィルターし、確認することができます。
```shell
cat query.fenl | kaskada-cli query run | jq '.outputTo.objectStore.outputPaths.paths'
```
これにより、以下のように、結果ファイルのリストが返されます。
```javascript
[
  "file:///<pwd>/data/results/3024b7ae-1429-4c12-867b-3a1f7e86099f/LfiWn-mIVspEbBE-G7yLYug3V2-dW4ASAGmV6g/6089a024-5d97-4f2c-9472-625791550505.parquet"
]
```

少数の行を返すクエリの場合は、CSV 形式で `STDOUT` に出力する方が便利な場合があります。
以下のようにオプションで出力方法を変更することができます。

```
cat query.fenl | kaskada-cli query run --stdout --response-as csv
```

## CLIクエリ引数の完全なリスト

CLI のクエリ引数の完全なリストは、`kaskada-cli query run --help`で確認できます。
```
Executes a query on kaskada

Usage:
  cli query run "query-text" [flags]

Flags:
      --changed-since-time int       (Optional) Unix timestamp bound (inclusive) after which results will be output. If 'response-behavior' is 'all-results', this will include rows for changes (events and ticks) after this time (inclusive). If it is 'final-results', this will include a final result for any entity that would be included in the changed results.
      --data-token string            (Optional) A token to run queries against. Enables repeatable queries.
      --dry-run true                 (Optional) If this is true, then the query is validated and if there are no errors, the resultant schema is returned. No actual computation of results is performed.
      --experimental-features true   (Optional) If this is true, then experimental features are allowed.  Data returned when using this flag is not guaranteed to be correct.
  -h, --help                         help for run
      --preview-rows int             (Optional) Produces a preview of the results with at least this many rows.
      --response-as string           (Optional) How to encode the results.  Either 'parquet' or 'csv'. (default "parquet")
      --result-behavior string       (Optional) Determines how results are returned.  Either 'all-results' or 'final-results'. (default "all-results")
      --stdout true                  (Optional) If this is true, output results are sent to STDOUT

Global Flags:
      --config string               config file (default is $HOME/.cli.yaml)
  -d, --debug                       get debug log output
      --kaskada-api-server string   Kaskada API Server
      --kaskada-client-id string    Kaskada Client ID
      --use-tls                     Use TLS when connecting to the Kaskada API (default true)
```