Python API リファレンス

コアクエリ関数

`chdb.query`

chDB エンジンを使用して SQL クエリを実行します。

これは、組み込みの ClickHouse エンジンを使用して SQL 文を実行するメインのクエリ関数です。さまざまな出力形式をサポートし、インメモリデータベースおよびファイルベースデータベースの両方で動作します。

構文

chdb.query(sql, output_format='CSV', path='', udf_path='')

パラメータ

パラメータ	型	デフォルト	説明
`sql`	str	required	実行する SQL クエリ文字列
`output_format`	str	`"CSV"`	結果の出力形式。サポートされる形式: • `"CSV"` - カンマ区切り値 • `"JSON"` - JSON 形式 • `"Arrow"` - Apache Arrow 形式 • `"Parquet"` - Parquet 形式 • `"DataFrame"` - Pandas DataFrame • `"ArrowTable"` - PyArrow Table • `"Debug"` - 詳細ログを有効化
`path`	str	`""`	データベースファイルのパス。デフォルトはインメモリデータベースです。ファイルパス、またはインメモリデータベース用の `":memory:"` を指定できます
`udf_path`	str	`""`	ユーザー定義関数 (UDF) ディレクトリへのパス

戻り値

指定された形式でクエリ結果を返します:

Return Type	Condition
`str`	CSV や JSON などのテキスト形式の場合
`pd.DataFrame`	`output_format` が `"DataFrame"` または `"dataframe"` の場合
`pa.Table`	`output_format` が `"ArrowTable"` または `"arrowtable"` の場合
chdb result object	上記以外の形式の場合

例外

Exception	Condition
`ChdbError`	SQL クエリの実行に失敗した場合
`ImportError`	DataFrame／Arrow 形式に必要な依存関係が不足している場合に発生

使用例

>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello

>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")

>>> # Query with UDF
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")

`chdb.sql`

chDB エンジンを使用して SQL クエリを実行します。

これは、組み込みの ClickHouse エンジンを使用して SQL 文を実行する主要なクエリ関数です。さまざまな出力形式をサポートし、インメモリおよびファイルベースのデータベースのどちらでも動作します。

構文

chdb.sql(sql, output_format='CSV', path='', udf_path='')

パラメータ

Parameter	Type	Default	Description
`sql`	str	required	実行する SQL クエリ文字列
`output_format`	str	`"CSV"`	結果の出力形式。サポートされる形式: • `"CSV"` - カンマ区切り値 • `"JSON"` - JSON 形式 • `"Arrow"` - Apache Arrow 形式 • `"Parquet"` - Parquet 形式 • `"DataFrame"` - Pandas DataFrame • `"ArrowTable"` - PyArrow Table • `"Debug"` - 冗長なログ出力を有効化
`path`	str	`""`	データベースファイルのパス。デフォルトはインメモリデータベース。ファイルパス、またはインメモリデータベース用の `":memory:"` を指定可能
`udf_path`	str	`""`	ユーザー定義関数 (User-Defined Functions) 用ディレクトリへのパス

戻り値

指定された形式でクエリ結果を返します:

Return Type	Condition
`str`	CSV や JSON などのテキスト形式の場合
`pd.DataFrame`	`output_format` が `"DataFrame"` または `"dataframe"` の場合
`pa.Table`	`output_format` が `"ArrowTable"` または `"arrowtable"` の場合
chdb result object	上記以外の形式の場合

例外

Exception	Condition
`ChdbError`	SQL クエリの実行に失敗した場合
`ImportError`	DataFrame／Arrow 形式に必要な依存関係が不足している場合に発生

使用例

>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello

>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")

>>> # Query with UDF
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")

`chdb.to_arrowTable`

クエリ結果を PyArrow Table に変換します。

chDB のクエリ結果を、効率的な列指向データ処理のために PyArrow Table に変換します。結果が空の場合は空のテーブルを返します。

構文

chdb.to_arrowTable(res)

パラメーター

Parameter	Description
`res`	バイナリ形式の Arrow データを含む chDB クエリ結果オブジェクト

戻り値

Return type	Description
`pa.Table`	クエリ結果を含む PyArrow の Table オブジェクト

送出される例外

Error type	Description
`ImportError`	pyarrow または pandas がインストールされていない場合に送出される

使用例

>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> table = chdb.to_arrowTable(result)
>>> print(table.to_pandas())
   id    msg
0   1  hello

`chdb.to_df`

クエリ結果を pandas の DataFrame に変換します。

chDB のクエリ結果を、まず PyArrow の Table に変換し、その後マルチスレッディングを用いて pandas に変換することで、より高い性能を実現します。

構文

chdb.to_df(r)

パラメータ

パラメータ	説明
`r`	バイナリ形式の Arrow データを含む chDB クエリ結果オブジェクト

戻り値

戻り値の型	説明
`pd.DataFrame`	クエリ結果を含む pandas の DataFrame

送出される例外

例外	条件
`ImportError`	pyarrow または pandas がインストールされていない場合

例

>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> df = chdb.to_df(result)
>>> print(df)
   id    msg
0   1  hello

接続とセッション管理

利用可能なセッション関数は以下のとおりです。

`chdb.connect`

chDB のバックグラウンドサーバーへの接続を作成します。

この関数は chDB (ClickHouse) データベースエンジンへの接続を確立します。 1 プロセスあたり開いておける接続は 1 つだけです。同じ接続文字列で複数回呼び出した場合は、同一の接続オブジェクトが返されます。

chdb.connect(connection_string: str = ':memory:') → Connection

パラメーター:

Parameter	Type	Default	Description
`connection_string`	str	`":memory:"`	データベース接続文字列。フォーマットの詳細は以下を参照してください。

基本フォーマット

Format	Description
`":memory:"`	インメモリのデータベース (デフォルト)
`"test.db"`	相対パスのデータベースファイル
`"file:test.db"`	相対パス指定と同じ
`"/path/to/test.db"`	絶対パスのデータベースファイル
`"file:/path/to/test.db"`	絶対パス指定と同じ

クエリパラメーター付き

Format	Description
`"file:test.db?param1=value1&param2=value2"`	パラメーター付きの相対パス
`"file::memory:?verbose&log-level=test"`	パラメーター付きインメモリデータベース
`"///path/to/test.db?param1=value1&param2=value2"`	パラメーター付きの絶対パス

クエリパラメーターの扱い

クエリパラメーターは、ClickHouse エンジンに起動時引数として渡されます。特別なパラメーターの処理:

Special Parameter	Becomes	Description
`mode=ro`	`--readonly=1`	読み取り専用モード
`verbose`	(flag)	詳細ログを有効にする
`log-level=test`	(setting)	ログレベルを設定する

パラメーターの完全な一覧については、clickhouse local --help --verbose を参照してください。

戻り値

Return Type	Description
`Connection`	次をサポートするデータベース接続オブジェクト: • `Connection.cursor()` によるカーソルの作成 • `Connection.query()` による直接クエリ実行 • `Connection.send_query()` によるストリーミングクエリ実行 • 自動クリーンアップのためのコンテキストマネージャープロトコル

送出される例外

Exception	Condition
`RuntimeError`	データベース接続に失敗した場合

注意

1 プロセスあたりサポートされる接続数は 1 つのみです。新しい接続を作成すると、既存の接続はクローズされます。

使用例

>>> # In-memory database
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # File-based database
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # With parameters
>>> conn = connect("data.db?mode=ro")  # Read-only mode
>>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
>>>
>>> # Using context manager for automatic cleanup
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Connection automatically closed

関連項目

Connection - データベース接続クラス
Cursor - DB-API 2.0 の操作用データベースカーソル

例外処理

class `chdb.ChdbError`

基底クラス: Exception

chDB 関連のエラーに対する基底例外クラスです。

この例外は、chDB のクエリ実行が失敗した場合やエラーが発生した場合にスローされます。標準の Python の Exception クラスを継承しており、基盤となる ClickHouse エンジンからのエラー情報を提供します。

class `chdb.session.Session`

基底クラス: object

Session はクエリの状態を保持します。 path が None の場合は一時ディレクトリを作成してデータベースパスとして使用し、セッションがクローズされるとその一時ディレクトリは削除されます。データを永続的に保持するデータベースを作成するためのパスを指定して渡すこともできます。

パスおよびその他のパラメータを渡すために、接続文字列を使用することもできます。

class chdb.session.Session(path=None)

例

Connection String	説明
`":memory:"`	インメモリデータベース
`"test.db"`	相対パス
`"file:test.db"`	上と同じ
`"/path/to/test.db"`	絶対パス
`"file:/path/to/test.db"`	上と同じ
`"file:test.db?param1=value1&param2=value2"`	クエリパラメータ付き相対パス
`"file::memory:?verbose&log-level=test"`	クエリパラメータ付きインメモリデータベース
`"///path/to/test.db?param1=value1&param2=value2"`	クエリパラメータ付き絶対パス

Connection string args handling

“file:test.db?param1=value1&param2=value2” のようにクエリパラメータを含む接続文字列では、 “param1=value1” は起動引数として ClickHouse エンジンに渡されます。

詳細については clickhouse local –help –verbose を参照してください。

一部の引数の特別な扱い:

“mode=ro” は ClickHouse に対して “–readonly=1”（read-only mode）として扱われます

Important

同時に保持できるセッションは 1 つだけです。新しいセッションを作成する場合は、既存のセッションをクローズする必要があります。
新しいセッションを作成すると、既存のセッションはクローズされます。

`cleanup`

例外処理付きでセッションリソースをクリーンアップします。

このメソッドは、クリーンアップ処理中に発生する可能性のある例外を抑制しつつセッションをクローズしようとします。特にエラーハンドリングの場面や、セッションの状態に関わらず確実にクリーンアップを実行したい場合に有用です。

構文

cleanup()

注記

このメソッドは決して例外を発生させないため、finally ブロックやデストラクタ内で安全に呼び出すことができます。

使用例

>>> session = Session("test.db")
>>> try:
...     session.query("INVALID SQL")
... finally:
...     session.cleanup()  # Safe cleanup regardless of errors

関連項目

close() - エラー伝播を行う明示的なセッションのクローズ

`close`

セッションをクローズし、リソースをクリーンアップします。

このメソッドは内部の接続を閉じ、グローバルなセッション状態をリセットします。このメソッドを呼び出した後は、セッションは無効となり、以降のクエリには使用できません。

構文

close()

注記

このメソッドは、セッションがコンテキストマネージャーとして使用されたとき、またはセッションオブジェクトが破棄されたときに自動的に呼び出されます。

重要

close() を呼び出した後にセッションを使用しようとすると、エラーが発生します。

使用例

>>> session = Session("test.db")
>>> session.query("SELECT 1")
>>> session.close()  # Explicitly close the session

`query`

SQL クエリを実行し、その結果を返します。

このメソッドは、セッションが接続しているデータベースに対して SQL クエリを実行し、指定された形式で結果を返します。さまざまな出力形式をサポートし、クエリ間でセッション状態を維持します。

構文

query(sql, fmt='CSV', udf_path='')

パラメータ

パラメータ	型	デフォルト	説明
`sql`	str	required	実行する SQL クエリ文字列
`fmt`	str	`"CSV"`	結果の出力形式。利用可能な形式: • `"CSV"` - カンマ区切り値 • `"JSON"` - JSON 形式 • `"TabSeparated"` - タブ区切り値 • `"Pretty"` - 整形済みのテーブル形式 • `"JSONCompact"` - コンパクトな JSON 形式 • `"Arrow"` - Apache Arrow 形式 • `"Parquet"` - Parquet 形式
`udf_path`	str	`""`	ユーザー定義関数へのパス。指定しない場合、セッション初期化時に設定された UDF パスが使用されます

戻り値

指定された形式でクエリ結果を返します。正確な戻り値の型は fmt パラメータに依存します:

文字列形式 (CSV, JSON など) は str を返します
バイナリ形式 (Arrow, Parquet) は bytes を返します

送出される例外

例外	条件
`RuntimeError`	セッションがクローズされているか不正な場合
`ValueError`	SQL クエリが不正な構文の場合

注記

「Debug」形式はサポートされておらず、警告付きで自動的に「CSV」に変換されます。デバッグには、代わりに接続文字列パラメータを使用してください。

Warning

このメソッドはクエリを同期的に実行し、すべての結果をメモリに読み込みます。結果セットが大きい場合は、ストリーミングで結果を取得するために send_query() の使用を検討してください。

使用例

>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}

>>> # Complex query with table creation
>>> session.query("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')")
>>> result = session.query("SELECT * FROM test ORDER BY id")
>>> print(result)
id,name
1,Alice
2,Bob

関連項目

send_query() - クエリをストリーミング実行するため
sql - このメソッドのエイリアス

`send_query`

SQL クエリを実行し、ストリーミング結果イテレータを返します。

このメソッドは、セッションが接続しているデータベースに対して SQL クエリを実行し、結果を一度にすべてメモリに読み込むことなく反復処理できるストリーミング結果オブジェクトを返します。これは特に、結果セットが大きい場合に有用です。

構文

send_query(sql, fmt='CSV') → StreamingResult

パラメータ

Parameter	Type	Default	Description
`sql`	str	required	実行する SQL クエリ文字列
`fmt`	str	`"CSV"`	結果の出力形式。利用可能な形式: • `"CSV"` - カンマ区切り値 • `"JSON"` - JSON 形式 • `"TabSeparated"` - タブ区切り値 • `"JSONCompact"` - コンパクト JSON 形式 • `"Arrow"` - Apache Arrow 形式 • `"Parquet"` - Parquet 形式

戻り値

Return Type	Description
`StreamingResult`	クエリ結果を逐次的に返すストリーミング結果イテレータ。`for` ループで使用したり、他のデータ構造に変換して利用できます。

送出される例外

Exception	Condition
`RuntimeError`	セッションがクローズされている、または無効な場合
`ValueError`	SQL クエリが不正な形式の場合

注記

“Debug” フォーマットはサポートされておらず、警告付きで自動的に “CSV” に変換されます。デバッグを行う場合は、代わりに接続文字列パラメータを使用してください。

注意

返される StreamingResult オブジェクトはデータベースへの接続を保持するため、速やかに消費するか、適切な方法で保存して扱ってください。

使用例

>>> session = Session("test.db")
>>> session.query("CREATE TABLE big_table (id INT, data String) ENGINE = MergeTree() order by id")
>>>
>>> # Insert large dataset
>>> for i in range(1000):
...     session.query(f"INSERT INTO big_table VALUES ({i}, 'data_{i}')")
>>>
>>> # Stream results to avoid memory issues
>>> streaming_result = session.send_query("SELECT * FROM big_table ORDER BY id")
>>> for chunk in streaming_result:
...     print(f"Processing chunk: {len(chunk)} bytes")
...     # Process chunk without loading entire result set

>>> # Using with context manager
>>> with session.send_query("SELECT COUNT(*) FROM big_table") as stream:
...     for result in stream:
...         print(f"Count result: {result}")

関連項目

query() - 非ストリーミングのクエリ実行用
chdb.state.sqlitelike.StreamingResult - ストリーミング結果イテレータ

`sql`

SQL クエリを実行し、結果を返します。

このメソッドは、セッションのデータベースに対して SQL クエリを実行し、指定された形式で結果を返します。さまざまな出力形式をサポートし、クエリ間でセッション状態を保持します。

構文

sql(sql, fmt='CSV', udf_path='')

パラメータ

Parameter	Type	Default	Description
`sql`	str	required	実行する SQL クエリ文字列
`fmt`	str	`"CSV"`	結果の出力形式。利用可能な形式: • `"CSV"` - カンマ区切り形式 • `"JSON"` - JSON 形式 • `"TabSeparated"` - タブ区切り形式 • `"Pretty"` - 表形式で見やすく整形された形式 • `"JSONCompact"` - コンパクトな JSON 形式 • `"Arrow"` - Apache Arrow 形式 • `"Parquet"` - Parquet 形式
`udf_path`	str	`""`	ユーザー定義関数のパス。指定されていない場合は、セッション初期化時に設定された UDF パスが使用されます

戻り値

指定された形式でクエリ結果を返します。正確な戻り値の型は fmt パラメータに依存します:

文字列形式 (CSV, JSON など) は str を返します
バイナリ形式 (Arrow, Parquet) は bytes を返します

例外:

Exception	Condition
`RuntimeError`	セッションがクローズされているか無効な場合
`ValueError`	SQL クエリが不正な場合

注記

"Debug" 形式はサポートされておらず、警告付きで自動的に "CSV" に変換されます。デバッグ用途には、代わりに接続文字列パラメータを使用してください。

Warning

このメソッドはクエリを同期的に実行し、すべての結果をメモリにロードします。結果セットが大きい場合は、結果をストリーミングするために send_query() の使用を検討してください。

使用例

>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}

>>> # Complex query with table creation
>>> session.query("CREATE TABLE test (id INT, name String) ENGINE = MergeTree() order by id")
>>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')")
>>> result = session.query("SELECT * FROM test ORDER BY id")
>>> print(result)
id,name
1,Alice
2,Bob

関連項目

send_query() - クエリをストリーミングで実行するために使用
sql - このメソッドの別名

状態管理

`chdb.state.connect`

chDB バックグラウンドサーバーへのConnectionを作成します。

この関数は chDB (ClickHouse) データベースエンジンへの接続を確立します。 1 プロセスあたり開いていられる接続は 1 つだけです。同じ接続文字列で複数回呼び出した場合、同じ接続オブジェクトが返されます。

構文

chdb.state.connect(connection_string: str = ':memory:') → Connection

パラメータ

Parameter	Type	Default	Description
`connection_string(str, optional)`	str	`":memory:"`	データベース接続文字列。以下の形式を参照してください。

基本的な形式

サポートされる接続文字列形式:

Format	Description
`":memory:"`	インメモリデータベース (デフォルト)
`"test.db"`	相対パスのデータベースファイル
`"file:test.db"`	相対パスと同等
`"/path/to/test.db"`	絶対パスのデータベースファイル
`"file:/path/to/test.db"`	絶対パスと同等

クエリパラメータ付き

Format	Description
`"file:test.db?param1=value1&param2=value2"`	パラメータ付き相対パス
`"file::memory:?verbose&log-level=test"`	パラメータ付きインメモリ
`"///path/to/test.db?param1=value1&param2=value2"`	パラメータ付き絶対パス

クエリパラメータの扱い

クエリパラメータは、起動引数として ClickHouse エンジンに渡されます。一部パラメータの特別な扱い:

Special Parameter	Becomes	Description
`mode=ro`	`--readonly=1`	読み取り専用モード
`verbose`	(flag)	詳細ログを有効にする
`log-level=test`	(setting)	ログレベルを設定する

パラメータの完全な一覧は clickhouse local --help --verbose を参照してください。

戻り値

Return Type	Description
`Connection`	次の機能をサポートするデータベース接続オブジェクト: • `Connection.cursor()` によるカーソルの作成 • `Connection.query()` による直接クエリ実行 • `Connection.send_query()` によるストリーミングクエリ • コンテキストマネージャープロトコルに対応した自動クリーンアップ

送出される例外

Exception	Condition
`RuntimeError`	データベースへの接続に失敗した場合に送出

警告

プロセスごとにサポートされる接続は 1 つのみです。新しい接続を作成すると、既存の接続は閉じられます。

使用例

>>> # In-memory database
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # File-based database
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # With parameters
>>> conn = connect("data.db?mode=ro")  # Read-only mode
>>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
>>>
>>> # Using context manager for automatic cleanup
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Connection automatically closed

関連項目

Connection - データベース接続クラス
Cursor - DB-API 2.0 操作用のデータベースカーソル

class `chdb.state.sqlitelike.Connection`

基底クラス: object

構文

class chdb.state.sqlitelike.Connection(connection_string: str)

`close`

接続を閉じてリソースを解放します。

このメソッドはデータベース接続を閉じ、アクティブなカーソルを含む関連するリソースを解放します。このメソッドを呼び出した後は、接続は無効になり、以降の操作には使用できません。

構文

close() → None

注記

このメソッドは冪等であり、複数回呼び出しても安全です。

警告

接続を閉じると、進行中のストリーミングクエリはすべてキャンセルされます。接続を閉じる前に、重要なデータがすべて処理されていることを確認してください。

例

>>> conn = connect("test.db")
>>> # Use connection for queries
>>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory")
>>> # Close when done
>>> conn.close()

>>> # Using with context manager (automatic cleanup)
>>> with connect("test.db") as conn:
...     conn.query("SELECT 1")
...     # Connection automatically closed

`cursor`

クエリを実行するための Cursor オブジェクトを作成します。

このメソッドは、クエリの実行および結果の取得のための標準的な DB-API 2.0 インターフェイスを提供するデータベースカーソルを作成します。カーソルを使用することで、クエリ実行および結果取得をきめ細かく制御できます。

構文

cursor() → Cursor

戻り値

戻り値の型	説明
`Cursor`	データベース操作用のカーソルオブジェクト

注記

新しいカーソルを作成すると、この接続に関連付けられている既存のカーソルは置き換えられます。1 つの接続で使用できるカーソルは 1 つだけです。

使用例

>>> conn = connect(":memory:")
>>> cursor = conn.cursor()
>>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
>>> cursor.execute("SELECT * FROM test")
>>> rows = cursor.fetchall()
>>> print(rows)
((1, 'Alice'),)

関連項目

Cursor - データベースカーソルの実装

`query`

SQL クエリを実行し、完全な結果を返します。

このメソッドは SQL クエリを同期的に実行し、結果セット全体を返します。さまざまな出力フォーマットをサポートし、フォーマット固有の後処理を自動的に適用します。

構文

query(query: str, format: str = 'CSV') → Any

パラメータ:

Parameter	Type	Default	Description
`query`	str	required	実行する SQL クエリ文字列
`format`	str	`"CSV"`	結果の出力フォーマット。サポートされるフォーマット: • `"CSV"` - カンマ区切り値 (文字列) • `"JSON"` - JSON 形式 (文字列) • `"Arrow"` - Apache Arrow 形式 (バイト列) • `"Dataframe"` - Pandas DataFrame (pandas が必要) • `"Arrowtable"` - PyArrow Table (pyarrow が必要)

戻り値

Return Type	Description
`str`	文字列形式 (CSV, JSON) のフォーマット用
`bytes`	Arrow フォーマット用
`pandas.DataFrame`	DataFrame フォーマット用
`pyarrow.Table`	ArrowTable フォーマット用

例外

Exception	Condition
`RuntimeError`	クエリの実行に失敗した場合
`ImportError`	フォーマットに必要なパッケージが未インストールの場合

Warning

このメソッドは結果セット全体をメモリ上に読み込みます。大きな結果セットを扱う場合は、ストリーミングのために send_query() の使用を検討してください。

使用例

>>> conn = connect(":memory:")
>>>
>>> # Basic CSV query
>>> result = conn.query("SELECT 1 as num, 'hello' as text")
>>> print(result)
num,text
1,hello

>>> # DataFrame format
>>> df = conn.query("SELECT number FROM numbers(5)", "dataframe")
>>> print(df)
   number
0       0
1       1
2       2
3       3
4       4

関連項目

send_query() - クエリをストリーミング実行する場合

`send_query`

SQL クエリを実行し、ストリーミング結果イテレータを返します。

このメソッドは SQL クエリを実行し、StreamingResult オブジェクトを返します。これにより、すべての結果を一度にメモリに読み込むことなく結果を反復処理できます。大規模な結果セットを処理する場合に最適です。

構文

send_query(query: str, format: str = 'CSV') → StreamingResult

パラメータ

Parameter	Type	Default	Description
`query`	str	required	実行する SQL クエリ文字列
`format`	str	`"CSV"`	結果の出力形式。サポートされている形式: • `"CSV"` - カンマ区切り値 • `"JSON"` - JSON 形式 • `"Arrow"` - Apache Arrow 形式（`record_batch()` メソッドを有効化） • `"dataframe"` - Pandas DataFrame のチャンク • `"arrowtable"` - PyArrow Table のチャンク

戻り値

Return Type	Description
`StreamingResult`	クエリ結果用のストリーミングイテレータ。次をサポートします: • イテレータプロトコル（for ループ） • コンテキストマネージャプロトコル（with 文） • `fetch()` メソッドによる手動フェッチ • PyArrow RecordBatch のストリーミング（Arrow 形式のみ）

送出される例外

Exception	Condition
`RuntimeError`	クエリ実行が失敗した場合
`ImportError`	指定した形式に必要なパッケージが未インストールの場合

注記

返される StreamingResult に対して record_batch() メソッドを利用できるのは “Arrow” 形式のみです。

使用例

>>> conn = connect(":memory:")
>>>
>>> # Basic streaming
>>> stream = conn.send_query("SELECT number FROM numbers(1000)")
>>> for chunk in stream:
...     print(f"Processing chunk: {len(chunk)} bytes")

>>> # Using context manager for cleanup
>>> with conn.send_query("SELECT * FROM large_table") as stream:
...     chunk = stream.fetch()
...     while chunk:
...         process_data(chunk)
...         chunk = stream.fetch()

>>> # Arrow format with RecordBatch streaming
>>> stream = conn.send_query("SELECT * FROM data", "Arrow")
>>> reader = stream.record_batch(rows_per_batch=10000)
>>> for batch in reader:
...     print(f"Batch shape: {batch.num_rows} x {batch.num_columns}")

関連項目

query() - ストリーミングしないクエリ実行用
StreamingResult - ストリーミング結果のイテレータ

class `chdb.state.sqlitelike.StreamingResult`

Bases: object

大規模なクエリ結果を処理するためのストリーミング結果イテレータ。

このクラスは、結果セット全体をメモリに読み込むことなくクエリ結果をストリーミングするためのイテレータインターフェイスを提供します。さまざまな出力形式をサポートし、手動で結果を取得したり PyArrow RecordBatch をストリーミングしたりするためのメソッドを提供します。

class chdb.state.sqlitelike.StreamingResult

`fetch`

ストリーミング結果の次の chunk を取得します。

このメソッドは、ストリーミング中のクエリ結果から利用可能な次の chunk のデータを取得します。返されるデータの形式は、ストリーミングクエリを開始した際に指定した形式に依存します。

構文

fetch() → Any

戻り値

戻り値の型	説明
`str`	テキスト形式（CSV、JSON）の場合
`bytes`	バイナリ形式（Arrow、Parquet）の場合
`None`	結果ストリームを読み尽くした場合

使用例

>>> stream = conn.send_query("SELECT * FROM large_table")
>>> chunk = stream.fetch()
>>> while chunk is not None:
...     process_data(chunk)
...     chunk = stream.fetch()

`cancel`

ストリーミングクエリをキャンセルし、リソースをクリーンアップします。

このメソッドは、進行中のストリーミングクエリをキャンセルし、関連するリソースを解放します。ストリームをすべて処理し終える前に結果の処理を停止したい場合に呼び出してください。

構文

cancel() → None

使用例

>>> stream = conn.send_query("SELECT * FROM very_large_table")
>>> for i, chunk in enumerate(stream):
...     if i >= 10:  # Only process first 10 chunks
...         stream.cancel()
...         break
...     process_data(chunk)

`close`

ストリーミング結果を閉じて、リソースをクリーンアップします。

cancel() のエイリアスです。ストリーミング結果イテレータをクローズし、関連するリソースを解放します。

構文

close() → None

`record_batch`

効率的なバッチ処理のための PyArrow RecordBatchReader を作成します。

このメソッドは、クエリ結果を Arrow 形式でバッチ単位に反復処理するための PyArrow RecordBatchReader を作成します。PyArrow を使用して大きな結果セットを処理する場合、これは最も効率的な方法です。

構文

record_batch(rows_per_batch: int = 1000000) → pa.RecordBatchReader

パラメータ

パラメータ	型	デフォルト	説明
`rows_per_batch`	int	`1000000`	バッチごとの行数

戻り値

戻り値の型	説明
`pa.RecordBatchReader`	バッチを反復処理するための PyArrow RecordBatchReader

注記

このメソッドは、ストリーミングクエリが format="Arrow" で初期化された場合にのみ利用できます。他のフォーマットで使用するとエラーが発生します。

使用例

>>> stream = conn.send_query("SELECT * FROM data", format="Arrow")
>>> reader = stream.record_batch(rows_per_batch=10000)
>>> for batch in reader:
...     print(f"Processing batch: {batch.num_rows} rows")
...     df = batch.to_pandas()
...     process_dataframe(df)

イテレータプロトコル

StreamingResult は Python のイテレータプロトコルをサポートしており、for ループで直接使用できます。

>>> stream = conn.send_query("SELECT number FROM numbers(1000000)")
>>> for chunk in stream:
...     print(f"Chunk size: {len(chunk)} bytes")

コンテキストマネージャープロトコル

StreamingResult は、リソースの自動クリーンアップのためにコンテキストマネージャープロトコルをサポートしています。

>>> with conn.send_query("SELECT * FROM data") as stream:
...     for chunk in stream:
...         process(chunk)
>>> # Stream automatically closed

class `chdb.state.sqlitelike.Cursor`

基底クラス: object

class chdb.state.sqlitelike.Cursor(connection)

`close`

カーソルを閉じてリソースをクリーンアップします。

このメソッドはカーソルを閉じ、関連するリソースをクリーンアップします。このメソッドを呼び出した後、カーソルは無効となり、その後の操作には使用できません。

構文

close() → None

注記

このメソッドは冪等であり、複数回呼び出しても安全です。接続がクローズされると、カーソルも自動的にクローズされます。

例

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchone()
>>> cursor.close()  # Cleanup cursor resources

`column_names`

直近に実行されたクエリから列名の一覧を返します。

このメソッドは、直前に実行された SELECT クエリの列名を返します。列名は、結果セットに表示される順序と同じ順序で返されます。

構文

column_names() → list

戻り値

戻り値の型	説明
`list`	列名の文字列リスト。クエリがまだ実行されていない場合、またはクエリが列を返さなかった場合は空のリストを返します。

使用例

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name, email FROM users LIMIT 1")
>>> print(cursor.column_names())
['id', 'name', 'email']

関連項目

column_types() - カラム型情報を取得
description - DB-API 2.0 におけるカラムの説明

`column_types`

直近に実行されたクエリから、カラム型のリストを返します。

このメソッドは、直近に実行された SELECT クエリにおける ClickHouse のカラム型名を返します。型は、結果セット内に現れる順序と同じ順序で返されます。

構文

column_types() → list

Returns

Return Type	Description
`list`	ClickHouse の型名を表す文字列のリスト。まだクエリが実行されていない場合、またはクエリが列を返さなかった場合は空のリストを返します

Examples

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT toInt32(1), toString('hello')")
>>> print(cursor.column_types())
['Int32', 'String']

関連項目

column_names() - 列名情報を取得
description - DB-API 2.0 の列説明情報

`commit`

保留中のトランザクションをコミットします。

このメソッドは、保留中のデータベーストランザクションをコミットします。ClickHouse ではほとんどの操作が自動コミットされますが、このメソッドは DB-API 2.0 との互換性のために提供されています。

注記

ClickHouse では通常、操作が自動コミットされるため、明示的なコミットはほとんどの場合不要です。このメソッドは標準的な DB-API 2.0 ワークフローとの互換性のために提供されています。

構文

commit() → None

Examples

>>> cursor = conn.cursor()
>>> cursor.execute("INSERT INTO test VALUES (1, 'data')")
>>> cursor.commit()

`property description : list`

DB-API 2.0 仕様に準拠したカラムの説明を返します。

このプロパティは、直近に実行された SELECT クエリの結果セット内の各カラムを表す 7 要素タプルのリストを返します。各タプルの内容は次のとおりです： (name, type_code, display_size, internal_size, precision, scale, null_ok)

現在は name と type_code のみが提供され、他のフィールドは None に設定されています。

Returns

Return Type	Description
`list`	各カラムを表す 7 要素タプルのリスト。SELECT クエリが実行されていない場合は空リストを返します

注記

これは cursor.description に関する DB-API 2.0 仕様に従います。この実装では、最初の 2 つの要素 (name と type_code) のみが有効なデータを持ちます。

Examples

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users LIMIT 1")
>>> for desc in cursor.description:
...     print(f"Column: {desc[0]}, Type: {desc[1]}")
Column: id, Type: Int32
Column: name, Type: String

関連項目

column_names() - カラム名のみを取得
column_types() - カラムの型のみを取得

`execute`

SQL クエリを実行し、フェッチ用に結果を準備します。

このメソッドは SQL クエリを実行し、fetch 系メソッドで取得するための結果を準備します。結果データの解析と、ClickHouse のデータ型に対する自動型変換を行います。

構文

execute(query: str) → None

パラメーター:

パラメーター	型	説明
`query`	str	実行する SQL クエリ文字列

送出される例外

例外	条件
`Exception`	クエリの実行または結果のパースに失敗した場合に送出されます

注記

このメソッドは cursor.execute() に関する DB-API 2.0 の仕様に準拠しています。実行後は fetchone()、fetchmany()、fetchall() を使用して結果を取得します。

注記

このメソッドは ClickHouse のデータ型を自動的に適切な Python の型に変換します:

Int/UInt 型 → int
Float 型 → float
String/FixedString → str
DateTime → datetime.datetime
Date → datetime.date
Bool → bool

例

>>> cursor = conn.cursor()
>>>
>>> # Execute DDL
>>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>>
>>> # Execute DML
>>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
>>>
>>> # Execute SELECT and fetch results
>>> cursor.execute("SELECT * FROM test")
>>> rows = cursor.fetchall()
>>> print(rows)
((1, 'Alice'),)

関連項目

fetchone() - 単一行を取得する
fetchmany() - 複数行を取得する
fetchall() - 残りのすべての行を取得する

`fetchall`

クエリ結果から残りのすべての行を取得します。

このメソッドは、現在のカーソル位置を起点として、現在のクエリ結果セット内に残っているすべての行を取得します。各行を表すタプルに対して Python の適切な型変換を適用し、それらを要素とするタプルを返します。

構文

fetchall() → tuple

戻り値:

戻り値の型	説明
`tuple`	結果セットの残りの行タプルをすべて含むタプルです。利用可能な行がない場合は空のタプルを返します。

警告

このメソッドは、残りの行をすべて一度にメモリに読み込みます。大きな結果セットの場合は、結果をバッチ処理するために fetchmany() の使用を検討してください。

例

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> all_users = cursor.fetchall()
>>> for user_id, user_name in all_users:
...     print(f"User {user_id}: {user_name}")

関連項目

fetchone() - 単一行を取得
fetchmany() - バッチ処理で複数行を取得

`fetchmany`

クエリ結果から複数の行を取得します。

このメソッドは、現在のクエリ結果セットから最大で size 行を取得します。各行を表すタプルを要素とするタプルを返し、各行には、Python の適切な型に変換されたカラム値が含まれます。

構文

fetchmany(size: int = 1) → tuple

パラメータ

Parameter	Type	Default	Description
`size`	int	`1`	取得する最大行数

戻り値

Return Type	Description
`tuple`	最大で 'size' 個の行タプルを含むタプル。結果セットが尽きている場合は、含まれる行数が少なくなることがあります

注記

このメソッドは DB-API 2.0 の仕様に従います。結果セットが尽きている場合、返される行数は「size」より少なくなります。

使用例

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT * FROM large_table")
>>>
>>> # Process results in batches
>>> while True:
...     batch = cursor.fetchmany(100)  # Fetch 100 rows at a time
...     if not batch:
...         break
...     process_batch(batch)

関連項目

fetchone() - 1 行を取得
fetchall() - 残りの行をすべて取得

`fetchone`

クエリ結果から次の行を取得します。

このメソッドは、現在のクエリ結果セットから次に利用可能な行を取得します。取得した行は、カラム値が適切な Python 型に変換されたタプルとして返されます。

構文

fetchone() → tuple | None

戻り値:

戻り値の型	説明
`Optional[tuple]`	次の行を、そのカラム値を要素とするタプルとして返します。これ以上行がなければ None を返します。

注記

このメソッドは DB-API 2.0 仕様に準拠しています。カラム値は、 ClickHouse のカラム型に基づいて適切な Python 型に自動変換されます。

例

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> row = cursor.fetchone()
>>> while row is not None:
...     user_id, user_name = row
...     print(f"User {user_id}: {user_name}")
...     row = cursor.fetchone()

関連項目

fetchmany() - 複数行を取得
fetchall() - 残りの全行を取得

`chdb.state.sqlitelike`

クエリ結果を PyArrow Table に変換します。

この関数は、chdb のクエリ結果を PyArrow Table 形式に変換し、効率的な列指向データアクセスと他のデータ処理ライブラリとの相互運用性を提供します。

構文

chdb.state.sqlitelike.to_arrowTable(res)

パラメータ:

パラメータ	型	説明
`res`	-	Arrow 形式データを含む chdb からのクエリ結果オブジェクト

戻り値

戻り値の型	説明
`pyarrow.Table`	クエリ結果を含む PyArrow テーブル

例外

例外	条件
`ImportError`	pyarrow または pandas パッケージが未インストールの場合

注記

この関数を使用するには、pyarrow と pandas の両方がインストールされている必要があります。次のコマンドでインストールしてください: pip install pyarrow pandas

Warning

結果が空の場合、スキーマを持たない空の PyArrow テーブルを返します。

使用例

>>> import chdb
>>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
>>> table = to_arrowTable(result)
>>> print(table.schema)
num: int64
text: string
>>> print(table.to_pandas())
   num   text
0    1  hello

`chdb.state.sqlitelike.to_df`

クエリ結果を Pandas DataFrame に変換します。

この関数は、chdb のクエリ結果をいったん PyArrow Table に変換してから DataFrame に変換し、最終的に Pandas DataFrame 形式として扱えるようにします。これにより、Pandas API を用いた便利なデータ分析が可能になります。

構文

chdb.state.sqlitelike.to_df(r)

パラメータ:

パラメータ	型	説明
`r`	-	Arrow フォーマットのデータを含む、chdb のクエリ結果オブジェクト

戻り値

戻り値の型	説明
`pandas.DataFrame`	適切な列名およびデータ型付きでクエリ結果を保持する DataFrame オブジェクト

例外

例外	条件
`ImportError`	pyarrow または pandas が未インストールの場合

注記

この関数は、大規模なデータセットでのパフォーマンス向上のために、 Arrow から Pandas への変換処理でマルチスレッドを使用します。

関連項目

to_arrowTable() - PyArrow Table フォーマットへの変換用

使用例

>>> import chdb
>>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
>>> df = to_df(result)
>>> print(df)
   num   text
0    1  hello
>>> print(df.dtypes)
num      int64
text    object
dtype: object

DataFrame 統合

class `chdb.dataframe.Table`

基底クラス:

class chdb.dataframe.Table(*args: Any, **kwargs: Any)

Database API (DBAPI) 2.0 インターフェイス

chDB はデータベース接続用に Python DB-API 2.0 互換インターフェイスを提供しており、標準的なデータベースインターフェイスに対応したツールやフレームワークで chDB を利用できます。

chDB の DB-API 2.0 インターフェイスには次の機能が含まれます:

Connections: 接続文字列を用いたデータベース接続管理
Cursors: クエリの実行および結果の取得
Type System: DB-API 2.0 準拠の型定数とコンバーター
Error Handling: 標準的なデータベース例外階層
Thread Safety: レベル 1 のスレッドセーフ (スレッド間でモジュールは共有できるが、接続は共有できない)

コア関数

Database API (DBAPI) 2.0 インターフェイスは、次のコア関数を実装します:

`chdb.dbapi.connect`

新しいデータベース接続を確立します。

構文

chdb.dbapi.connect(*args, **kwargs)

パラメータ

Parameter	Type	Default	Description
`path`	str	`None`	データベースファイルのパス。インメモリデータベースの場合は None

例外

Exception	Condition
`err.Error`	接続を確立できない場合に発生します

`chdb.dbapi.get_client_info()`

クライアントバージョン情報を取得します。

MySQLdb 互換性のために、chDB クライアントのバージョンを文字列として返します。

構文

chdb.dbapi.get_client_info()

戻り値

Return Type	説明
`str`	'major.minor.patch' 形式のバージョン文字列

型コンストラクタ

`chdb.dbapi.Binary(x)`

x をバイナリ型として返します。

この関数は、DB-API 2.0 仕様に従い、バイナリ型のデータベースフィールドで使用するために、入力を bytes 型に変換します。

構文

chdb.dbapi.Binary(x)

パラメータ

Parameter	Type	Description
`x`	-	バイナリに変換する入力データ

戻り値

Return Type	Description
`bytes`	バイト列に変換された入力データ

Connection クラス

class `chdb.dbapi.connections.Connection(path=None)`

Bases: object

chDB データベースへの DB-API 2.0 準拠コネクション。

このクラスは、chDB データベースへの接続および操作のための標準的な DB-API インターフェイスを提供します。インメモリおよびファイルベースの両方のデータベースをサポートします。

このコネクションは基盤となる chDB エンジンを管理し、クエリの実行、トランザクションの管理（ClickHouse では no-op となります）、カーソルの作成のためのメソッドを提供します。

class chdb.dbapi.connections.Connection(path=None)

パラメータ

Parameter	Type	Default	Description
`path`	str	`None`	データベースファイルのパス。None の場合はインメモリデータベースを使用します。'database.db' のようなファイルパス、または ':memory:' を使用する場合は None を指定できます

変数

Variable	Type	Description
`encoding`	str	クエリ文字列の文字エンコーディング。デフォルトは 'utf8' です
`open`	bool	接続が開いていれば True、閉じていれば False です

例

>>> # In-memory database
>>> conn = Connection()
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchall()
>>> conn.close()

>>> # File-based database
>>> conn = Connection('mydata.db')
>>> with conn.cursor() as cur:
...     cur.execute("CREATE TABLE users (id INT, name STRING) ENGINE = MergeTree() order by id")
...     cur.execute("INSERT INTO users VALUES (1, 'Alice')")
>>> conn.close()

>>> # Context manager usage
>>> with Connection() as cur:
...     cur.execute("SELECT version()")
...     version = cur.fetchone()

注記

ClickHouse は従来型のトランザクションをサポートしていないため、commit() および rollback() 操作は実質的に何も処理しませんが、DB-API への準拠のために提供されています。

`close`

データベース接続を閉じます。

基盤となる chDB 接続を閉じ、この接続を閉じられたものとしてマークします。この接続に対して後続の操作を行うと、Error がスローされます。

構文

close()

発生する例外

例外	条件
`err.Error`	接続がすでにクローズされている場合

`commit`

現在のトランザクションをコミットします。

構文

commit()

注記

従来型トランザクションをサポートしていない chDB/ClickHouse では、この操作は何も行いません（no-op）。 DB-API 2.0 準拠のために提供されています。

`cursor`

クエリを実行するための新しいカーソルを作成します。

構文

cursor(cursor=None)

パラメータ

パラメータ	型	説明
`cursor`	-	後方互換性のために存在するが、使用されない

戻り値

戻り値の型	説明
`Cursor`	この接続に対する新しいカーソルオブジェクト

送出される例外

例外	条件
`err.Error`	接続がクローズされている場合

使用例

>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1")
>>> result = cur.fetchone()

`escape`

SQL クエリに安全に含められるよう、値をエスケープします。

構文

escape(obj, mapping=None)

パラメーター

パラメーター	型	説明
`obj`	-	エスケープする値（文字列、バイト列、数値など）
`mapping`	-	エスケープに使用するオプションの文字マッピング

戻り値

戻り値の型	説明
-	SQL クエリに適した形式にエスケープされた入力値

例

>>> conn = Connection()
>>> safe_value = conn.escape("O'Reilly")
>>> query = f"SELECT * FROM users WHERE name = {safe_value}"

`escape_string`

SQL クエリで使用するために文字列値をエスケープします。

構文

escape_string(s)

パラメータ

Parameter	Type	Description
`s`	str	エスケープする文字列

戻り値

Return Type	Description
`str`	SQL に安全に埋め込めるようにエスケープされた文字列

`property open`

接続が開いているかどうかを確認します。

戻り値

Return Type	Description
`bool`	接続が開いていれば True、閉じていれば False

`query`

SQL クエリを直接実行し、生の結果を返します。

このメソッドはカーソルインターフェイスを経由せずにクエリを直接実行します。標準的な DB-API の利用には、cursor() メソッドの使用を推奨します。

構文

query(sql, fmt='CSV')

パラメータ:

パラメータ	型	デフォルト	説明
`sql`	str または bytes	必須	実行する SQL クエリ
`fmt`	str	`"CSV"`	出力形式。サポートされる形式には「CSV」「JSON」「Arrow」「Parquet」などがあります。

戻り値

戻り値の型	説明
-	指定された形式でのクエリ結果

送出される例外

例外	条件
`err.InterfaceError`	接続が閉じられている場合、またはクエリが失敗した場合

例

>>> conn = Connection()
>>> result = conn.query("SELECT 1, 'hello'", "CSV")
>>> print(result)
"1,hello\n"

`property resp`

最後に実行されたクエリのレスポンスを取得します。

戻り値

戻り値の型	説明
-	直近の `query()` 呼び出しによる生のレスポンス

注記

このプロパティは、query() が直接呼び出されるたびに更新されます。カーソル経由で実行されたクエリは反映されません。

`rollback`

現在のトランザクションをロールバックします。

構文

rollback()

注記

これは従来型のトランザクションをサポートしない chDB/ClickHouse に対しては実質的に何も行いません（no-op）。DB-API 2.0 準拠のために提供されています。

Cursor クラス

class `chdb.dbapi.cursors.Cursor`

Bases: object

クエリを実行し、結果を取得するための DB-API 2.0 カーソルです。

このカーソルは、SQL ステートメントの実行、クエリ結果の管理、および結果セット内の移動のためのメソッドを提供します。パラメータバインディングや一括操作をサポートし、DB-API 2.0 仕様に準拠しています。

Cursor インスタンスを直接作成しないでください。代わりに Connection.cursor() を使用してください。

class chdb.dbapi.cursors.Cursor(connection)

Variable	Type	Description
`description`	tuple	直前のクエリ結果の列メタデータ
`rowcount`	int	直前のクエリで影響を受けた行数（不明な場合は -1）
`arraysize`	int	一度にフェッチする行数のデフォルト値（デフォルト: 1）
`lastrowid`	-	最後に挿入された行の ID（該当する場合）
`max_stmt_length`	int	executemany() 用ステートメントの最大サイズ（デフォルト: 1024000）

例

>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1 as id, 'test' as name")
>>> result = cur.fetchone()
>>> print(result)  # (1, 'test')
>>> cur.close()

注記

完全な仕様については、DB-API 2.0 Cursor Objects を参照してください。

`callproc`

ストアドプロシージャを実行します（プレースホルダーとしての実装）。

構文

callproc(procname, args=())

パラメーター

Parameter	Type	Description
`procname`	str	実行するストアドプロシージャの名前
`args`	sequence	プロシージャに渡すパラメーター

戻り値

Return Type	Description
`sequence`	元の args 引数（変更されません）

注記

chDB/ClickHouse は、従来の意味でのストアドプロシージャをサポートしていません。このメソッドは DB-API 2.0 準拠のために提供されていますが、実際の処理は一切行いません。すべての SQL 操作には execute() を使用してください。

Compatibility

これはプレースホルダー実装です。OUT/INOUT パラメーター、複数の結果セット、サーバー変数といった従来のストアドプロシージャの機能は、基盤となる ClickHouse エンジンではサポートされていません。

`close`

カーソルを閉じて、関連するリソースを解放します。

クローズ後、カーソルは使用不能となり、どのような操作も例外を送出します。カーソルを閉じると、残りのすべてのデータが消費され、基盤となるカーソルが解放されます。

構文

close()

`execute`

オプションのパラメータバインディング付きで SQL クエリを実行します。

このメソッドは、オプションのパラメータ置換付きで単一の SQL 文を実行します。柔軟に利用できるよう、複数のパラメータプレースホルダー形式をサポートします。

構文

execute(query, args=None)

パラメーター

Parameter	Type	Default	Description
`query`	str	必須	実行する SQL クエリ
`args`	tuple/list/dict	`None`	プレースホルダーにバインドするパラメーター

戻り値

Return Type	Description
`int`	影響を受けた行数（不明な場合は -1）

パラメーター指定のスタイル

Style	Example
クエスチョンマーク形式	`"SELECT * FROM users WHERE id = ?"`
名前付き形式	`"SELECT * FROM users WHERE name = %(name)s"`
フォーマット形式（レガシー）	`"SELECT * FROM users WHERE age = %s"` (legacy)

例

>>> # Question mark parameters
>>> cur.execute("SELECT * FROM users WHERE id = ? AND age > ?", (123, 18))
>>>
>>> # Named parameters
>>> cur.execute("SELECT * FROM users WHERE name = %(name)s", {'name': 'Alice'})
>>>
>>> # No parameters
>>> cur.execute("SELECT COUNT(*) FROM users")

送出される例外

例外	条件
`ProgrammingError`	カーソルがクローズされている場合、またはクエリが不正な場合
`InterfaceError`	実行中にデータベースエラーが発生した場合

`executemany(query, args)`

異なるパラメータセットでクエリを複数回実行します。

このメソッドは、同じSQLクエリを異なるパラメータ値で複数回効率的に実行します。特に大量のINSERT操作に有用です。

構文

executemany(query, args)

パラメーター

Parameter	Type	Description
`query`	str	複数回実行する SQL クエリ
`args`	sequence	各実行ごとのパラメーター（タプル / 辞書 / リスト）のシーケンス

戻り値

Return Type	Description
`int`	すべての実行を通じて影響を受けた行の総数

使用例

>>> # Bulk insert with question mark parameters
>>> users_data = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
>>> cur.executemany("INSERT INTO users VALUES (?, ?)", users_data)
>>>
>>> # Bulk insert with named parameters
>>> users_data = [
...     {'id': 1, 'name': 'Alice'},
...     {'id': 2, 'name': 'Bob'}
... ]
>>> cur.executemany(
...     "INSERT INTO users VALUES (%(id)s, %(name)s)",
...     users_data
... )

注記

この方法では、クエリ実行処理を最適化することで、複数行に対する INSERT および UPDATE 操作のパフォーマンスを向上させます。

`fetchall()`

クエリ結果から残りのすべての行を取得します。

構文

fetchall()

戻り値

戻り値の型	説明
`list`	残りのすべての行を表すタプルのリスト

例外

例外	発生条件
`ProgrammingError`	事前に execute() が呼び出されていない場合

警告

このメソッドは、結果セットが大きい場合に大量のメモリを消費する可能性があります。大規模なデータセットには fetchmany() の使用を検討してください。

例

>>> cursor.execute("SELECT id, name FROM users")
>>> all_rows = cursor.fetchall()
>>> print(len(all_rows))  # Number of total rows

`fetchmany`

クエリ結果から複数行を取得します。

構文

fetchmany(size=1)

パラメーター

Parameter	Type	Default	Description
`size`	int	`1`	取得する行数。指定しない場合は cursor.arraysize の値が使用されます。

戻り値

Return Type	Description
`list`	取得した行を表すタプルのリスト

送出される例外

Exception	Condition
`ProgrammingError`	事前に execute() が呼び出されていない場合

使用例

>>> cursor.execute("SELECT id, name FROM users")
>>> rows = cursor.fetchmany(3)
>>> print(rows)  # [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]

`fetchone`

クエリ結果から次の行を取得します。

構文

fetchone()

戻り値

戻り値の型	説明
`tuple or None`	次の行をタプルとして返す。利用可能な行がない場合は `None` を返す

発生する例外

例外	条件
`ProgrammingError`	事前に `execute()` が呼び出されていない場合

例

>>> cursor.execute("SELECT id, name FROM users LIMIT 3")
>>> row = cursor.fetchone()
>>> print(row)  # (1, 'Alice')
>>> row = cursor.fetchone()
>>> print(row)  # (2, 'Bob')

`max_stmt_length = 1024000`

executemany() によって生成されるステートメントの最大長。

デフォルト値は 1024000 です。

`mogrify`

データベースに送信される正確なクエリ文字列を返します。

このメソッドは、パラメータ置換後の最終的な SQL クエリを表示し、デバッグやログ出力の用途に役立ちます。

構文

mogrify(query, args=None)

パラメーター

Parameter	Type	Default	Description
`query`	str	必須	パラメーター用プレースホルダーを含む SQL クエリ
`args`	tuple/list/dict	`None`	置換に使用するパラメーター

戻り値

Return Type	Description
`str`	パラメーターが適用された最終的な SQL クエリ文字列

例

>>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,))
"SELECT * FROM users WHERE id = 123"

注記

このメソッドは、Psycopg が使用している DB-API 2.0 への拡張に準拠しています。

`nextset`

次の結果セットに移動します（サポートされていません）。

構文

nextset()

戻り値

戻り値の型	説明
`None`	複数の結果セットはサポートされていないため、常に None を返します

注記

chDB/ClickHouse は、単一のクエリから複数の結果セットをサポートしていません。このメソッドは DB-API 2.0 準拠のために提供されていますが、常に None を返します。

`setinputsizes`

パラメータの入力サイズを設定します（実際には何も行わない実装）。

構文

setinputsizes(*args)

パラメータ

Parameter	Type	Description
`*args`	-	列サイズ指定（無視されます）

注記

このメソッド自体は何も行いませんが、DB-API 2.0 仕様で定められているため必要となります。 chDB は出力サイズの処理を内部で自動的に行います。

`setoutputsizes`

出力列のサイズを設定します（実質的に何もしない実装です）。

構文

setoutputsizes(*args)

パラメータ

Parameter	Type	Description
`*args`	-	列サイズ指定（無視されます）

注記

このメソッド自体は何も行いませんが、DB-API 2.0 仕様で定められているため必要となります。 chDB は出力サイズの処理を内部で自動的に行います。

エラークラス

chdb データベース操作用の例外クラスです。

このモジュールは、Python Database API Specification v2.0 に従い、 chdb におけるデータベース関連エラーを処理するための完全な例外クラス階層を提供します。

例外階層は次のように構成されています。

StandardError
├── Warning
└── Error
    ├── InterfaceError
    └── DatabaseError
        ├── DataError
        ├── OperationalError
        ├── IntegrityError
        ├── InternalError
        ├── ProgrammingError
        └── NotSupportedError

各例外クラスは特定の種類のデータベースエラーを表します。

Exception	Description
`Warning`	データベース操作中の致命的ではない警告
`InterfaceError`	データベースインターフェース自体に関する問題
`DatabaseError`	すべてのデータベース関連エラーの基底クラス
`DataError`	データ処理上の問題（無効な値、型エラーなど）
`OperationalError`	データベースの運用上の問題（接続、リソースなど）
`IntegrityError`	制約違反（外部キー、一意制約など）
`InternalError`	データベース内部エラーおよび破損状態
`ProgrammingError`	SQL 構文エラーおよび API の誤用
`NotSupportedError`	サポートされていない機能または操作

注記

これらの例外クラスは Python DB API 2.0 の仕様に準拠しており、さまざまなデータベース操作に対して一貫したエラー処理を提供します。

関連項目

Python Database API Specification v2.0
chdb.dbapi.connections - データベース接続管理
chdb.dbapi.cursors - データベースカーソル操作

例

>>> try:
...     cursor.execute("SELECT * FROM nonexistent_table")
... except ProgrammingError as e:
...     print(f"SQL Error: {e}")
...
SQL Error: Table 'nonexistent_table' doesn't exist

>>> try:
...     cursor.execute("INSERT INTO users (id) VALUES (1), (1)")
... except IntegrityError as e:
...     print(f"Constraint violation: {e}")
...
Constraint violation: Duplicate entry '1' for key 'PRIMARY'

exception `chdb.dbapi.err.DataError`

Bases: DatabaseError

処理中のデータの問題が原因で発生するエラーに対して送出される例外です。

この例外は、次のような処理対象データに起因する問題によりデータベース操作が失敗した場合に送出されます:

ゼロによる除算
数値が許容範囲外である場合
不正な日付/時刻の値
文字列の切り詰めエラー
型変換の失敗
カラム型に対して不正なデータ形式

Raises

Exception	Condition
`DataError`	データの検証または処理が失敗した場合

Examples

>>> # Division by zero in SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero

>>> # Invalid date format
>>> cursor.execute("INSERT INTO table VALUES ('invalid-date')")
DataError: Invalid date format

exception `chdb.dbapi.err.DatabaseError`

Bases: Error

データベースに関連するエラーに対して送出される例外です。

これは、すべてのデータベース関連エラーの基底クラスです。データベース操作の実行中に発生し、インターフェースではなくデータベース自体に起因するすべてのエラーを対象とします。

代表的なケースは次のとおりです。

SQL 実行時のエラー
データベース接続障害
トランザクション関連の問題
データベース固有の制約違反

注記

これは、DataError、OperationalError など、より特化したデータベースエラー型の親クラスとして機能します。

exception `chdb.dbapi.err.Error`

Bases: StandardError

他のすべてのエラー例外（Warning を除く）の基底クラスとなる例外です。

これは、chdb におけるすべてのエラー例外（警告を除く）の基底クラスです。操作の正常な完了を妨げる、すべてのデータベースエラー状態の親クラスとして機能します。

注記

この例外階層は、Python DB API 2.0 仕様に従っています。

See also

Warning - 操作の完了を妨げない非致命的な警告用

exception `chdb.dbapi.err.IntegrityError`

Bases: DatabaseError

データベースのリレーショナル整合性が損なわれた場合に送出される例外です。

この例外は、データベース操作が整合性制約に違反した場合に送出されます。たとえば、次のようなケースが含まれます。

外部キー制約違反
主キーまたは一意制約違反（重複キー）
CHECK 制約違反
NOT NULL 制約違反
参照整合性違反

Raises

Exception	Condition
`IntegrityError`	データベースの整合性制約違反時に送出

Examples

>>> # Duplicate primary key
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'John')")
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Jane')")
IntegrityError: Duplicate entry '1' for key 'PRIMARY'

>>> # Foreign key violation
>>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)")
IntegrityError: Cannot add or update a child row: foreign key constraint fails

exception `chdb.dbapi.err.InterfaceError`

Bases: Error

データベース自体ではなく、データベースインターフェースに関連するエラーに対して送出される例外です。

この例外は、次のようなデータベースインターフェース実装上の問題がある場合に送出されます。

無効な接続パラメータ
API の誤った使用（クローズ済み接続に対するメソッド呼び出し）
インターフェースレベルでのプロトコルエラー
モジュールのインポートまたは初期化の失敗

送出される例外

例外	条件
`InterfaceError`	データベース操作とは無関係なインターフェースエラーが発生した場合

注記

これらのエラーは通常、プログラミングエラーや設定ミスであり、クライアントコードまたは設定を修正することで解決できます。

exception `chdb.dbapi.err.InternalError`

Bases: DatabaseError

データベースで内部エラーが発生した際に送出される例外です。

この例外は、データベースシステムがアプリケーション起因ではない内部エラーに遭遇した場合に送出されます。たとえば:

無効なカーソル状態（カーソルがもはや有効ではない）
トランザクション状態の不整合（トランザクションが同期から外れている）
データベース破損の問題
内部データ構造の破損
システムレベルのデータベースエラー

送出される例外

例外	条件
`InternalError`	データベース内部の不整合が検出された場合

Warning

内部エラーは、データベース管理者の対応が必要となる重大なデータベース問題を示している可能性があります。これらのエラーは通常、アプリケーションレベルでのリトライロジックでは回復できません。

注記

これらのエラーは一般的にアプリケーションの制御範囲外であり、データベースの再起動や修復作業が必要になる場合があります。

exception `chdb.dbapi.err.NotSupportedError`

Bases: DatabaseError

メソッドまたはデータベース API がサポートされていない場合に送出される例外です。

この例外は、アプリケーションが、現在のデータベース構成またはバージョンでサポートされていないデータベース機能や API メソッドを使用しようとしたときに送出されます。たとえば:

トランザクションをサポートしない接続で rollback() を要求した場合
データベースのバージョンでサポートされていない高度な SQL 機能の使用
現在のドライバーで実装されていないメソッドの呼び出し
無効化されているデータベース機能の使用を試みた場合

送出される例外

例外	条件
`NotSupportedError`	未サポートのデータベース機能にアクセスした場合

例

>>> # Transaction rollback on non-transactional connection
>>> connection.rollback()
NotSupportedError: Transactions are not supported

>>> # Using unsupported SQL syntax
>>> cursor.execute("SELECT * FROM table WITH (NOLOCK)")
NotSupportedError: WITH clause not supported in this database version

注記

これらのエラーを回避するには、データベースのドキュメントとドライバーのサポート状況を確認してください。可能であれば、適切なフォールバック処理も検討してください。

exception `chdb.dbapi.err.OperationalError`

Bases: DatabaseError

データベースの操作に関連するエラーに対して送出される例外です。

この例外は、データベース操作中に発生し、必ずしもプログラマーの制御下にはないエラーに対して送出されます。例としては次のようなものがあります:

データベースからの予期しない切断
データベースサーバーが見つからない、または到達不能
トランザクション処理の失敗
処理中のメモリ割り当てエラー
ディスク容量またはその他リソースの枯渇
データベースサーバー内部エラー
認証または認可の失敗

送出される例外

例外	条件
`OperationalError`	データベース操作が運用上の問題により失敗した場合

注記

これらのエラーは一般的に一時的なものであり、操作をリトライするか、システムレベルの問題に対処することで解決する場合があります。

警告

一部の運用上のエラーは、管理者による対応が必要な重大なシステム障害を示している場合があります。

exception `chdb.dbapi.err.ProgrammingError`

Bases: DatabaseError

データベース操作におけるプログラミングエラーに対して送出される例外です。

この例外は、アプリケーションによるデータベースの利用方法にプログラミング上の誤りがある場合に送出されます。例としては次のようなものがあります:

テーブルまたはカラムが見つからない
作成処理時に、テーブルまたはインデックスがすでに存在する
ステートメント内のSQL構文エラー
プリペアドステートメントで指定されたパラメーター数が不正
無効なSQL操作（例: 存在しないオブジェクトに対するDROP）
データベースAPIメソッドの誤った使用方法

Raises

Exception	Condition
`ProgrammingError`	SQLステートメントまたはAPIの利用方法に誤りがある場合

Examples

>>> # Table not found
>>> cursor.execute("SELECT * FROM nonexistent_table")
ProgrammingError: Table 'nonexistent_table' doesn't exist

>>> # SQL syntax error
>>> cursor.execute("SELCT * FROM users")
ProgrammingError: You have an error in your SQL syntax

>>> # Wrong parameter count
>>> cursor.execute("INSERT INTO users (name, age) VALUES (%s)", ('John',))
ProgrammingError: Column count doesn't match value count

exception `chdb.dbapi.err.StandardError`

Bases: Exception

chdb の操作に関連する例外。

これは、すべての chdb 関連の例外の基底クラスです。Python 組み込みの Exception クラスを継承しており、データベース操作における例外階層のルートとして機能します。

注記

この例外クラスは、データベースの例外処理に関する Python DB API 2.0 仕様に準拠しています。

exception `chdb.dbapi.err.Warning`

Bases: StandardError

挿入時のデータ切り捨てなどの重要な警告に対してスローされる例外。

この例外は、データベース操作自体は完了したものの、アプリケーション側で注意喚起が必要な重要な警告が発生した場合にスローされます。一般的なシナリオとしては次のようなものがあります:

挿入時のデータ切り捨て
数値変換における精度の損失
文字セット変換に関する警告

注記

これは、警告用例外に関する Python DB API 2.0 仕様に準拠しています。

モジュール定数

`chdb.dbapi.apilevel = '2.0'`

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

指定されたオブジェクトから新しい文字列オブジェクトを作成します。encoding または errors が指定されている場合、そのオブジェクトはデータバッファを提供している必要があり、そのバッファは指定されたエンコーディングおよびエラーハンドラーを使ってデコードされます。それ以外の場合は、object.__str__()（定義されている場合）の結果、または repr(object) を返します。

encoding のデフォルトは ‘utf-8’ です。
errors のデフォルトは ‘strict’ です。

`chdb.dbapi.threadsafety = 1`

int([x]) -> integer
int(x, base=10) -> integer

数値または文字列を整数に変換します。引数が指定されない場合は 0 を返します。x が数値であれば、x._int_() を返します。浮動小数点数の場合は 0 に向かって切り捨てます。

x が数値でない場合、または base が指定された場合、x は指定された基数の整数リテラルを表す文字列、bytes、または bytearray インスタンスである必要があります。リテラルの前には ‘+’ または ‘-’ を付けることができ、前後に空白を含めることもできます。基数のデフォルトは 10 です。有効な基数は 0 および 2〜36 です。基数 0 の場合は、その文字列を整数リテラルとして解釈し、表記から基数を判断します。

>>> int(‘0b100’, base=0)
4

`chdb.dbapi.paramstyle = 'format'`

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

与えられたオブジェクトから新しい文字列オブジェクトを生成します。encoding または errors が指定されている場合、オブジェクトはデータバッファを提供している必要があり、そのバッファは指定されたエンコーディングとエラーハンドラーを用いてデコードされます。それ以外の場合は、object._str_()（定義されている場合）の戻り値、または repr(object) を返します。 encoding のデフォルトは ‘utf-8’ です。 errors のデフォルトは ‘strict’ です。

型定数

`chdb.dbapi.STRING = frozenset({247, 253, 254})`

DB-API 2.0 の型比較用に拡張された frozenset です。

このクラスは frozenset を拡張して、DB-API 2.0 の型比較セマンティクスをサポートします。これにより、個々の要素を等価演算子および非等価演算子の両方を使って集合に対して柔軟に型チェックできるようにします。

STRING、BINARY、NUMBER などの型定数に対して使用され、 field_type が単一の型値であるときに「field_type == STRING」のような比較を可能にします。

使用例

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

`chdb.dbapi.BINARY = frozenset({249, 250, 251, 252})`

DB-API 2.0 の型比較のために拡張された frozenset です。

このクラスは frozenset を拡張して、DB-API 2.0 の型比較セマンティクスをサポートします。個々の要素を、等価・非等価演算子の両方を用いて集合と比較できる柔軟な型チェックを可能にします。

これは STRING、BINARY、NUMBER などの型定数に対して使用され、 field_type が単一の型値である場合に field_type == STRING のような比較を行えるようにします。

使用例

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

`chdb.dbapi.NUMBER = frozenset({0, 1, 3, 4, 5, 8, 9, 13})`

DB-API 2.0 の型比較のために拡張された frozenset。

使用例

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

`chdb.dbapi.DATE = frozenset({10, 14})`

DB-API 2.0 の型比較のために拡張された frozenset です。

このクラスは frozenset を拡張し、DB-API 2.0 の型比較セマンティクスをサポートします。個々の要素に対し、等価演算子および非等価演算子の両方を用いた柔軟な型チェックを可能にします。

これは STRING、BINARY、NUMBER などの型定数に対して使用され、 field_type が単一の型値である場合に “field_type == STRING” のような比較が行えるようにします。

使用例

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

`chdb.dbapi.TIME = frozenset({11})`

DB-API 2.0 の型比較用に拡張された frozenset。

このクラスは frozenset を拡張し、DB-API 2.0 における型比較のセマンティクスをサポートします。これにより、個々の要素を等価演算子および不等価演算子の両方を使って集合に対して柔軟に型チェックを行えるようになります。

これは STRING、BINARY、NUMBER などの型定数に使用され、 field_type が単一の型値である場合に field_type == STRING のような比較を可能にします。

使用例

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

`chdb.dbapi.TIMESTAMP = frozenset({7, 12})`

DB-API 2.0 の型比較のために拡張された frozenset。

このクラスは frozenset を拡張し、DB-API 2.0 の型比較セマンティクスをサポートします。個々の要素を等価演算子および不等価演算子の両方を使って集合と比較できる、柔軟な型チェックを可能にします。

これは STRING、BINARY、NUMBER などの型定数に対して使用され、 field_type が単一の型値である場合に、field_type == STRING のような比較を行えるようにします。

例

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

`chdb.dbapi.DATETIME = frozenset({7, 12})`

DB-API 2.0 の型比較のために拡張された frozenset です。

例

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

`chdb.dbapi.ROWID = frozenset({})`

DB-API 2.0 の型比較のために拡張された frozenset。

このクラスは、DB-API 2.0 の型比較セマンティクスをサポートするために frozenset を拡張したものです。これにより、個々の項目を、等価演算子および不等価演算子の両方を使用して集合に対して柔軟に型チェックを行えるようになります。

これは STRING、BINARY、NUMBER などの型定数に対して使用され、 field_type が単一の型値である場合に “field_type == STRING” のような比較を行えるようにします。

例

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

使用例

基本的なクエリ例:

import chdb.dbapi as dbapi

print("chdb driver version: {0}".format(dbapi.get_client_info()))

# Create connection and cursor
conn = dbapi.connect()
cur = conn.cursor()

# Execute query
cur.execute('SELECT version()')
print("description:", cur.description)
print("data:", cur.fetchone())

# Clean up
cur.close()
conn.close()

データ操作:

import chdb.dbapi as dbapi

conn = dbapi.connect()
cur = conn.cursor()

# Create table
cur.execute("""
    CREATE TABLE employees (
        id UInt32,
        name String,
        department String,
        salary Decimal(10,2)
    ) ENGINE = Memory
""")

# Insert data
cur.execute("""
    INSERT INTO employees VALUES
    (1, 'Alice', 'Engineering', 75000.00),
    (2, 'Bob', 'Marketing', 65000.00),
    (3, 'Charlie', 'Engineering', 80000.00)
""")

# Query data
cur.execute("SELECT * FROM employees WHERE department = 'Engineering'")

# Fetch results
print("Column names:", [desc[0] for desc in cur.description])
for row in cur.fetchall():
    print(row)

conn.close()

接続管理:

import chdb.dbapi as dbapi

# In-memory database (default)
conn1 = dbapi.connect()

# Persistent database file
conn2 = dbapi.connect("./my_database.chdb")

# Connection with parameters
conn3 = dbapi.connect("./my_database.chdb?log-level=debug&verbose")

# Read-only connection
conn4 = dbapi.connect("./my_database.chdb?mode=ro")

# Automatic connection cleanup
with dbapi.connect("test.chdb") as conn:
    cur = conn.cursor()
    cur.execute("SELECT count() FROM numbers(1000)")
    result = cur.fetchone()
    print(f"Count: {result[0]}")
    cur.close()

ベストプラクティス

接続管理: 使用後は必ず接続とカーソルを閉じる
コンテキストマネージャー: 自動クリーンアップのためにwith文を使用する
バッチ処理: 大規模な結果セットにはfetchmany()を使用する
エラー処理: データベース操作をtry-exceptブロックで囲む
パラメータバインディング: 可能な限りパラメータ化クエリを使用する
メモリ管理: 非常に大規模なデータセットではfetchall()の使用を避ける

注記

chDBのDB-API 2.0インターフェースは、ほとんどのPythonデータベースツールと互換性がある
このインターフェースはレベル1のスレッドセーフティを提供する（スレッドはモジュールを共有できるが、接続は共有できない）
接続文字列はchDBセッションと同じパラメータをサポートする
すべての標準DB-API 2.0例外がサポートされている

警告

リソースリークを避けるため、必ずカーソルと接続を閉じる
大規模な結果セットはバッチで処理する
パラメータバインディング構文はフォーマットスタイルに従う: %s

ユーザー定義関数 (UDF)

chDB 向けのユーザー定義関数モジュール。

このモジュールは、chDB におけるユーザー定義関数 (UDF) の作成と管理のための機能を提供します。独自の Python 関数を定義し、それを SQL クエリから呼び出すことで、chDB の機能を拡張できます。

`chdb.udf.chdb_udf`

chDB の Python UDF（ユーザー定義関数）用デコレータ。

構文

chdb.udf.chdb_udf(return_type='String')

パラメータ

Parameter	Type	Default	Description
`return_type`	str	`"String"`	関数の戻り値の型。ClickHouse のデータ型のいずれかである必要があります

注意事項

関数はステートレスである必要があります。UDF のみがサポートされ、UDAF はサポートされません。
デフォルトの戻り値の型は String です。戻り値の型は ClickHouse のデータ型のいずれかである必要があります。
関数は String 型（文字列型）の引数を受け取る必要があります。すべての引数は文字列です。
関数は入力の各行に対して呼び出されます。
関数は pure Python の関数である必要があります。使用するモジュールはすべてその関数内でインポートしてください。
使用される Python インタープリタは、スクリプトの実行に使用されるものと同一です。

例

@chdb_udf()
def sum_udf(lhs, rhs):
    return int(lhs) + int(rhs)

@chdb_udf()
def func_use_json(arg):
    import json
    # ... use json module

`chdb.udf.generate_udf`

UDF の構成および実行スクリプトファイルを生成します。

この関数は、chDB の User Defined Function (UDF) に必要なファイルを作成します。

入力データを処理する Python の実行スクリプト
UDF を ClickHouse に登録する XML 構成ファイル

構文

chdb.udf.generate_udf(func_name, args, return_type, udf_body)

パラメータ

パラメータ	型	説明
`func_name`	str	UDF 関数の名前
`args`	list	関数の引数名のリスト
`return_type`	str	関数の ClickHouse における戻り値型
`udf_body`	str	UDF 関数の Python ソースコードの本体

注記

この関数は通常 @chdb_udf デコレータから呼び出されるものであり、ユーザーが直接呼び出すべきものではありません。

ユーティリティ

chDB 向けのユーティリティ関数およびヘルパー関数です。

このモジュールには、chDB を扱うための各種ユーティリティ関数が含まれており、データ型推論、データ変換用ヘルパー、およびデバッグ用ユーティリティなどを提供します。

`chdb.utils.convert_to_columnar`

辞書のリストをカラム形式に変換します。

この関数は辞書のリストを受け取り、各キーがカラムに対応し、各値がそのカラムの値のリストとなる辞書に変換します。辞書内で欠損している値は None として表現されます。

構文

chdb.utils.convert_to_columnar(items: List[Dict[str, Any]]) → Dict[str, List[Any]]

パラメーター

Parameter	Type	Description
`items`	`List[Dict[str, Any]]`	変換する辞書のリストです

戻り値

Return Type	Description
`Dict[str, List[Any]]`	キーが列名、値が各列の値のリストである辞書を返します

例

>>> items = [
...     {"name": "Alice", "age": 30, "city": "New York"},
...     {"name": "Bob", "age": 25},
...     {"name": "Charlie", "city": "San Francisco"}
... ]
>>> convert_to_columnar(items)
{
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [30, 25, None],
    'city': ['New York', None, 'San Francisco']
}

`chdb.utils.flatten_dict`

ネストされた辞書をフラット化します。

この関数はネストされた辞書を受け取り、セパレーターでネストされたキーを連結してフラット化します。辞書のリストは JSON 文字列としてシリアライズされます。

構文

chdb.utils.flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '_') → Dict[str, Any]

パラメーター

パラメーター	型	デフォルト	説明
`d`	`Dict[str, Any]`	必須	フラット化する辞書
`parent_key`	str	`""`	各キーに前置するベースキー
`sep`	str	`"_"`	連結したキー間の区切り文字として使用する文字

戻り値

戻り値の型	説明
`Dict[str, Any]`	フラット化された辞書

例

>>> nested_dict = {
...     "a": 1,
...     "b": {
...         "c": 2,
...         "d": {
...             "e": 3
...         }
...     },
...     "f": [4, 5, {"g": 6}],
...     "h": [{"i": 7}, {"j": 8}]
... }
>>> flatten_dict(nested_dict)
{
    'a': 1,
    'b_c': 2,
    'b_d_e': 3,
    'f_0': 4,
    'f_1': 5,
    'f_2_g': 6,
    'h': '[{"i": 7}, {"j": 8}]'
}

`chdb.utils.infer_data_type`

値のリストに対して最も適したデータ型を推論します。

この関数は値のリストを調べ、そのリスト内のすべての値を表現できる最も適切なデータ型を決定します。整数、符号なし整数、小数（decimal）、および浮動小数点数型を考慮し、値がいずれの数値型でも表現できない場合、またはすべての値が None の場合は「string」をデフォルトとして使用します。

構文

chdb.utils.infer_data_type(values: List[Any]) → str

パラメータ

Parameter	Type	Description
`values`	`List[Any]`	解析する値のリスト。任意の型の値を含めることができます

戻り値

戻り値の型	説明
`str`	推論されたデータ型を表す文字列。返される可能性のある値は次のとおりです: 「int8」「int16」「int32」「int64」「int128」「int256」「uint8」「uint16」「uint32」「uint64」「uint128」「uint256」「decimal128」「decimal256」「float32」「float64」または「string」。

注記

リスト内のすべての値が None の場合、関数は「string」を返します。
リスト内に 1 つでも文字列が含まれている場合、関数は直ちに「string」を返します。
関数は、数値がその範囲と精度に基づいて整数、小数（decimal）、または浮動小数点数として表現できると仮定します。

`chdb.utils.infer_data_types`

列指向データ構造の各列に対してデータ型を推論します。

この関数は各列内の値を分析し、データのサンプルに基づいて、各列に最も適したデータ型を推論します。

構文

chdb.utils.infer_data_types`(column_data: Dict[str, List[Any]], n_rows: int = 10000) → List[tuple]

パラメータ

Parameter	Type	Default	Description
`column_data`	`Dict[str, List[Any]]`	required	キーが列名、値が列値のリストである辞書
`n_rows`	int	`10000`	型推論に使用するサンプリング行数

戻り値

Return Type	Description
`List[tuple]`	各要素が列名と推論されたデータ型を含むタプルから成るリスト

抽象基底クラス

class `chdb.rwabc.PyReader`(data: Any)`

基底クラス: ABC

class chdb.rwabc.PyReader(data: Any)

abstractmethod `read`

指定された数の行を、与えられた列から読み取り、オブジェクトのリストを返します。ここで各オブジェクトは、1 つの列に対する値の並びです。

abstractmethod (col_names: List[str], count: int) → List[Any]

パラメータ

パラメータ	型	説明
`col_names`	`List[str]`	読み取る列名のリスト
`count`	int	読み取る行数の上限

戻り値

戻り値の型	説明
`List[Any]`	各列に対応するシーケンスを要素とするリスト

class `chdb.rwabc.PyWriter`

基底クラス: ABC

class chdb.rwabc.PyWriter(col_names: List[str], types: List[type], data: Any)

abstractmethod finalize

ブロックから最終的なデータを組み立てて返します。サブクラスで必ず実装する必要があります。

abstractmethod finalize() → bytes

戻り値

戻り値の型	説明
`bytes`	最終的なシリアライズ済みデータ

abstractmethod `write`

列データをブロックに保存します。サブクラスで実装する必要があります。

abstractmethod write(col_names: List[str], columns: List[List[Any]]) → None

パラメータ

Parameter	Type	Description
`col_names`	`List[str]`	書き込み対象となる列名のリスト
`columns`	`List[List[Any]]`	列データのリスト。各列は1つのリストとして表現される

例外処理

class `chdb.ChdbError`

Bases: Exception

chDB 関連のエラーに対する基底の例外クラスです。

この例外は、chDB のクエリ実行に失敗した場合やエラーが発生した場合に送出されます。標準の Python の Exception クラスを継承しており、基盤となる ClickHouse エンジンからのエラー情報を提供します。

例外メッセージには通常、ClickHouse からの詳細なエラー情報が含まれます。たとえば、構文エラー、型の不一致、テーブル／カラムの不足、その他のクエリ実行上の問題などです。

変数

Variable	Type	Description
`args`	-	エラーメッセージおよび追加の引数を含むタプル

例

>>> try:
...     result = chdb.query("SELECT * FROM non_existent_table")
... except chdb.ChdbError as e:
...     print(f"Query failed: {e}")
Query failed: Table 'non_existent_table' doesn't exist

>>> try:
...     result = chdb.query("SELECT invalid_syntax FROM")
... except chdb.ChdbError as e:
...     print(f"Syntax error: {e}")
Syntax error: Syntax error near 'FROM'

注記

この例外は、背後で動作する ClickHouse エンジンがエラーを報告した際に、 chdb.query() および関連関数によって自動的に送出されます。失敗する可能性のあるクエリを実行する場合は、この例外を捕捉し、アプリケーション内で適切なエラー処理を行ってください。

バージョン情報

`chdb.chdb_version = ('3', '6', '0')`

組み込みのイミュータブルなシーケンスです。

引数を指定しない場合、コンストラクターは空のタプルを返します。 iterable が指定された場合、タプルはそのイテラブルの要素から初期化されます。

引数がタプルである場合、戻り値は同一のオブジェクトになります。

`chdb.engine_version = '25.5.2.1'`

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

指定されたオブジェクトから新しい文字列オブジェクトを作成します。encoding または errors が指定された場合、そのオブジェクトは、指定されたエンコーディングとエラーハンドラーを使ってデコードされるデータバッファを公開している必要があります。指定されていない場合は、object._str_()（定義されていれば）の結果、または repr(object) を返します。

encoding のデフォルトは ‘utf-8’ です。
errors のデフォルトは ‘strict’ です。

`chdb.version = '3.6.0'`

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

encoding のデフォルトは ‘utf-8’ です。
errors のデフォルトは ‘strict’ です。

コアクエリ関数​

chdb.query​

chdb.sql​

chdb.to_arrowTable​

chdb.to_df​

接続とセッション管理​

chdb.connect​

例外処理​

class chdb.ChdbError​

class chdb.session.Session​

cleanup​

close​

query​

send_query​

sql​

状態管理​

chdb.state.connect​

class chdb.state.sqlitelike.Connection​

close​

cursor​

query​

send_query​

class chdb.state.sqlitelike.StreamingResult​

fetch​

cancel​

close​

record_batch​

イテレータプロトコル​

コンテキストマネージャープロトコル​

class chdb.state.sqlitelike.Cursor​

close​

column_names​

column_types​

commit​

property description : list​

execute​

fetchall​

fetchmany​

fetchone​

chdb.state.sqlitelike​

chdb.state.sqlitelike.to_df​

DataFrame 統合​

class chdb.dataframe.Table​

Database API (DBAPI) 2.0 インターフェイス​

コア関数​

chdb.dbapi.connect​

chdb.dbapi.get_client_info()​

型コンストラクタ​

chdb.dbapi.Binary(x)​

Connection クラス​

class chdb.dbapi.connections.Connection(path=None)​

close​

commit​

cursor​

escape​

escape_string​

property open​

query​

property resp​

rollback​

Cursor クラス​

class chdb.dbapi.cursors.Cursor​

callproc​

close​

execute​

executemany(query, args)​

fetchall()​

fetchmany​

fetchone​

max_stmt_length = 1024000​

mogrify​

nextset​

setinputsizes​

setoutputsizes​

エラークラス​

exception chdb.dbapi.err.DataError​

exception chdb.dbapi.err.DatabaseError​

exception chdb.dbapi.err.Error​

exception chdb.dbapi.err.IntegrityError​

exception chdb.dbapi.err.InterfaceError​

コアクエリ関数

`chdb.query`

`chdb.sql`

`chdb.to_arrowTable`

`chdb.to_df`

接続とセッション管理

`chdb.connect`

例外処理

class `chdb.ChdbError`

class `chdb.session.Session`

`cleanup`

`close`

`query`

`send_query`

`sql`

状態管理

`chdb.state.connect`

class `chdb.state.sqlitelike.Connection`

`close`

`cursor`

`query`

`send_query`

class `chdb.state.sqlitelike.StreamingResult`

`fetch`

`cancel`

`close`

`record_batch`

イテレータプロトコル

コンテキストマネージャープロトコル

class `chdb.state.sqlitelike.Cursor`

`close`

`column_names`

`column_types`

`commit`

`property description : list`

`execute`

`fetchall`

`fetchmany`

`fetchone`

`chdb.state.sqlitelike`

`chdb.state.sqlitelike.to_df`

DataFrame 統合

class `chdb.dataframe.Table`

Database API (DBAPI) 2.0 インターフェイス

コア関数

`chdb.dbapi.connect`

`chdb.dbapi.get_client_info()`

型コンストラクタ

`chdb.dbapi.Binary(x)`

Connection クラス

class `chdb.dbapi.connections.Connection(path=None)`

`close`

`commit`

`cursor`

`escape`

`escape_string`

`property open`

`query`

`property resp`

`rollback`

Cursor クラス

class `chdb.dbapi.cursors.Cursor`

`callproc`

`close`

`execute`

`executemany(query, args)`

`fetchall()`

`fetchmany`

`fetchone`

`max_stmt_length = 1024000`

`mogrify`

`nextset`

`setinputsizes`

`setoutputsizes`

エラークラス

exception `chdb.dbapi.err.DataError`

exception `chdb.dbapi.err.DatabaseError`

exception `chdb.dbapi.err.Error`

exception `chdb.dbapi.err.IntegrityError`

exception `chdb.dbapi.err.InterfaceError`