特徴量エンジンKaskadaリファレンス〜Jupyter Notebookマジックコマンド環境でのクエリ実行

# はじめに

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

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

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

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

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

## fenlmagic でのクエリ実行
fenlmagic IPython 拡張機能を使用すると、クエリの反復処理が容易になります。

fenlmagic IPython 拡張機能はオプションであり、Kaskada を使用するために必須ではありませんが、ワークフローに合ったクライアント インターフェイスを自由に選択することができます。

キーワード`%%fenl`を、クエリ ブロックの先頭に付けることで、Fenl クエリを作成できます

```
%%fenl
{
    time: Purchase.purchase_time,
    entity: Purchase.customer_id,
    max_amount: Purchase.amount | max(),
    min_amount: Purchase.amount | min(),
}
```
## テーブルとビュー
クエリは基本的に、テーブルを操作対象とします。ただし、クエリはビュー、またはテーブルとビューの組み合わせに対して操作することもできます。

以下は、ビューを使用して、テーブルを使用した式によって生成された値をフィルター処理する例です。

```javascript
%%fenl
{
  time: Purchase.purchase_time,
  entity: Purchase.customer_id,
  total_purchases: Purchase.amount | sum(),
} | when(PurchaseStats.max_amount > 100)
```

### fenlmagicオプションパラメータ
fenlmagic を使用してクエリを実行する場合、次のオプションのパラメーターを使用できます。

 - `--output` : クエリ結果の出力形式
   - `df`(データフレーム) (デフォルト)、`json`、`parquet`または`redis-bulk`のいずれか。
   - `redis-bulk`の場合、 `result_behavior` は 自動的に、`final-results`であるとみなされます 
 - `--var` : 指定された名前のローカル変数に本体を割り当てます。

その他、下記については、以下で説明します。

 - `--data-token`
 - `--result-behavior`
 - `--preview-rows`



## `--data-token`利用


Kaskadaのクエリは、テーブルやビューのデータを用いますが、このデータは更新されている可能性があります。
データのロード時にはロードが成功裏に行われた結果として、トークンIDが返されます。
`--data-token`は、このトークンIDを使って、反復可能な（常に結果が変わらない）クエリを実現します。
同じデータ トークンに対して実行されるクエリは、常に同じ入力データに対して実行されます。

以下に例を示します。

最初のファイルのロード後に返されたデータ トークン ID を使用し、結果には最初のファイルの行のみが含まれます。

```javascript
%%fenl --data-token bdc9e595-a8a0-448c-9a95-c2e3d886b633
purchases
data_token_id: "bdc9e595-a8a0-448c-9a95-c2e3d886b633"
request_details {
  request_id: "3f737ff336666515a54dd29a9c5ace3a"
}
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/176567/6d190e67-47f9-1f67-616d-e714e95f3e68.png)



2 番目のファイルのロード後に返されたデータ トークン ID と、両方のファイルからの結果行を使用します。

```javascript
%%fenl --data-token 24c83cac-8cf4-4a45-98f0-dac8d5b303a2
purchases
data_token_id: "24c83cac-8cf4-4a45-98f0-dac8d5b303a2"
request_details {
  request_id: "3f737ff336666515a54dd29a9c5ace3a"
}
```


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/176567/2ab4e669-ca8c-3bd0-a7a4-6bfdbd095967.png)




## `--result-behavior`利用

`--result-behavior`は、クエリの結果の振る舞いを決定します。

各エンティティのすべての結果を返すには `all-results`(デフォルト)を使用します。
```
%%fenl --result-behavior all-results
purchases
data_token_id: "7bd4e740-9e63-418e-ba9b-5582db010959"
request_details {
  request_id: "1badb8b0e220e26cc15b93b234ac3c14"
}
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/176567/1eaaa80e-372c-a202-5993-c2a77171b32f.png)


`final-results`は、各エンティティの最新のイベントのみを返します
```
%%fenl --result-behavior final-results
purchases
data_token_id: "7bd4e740-9e63-418e-ba9b-5582db010959"
request_details {
  request_id: "145bc51d9bac47f17fd202e5785e58b7"
}
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/176567/d87794b8-b925-18d5-00c9-0deff4060fb2.png)


## `--preview-rows`利用
`--preview-rows`は、少なくとも指定した数の行を含むデータのプレビューを生成します。


以下のように、`50`を指定すると、`transactions`に含まれる、少なくとも 50 行のプレビューが返されます。
```
%%fenl --preview-rows 50
transactions
```

例えば、`transactions`が100000行のデータを持つとき、完全な100000行のデータセットではなく、例えば、71599 行のデータフレームを返します。

ここで、わずか 50 行が要求されたのに、何千行も返されるのは奇妙に思えるかもしれません。これは、クエリがバッチで動作し、要求された行の最小セットに到達するために処理されたすべてのバッチの結果を返すために発生します。ここでは、コンピューティングは 1 つのバッチのみを処理し、バッチのサイズは 71599 行でした。

なお、最終結果を生成するにはすべての入力を処理する必要があるため`--result-behavior final-results`を使用すると、、`--preview-rowswith` を使用したとしても、データセット全体が処理されます。