返回值
以指定的格式返回查询结果:
引发异常
示例
使用 chDB 引擎执行 SQL 查询。 这是主要的查询函数,使用嵌入式 ClickHouse 引擎执行 SQL 语句。支持多种输出格式,并且可用于临时 或基于文件的数据库。 语法
返回值
按指定格式返回查询结果:
引发异常
示例
将查询结果转换为 PyArrow 表。 将 chDB 的查询结果转换为 PyArrow 表,以高效处理列式数据。 如果结果为空,则返回空表。 语法
返回值
引发的异常
示例
将查询结果转换为 pandas DataFrame。 先将 chDB 的查询结果转换为 PyArrow Table,再使用多线程将其转换为 pandas,以提升性能。 语法
返回值
引发异常
示例
基础版格式
带查询参数
查询参数处理
查询参数会作为启动参数传递给 ClickHouse 引擎。
特殊参数处理如下:
如需完整参数列表,请参见
clickhouse local --help --verbose
返回值
抛出异常
一个进程运行一个绑定到单一数据库路径的嵌入式引擎。可同时存在多个到同一路径的连接并并发运行查询。任何连接处于打开状态时,打开不同的路径将引发
RuntimeError;请先关闭已打开的连接。Connection- 数据库连接类Cursor- 用于 DB-API 2.0 操作的数据库游标
Exception
与 chDB 相关错误的基础异常类。
当 chDB 查询执行失败或发生
错误时,会引发此异常。它继承自标准 Python 的 Exception 类,
并提供来自底层 ClickHouse 引擎的错误信息。
基类:
object
Session 会保留查询状态。
如果 path 为 None,会话会使用进程范围的临时 (:memory:) 数据库,因此所有未指定 path 的会话 都能看到彼此的表;仅当最后一个此类会话 或 connection 关闭时,其临时目录才会被删除。
你也可以传入一个 path,在该 path 创建数据库,数据将保存在那里。
你也可以使用连接字符串传入该 path 和其他参数。
连接字符串参数处理对于包含查询参数的连接字符串,例如 “file:test.db?param1=value1¶m2=value2”,
其中的 “param1=value1” 会作为启动参数传递给 ClickHouse 引擎。更多详情,请参见
clickhouse local –help –verbose一些特殊参数的处理方式:- “mode=ro” 在 clickhouse 中会转换为 “–readonly=1” (只读模式)
重要
- 多个会话可以共存,只要它们共享相同的数据库路径。
- 若要使用不同的数据库路径,请先关闭已打开的会话。
在处理异常时清理会话资源。 此方法会尝试关闭会话,同时抑制清理过程中可能发生的任何异常。在异常处理场景中,或者当你需要确保无论会话处于何种状态都能执行清理时,它尤其有用。 语法
此方法绝不会抛出异常,因此可安全地在
finally 块或析构函数中调用。
close()- 用于显式关闭会话,并传播错误
关闭会话并清理资源。 此方法会关闭底层连接并重置全局会话状态。 调用此方法后,会话将失效,无法再用于 后续查询。 语法
当会话用作上下文管理器时,
或会话对象被销毁时,此方法会自动调用。
执行 SQL 查询并返回结果。 此方法会在会话的数据库中执行 SQL 查询,并以指定格式返回结果。该方法支持多种输出格式,并在多次查询之间保持会话状态。 语法
返回值
以指定格式返回查询结果。
具体返回类型取决于
fmt 参数:
- String 格式 (CSV、JSON 等) 返回
str - 二进制格式 (Arrow、Parquet) 返回
bytes
不支持 “Debug” 格式,系统会自动将其转换为 “CSV” 并发出警告。
如需调试,请改用连接字符串参数。
send_query()- 用于以流式方式执行查询sql- 该方法的别名
执行 SQL 查询,并返回一个流式结果迭代器。 此方法会针对会话的数据库执行 SQL 查询,并返回一个流式结果对象,让你能够遍历结果,而无需一次将全部内容加载到内存中。这对于大型结果集尤其有用。 语法
返回值
抛出异常
不支持 “Debug” 格式,并会在发出警告后自动转换为 “CSV”。
如需调试,请改用 connection string 参数。
query()- 用于执行非流式查询chdb.state.sqlitelike.StreamingResult- 流式结果迭代器
执行 SQL 查询并返回结果。 此方法会在会话的数据库中执行 SQL 查询,并以指定格式返回结果。该方法支持多种输出格式,并在多次查询之间保持会话状态。 语法
返回值
以指定格式返回查询结果。
具体返回类型取决于
fmt 参数:
- String 格式 (CSV、JSON 等) 返回 str
- 二进制格式 (Arrow、Parquet) 返回 bytes
不支持 “Debug” 格式,并会自动将其转换为 “CSV”,同时发出警告。
如需调试,请改用连接字符串参数。
send_query()- 用于流式执行查询sql- 该方法的别名
基础格式
支持的连接字符串格式:
带查询参数
查询参数处理
查询参数会作为启动参数传递给 ClickHouse 引擎。
特殊参数处理如下:
完整参数列表请参见
clickhouse local --help --verbose
返回值
引发
一个进程运行一个绑定到单个数据库路径的嵌入式引擎。可同时存在多个连接到同一路径的连接,并并发执行查询。当任何连接处于打开状态时,打开不同的路径会引发
RuntimeError;请先关闭已打开的连接。Connection- 数据库连接类Cursor- 用于 DB-API 2.0 操作的数据库游标
object
语法
关闭连接并清理资源。 此方法会关闭数据库连接,并清理所有相关资源, 包括活动游标。调用此方法后, 该连接将失效,无法再用于后续操作。 语法
此方法是幂等的——多次调用也很安全。
创建一个用于执行查询的 Cursor 对象。 此方法会创建一个数据库游标,提供执行查询和获取结果所需的标准 DB-API 2.0 接口。 该游标可对查询执行 和结果获取进行更细粒度的控制。 语法
创建新游标会替换与此连接关联的现有游标。每个连接仅支持一个游标。
Cursor- 数据库游标的实现
执行 SQL 查询并返回完整结果。 此方法会同步执行 SQL 查询,并返回完整的 结果集。它支持多种输出格式,并会自动进行 格式特定的后处理。 语法
返回值
引发的异常
示例
send_query()- 用于以流式方式执行查询
执行 SQL 查询并返回一个流式结果迭代器。 此方法会执行 SQL 查询,并返回一个 StreamingResult 对象, 让你能够遍历结果,而不必一次性将所有内容 加载到内存中。这非常适合处理大型结果集。 语法
返回
引发
只有 “Arrow” 格式支持对返回的 StreamingResult 调用
record_batch() 方法。query()- 用于执行非流式查询StreamingResult- 流式结果迭代器
基类:
object
用于处理大型查询结果的流式结果迭代器。
此类提供迭代器接口,可在不将整个结果集加载到内存中的情况下流式处理查询结果。它支持多种输出格式,并提供用于手动拉取结果和流式传输 PyArrow RecordBatch 的方法。
拉取下一批流式结果。 此方法会从流式查询结果中拉取下一批可用数据。返回数据的格式取决于发起流式查询时指定的格式。 语法
示例
取消流式查询并清理资源。 此方法会取消任何正在进行的流式查询,并释放相关 资源。当你希望在流耗尽之前停止处理结果时, 应调用它。 语法
关闭流式结果并清理资源。
cancel() 的别名。用于关闭流式结果迭代器,
并释放相关资源。
语法
创建一个 PyArrow RecordBatchReader,以高效进行批次处理。 该方法会创建一个 PyArrow RecordBatchReader,使您能够高效地 迭代 Arrow 格式的查询结果。这是在使用 PyArrow 时处理大型 结果集的最高效方式。 语法
返回值
该方法仅在流式查询以
format="Arrow" 启动时可用。与其他格式一起使用会引发错误。StreamingResult 支持 Python 的迭代器协议,因此可以 直接用于 for 循环:
StreamingResult 支持上下文管理器协议,可自动清理资源:
基类:
object
关闭游标并释放资源。 此方法会关闭游标并释放所有相关资源。 调用此方法后,游标将失效,且无法再 用于后续操作。 语法
此方法具有幂等性——多次调用也是安全的。
连接关闭时,游标也会自动关闭。
返回最近一次执行的查询的列名列表。 此方法返回最近一次执行的 SELECT 查询的列名。返回的名称顺序与它们在结果集中的顺序 一致。 语法
示例
column_types()- 获取列类型信息description- DB-API 2.0 列描述
返回上一次执行的查询中的列类型列表。 此方法返回最近一次执行的 SELECT 查询的 ClickHouse 列类型名称。返回的类型顺序与其在结果集中的出现顺序一致。 语法
示例
column_names()- 获取列名信息description- DB-API 2.0 列说明
提交所有待处理的事务。 此方法会提交所有待处理的数据库事务。在 ClickHouse 中, 大多数操作都会自动提交,但提供此方法是为了兼容 DB-API 2.0。
ClickHouse 通常会自动提交操作,因此通常无需显式提交。
提供此方法是为了兼容标准的 DB-API 2.0 工作流程。
按照 DB-API 2.0 规范返回列描述。 此属性会返回一个包含 7 项 Tuple 的列表,用于描述最近一次执行的 SELECT 查询结果集中的每一列。每个 Tuple 包含: (name, type_code, display_size, internal_size, precision, scale, null_ok) 目前,仅提供 name 和 type_code,其他字段均设为 None。 返回值
这符合 DB-API 2.0 中对
cursor.description 的规范。
在此实现中,只有前两个元素 (name 和 type_code) 包含有效
数据。column_names()- 仅获取列名column_types()- 仅获取列类型
执行 SQL 查询,并为后续拉取结果做好准备。 此方法执行 SQL 查询,并将结果准备为可通过 fetch 方法获取。它会处理结果数据的解析,以及 ClickHouse 数据类型的自动转换。 语法
引发
此方法遵循 DB-API 2.0 中
cursor.execute() 的规范。
执行后,请使用 fetchone()、fetchmany() 或 fetchall()
获取结果。该方法会自动将 ClickHouse 数据类型转换为相应的
Python 类型:
- Int/UInt 类型 → int
- Float 类型 → float
- String/FixedString → str
- DateTime → datetime.datetime
- Date → datetime.date
- Bool → bool
fetchone()- 获取单行fetchmany()- 获取多行fetchall()- 获取所有剩余行
从查询结果中拉取所有剩余行。 此方法从当前游标位置开始, 拉取当前查询结果集中所有剩余行。它返回一个由行 Tuple 组成的 Tuple,并应用适当的 Python 类型转换。 语法
示例
fetchone()- 拉取单行数据fetchmany()- 分批拉取多行数据
从查询结果中拉取多行。 此方法会从当前查询结果集中最多拉取 ‘size’ 行。它返回一个由行 Tuple 组成的 Tuple,其中每一行都包含经过适当 Python 类型转换的列值。 语法
返回值
此方法遵循 DB-API 2.0 规范。如果结果集已耗尽,返回的行数
会少于 ‘size’。
fetchone()- 拉取单行fetchall()- 拉取所有剩余行
从查询结果中拉取下一行。 此方法会从当前查询结果集 中拉取下一条可用记录。它会返回一个包含各列值的 Tuple, 并进行适当的 Python 类型转换。 语法
此方法遵循 DB-API 2.0 规范。列值会根据
ClickHouse 列类型自动转换为相应的 Python
类型。
fetchmany()- 拉取多行fetchall()- 拉取所有剩余行
将查询结果转换为 PyArrow Table。 此函数会将 chdb 的查询结果转换为 PyArrow Table 格式, 从而实现高效的列式数据访问,并可与其他数据处理库 互操作。 语法
返回值
引发异常
此函数要求同时安装 pyarrow 和 pandas。
可使用以下命令安装:
pip install pyarrow pandas将查询结果转换为 Pandas DataFrame。 此函数会先将 chdb 查询结果转换为 PyArrow Table,然后再转换为 DataFrame,从而能够通过 Pandas API 方便地进行数据分析。 语法
返回:
引发
此函数使用多线程将 Arrow 转换为 Pandas,
以提升大型数据集的处理性能。
to_arrowTable()- 用于转换为 PyArrow Table 格式
- 连接:使用 connection string 管理数据库连接
- 游标:执行查询并获取结果
- 类型系统:符合 DB-API 2.0 规范的类型常量和转换器
- 错误处理:标准的数据库异常层次结构
- 线程安全:1 级线程安全 (线程可共享模块,但不可共享连接)
Database API (DBAPI) 2.0 接口提供以下核心函数: 初始化新的数据库连接。 语法
抛出
获取客户端版本信息。 以字符串形式返回 chDB 客户端版本号,以兼容 MySQLdb。 语法
将 x 以二进制类型返回。 此函数会将输入转换为 bytes 类型,以便根据 DB-API 2.0 规范用于二进制 database 字段。 语法
返回值
基类:
object
符合 DB-API 2.0 规范的 chDB 数据库连接。
此类提供标准的 DB-API 接口,用于连接到 chDB 数据库并与之交互。它同时支持临时数据库和基于文件的数据库。
该连接管理底层的 chDB engine,并提供用于
执行查询、管理事务 (对 ClickHouse 而言是空操作) 以及创建游标的方法。
变量
示例
ClickHouse 不支持传统事务,因此 commit() 和 rollback()
操作实际上都是空操作,但为了符合 DB-API 规范,仍提供了这两个方法。
关闭数据库连接。 关闭底层的 chDB 连接,并将该连接标记为已关闭。 此后对该连接执行的操作将引发 Error。 语法
提交当前事务。 语法
对于 chDB/ClickHouse,这属于空操作,因为它不支持传统的
事务。提供此项是为了符合 DB-API 2.0 规范。
创建一个用于执行查询的新游标。 语法
返回值
引发
示例
对值进行转义,以便安全地插入 SQL 查询中。 语法
返回值
示例
对字符串值进行转义,以用于 SQL 查询。 语法
返回值
检查连接是否已打开。 返回值
直接执行 SQL 查询并返回原始结果。 此方法会绕过游标接口,直接执行查询。 对于标准的 DB-API 用法,建议优先使用 cursor() 方法。 语法
返回值
引发异常
示例
获取最后一次查询的响应。 返回值
每次直接调用 query() 时,此属性都会更新。
通过游标执行的查询不会反映在此属性中。
回滚当前事务。 语法
对于 chDB/ClickHouse,这属于空操作,因为它不支持传统的
事务。提供此项是为了符合 DB-API 2.0 规范。
基类:
object
用于执行查询并获取结果的 DB-API 2.0 游标。
该游标提供用于执行 SQL 语句、管理查询结果以及浏览结果集的方法。它支持参数绑定、批量操作,
并遵循 DB-API 2.0 规范。
不要直接创建 Cursor 实例。请改用 Connection.cursor()。
示例
完整的规范说明请参见 DB-API 2.0 Cursor Objects。
执行存储过程 (占位用实现) 。 语法
返回值
chDB/ClickHouse 并不支持传统意义上的存储过程。
提供此 method 是为了符合 DB-API 2.0 规范,但它实际上
不会执行任何操作。所有 SQL 操作都请使用 execute()。
关闭游标并释放相关资源。 关闭后,游标将无法再使用,任何操作都会抛出异常。 关闭游标会读取完所有剩余数据,并释放底层游标。 语法
执行 SQL 查询,并可选择绑定参数。 此方法执行单条 SQL 语句,并可选择进行参数替换。 它支持多种参数占位符形式,使用更灵活。 语法
返回值
参数风格
示例
使用不同的参数集多次执行查询。 该方法可高效地对同一 SQL 查询执行多次, 每次使用不同的参数值。它尤其适用于批量 INSERT 操作。 语法
返回值
示例
该方法通过优化查询执行流程,提高多行 INSERT 和 UPDATE 操作的性能。
从查询结果中获取所有剩余行。 语法
抛出
示例
从查询结果中获取多行。 语法
返回值
引发异常
示例
从查询结果中获取下一行。 语法
抛出
示例
executemany() 生成的最大语句大小。
默认值为 1024000。
返回将发送到数据库的精确查询字符串。 此方法会显示参数替换后的最终 SQL 查询, 这对调试和日志很有帮助。 语法
返回值
示例
此方法遵循 Psycopg 所采用的 DB-API 2.0 扩展规范。
切换到下一个结果集 (不支持) 。 语法
chDB/ClickHouse 不支持单个查询返回多个结果集。
提供此方法是为了符合 DB-API 2.0 规范,但它始终返回 None。
设置参数输入大小 (实际为空操作) 。 语法
此方法不执行任何操作,但 DB-API 2.0 规范要求必须提供该方法。
chDB 会在内部自动处理参数大小。
设置输出列的大小 (空操作实现) 。 语法
此方法本身不执行任何操作,但 DB-API 2.0 规范要求必须提供。
chDB 会自动在内部处理输出大小。
用于 chdb database 操作的异常类。 该模块提供了完整的异常类层次结构,用于处理 chdb 中与 database 相关的 error,并遵循 Python Database API Specification v2.0。 异常类层次结构如下:
这些异常类符合 Python DB API 2.0 规范,
可在不同的数据库操作中提供一致的错误处理。
- Python Database API Specification v2.0
chdb.dbapi.connections- 数据库连接管理chdb.dbapi.cursors- 数据库游标操作
基类:
DatabaseError
因处理中的数据存在问题而引发的异常。
当数据库操作因正在处理的数据出现问题而失败时,会引发此异常,例如:
- 除零操作
- 数值超出范围
- 无效的日期/时间值
- 字符串截断错误
- 类型转换失败
- 不符合列类型的数据格式
示例
基类:
Error
为与数据库相关的错误而引发的异常。
这是所有数据库相关错误的基类。它涵盖数据库操作期间发生的、
与数据库本身相关而非与接口相关的
所有错误。
常见场景包括:
- SQL 执行错误
- 数据库连接问题
- 与事务相关的问题
- 违反数据库特定约束
这是更具体的数据库错误类型的父类,
例如
DataError、OperationalError 等。基类:
StandardError
作为所有其他错误异常 (Warning 除外) 的基类异常。
这是 chdb 中所有错误异常的基类,不包括警告。
它是所有会导致操作无法成功完成的数据库错误情况的父类。
此异常层次结构遵循 Python DB API 2.0 规范。
Warning- 用于不会阻止操作完成的非致命警告
DatabaseError
当数据库的关系完整性遭到破坏时引发的异常。
当数据库操作违反完整性约束时,会引发此异常,
包括:
- 违反外键约束
- 违反主键或唯一约束 (键重复)
- 违反检查约束
- 违反 NOT NULL 约束
- 违反参照完整性
示例
基类:
Error
当错误与数据库接口而不是数据库本身相关时,会引发此异常。
当数据库接口实现出现问题时,会引发此异常,例如:
- 无效的连接参数
- API 使用不当 (在已关闭的连接上调用方法)
- 接口层协议错误
- 模块导入或初始化失败
这些错误通常属于编程错误或配置问题,
可通过修正客户端代码或配置来解决。
基类:
DatabaseError
当数据库遇到内部错误时引发的异常。
当数据库系统遇到并非由应用程序导致的内部错误时,会引发此异常,例如:
- 游标状态无效 (游标已失效)
- 事务状态不一致 (事务不同步)
- 数据库损坏
- 内部数据结构损坏
- 系统级数据库错误
这些错误通常不在应用程序的控制范围内,可能需要重启数据库或执行修复操作。
基类:
DatabaseError
在某个方法或数据库 API 不受支持时引发的异常。
当应用程序尝试使用当前数据库配置或版本不支持的数据库功能或 API 方法时,会引发此异常,例如:
- 在不支持事务的连接上调用
rollback() - 使用当前数据库版本不支持的高级 SQL 功能
- 调用当前 driver 中未实现的方法
- 尝试使用已禁用的数据库功能
示例
请查阅数据库文档并确认驱动支持的功能,以避免
这些错误。可行时,请考虑采用平稳的回退机制。
基类:
DatabaseError
因与数据库操作相关的错误而引发的异常。
当数据库操作期间发生错误,
且这些错误不一定在程序员的控制范围内时,会引发此异常,包括:
- 与数据库的连接意外中断
- 找不到数据库服务器或无法连接
- 事务处理失败
- 处理过程中发生内存分配错误
- 磁盘空间不足或资源耗尽
- 数据库服务器内部错误
- 身份验证或授权失败
这些错误通常是暂时性的,可通过重试操作
或解决系统级问题来恢复。
基类:
DatabaseError
在数据库操作中发生编程错误时引发的异常。
当应用程序使用数据库时存在编程错误,就会引发此异常,包括:
- 找不到表或列
- 创建时表或索引已存在
- 语句中的 SQL 语法错误
- 预处理语句中指定的参数个数不正确
- 无效的 SQL 操作 (例如,对不存在的对象执行 DROP)
- 数据库 API 方法使用不当
示例
基类:
Exception
与 chdb 操作相关的异常。
这是所有 chdb 相关异常的基类。它继承自
Python 内置的 Exception 类,并作为数据库操作异常层级结构的根类。
该异常类遵循 Python DB API 2.0 规范,
用于处理数据库异常。
基类:
StandardError
在插入过程中发生数据截断等重要警告时引发的异常。
当数据库操作已完成,但伴有
需要提醒应用程序注意的重要警告时,就会引发此异常。
常见场景包括:
- 插入过程中的数据截断
- 数值转换中的精度丢失
- 字符集转换警告
这遵循 Python DB API 2.0 对警告类异常的规范。
object._\_str_\_() (如果已定义)
或 repr(object) 的结果。
- encoding 默认为‘utf-8’。
- errors 默认为‘strict’。
用于 DB-API 2.0 类型比较的扩展型 frozenset。 此类扩展了 frozenset,以支持 DB-API 2.0 的类型比较语义。 它可实现更灵活的类型检查,既可以使用相等运算符,也可以使用不等运算符, 将单个项与该集合进行比较。 这类用法适用于 STRING、BINARY、NUMBER 等类型常量,以便进行 诸如“field_type == STRING”之类的比较,其中 field_type 是单个类型值。 示例
为 DB-API 2.0 类型比较扩展的 frozenset。 此类扩展了 frozenset,以支持 DB-API 2.0 的类型比较语义。 它支持灵活的类型检查,允许使用相等和不等运算符 将单个项与该集合进行比较。 这用于 STRING、BINARY、NUMBER 等类型常量,从而支持 诸如 “field_type == STRING” 这样的比较,其中 field_type 是单个类型值。 示例
用于 DB-API 2.0 类型比较的扩展型 frozenset。 此类扩展了 frozenset,以支持 DB-API 2.0 的类型比较语义。 它支持更灵活的类型检查,使单个项既可以使用相等运算符, 也可以使用不等运算符与该集合进行比较。 这用于 STRING、BINARY、NUMBER 等类型常量,以支持 类似“field_type == STRING”这样的比较,其中 field_type 是单个类型值。 示例
用于 DB-API 2.0 类型比较的扩展型 frozenset。 该类扩展了 frozenset,以支持 DB-API 2.0 的类型比较语义。 它支持更灵活的类型检查,即可使用相等和不等运算符将单个项 与该集合进行比较。 它用于 STRING、BINARY、NUMBER 等类型常量,以便支持 诸如 “field_type == STRING” 这样的比较,其中 field_type 是单个类型值。 示例
用于 DB-API 2.0 类型比较的扩展版 frozenset。 此类在 frozenset 的基础上进行了扩展,以支持 DB-API 2.0 的类型比较语义。 它支持更灵活的类型检查,使单个项既可以通过相等运算符,也可以通过不等运算符 与该集合进行比较。 这可用于 STRING、BINARY、NUMBER 等类型常量,从而支持 诸如“field_type == STRING”这样的比较,其中 field_type 是单个类型值。 示例
用于 DB-API 2.0 类型比较的扩展版 frozenset。 此类扩展了 frozenset,以支持 DB-API 2.0 的类型比较语义。 它支持更灵活的类型检查,可以使用相等或不等运算符, 将单个项与该集合进行比较。 它用于 STRING、BINARY、NUMBER 等类型常量,以支持 “field_type == STRING”这类比较,其中 field_type 是单个类型值。 示例
为 DB-API 2.0 类型比较扩展的 frozenset。 此类扩展了 frozenset,以支持 DB-API 2.0 的类型比较语义。 它支持灵活的类型检查,使单个项既可使用相等运算符,也可使用不等运算符 与该集合进行比较。 这用于 STRING、BINARY、NUMBER 等类型常量,以支持 诸如“field_type == STRING”这样的比较,其中 field_type 是单个类型值。 示例
- 连接管理:使用完毕后务必关闭连接和游标
- 上下文管理器:使用
with语句自动清理资源 - 批次处理:对于较大的结果集,使用
fetchmany() - 错误处理:将数据库操作放在 try-except 块中
- 参数绑定:尽可能使用参数化查询
- 内存管理:对于非常大的数据集,避免使用
fetchall()
- chDB 的 DB-API 2.0 接口与大多数 Python 数据库工具兼容
- 该接口提供 Level 1 线程安全 (线程可以共享模块,但不能共享连接)
- 连接字符串支持与 chDB 会话相同的参数
- 支持所有标准的 DB-API 2.0 异常
NULL 显示为 \N,并对字符串和日期值进行 CSV 引号转义。
将 Python 函数注册为 chDB SQL 函数。
语法
每个类型参数 (
arg_types 的元素和 return_type) 均可接受:
ChdbType常量:INT64、STRING、FLOAT64等。- ClickHouse 类型字符串:
"Int64"、"String"、"DateTime64(6)"、"DateTime('UTC')"等。 - Python 类型:
int、float、str、bool、bytes、datetime.date、datetime.datetime— 根据自动类型映射进行映射
drop_function,再重新注册函数。
示例
移除先前注册的 Python UDF。如果该函数尚未注册,则不会执行任何操作,因此可放心无条件调用。 语法
用于将 Python 函数注册为 chDB SQL 函数。该函数仍可像普通 Python 函数一样调用,同时可通过其
__name__ 在 SQL 查询中使用。
语法
create_function 相同 (name 和 func 除外,它们由被装饰的函数派生) 。
示例
从
chdb.sqltypes 中导入类型:
可以通过多种方式指定类型:
使用
on_null 参数控制 NULL 值的处理方式。
使用
on_error 参数控制异常处理方式。
UDF 完全支持具有时区信息的
Date、Date32、DateTime 和 DateTime64 类型。
- 输入的 ClickHouse
DateTime/DateTime64值会转换为包含时区信息的 Pythondatetime对象 - Python
datetime输出对象返回至 ClickHouse 时会保留时区信息 chdb.sqltypes中的DATETIME64类型默认标度为 6 (微秒) ,相当于DateTime64(6)
chDB Python UDF (用户自定义函数) 装饰器。 语法
注意
- 函数应为无状态。仅支持 UDFs,不支持 UDAFs。
- 默认返回类型为 String。返回类型应为 ClickHouse 数据类型之一。
- 函数应接受 String 类型的参数。所有参数均为字符串。
- 函数会对输入的每一行调用一次。
- 函数应为纯 Python 函数。请导入函数中使用的所有模块。
- 所用的 Python 解释器与运行脚本时使用的解释器相同。
生成 UDF 配置文件和可执行脚本。 此函数会为 chDB 中的用户自定义函数 (UDF) 创建所需的文件:
- 用于处理输入数据的 Python 可执行脚本
- 用于在 ClickHouse 中注册 UDF 的 XML 配置文件
此函数通常由 @chdb_udf 装饰器调用,用户不应直接调用。
适用于 chDB 的实用函数和辅助工具。 本模块包含各种用于 chDB 的实用函数,例如数据类型推断、数据转换辅助函数以及调试工具。
将字典列表转换为列式格式。 该函数接受一个字典列表,并将其转换为一个字典, 其中每个键对应一列,每个值则是该列的值列表。 字典中缺失的值会表示为 None。 语法
返回值
示例
将嵌套字典扁平化。 此函数接收一个嵌套字典并将其扁平化,使用分隔符拼接嵌套键。 由字典组成的列表会被序列化为 JSON 字符串。 语法
返回值
示例
为一组值推断最合适的数据类型。 此函数会检查一组值,并确定能够表示列表中所有值的最合适数据类型。它会考虑整数、无符号整数、Decimal 和浮点类型;如果这些值无法用任何数值类型表示,或者所有值均为 None,则默认使用“string”。 语法
返回值
- 如果列表中的所有值都是 None,函数将返回 “string”。
- 如果列表中的任意值是字符串,函数会立即返回 “string”。
- 该函数假定数值可根据其范围和精度表示为整数、 Decimal 或浮点数。
为列式数据结构中的每一列推断数据类型。 此函数会分析各列中的值,并根据数据样本为每一列推断出最合适的 数据类型。 语法
返回值
基类:
ABC
从给定列中读取指定数量的行,并返回一个对象列表, 其中每个对象对应一列的值序列。
返回值
基类:
ABC
组装并返回各个块中的最终数据。必须由子类实现。
将数据列写入块中。必须由子类实现。
基类:
Exception
与 chDB 相关错误的基础异常类。
当 chDB 查询执行失败或发生错误时,会引发此异常。它继承自标准 Python 的 Exception 类,并提供来自底层 ClickHouse engine 的错误信息。
异常消息通常包含来自 ClickHouse 的详细错误信息,包括语法错误、类型不匹配、缺失的表/列,以及其他查询执行问题。
变量
示例
当底层 ClickHouse 引擎报告错误时,chdb.query() 及相关
函数会自动引发此异常。
在处理可能失败的查询时,您应捕获此异常,
以便在应用程序中进行适当的错误处理。
- encoding 默认为 ‘utf-8’。
- errors 默认为 ‘strict’。
- encoding 默认为 ‘utf-8’。
- errors 默认为 ‘strict’。