跳到主要内容
跳到主要内容

安装 chDB for Python

要求​

在 macOS 和 Linux (x86_64 和 ARM64) 上需要 Python 3.8+

安装​

使用​

CLI 示例:

Python 文件示例:

查询可以使用任何 支持的格式 返回数据，也可以返回 Dataframe 和 Debug。

GitHub 仓库​

您可以在 chdb-io/chdb 找到该项目的 GitHub 仓库。

数据输入​

以下方法可用于访问磁盘和内存中的数据格式：

在文件上查询 (Parquet, CSV, JSON, Arrow, ORC 及 60+ 其他格式)​

您可以执行 SQL 并返回所需格式的数据。

处理 Parquet 或 CSV

Pandas DataFrame 输出

在表上查询 (Pandas DataFrame, Parquet 文件/字节, Arrow 字节)​

在 Pandas DataFrame 上查询

使用有状态会话查询​

会话将保持查询的状态。所有 DDL 和 DML 状态将保存在一个目录中。可以将目录路径作为参数传入。如果未传入，将创建一个临时目录。

如果未指定路径，当会话对象被删除时，临时目录将被删除。否则，将保留该路径。

注意，默认数据库是 _local，默认引擎是 Memory，这意味着所有数据将存储在内存中。如果您想将数据存储在磁盘中，应该创建另一个数据库。

另请参见: test_stateful.py。

使用 Python DB-API 2.0 查询​

使用 UDF (用户定义函数) 查询​

关于 chDB Python UDF (用户定义函数) 装饰器的一些说明。

  1. 该函数应为无状态。仅支持 UDF，不支持 UDAF (用户定义聚合函数)。
  2. 默认返回类型为字符串。如果您想更改返回类型，可以将其作为参数传入。返回类型应为 以下类型之一。
  3. 该函数应接受字符串类型的参数。由于输入为 TabSeparated，所有参数均为字符串。
  4. 该函数将对每行输入进行调用。示例:
  5. 该函数应为纯 Python 函数。您应导入所有在 函数内部 使用的 Python 模块。
  6. 使用的 Python 解释器与运行脚本时使用的解释器相同。您可以通过 sys.executable 获取它。

另请参见: test_udf.py。

Python 表引擎​

在 Pandas DataFrame 上查询​

在 Arrow 表上查询​

在 chdb.PyReader 类实例上查询​

  1. 您必须从 chdb.PyReader 类继承并实现 read 方法。
  2. read 方法应:
    1. 返回一个列表的列表，第一个维度为列，第二个维度为行，列的顺序应与 read 的第一个参数 col_names 相同。
    2. 当没有更多数据可读时，返回一个空列表。
    3. 是有状态的，游标应在 read 方法中更新。
  3. 可以实现可选的 get_schema 方法来返回表的模式。原型为 def get_schema(self) -> List[Tuple[str, str]]:，返回值是一个元组的列表，每个元组包含列名和列类型。列类型应为 以下类型之一。

另请参见: test_query_py.py。

限制​

  1. 支持的列类型: pandas.Series, pyarrow.array, chdb.PyReader
  2. 支持的数据类型: Int, UInt, Float, String, Date, DateTime, Decimal
  3. Python 对象类型将被转换为字符串
  4. Pandas DataFrame 性能最佳，Arrow 表优于 PyReader

有关更多示例，请参见 examples 和 tests。