# DPE SDKのData Managerコネクター

> Data Managerコネクターを使用すると、Data Managerの内容のクエリ、挿入、更新、削除をプログラムから実行できます。

---

## コネクターの作成

`connect()`メソッドは、いずれかのDBMS `source`でData Managerコネクターを作成するのに使用します。 

```python
from forepaas.worker.connect import connect

cn_prim = connect("dwh/data_prim/")
cn_mart = connect("dwh/data_mart/")
```

---

### list()
データベースのテーブルのリストを取得します。

**出力**

| タイプ  | 説明 | 例 |
| :---: | :---        | :---    |
| list | テーブル名のリスト | ```["prim_sales","raw_sales","ref_products"]``` |

---

### query(sql, limit=-1, return_type='dataframe')

対応した`source`に対してSQLクエリを実行し、データフレーム（デフォルト）、反復可能なカーソル、または辞書のリストを返します。

**入力パラメータ**

| 名前  | タイプ  | 説明 | 例 |
| :---  | :---: | :---        | :---    |
| sql   | str| 実行するSQLクエリ | ```select * from ref_clients``` |
| limit | int | 結果の最大数（-1：制限なし） | -1 |
| return_type | str | 戻り値のタイプ | 「dataframe」、「cursor」、または「dict」 |

**出力**

| タイプ  | 説明 | 例 |
| :---: | :---        | :---    |
| mixed | 選択したタイプ（dataframe、cursor、list[dict]）の結果 |      |

---

### select(table_name, filters={}, limit=-1, return_type='dataframe' )

シンプルなフィルターを用いてテーブルからデータを抽出し、データフレーム（デフォルト）、反復可能なカーソル、または辞書のリストを返します。

**入力パラメータ**

| 名前  | タイプ  | 説明 | 例 |
| :---  | :---: | :---        | :---    |
| table | str | ソーステーブル名 | `ref_clients` |
| filters | dict | フィルターとして使用する値の辞書。`key`はフィルタリング対象の属性で、`値`をフィルタリング値として使用。`List`はIN演算子を生成、それ以外の場合は`=`演算子を生成 | None / ```{"profile_id":[1,2,3], "client_age":18}``` |
| limit | int | 結果の最大数（-1：制限なし） | -1 |
| return_type | string | 戻り値のタイプ | 「dataframe」、「cursor」、または「dict」 |


**出力**

| タイプ  | 説明 | 例 |
| :---: | :---        | :---    |
| mixed | 選択したタイプ（dataframe、cursor、list[dict]）の結果 |      |

---

### update(table, set, filters=None, ignore=False)
シンプルなパラメータを使用して`UPDATE` SQLクエリを実行し、影響を受ける行の数を返します。

**入力パラメータ**

| 名前  | タイプ  | 説明 | 例 |
| :---  | :---: | :---        | :---    |
| table | str | ソーステーブルの名前 | `'ref_clients'` |
| set | dict | 更新対象の値の辞書。キーであるフィールド名を更新し、値である値を更新 | ```{“profile_id”:1}``` |
| filters | dict | フィルターとして使用する値の辞書。`key`はフィルタリング対象の属性で、`値`をフィルタリング値として使用。`List`はIN演算子を生成、それ以外の場合は`=`演算子を生成 | None / ```{"profile_id":[1,2,3], "client_age":18}``` |
| ignore | boolean | `True`の場合、`UPDATE IGNORE`クエリを実行。それ以外の場合は、`UPDATE`クエリを実行 | `True`、`False` |

**出力**

| タイプ  | 説明 | 例 |
| :---: | :---        | :---    |
| int   | 更新された行の数（DBMS対応の場合） | 42 |


---

### delete(table, filters)
フィルタリング条件を使用して特定のクエリに基づいた削除を実行します。削除された行数を返します。  
フィルターが必要ない場合は、下記の`truncate`メソッドを使用します。

**入力パラメータ**

| 名前  | タイプ  | 説明 | 例 |
| :---  | :---: | :---        | :---    |
| table | str | ソーステーブルの名前 | `'ref_clients'` |
| filters | dict | フィルターとして使用する値の辞書。`key`はフィルタリング対象の属性で、`値`をフィルタリング値として使用。`List`はIN演算子を生成、それ以外の場合は`=`演算子を生成 | ```{"client_name":"Test"}``` |

**出力**

| タイプ  | 説明 | 例 |
| :---: | :---        | :---    |
| int   | 削除された行の数（DBMS対応の場合） | 42 |

---

### truncate(table)
テーブルのすべての行を削除（クリア）します。

**入力パラメータ**

| 名前  | タイプ  | 説明 | 例 |
| :---  | :---: | :---        | :---    |
| table | str | ソーステーブルの名前 | `'ref_clients'` |

**出力**

| タイプ  | 説明 | 例 |
| :---: | :---        | :---    |
| boolean | 削除が成功した場合はTrue。テーブルが存在しない場合はFalse。それ以外の場合は例外を生成 | `True`、`False` |

---

### insert(table, rows, odku=0, returnWarnings=False)

insertクエリを実行し、オプションで`on duplicate key update`（ODKU）操作を追加して、バッチの挿入に関する統計情報を返します。  
ODKUオプションを有効にした場合、挿入を行う各行の既存の主キーの値に関して、このクエリはエラーを返す代わりに既存の行に対する更新を自動的に実行します。

!> 挿入を行う各行に対し、少なくとも宛先テーブルの主キーを提供する**必要がある**ことに注意してください。

> [こちら](https://forepaas-sdk.readthedocs.io/jp/latest/packages/connector.html?highlight=bulk_insert#bulk-insert)に記載されているように、この関数の代わりにモジュール**bulk_insert**を使用することをお勧めします。このモジュールの方が、データチャンクおよび挿入を効果的に管理できます。

**入力パラメータ**

| 名前  | タイプ  | 説明 | 例 |
| :---  | :---: | :---        | :---    |
| table | str | ソーステーブルの名前 | `'ref_clients'` |
| rows | dataframe | 挿入または更新対象のデータフレーム | ```pd.DataFrame([ {"id":1, "name":"john"}, {"id":2, "name":"bob"}])``` |
| odku | boolean  | `False` = ODKUを実行しない、`True` = ODKUを実行する | `True`、`False` |
| returnWarnings | boolean | Trueの場合、返される警告文字列のタイプごとに集計およびカウントされた警告数が返される | True/False |

**出力**

| タイプ  | 説明 | 例 |
| :---: | :---        | :---    |
| dict | 挿入されたバッチに関する統計情報 | ```{"inserts":13, "skipped":10, "updates":3, "records": 30, "affected":4, "warnings": {"integer truncated":4}}``` |


**補足情報**

*挿入の統計情報について*

PostgreSQLまたはSnowFlakeのライブラリで収集される統計情報が不足しているため、ForePaaSのコネクターから返される統計情報は、次のように限られた要素に基づいて計算されています。- エラーが発生していない場合、*inserts*および*skipped*の行数は、挿入の前後の合計行数と、指定された*records*（挿入対象のデータの長さ）に基づいて計算されます。例えば、5つの行から成るテーブルに3つの行を挿入し、合計で7つの行になった場合、2つの行が*inserted*、1つの行が*skipped*で、*records*は3であると見なされます。- データのバッチでエラーが発生した場合は、バッチ全体に警告のマークが付きます。- SnowFlakeの場合の注意：`insert_many()`および`insert_dataframe()`で返される統計情報では*warnings*は計算されず、挿入されない行やスキップされた行にはすべて*skipped*のマークが付きます。