特徴量エンジンKaskadaリファレンス~テーブル

# はじめに

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

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

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

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

https://kaskada.io/docs-site/kaskada/main/developing/tables.html

# 外部データ利用

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/176567/8e65f20f-77c7-88ff-b94d-d934adc248dc.png)

Kaskadaにおけるデータ操作は、データ入力に対して、離散タイムラインと連続タイムラインへの変換を繰り返し、データを出力するものである、と捉えることができます。

ここでは、データ操作のための準備について、見ていきます。

## 

次のステップにより、外部のデータが「タイムライン」データとして、Kaskadaで利用可能になります。

 - Kaskada APIを介して、Kaskadaにテーブルを定義
 - Kaskadaテーブルにデータをロード


# テーブル
Kaskada はデータをテーブルに保存します。テーブルは複数の行で構成され、各行は同じ型の値です。

## テーブル管理
### テーブル作成
すべてのテーブルは、データの構造を定義するスキーマに関連付けられています。
スキーマは、テーブルに含まれる項目を網羅的に定義する必要はなく、多くはテーブルにロードしたデータから推測されます。
ただし、Kaskada のデータ モデルでは必須の項目が存在するため、テーブル定義において、それらを指定する必要があります。Kaskadaのテーブルには、**その行に関連付けられた時刻**と**エンティティを識別する列**が含まれている必要があります。

つまり、レコードは、以下の二つを持つ必要があることになります。
   - エンティティキー
   - 時刻・タイムスタンプ

テーブルを作成するときは、どの列に各行の時間とエンティティが含まれるかを Kaskada に指示する必要があります。

 - 時刻列は`time_column_name`パラメータを使用して指定します。このパラメータは、時間値を含むテーブルのデータ内の列名を識別する必要があります。時刻はイベントが発生した時刻を指す必要があります。

 - エンティティキーは`entity_key_column_name`パラメータを使用して指定します。このパラメータは、エンティティ キー値を含むテーブル データ内の列名を識別する必要があります。エンティティ キーは、各イベントが関連付けられている世界の物体を識別する必要があります。「正しい」値を選択することについてあまり心配する必要はありません。`with_key()`関数を使用するとエンティティを簡単に変更できます。

また、以下のパラメータを指定して、テーブルの動作をさらに構成することが可能です。

 - `subsort_column_name`パラメーターを使用して、各行に関連付けられたサブソート列を指定できます。この値は、同じ時間値に関連付けられた行を順序付けるために使用されます。（サブソート列が指定されていない場合、Kaskada はサブソート列を生成します。）

 - `grouping_id`パラメータを使用して、エンティティのタイプを指定できます。グループ化 ID は、各イベントがどのような種類のエンティティに関連付けられているかを指定します。異なるテーブルのイベントを結合する場合、同じエンティティ キーとグループ ID を持つイベントは同じエンティティの一部として扱われます。


テーブルの作成例を次に示します。


```python
from kaskada import table
from kaskada.api.session import LocalBuilder

session = LocalBuilder().build()

table.create_table(
  # The table's name
  table_name = "Purchase",
  # The name of a column in your data that contains the time associated with each row
  time_column_name = "purchase_time",
  # The name of a column in your data that contains the entity key associated with each row
  entity_key_column_name = "customer_id",
)
```
これにより、 `Purchase`という名前のテーブルが作成されます。このテーブルにロードされるデータはすべて、 `purchase_time`という名前のタイムスタンプ フィールドと`customer_id`という名前のエンティティキーフィールドを持つ必要があります。


## テーブル一覧
`list_tables()`メソッドは、定義されたすべてのテーブルを返します。オプションの検索文字列を使用して結果をフィルタリングできます。

テーブルをリストする例を次に示します。


```python
from kaskada import table
from kaskada.api.session import LocalBuilder

session = LocalBuilder().build()

table.list_tables()
```

### テーブルの取得
名前を使用してテーブルを取得できます。


```python
from kaskada import table
from kaskada.api.session import LocalBuilder

session = LocalBuilder().build()

table.get_table("Purchase")
```

### テーブルの更新
テーブルは現在不変です。テーブルを更新するには、テーブルを削除し、新しい式で再作成する必要があります。

### テーブルの削除
名前を使用してテーブルを削除できます。


```python
from kaskada import table
from kaskada.api.session import LocalBuilder

session = LocalBuilder().build()

table.delete_table("Purchase")
```
テーブルを削除すると、テーブルにアップロードされたデータも削除されることに注意してください。

別のビューやマテリアライゼーションがテーブルを参照している場合、削除は失敗し、前提条件(precondition)エラーが返されます。

テーブルの削除を続行するには、依存リソースを削除するか、テーブルを強制的に削除する`force`フラグを指定します。依存リソースを削除せずにテーブルを強制的に削除すると、依存リソースが正しく機能しなくなる可能性があります。


```python
from kaskada import table
from kaskada.api.session import LocalBuilder

session = LocalBuilder().build()

table.delete_table("Purchase", force = True)
```