mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-12-18 20:32:43 +00:00
258 lines
8.9 KiB
Markdown
258 lines
8.9 KiB
Markdown
---
|
||
title: Python向けのchDBのインストール
|
||
sidebar_label: Python
|
||
slug: /ja/chdb/install/python
|
||
description: Python向けのchDBのインストール方法
|
||
keywords: [chdb, embedded, clickhouse-lite, python, install]
|
||
---
|
||
|
||
# Python向けのchDBのインストール
|
||
|
||
## 必要条件
|
||
|
||
macOSとLinux（x86_64およびARM64）上のPython 3.8+
|
||
|
||
## インストール
|
||
|
||
```bash
|
||
pip install chdb
|
||
```
|
||
|
||
## 使用法
|
||
|
||
CLI例:
|
||
|
||
```python
|
||
python3 -m chdb [SQL] [OutputFormat]
|
||
```
|
||
|
||
```python
|
||
python3 -m chdb "SELECT 1, 'abc'" Pretty
|
||
```
|
||
|
||
Pythonファイル例:
|
||
|
||
```python
|
||
import chdb
|
||
|
||
res = chdb.query("SELECT 1, 'abc'", "CSV")
|
||
print(res, end="")
|
||
```
|
||
|
||
クエリは、`Dataframe`や`Debug`を含む[サポート形式](/docs/ja/interfaces/formats)のいずれかを使用してデータを返すことができます。
|
||
|
||
## GitHubリポジトリ
|
||
|
||
プロジェクトのGitHubリポジトリは[chdb-io/chdb](https://github.com/chdb-io/chdb)にあります。
|
||
|
||
## データ入力
|
||
|
||
以下のメソッドを使用して、オンディスクおよびインメモリのデータフォーマットにアクセス可能です。
|
||
|
||
### ファイル上でのクエリ (Parquet, CSV, JSON, Arrow, ORC など60+)
|
||
|
||
SQLを実行し、希望の形式でデータを返せます。
|
||
|
||
```python
|
||
import chdb
|
||
res = chdb.query('select version()', 'Pretty'); print(res)
|
||
```
|
||
|
||
**ParquetまたはCSVでの操作**
|
||
|
||
```python
|
||
# データ型の詳細は tests/format_output.py を参照
|
||
res = chdb.query('select * from file("data.parquet", Parquet)', 'JSON'); print(res)
|
||
res = chdb.query('select * from file("data.csv", CSV)', 'CSV'); print(res)
|
||
print(f"SQL read {res.rows_read()} rows, {res.bytes_read()} bytes, elapsed {res.elapsed()} seconds")
|
||
```
|
||
|
||
**Pandas dataframe出力**
|
||
```python
|
||
# 詳細はhttps://clickhouse.com/docs/ja/interfaces/formatsを参照
|
||
chdb.query('select * from file("data.parquet", Parquet)', 'Dataframe')
|
||
```
|
||
|
||
### テーブル上でのクエリ (Pandas DataFrame, Parquet file/bytes, Arrow bytes)
|
||
|
||
**Pandas DataFrame上でのクエリ**
|
||
|
||
```python
|
||
import chdb.dataframe as cdf
|
||
import pandas as pd
|
||
# 2つのDataFrameを結合
|
||
df1 = pd.DataFrame({'a': [1, 2, 3], 'b': ["one", "two", "three"]})
|
||
df2 = pd.DataFrame({'c': [1, 2, 3], 'd': ["①", "②", "③"]})
|
||
ret_tbl = cdf.query(sql="select * from __tbl1__ t1 join __tbl2__ t2 on t1.a = t2.c",
|
||
tbl1=df1, tbl2=df2)
|
||
print(ret_tbl)
|
||
# DataFrameテーブルでのクエリ
|
||
print(ret_tbl.query('select b, sum(a) from __table__ group by b'))
|
||
```
|
||
|
||
### 状態を持つセッションでのクエリ
|
||
|
||
セッションはクエリの状態を保持します。すべてのDDLおよびDMLの状態はディレクトリに保持されます。ディレクトリパスは引数として渡すことができます。指定されない場合、一時ディレクトリが作成されます。
|
||
|
||
パスが指定されない場合、セッションオブジェクトが削除されるときに一時ディレクトリが削除されます。そうでない場合、パスは保持されます。
|
||
|
||
デフォルトのデータベースは`_local`で、デフォルトのエンジンは`Memory`であるため、すべてのデータはメモリに保存されます。ディスクにデータを保存したい場合は、別のデータベースを作成する必要があります。
|
||
|
||
```python
|
||
from chdb import session as chs
|
||
|
||
## 一時セッションでDB、テーブル、ビューを作成し、セッションが削除されると自動的にクリーンアップします。
|
||
sess = chs.Session()
|
||
sess.query("CREATE DATABASE IF NOT EXISTS db_xxx ENGINE = Atomic")
|
||
sess.query("CREATE TABLE IF NOT EXISTS db_xxx.log_table_xxx (x String, y Int) ENGINE = Log;")
|
||
sess.query("INSERT INTO db_xxx.log_table_xxx VALUES ('a', 1), ('b', 3), ('c', 2), ('d', 5);")
|
||
sess.query(
|
||
"CREATE VIEW db_xxx.view_xxx AS SELECT * FROM db_xxx.log_table_xxx LIMIT 4;"
|
||
)
|
||
print("ビューから選択:\n")
|
||
print(sess.query("SELECT * FROM db_xxx.view_xxx", "Pretty"))
|
||
```
|
||
|
||
関連情報: [test_stateful.py](https://github.com/chdb-io/chdb/blob/main/tests/test_stateful.py).
|
||
|
||
### Python DB-API 2.0でのクエリ
|
||
|
||
```python
|
||
import chdb.dbapi as dbapi
|
||
print("chdbドライバーバージョン: {0}".format(dbapi.get_client_info()))
|
||
|
||
conn1 = dbapi.connect()
|
||
cur1 = conn1.cursor()
|
||
cur1.execute('select version()')
|
||
print("説明: ", cur1.description)
|
||
print("データ: ", cur1.fetchone())
|
||
cur1.close()
|
||
conn1.close()
|
||
```
|
||
|
||
### UDF（ユーザー定義関数）でのクエリ
|
||
|
||
```python
|
||
from chdb.udf import chdb_udf
|
||
from chdb import query
|
||
|
||
@chdb_udf()
|
||
def sum_udf(lhs, rhs):
|
||
return int(lhs) + int(rhs)
|
||
|
||
print(query("select sum_udf(12,22)"))
|
||
```
|
||
|
||
chDBのPython UDF（ユーザー定義関数）デコレーターに関する注意点。
|
||
1. 関数はステートレスであるべきです。UDF（ユーザー定義関数）のみがサポートされており、UDAF（ユーザー定義集約関数）はサポートされていません。
|
||
2. デフォルトの戻り値の型はStringです。戻り値の型を変更したい場合は、引数として渡すことができます。戻り値の型は[次のいずれか](/ja/sql-reference/data-types)である必要があります。
|
||
3. 関数はString型の引数を受け取るべきです。入力がタブ区切りであるため、すべての引数は文字列です。
|
||
4. 関数は入力の各行ごとに呼び出されるでしょう。例：
|
||
```python
|
||
def sum_udf(lhs, rhs):
|
||
return int(lhs) + int(rhs)
|
||
|
||
for line in sys.stdin:
|
||
args = line.strip().split('\t')
|
||
lhs = args[0]
|
||
rhs = args[1]
|
||
print(sum_udf(lhs, rhs))
|
||
sys.stdout.flush()
|
||
```
|
||
5. 関数は純粋なPython関数であるべきです。関数内で使用するすべてのPythonモジュールをインポートする必要があります。
|
||
```python
|
||
def func_use_json(arg):
|
||
import json
|
||
...
|
||
```
|
||
6. 使用されるPythonインタープリタは、スクリプトを実行しているものと同じです。`sys.executable`から取得できます。
|
||
|
||
関連情報: [test_udf.py](https://github.com/chdb-io/chdb/blob/main/tests/test_udf.py).
|
||
|
||
### Pythonテーブルエンジン
|
||
|
||
### Pandas DataFrameでのクエリ
|
||
|
||
```python
|
||
import chdb
|
||
import pandas as pd
|
||
df = pd.DataFrame(
|
||
{
|
||
"a": [1, 2, 3, 4, 5, 6],
|
||
"b": ["tom", "jerry", "auxten", "tom", "jerry", "auxten"],
|
||
}
|
||
)
|
||
|
||
chdb.query("SELECT b, sum(a) FROM Python(df) GROUP BY b ORDER BY b").show()
|
||
```
|
||
|
||
### Arrowテーブルでのクエリ
|
||
|
||
```python
|
||
import chdb
|
||
import pyarrow as pa
|
||
arrow_table = pa.table(
|
||
{
|
||
"a": [1, 2, 3, 4, 5, 6],
|
||
"b": ["tom", "jerry", "auxten", "tom", "jerry", "auxten"],
|
||
}
|
||
)
|
||
|
||
chdb.query(
|
||
"SELECT b, sum(a) FROM Python(arrow_table) GROUP BY b ORDER BY b", "debug"
|
||
).show()
|
||
```
|
||
|
||
### chdb.PyReaderクラスのインスタンスでのクエリ
|
||
|
||
1. chdb.PyReaderクラスを継承し、`read`メソッドを実装する必要があります。
|
||
2. `read`メソッドは以下を行う必要があります:
|
||
1. リストのリストを返すこと。第一次元はカラム、第二次元は行です。カラムの順序は、`read`の最初の引数`col_names`と同じであるべきです。
|
||
1. 読み疲れた時に空のリストを返すこと。
|
||
1. 状態を持ち、カーソルは`read`メソッド内で更新されるべきです。
|
||
3. オプションで`get_schema`メソッドを実装してテーブルのスキーマを返すことができます。プロトタイプは`def get_schema(self) -> List[Tuple[str, str]]:`です。返り値はタプルのリストで、各タプルはカラム名とカラムの型を含みます。カラム型は[次のいずれか](/ja/sql-reference/data-types)である必要があります。
|
||
|
||
<br />
|
||
|
||
```python
|
||
import chdb
|
||
|
||
class myReader(chdb.PyReader):
|
||
def __init__(self, data):
|
||
self.data = data
|
||
self.cursor = 0
|
||
super().__init__(data)
|
||
|
||
def read(self, col_names, count):
|
||
print("Python func read", col_names, count, self.cursor)
|
||
if self.cursor >= len(self.data["a"]):
|
||
return []
|
||
block = [self.data[col] for col in col_names]
|
||
self.cursor += len(block[0])
|
||
return block
|
||
|
||
reader = myReader(
|
||
{
|
||
"a": [1, 2, 3, 4, 5, 6],
|
||
"b": ["tom", "jerry", "auxten", "tom", "jerry", "auxten"],
|
||
}
|
||
)
|
||
|
||
chdb.query(
|
||
"SELECT b, sum(a) FROM Python(reader) GROUP BY b ORDER BY b"
|
||
).show()
|
||
```
|
||
|
||
関連情報: [test_query_py.py](https://github.com/chdb-io/chdb/blob/main/tests/test_query_py.py).
|
||
|
||
## 制限事項
|
||
|
||
1. サポートされているカラム型: pandas.Series, pyarrow.array, chdb.PyReader
|
||
1. サポートされているデータ型: Int, UInt, Float, String, Date, DateTime, Decimal
|
||
1. Pythonオブジェクト型はStringに変換される
|
||
1. Pandas DataFrameのパフォーマンスは最高で、Arrow TableはPyReaderよりも優れています。
|
||
|
||
<br />
|
||
|
||
より多くの例については、[examples](https://github.com/chdb-io/chdb/tree/main/examples)および[tests](https://github.com/chdb-io/chdb/tree/main/tests)を参照してください。
|