⌘+k ctrl+k
1.4 (LTS)
搜索快捷键 cmd + k | ctrl + k
关系型 API

关系型 API 是一种用于逐步构建查询的替代 API。该 API 以 DuckDBPyRelation 节点为核心。关系可以被视为 SQL 查询的符号化表示。

惰性求值 (Lazy Evaluation)

关系对象本身不持有任何数据，且在调用 触发执行的方法 之前，不会执行任何操作。

例如，我们创建一个加载 10 亿行数据的关系对象

import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("from range(1_000_000_000)")

在执行时刻，rel 不持有任何数据，也不会从数据库中检索任何数据。

通过调用 rel.show() 或直接在终端打印 rel，会获取前 1 万行数据。如果行数超过 1 万，输出窗口将显示 >9999 行（因为关系中的总行数未知）。

通过调用 输出 方法，数据将被检索并以指定格式存储

rel.to_table("example_rel")

# 100% ▕████████████████████████████████████████████████████████████▏

关系创建

本节详细介绍了如何创建关系对象。这些方法均采用 惰性求值。

名称 描述
from_arrow 从 Arrow 对象创建关系对象
from_csv_auto 从 'name' 指向的 CSV 文件创建关系对象
from_df 从 df 中的 DataFrame 创建关系对象
from_parquet 从 Parquet 文件创建关系对象
from_query 执行 SQL 查询。如果是 SELECT 语句，则从给定的 SQL 查询创建关系对象；否则直接执行该查询。
query 执行 SQL 查询。如果是 SELECT 语句，则从给定的 SQL 查询创建关系对象；否则直接执行该查询。
read_csv 从 'name' 指向的 CSV 文件创建关系对象
read_json 从 'name' 指向的 JSON 文件创建关系对象
read_parquet 从 Parquet 文件创建关系对象
sql 执行 SQL 查询。如果是 SELECT 语句，则从给定的 SQL 查询创建关系对象；否则直接执行该查询。
table 为指定的表创建关系对象
table_function 使用给定的参数从指定的表函数创建关系对象
values 从传入的值创建关系对象
view 为指定的视图创建关系对象

from_arrow

签名 
from_arrow(self: _duckdb.DuckDBPyConnection, arrow_object: object) -> _duckdb.DuckDBPyRelation
描述

从 Arrow 对象创建关系对象

参数

  • arrow_object : pyarrow.Table, pyarrow.RecordBatch

    用于创建关系对象的 Arrow 对象

示例 
import duckdb
import pyarrow as pa

ids = pa.array([1], type=pa.int8())
texts = pa.array(['a'], type=pa.string())
example_table = pa.table([ids, texts], names=["id", "text"])

duckdb_conn = duckdb.connect()

rel = duckdb_conn.from_arrow(example_table)

rel.show()
结果 
┌──────┬─────────┐
│  id  │  text   │
│ int8 │ varchar │
├──────┼─────────┤
│    1 │ a       │
└──────┴─────────┘

from_csv_auto

签名 
from_csv_auto(self: _duckdb.DuckDBPyConnection, path_or_buffer: object, **kwargs) -> _duckdb.DuckDBPyRelation
描述

从 'name' 指向的 CSV 文件创建关系对象

别名: read_csv

参数

  • path_or_buffer : Union[str, StringIO, TextIOBase]

    CSV 文件的路径或用于读取的缓冲区。

  • header : Optional[bool], Optional[int]

    用作列名的行号，若无表头则为 None。

  • compression : Optional[str]

    压缩类型（例如 'gzip', 'bz2'）。

  • sep : Optional[str]

    使用的分隔符；默认为逗号。

  • delimiter : Optional[str]

    使用的替代分隔符。

  • dtype : Optional[Dict[str, str]], Optional[List[str]]

    各列的数据类型。

  • na_values : Optional[str], Optional[List[str]]

    识别为 NA/NaN 的额外字符串。

  • skiprows : Optional[int]

    开始时跳过的行数。

  • quotechar : Optional[str]

    用于引用字段的字符。

  • escapechar : Optional[str]

    用于转义分隔符或引用字符的字符。

  • encoding : Optional[str]

    读写时使用的 UTF 编码。

  • parallel : Optional[bool]

    启用并行读取。

  • date_format : Optional[str]

    解析日期的格式。

  • timestamp_format : Optional[str]

    解析时间戳的格式。

  • sample_size : Optional[int]

    用于推断模式（schema）的采样行数。

  • all_varchar : Optional[bool]

    将所有列视为 VARCHAR 类型。

  • normalize_names : Optional[bool]

    将列名标准化为小写。

  • null_padding : Optional[bool]

    对缺少列的行启用空值填充。

  • names : Optional[List[str]]

    要使用的列名列表。

  • lineterminator : Optional[str]

    换行符。

  • columns : Optional[Dict[str, str]]

    模式的列映射。

  • auto_type_candidates : Optional[List[str]]

    用于自动类型推断的列列表。

  • max_line_size : Optional[int]

    最大行大小（字节）。

  • ignore_errors : Optional[bool]

    忽略解析错误。

  • store_rejects : Optional[bool]

    存储被拒绝的行。

  • rejects_table : Optional[str]

    用于存储被拒绝行的表名。

  • rejects_scan : Optional[str]

    用于扫描被拒绝数据的设置。

  • rejects_limit : Optional[int]

    限制存储的被拒绝行数。

  • force_not_null : Optional[List[str]]

    强制为 NOT NULL 的列列表。

  • buffer_size : Optional[int]

    缓冲区大小（字节）。

  • decimal : Optional[str]

    识别为小数点的字符。

  • allow_quoted_nulls : Optional[bool]

    允许带引号的 NULL 值。

  • filename : Optional[bool], Optional[str]

    添加文件名列或指定文件名。

  • hive_partitioning : Optional[bool]

    启用 Hive 风格的分区。

  • union_by_name : Optional[bool]

    按列名而不是位置合并文件。

  • hive_types : Optional[Dict[str, str]]

    列的 Hive 类型。

  • hive_types_autocast : Optional[bool]

    自动转换 Hive 类型。

  • connection : DuckDBPyConnection

    要使用的 DuckDB 连接。

示例 
import csv
import duckdb

duckdb_conn = duckdb.connect()

with open('code_example.csv', 'w', newline='') as csvfile:
    fieldnames = ['id', 'text']
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
    writer.writeheader()
    writer.writerow({'id': '1', 'text': 'a'})

rel = duckdb_conn.from_csv_auto("code_example.csv")

rel.show()
结果 
┌───────┬─────────┐
│  id   │  text   │
│ int64 │ varchar │
├───────┼─────────┤
│     1 │ a       │
└───────┴─────────┘

from_df

签名 
from_df(self: _duckdb.DuckDBPyConnection, df: pandas.DataFrame) -> _duckdb.DuckDBPyRelation
描述

从 df 中的 DataFrame 创建关系对象

参数

  • df : pandas.DataFrame

    要转换为 DuckDB 关系对象的 pandas DataFrame。

示例 
import duckdb
import pandas as pd

df = pd.DataFrame(data = {'id': [1], "text":["a"]})

duckdb_conn = duckdb.connect()

rel = duckdb_conn.from_df(df)

rel.show()
结果 
┌───────┬─────────┐
│  id   │  text   │
│ int64 │ varchar │
├───────┼─────────┤
│     1 │ a       │
└───────┴─────────┘

from_parquet

签名 
from_parquet(*args, **kwargs)
Overloaded function.

1. from_parquet(self: _duckdb.DuckDBPyConnection, file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> _duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_glob

2. from_parquet(self: _duckdb.DuckDBPyConnection, file_globs: collections.abc.Sequence[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> _duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_globs
描述

从 Parquet 文件创建关系对象

别名: read_parquet

参数

  • file_glob : str

    指向要读取的 Parquet 文件的文件路径或 glob 模式。

  • binary_as_string : bool, default: False

    将二进制列解释为字符串而不是二进制大对象 (blobs)。

  • file_row_number : bool, default: False

    添加包含每个文件内行号的列。

  • filename : bool, default: False

    添加包含每行数据来源文件名的列。

  • hive_partitioning : bool, default: False

    启用对文件路径中 Hive 风格分区的自动检测。

  • union_by_name : bool, default: False

    通过匹配列名而不是位置来合并 Parquet 文件。

  • compression : object

    读取 Parquet 文件时可选的压缩编解码器。

示例 
import duckdb
import pyarrow as pa
import pyarrow.parquet as pq

ids = pa.array([1], type=pa.int8())
texts = pa.array(['a'], type=pa.string())
example_table = pa.table([ids, texts], names=["id", "text"])

pq.write_table(example_table, "code_example.parquet")

duckdb_conn = duckdb.connect()

rel = duckdb_conn.from_parquet("code_example.parquet")

rel.show()
结果 
┌──────┬─────────┐
│  id  │  text   │
│ int8 │ varchar │
├──────┼─────────┤
│    1 │ a       │
└──────┴─────────┘

from_query

签名 
from_query(self: _duckdb.DuckDBPyConnection, query: object, *, alias: str = '', params: object = None) -> _duckdb.DuckDBPyRelation
描述

执行 SQL 查询。如果是 SELECT 语句，则从给定的 SQL 查询创建关系对象；否则直接执行该查询。

警告。 由于存在显著的性能开销，不建议在此方法中传递 params。参数化查询请改用 execute()。

别名: query, sql

参数

  • query : object

    要执行并转换为关系对象的 SQL 查询或子查询。

  • alias : str, default: ''

    分配给结果关系的可选别名。

  • params : object

    可选的查询参数。不建议使用，因为会有 显著的性能开销。参数化查询请改用 execute()。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.from_query("from range(1,2) tbl(id)")

rel.show()
结果 
┌───────┐
│  id   │
│ int64 │
├───────┤
│     1 │
└───────┘

query

签名 
query(self: _duckdb.DuckDBPyConnection, query: object, *, alias: str = '', params: object = None) -> _duckdb.DuckDBPyRelation
描述

执行 SQL 查询。如果是 SELECT 语句，则从给定的 SQL 查询创建关系对象；否则直接执行该查询。

警告。 由于存在显著的性能开销，不建议在此方法中传递 params。参数化查询请改用 execute()。

别名: from_query, sql

参数

  • query : object

    要执行并转换为关系对象的 SQL 查询或子查询。

  • alias : str, default: ''

    分配给结果关系的可选别名。

  • params : object

    可选的查询参数。不建议使用，因为会有 显著的性能开销。参数化查询请改用 execute()。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.query("from range(1,2) tbl(id)")

rel.show()
结果 
┌───────┐
│  id   │
│ int64 │
├───────┤
│     1 │
└───────┘

read_csv

签名 
read_csv(self: _duckdb.DuckDBPyConnection, path_or_buffer: object, **kwargs) -> _duckdb.DuckDBPyRelation
描述

从 'name' 指向的 CSV 文件创建关系对象

别名: from_csv_auto

参数

  • path_or_buffer : Union[str, StringIO, TextIOBase]

    CSV 文件的路径或用于读取的缓冲区。

  • header : Optional[bool], Optional[int]

    用作列名的行号，若无表头则为 None。

  • compression : Optional[str]

    压缩类型（例如 'gzip', 'bz2'）。

  • sep : Optional[str]

    使用的分隔符；默认为逗号。

  • delimiter : Optional[str]

    使用的替代分隔符。

  • dtype : Optional[Dict[str, str]], Optional[List[str]]

    各列的数据类型。

  • na_values : Optional[str], Optional[List[str]]

    识别为 NA/NaN 的额外字符串。

  • skiprows : Optional[int]

    开始时跳过的行数。

  • quotechar : Optional[str]

    用于引用字段的字符。

  • escapechar : Optional[str]

    用于转义分隔符或引用字符的字符。

  • encoding : Optional[str]

    读写时使用的 UTF 编码。

  • parallel : Optional[bool]

    启用并行读取。

  • date_format : Optional[str]

    解析日期的格式。

  • timestamp_format : Optional[str]

    解析时间戳的格式。

  • sample_size : Optional[int]

    用于推断模式（schema）的采样行数。

  • all_varchar : Optional[bool]

    将所有列视为 VARCHAR 类型。

  • normalize_names : Optional[bool]

    将列名标准化为小写。

  • null_padding : Optional[bool]

    对缺少列的行启用空值填充。

  • names : Optional[List[str]]

    要使用的列名列表。

  • lineterminator : Optional[str]

    换行符。

  • columns : Optional[Dict[str, str]]

    模式的列映射。

  • auto_type_candidates : Optional[List[str]]

    用于自动类型推断的列列表。

  • max_line_size : Optional[int]

    最大行大小（字节）。

  • ignore_errors : Optional[bool]

    忽略解析错误。

  • store_rejects : Optional[bool]

    存储被拒绝的行。

  • rejects_table : Optional[str]

    用于存储被拒绝行的表名。

  • rejects_scan : Optional[str]

    用于扫描被拒绝数据的设置。

  • rejects_limit : Optional[int]

    限制存储的被拒绝行数。

  • force_not_null : Optional[List[str]]

    强制为 NOT NULL 的列列表。

  • buffer_size : Optional[int]

    缓冲区大小（字节）。

  • decimal : Optional[str]

    识别为小数点的字符。

  • allow_quoted_nulls : Optional[bool]

    允许带引号的 NULL 值。

  • filename : Optional[bool], Optional[str]

    添加文件名列或指定文件名。

  • hive_partitioning : Optional[bool]

    启用 Hive 风格的分区。

  • union_by_name : Optional[bool]

    按列名而不是位置合并文件。

  • hive_types : Optional[Dict[str, str]]

    列的 Hive 类型。

  • hive_types_autocast : Optional[bool]

    自动转换 Hive 类型。

  • connection : DuckDBPyConnection

    要使用的 DuckDB 连接。

示例 
import csv
import duckdb

duckdb_conn = duckdb.connect()

with open('code_example.csv', 'w', newline='') as csvfile:
    fieldnames = ['id', 'text']
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
    writer.writeheader()
    writer.writerow({'id': '1', 'text': 'a'})

rel = duckdb_conn.read_csv("code_example.csv")

rel.show()
结果 
┌───────┬─────────┐
│  id   │  text   │
│ int64 │ varchar │
├───────┼─────────┤
│     1 │ a       │
└───────┴─────────┘

read_json

签名 
read_json(self: _duckdb.DuckDBPyConnection, path_or_buffer: object, *, columns: typing.Optional[object] = None, sample_size: typing.Optional[object] = None, maximum_depth: typing.Optional[object] = None, records: typing.Optional[str] = None, format: typing.Optional[str] = None, date_format: typing.Optional[object] = None, timestamp_format: typing.Optional[object] = None, compression: typing.Optional[object] = None, maximum_object_size: typing.Optional[object] = None, ignore_errors: typing.Optional[object] = None, convert_strings_to_integers: typing.Optional[object] = None, field_appearance_threshold: typing.Optional[object] = None, map_inference_threshold: typing.Optional[object] = None, maximum_sample_files: typing.Optional[object] = None, filename: typing.Optional[object] = None, hive_partitioning: typing.Optional[object] = None, union_by_name: typing.Optional[object] = None, hive_types: typing.Optional[object] = None, hive_types_autocast: typing.Optional[object] = None) -> _duckdb.DuckDBPyRelation
描述

从 'name' 指向的 JSON 文件创建关系对象

参数

  • path_or_buffer : object

    包含要读取 JSON 数据的路径或类文件对象。

  • columns : object

    可选的投影列名列表（从 JSON 数据中）。

  • sample_size : object

    用于推断 JSON 模式的采样行数。

  • maximum_depth : object

    解析 JSON 对象时的最大深度。

  • records : str

    指定 JSON 是否处于记录模式的格式字符串。

  • format : str

    JSON 数据的格式（例如 'auto', 'newline_delimited'）。

  • date_format : object

    解析日期字段的格式字符串。

  • timestamp_format : object

    解析时间戳字段的格式字符串。

  • compression : object

    用于 JSON 数据的压缩编解码器（例如 'gzip'）。

  • maximum_object_size : object

    单个 JSON 对象的最大字节大小。

  • ignore_errors : object

    若为 True，跳过解析错误的 JSON 记录。

  • convert_strings_to_integers : object

    若为 True，尝试在适当的情况下将字符串转换为整数。

  • field_appearance_threshold : object

    嵌套 JSON 中推断可选字段的阈值。

  • map_inference_threshold : object

    从 JSON 对象模式推断 Map 的阈值。

  • maximum_sample_files : object

    用于模式推断的最大采样文件数。

  • filename : object

    若为 True，包含一列显示每行的源文件名。

  • hive_partitioning : object

    若为 True，基于目录结构启用 Hive 分区。

  • union_by_name : object

    若为 True，按名称而不是位置对齐 JSON 列。

  • hive_types : object

    若为 True，将目录结构中的 Hive 类型用于模式。

  • hive_types_autocast : object

    若为 True，自动转换数据类型以匹配 Hive 类型。

示例 
import duckdb
import json

with open("code_example.json", mode="w") as f:
    json.dump([{'id': 1, "text":"a"}], f)
    
duckdb_conn = duckdb.connect()

rel = duckdb_conn.read_json("code_example.json")

rel.show()
结果 
┌───────┬─────────┐
│  id   │  text   │
│ int64 │ varchar │
├───────┼─────────┤
│     1 │ a       │
└───────┴─────────┘

read_parquet

签名 
read_parquet(*args, **kwargs)
Overloaded function.

1. read_parquet(self: _duckdb.DuckDBPyConnection, file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> _duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_glob

2. read_parquet(self: _duckdb.DuckDBPyConnection, file_globs: collections.abc.Sequence[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> _duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_globs
描述

从 Parquet 文件创建关系对象

别名: from_parquet

参数

  • file_glob : str

    指向要读取的 Parquet 文件的文件路径或 glob 模式。

  • binary_as_string : bool, default: False

    将二进制列解释为字符串而不是二进制大对象 (blobs)。

  • file_row_number : bool, default: False

    添加包含每个文件内行号的列。

  • filename : bool, default: False

    添加包含每行数据来源文件名的列。

  • hive_partitioning : bool, default: False

    启用对文件路径中 Hive 风格分区的自动检测。

  • union_by_name : bool, default: False

    通过匹配列名而不是位置来合并 Parquet 文件。

  • compression : object

    读取 Parquet 文件时可选的压缩编解码器。

示例 
import duckdb
import pyarrow as pa
import pyarrow.parquet as pq

ids = pa.array([1], type=pa.int8())
texts = pa.array(['a'], type=pa.string())
example_table = pa.table([ids, texts], names=["id", "text"])

pq.write_table(example_table, "code_example.parquet")

duckdb_conn = duckdb.connect()

rel = duckdb_conn.read_parquet("code_example.parquet")

rel.show()
结果 
┌──────┬─────────┐
│  id  │  text   │
│ int8 │ varchar │
├──────┼─────────┤
│    1 │ a       │
└──────┴─────────┘

sql

签名 
sql(self: _duckdb.DuckDBPyConnection, query: object, *, alias: str = '', params: object = None) -> _duckdb.DuckDBPyRelation
描述

执行 SQL 查询。如果是 SELECT 语句，则从给定的 SQL 查询创建关系对象；否则直接执行该查询。

警告。 由于存在显著的性能开销，不建议在此方法中传递 params。参数化查询请改用 execute()。

别名: from_query, query

参数

  • query : object

    要执行并转换为关系对象的 SQL 查询或子查询。

  • alias : str, default: ''

    分配给结果关系的可选别名。

  • params : object

    可选的查询参数。不建议使用，因为会有 显著的性能开销。参数化查询请改用 execute()。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("from range(1,2) tbl(id)")

rel.show()
结果 
┌───────┐
│  id   │
│ int64 │
├───────┤
│     1 │
└───────┘

table

签名 
table(self: _duckdb.DuckDBPyConnection, table_name: str) -> _duckdb.DuckDBPyRelation
描述

为指定的表创建关系对象

参数

  • table_name : str

    用于创建关系对象的表名。

示例 
import duckdb

duckdb_conn = duckdb.connect()

duckdb_conn.sql("create table code_example as select * from range(1,2) tbl(id)")

rel = duckdb_conn.table("code_example")

rel.show()
结果 
┌───────┐
│  id   │
│ int64 │
├───────┤
│     1 │
└───────┘

table_function

签名 
table_function(self: _duckdb.DuckDBPyConnection, name: str, parameters: object = None) -> _duckdb.DuckDBPyRelation
描述

使用给定的参数从指定的表函数创建关系对象

参数

  • name : str

    要调用的表函数名称。

  • parameters : object

    传递给表函数的可选参数。

示例 
import duckdb

duckdb_conn = duckdb.connect()

duckdb_conn.sql("""
    create macro get_record_for(x) as table
    select x*range from range(1,2)
""")

rel = duckdb_conn.table_function(name="get_record_for", parameters=[1])

rel.show()
结果 
┌───────────────┐
│ (1 * "range") │
│     int64     │
├───────────────┤
│             1 │
└───────────────┘

values

签名 
values(self: _duckdb.DuckDBPyConnection, *args) -> _duckdb.DuckDBPyRelation
描述

从传入的值创建关系对象

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.values([1, 'a'])

rel.show()
结果 
┌───────┬─────────┐
│ col0  │  col1   │
│ int32 │ varchar │
├───────┼─────────┤
│     1 │ a       │
└───────┴─────────┘

view

签名 
view(self: _duckdb.DuckDBPyConnection, view_name: str) -> _duckdb.DuckDBPyRelation
描述

为指定的视图创建关系对象

参数

  • view_name : str

    用于创建关系对象的视图名。

示例 
import duckdb

duckdb_conn = duckdb.connect()

duckdb_conn.sql("create table code_example as select * from range(1,2) tbl(id)")

rel = duckdb_conn.view("code_example")

rel.show()
结果 
┌───────┐
│  id   │
│ int64 │
├───────┤
│     1 │
└───────┘

关系定义详情

本节详细介绍了如何检查关系对象。

名称 描述
alias 获取当前别名名称
columns 返回包含关系中各列名称的列表。
describe 提供关系各列的基本统计信息（如最小值、最大值）以及是否存在 NULL 值。
description 返回结果的描述信息
dtypes 返回包含关系中各列类型的列表。
explain explain(self: _duckdb.DuckDBPyRelation, type: _duckdb.ExplainType = 'standard') -> str
query 在引用该关系对象的名为 virtual_table_name 的视图上运行 sql_query 中的 SQL 查询
set_alias 将关系对象重命名为新的别名
shape 包含行数和列数的元组。
show 显示数据摘要
sql_query 获取等效于该关系对象的 SQL 查询
type 获取关系的类型。
types 返回包含关系中各列类型的列表。

alias

描述

获取当前别名名称

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.alias
结果 
unnamed_relation_43c808c247431be5

columns

描述

返回包含关系中各列名称的列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.columns
结果 
 ['id', 'description', 'value', 'created_timestamp']

describe

签名 
describe(self: _duckdb.DuckDBPyRelation) -> _duckdb.DuckDBPyRelation
描述

提供关系各列的基本统计信息（如最小值、最大值）以及是否存在 NULL 值。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.describe()
结果 
┌─────────┬──────────────────────────────────────┬─────────────────┬────────────────────┬────────────────────────────┐
│  aggr   │                  id                  │   description   │       value        │     created_timestamp      │
│ varchar │               varchar                │     varchar     │       double       │          varchar           │
├─────────┼──────────────────────────────────────┼─────────────────┼────────────────────┼────────────────────────────┤
│ count   │ 9                                    │ 9               │                9.0 │ 9                          │
│ mean    │ NULL                                 │ NULL            │                5.0 │ NULL                       │
│ stddev  │ NULL                                 │ NULL            │ 2.7386127875258306 │ NULL                       │
│ min     │ 08fdcbf8-4e53-4290-9e81-423af263b518 │ value is even   │                1.0 │ 2025-04-09 15:41:20.642+02 │
│ max     │ fb10390e-fad5-4694-91cb-e82728cb6f9f │ value is uneven │                9.0 │ 2025-04-09 15:49:20.642+02 │
│ median  │ NULL                                 │ NULL            │                5.0 │ NULL                       │
└─────────┴──────────────────────────────────────┴─────────────────┴────────────────────┴────────────────────────────┘

description

描述

返回结果的描述信息

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.description
结果 
[('id', 'UUID', None, None, None, None, None),
 ('description', 'STRING', None, None, None, None, None),
 ('value', 'NUMBER', None, None, None, None, None),
 ('created_timestamp', 'DATETIME', None, None, None, None, None)]

dtypes

描述

返回包含关系中各列类型的列表。

别名: types

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.dtypes
结果 
 [UUID, VARCHAR, BIGINT, TIMESTAMP WITH TIME ZONE]

explain

描述

explain(self: _duckdb.DuckDBPyRelation, type: _duckdb.ExplainType = 'standard') -> str

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.explain()
结果 
┌───────────────────────────┐
│         PROJECTION        │
│    ────────────────────   │
│             id            │
│        description        │
│           value           │
│     created_timestamp     │
│                           │
│          ~9 Rows          │
└─────────────┬─────────────┘
┌─────────────┴─────────────┐
│           RANGE           │
│    ────────────────────   │
│      Function: RANGE      │
│                           │
│          ~9 Rows          │
└───────────────────────────┘

query

签名 
query(self: _duckdb.DuckDBPyRelation, virtual_table_name: str, sql_query: str) -> _duckdb.DuckDBPyRelation
描述

在引用该关系对象的名为 virtual_table_name 的视图上运行 sql_query 中的 SQL 查询

参数

  • virtual_table_name : str

    在 SQL 查询中引用时分配给当前关系的名称。

  • sql_query : str

    使用虚拟表名查询关系对象的 SQL 查询字符串。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.query(virtual_table_name="rel_view", sql_query="from rel")

duckdb_conn.sql("show rel_view")
结果 
┌───────────────────┬──────────────────────────┬─────────┬─────────┬─────────┬─────────┐
│    column_name    │       column_type        │  null   │   key   │ default │  extra  │
│      varchar      │         varchar          │ varchar │ varchar │ varchar │ varchar │
├───────────────────┼──────────────────────────┼─────────┼─────────┼─────────┼─────────┤
│ id                │ UUID                     │ YES     │ NULL    │ NULL    │ NULL    │
│ description       │ VARCHAR                  │ YES     │ NULL    │ NULL    │ NULL    │
│ value             │ BIGINT                   │ YES     │ NULL    │ NULL    │ NULL    │
│ created_timestamp │ TIMESTAMP WITH TIME ZONE │ YES     │ NULL    │ NULL    │ NULL    │
└───────────────────┴──────────────────────────┴─────────┴─────────┴─────────┴─────────┘

set_alias

签名 
set_alias(self: _duckdb.DuckDBPyRelation, alias: str) -> _duckdb.DuckDBPyRelation
描述

将关系对象重命名为新的别名

参数

  • alias : str

    分配给关系的别名。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.set_alias('abc').select('abc.id')
结果 
In the SQL query, the alias will be `abc`

shape

描述

包含行数和列数的元组。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.shape
结果 
(9, 4)

show

签名 
show(self: _duckdb.DuckDBPyRelation, *, max_width: typing.Optional[typing.SupportsInt] = None, max_rows: typing.Optional[typing.SupportsInt] = None, max_col_width: typing.Optional[typing.SupportsInt] = None, null_value: typing.Optional[str] = None, render_mode: object = None) -> None
描述

显示数据摘要

参数

  • max_width : int

    整个输出的最大显示宽度（字符）。

  • max_rows : int

    最大显示行数。

  • max_col_width : int

    每列显示的最大字符数。

  • null_value : str

    显示 NULL 值时使用的字符串。

  • render_mode : object

    输出显示的渲染模式。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.show()
结果 
┌──────────────────────────────────────┬─────────────────┬───────┬────────────────────────────┐
│                  id                  │   description   │ value │     created_timestamp      │
│                 uuid                 │     varchar     │ int64 │  timestamp with time zone  │
├──────────────────────────────────────┼─────────────────┼───────┼────────────────────────────┤
│ 642ea3d7-793d-4867-a759-91c1226c25a0 │ value is uneven │     1 │ 2025-04-09 15:41:20.642+02 │
│ 6817dd31-297c-40a8-8e40-8521f00b2d08 │ value is even   │     2 │ 2025-04-09 15:42:20.642+02 │
│ 45143f9a-e16e-4e59-91b2-3a0800eed6d6 │ value is uneven │     3 │ 2025-04-09 15:43:20.642+02 │
│ fb10390e-fad5-4694-91cb-e82728cb6f9f │ value is even   │     4 │ 2025-04-09 15:44:20.642+02 │
│ 111ced5c-9155-418e-b087-c331b814db90 │ value is uneven │     5 │ 2025-04-09 15:45:20.642+02 │
│ 66a870a6-aef0-4085-87d5-5d1b35d21c66 │ value is even   │     6 │ 2025-04-09 15:46:20.642+02 │
│ a7e8e796-bca0-44cd-a269-1d71090fb5cc │ value is uneven │     7 │ 2025-04-09 15:47:20.642+02 │
│ 74908d48-7f2d-4bdd-9c92-1e7920b115b5 │ value is even   │     8 │ 2025-04-09 15:48:20.642+02 │
│ 08fdcbf8-4e53-4290-9e81-423af263b518 │ value is uneven │     9 │ 2025-04-09 15:49:20.642+02 │
└──────────────────────────────────────┴─────────────────┴───────┴────────────────────────────┘

sql_query

签名 
sql_query(self: _duckdb.DuckDBPyRelation) -> str
描述

获取等效于该关系对象的 SQL 查询

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.sql_query()
结果 
SELECT 
    gen_random_uuid() AS id, 
    concat('value is ', CASE  WHEN ((mod("range", 2) = 0)) THEN ('even') ELSE 'uneven' END) AS description, 
    "range" AS "value", 
    (now() + CAST(concat("range", ' ', 'minutes') AS INTERVAL)) AS created_timestamp 
FROM "range"(1, 10)

type

描述

获取关系的类型。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.type
结果 
QUERY_RELATION

types

描述

返回包含关系中各列类型的列表。

别名: dtypes

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.types
结果 
[UUID, VARCHAR, BIGINT, TIMESTAMP WITH TIME ZONE]

转换

本节包含可用于链式查询的方法。这些方法均采用 惰性求值。

名称 描述
aggregate 根据关系上的可选组 group_expr 计算聚合函数 aggr_expr
apply 对关系中的单列或多列应用函数，并可选择性地进行分组计算
cross 创建两个关系对象的交叉/笛卡尔积
except_ 创建当前关系对象与 other_rel 关系对象的差集 (Except)
filter 通过 filter_expr 中的过滤条件过滤关系对象
insert 将给定值插入关系对象
insert_into 将关系对象插入到名为 table_name 的现有表中
intersect 创建当前关系对象与 other_rel 关系对象的交集 (Intersect)
join 使用 join_condition 中的条件表达式将当前关系对象与 other_rel 联接。支持的联接类型包括 'inner', 'left', 'right', 'outer', 'semi' 和 'anti'
limit 仅检索该关系对象的前 n 行，从 offset 开始
map 在关系对象上调用传入的函数
order 通过 order_expr 对关系对象进行重排序
project 通过 project_expr 中的投影表达式投影关系对象
select 通过 project_expr 中的投影表达式投影关系对象
sort 通过提供的表达式对关系对象进行重排序
union 创建当前关系对象与 other_rel 关系对象的并集 (Union)
update 使用提供的表达式更新给定关系

aggregate

签名 
aggregate(self: _duckdb.DuckDBPyRelation, aggr_expr: object, group_expr: str = '') -> _duckdb.DuckDBPyRelation
描述

根据关系上的可选组 group_expr 计算聚合函数 aggr_expr

参数

  • aggr_expr : str, list[Expression]

    列和聚合函数的列表。

  • group_expr : str, default: ''

    包含在 group_by 中的列列表。如果为 None，则应用 group by all。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel = rel.aggregate('max(value)')
结果 
┌──────────────┐
│ max("value") │
│    int64     │
├──────────────┤
│            9 │
└──────────────┘

apply

签名 
apply(self: _duckdb.DuckDBPyRelation, function_name: str, function_aggr: str, group_expr: str = '', function_parameter: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

对关系中的单列或多列应用函数，并可选择性地进行分组计算

参数

  • function_name : str

    要在关系上应用的函数名称。

  • function_aggr : str

    应用该函数的列列表。

  • group_expr : str, default: ''

    用于分组的可选 SQL 表达式。

  • function_parameter : str, default: ''

    传递给函数的可选参数。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.apply(
    function_name="count", 
    function_aggr="id", 
    group_expr="description",
    projected_columns="description"
)
结果 
┌─────────────────┬───────────┐
│   description   │ count(id) │
│     varchar     │   int64   │
├─────────────────┼───────────┤
│ value is uneven │         5 │
│ value is even   │         4 │
└─────────────────┴───────────┘

cross

签名 
cross(self: _duckdb.DuckDBPyRelation, other_rel: _duckdb.DuckDBPyRelation) -> _duckdb.DuckDBPyRelation
描述

创建两个关系对象的交叉/笛卡尔积

参数

  • other_rel : _duckdb.DuckDBPyRelation

    执行交叉积的另一个关系对象。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.cross(other_rel=rel.set_alias("other_rel"))
结果 
┌─────────────────────────────┬─────────────────┬───────┬───────────────────────────┬──────────────────────────────────────┬─────────────────┬───────┬───────────────────────────┐
│             id              │   description   │ value │     created_timestamp     │                  id                  │   description   │ value │     created_timestamp     │
│            uuid             │     varchar     │ int64 │ timestamp with time zone  │                 uuid                 │     varchar     │ int64 │ timestamp with time zone  │
├─────────────────────────────┼─────────────────┼───────┼───────────────────────────┼──────────────────────────────────────┼─────────────────┼───────┼───────────────────────────┤
│ cb2b453f-1a06-4f5e-abe1-b…  │ value is uneven │     1 │ 2025-04-10 09:53:29.78+02 │ cb2b453f-1a06-4f5e-abe1-bfd413581bcf │ value is uneven │     1 │ 2025-04-10 09:53:29.78+02 │
...

except_

签名 
except_(self: _duckdb.DuckDBPyRelation, other_rel: _duckdb.DuckDBPyRelation) -> _duckdb.DuckDBPyRelation
描述

创建当前关系对象与 other_rel 关系对象的差集 (Except)

参数

  • other_rel : _duckdb.DuckDBPyRelation

    从当前关系中减去的另一个关系对象（集合差集）。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.except_(other_rel=rel.set_alias("other_rel"))
结果 
The relation query is executed twice, therefore generating different ids and timestamps:
┌──────────────────────────────────────┬─────────────────┬───────┬────────────────────────────┐
│                  id                  │   description   │ value │     created_timestamp      │
│                 uuid                 │     varchar     │ int64 │  timestamp with time zone  │
├──────────────────────────────────────┼─────────────────┼───────┼────────────────────────────┤
│ f69ed6dd-a7fe-4de2-b6af-1c2418096d69 │ value is uneven │     3 │ 2025-04-10 11:43:05.711+02 │
│ 08ad11dc-a9c2-4aaa-9272-760b27ad1f5d │ value is uneven │     7 │ 2025-04-10 11:47:05.711+02 │
...

filter

签名 
filter(self: _duckdb.DuckDBPyRelation, filter_expr: object) -> _duckdb.DuckDBPyRelation
描述

通过 filter_expr 中的过滤条件过滤关系对象

参数

  • filter_expr : str, Expression

    应用于关系的过滤表达式。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.filter("value = 2")
结果 
┌──────────────────────────────────────┬───────────────┬───────┬───────────────────────────┐
│                  id                  │  description  │ value │     created_timestamp     │
│                 uuid                 │    varchar    │ int64 │ timestamp with time zone  │
├──────────────────────────────────────┼───────────────┼───────┼───────────────────────────┤
│ b0684ab7-fcbf-41c5-8e4a-a51bdde86926 │ value is even │     2 │ 2025-04-10 09:54:29.78+02 │
└──────────────────────────────────────┴───────────────┴───────┴───────────────────────────┘

insert

签名 
insert(self: _duckdb.DuckDBPyRelation, values: object) -> None
描述

将给定值插入关系对象

参数

  • values : object

    要插入的匹配关系列列表的值元组。

示例 
import duckdb

from datetime import datetime
from uuid import uuid4

duckdb_conn = duckdb.connect()

duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
).to_table("code_example")

rel = duckdb_conn.table("code_example")

rel.insert(
    (
        uuid4(), 
        'value is even',
        10, 
        datetime.now()
    )
)

rel.filter("value = 10")
结果 
┌──────────────────────────────────────┬───────────────┬───────┬───────────────────────────────┐
│                  id                  │  description  │ value │       created_timestamp       │
│                 uuid                 │    varchar    │ int64 │   timestamp with time zone    │
├──────────────────────────────────────┼───────────────┼───────┼───────────────────────────────┤
│ c6dfab87-fae6-4213-8f76-1b96a8d179f6 │ value is even │    10 │ 2025-04-10 10:02:24.652218+02 │
└──────────────────────────────────────┴───────────────┴───────┴───────────────────────────────┘

insert_into

签名 
insert_into(self: _duckdb.DuckDBPyRelation, table_name: str) -> None
描述

将关系对象插入到名为 table_name 的现有表中

参数

  • table_name : str

    要插入数据的表名。关系对象的列顺序必须与表一致。

示例 
import duckdb

from datetime import datetime
from uuid import uuid4

duckdb_conn = duckdb.connect()

duckdb_conn.sql("""
        select
            gen_random_uuid() as id,
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value,
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
).to_table("code_example")

rel = duckdb_conn.values(
    [
        uuid4(),
        'value is even',
        10,
        datetime.now()
    ]
)

rel.insert_into("code_example")

duckdb_conn.table("code_example").filter("value = 10")
结果 
┌──────────────────────────────────────┬───────────────┬───────┬───────────────────────────────┐
│                  id                  │  description  │ value │       created_timestamp       │
│                 uuid                 │    varchar    │ int64 │   timestamp with time zone    │
├──────────────────────────────────────┼───────────────┼───────┼───────────────────────────────┤
│ 271c5ddd-c1d5-4638-b5a0-d8c7dc9e8220 │ value is even │    10 │ 2025-04-10 14:29:18.616379+02 │
└──────────────────────────────────────┴───────────────┴───────┴───────────────────────────────┘

intersect

签名 
intersect(self: _duckdb.DuckDBPyRelation, other_rel: _duckdb.DuckDBPyRelation) -> _duckdb.DuckDBPyRelation
描述

创建当前关系对象与 other_rel 关系对象的交集 (Intersect)

参数

  • other_rel : _duckdb.DuckDBPyRelation

    与当前关系求交集的另一个关系对象（集合交集）。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.intersect(other_rel=rel.set_alias("other_rel"))
结果 
The relation query is executed once with `rel` and once with `other_rel`,
therefore generating different ids and timestamps:
┌──────┬─────────────┬───────┬──────────────────────────┐
│  id  │ description │ value │    created_timestamp     │
│ uuid │   varchar   │ int64 │ timestamp with time zone │
├──────┴─────────────┴───────┴──────────────────────────┤
│                        0 rows                         │
└───────────────────────────────────────────────────────┘

join

签名 
join(self: _duckdb.DuckDBPyRelation, other_rel: _duckdb.DuckDBPyRelation, condition: object, how: str = 'inner') -> _duckdb.DuckDBPyRelation
描述

使用 join_condition 中的条件表达式将当前关系对象与 other_rel 联接。支持的联接类型包括 'inner', 'left', 'right', 'outer', 'semi' 和 'anti'

根据提供 condition 参数的方式，生成的 JOIN 子句为

  • USING
import duckdb

duckdb_conn = duckdb.connect()

rel1 = duckdb_conn.sql("select range as id, concat('dummy 1', range) as text from range(1,10)")
rel2 = duckdb_conn.sql("select range as id, concat('dummy 2', range) as text from range(5,7)")

rel1.join(rel2, condition="id", how="inner").sql_query()

使用如下 SQL

SELECT * 
FROM (
        SELECT "range" AS id, 
            concat('dummy 1', "range") AS "text" 
        FROM "range"(1, 10)
    ) AS unnamed_relation_41bc15e744037078 
INNER JOIN (
        SELECT "range" AS id, 
        concat('dummy 2', "range") AS "text" 
        FROM "range"(5, 7)
    ) AS unnamed_relation_307e245965aa2c2b 
USING (id)
  • ON
import duckdb

duckdb_conn = duckdb.connect()

rel1 = duckdb_conn.sql("select range as id, concat('dummy 1', range) as text from range(1,10)")
rel2 = duckdb_conn.sql("select range as id, concat('dummy 2', range) as text from range(5,7)")

rel1.join(rel2, condition=f"{rel1.alias}.id = {rel2.alias}.id", how="inner").sql_query()

使用如下 SQL

SELECT * 
FROM (
        SELECT "range" AS id, 
            concat('dummy 1', "range") AS "text" 
        FROM "range"(1, 10)
    ) AS unnamed_relation_41bc15e744037078 
INNER JOIN (
        SELECT "range" AS id, 
        concat('dummy 2', "range") AS "text" 
        FROM "range"(5, 7)
    ) AS unnamed_relation_307e245965aa2c2b 
ON ((unnamed_relation_41bc15e744037078.id = unnamed_relation_307e245965aa2c2b.id))

关系型 API 不提供 NATURAL, POSITIONAL 和 ASOF 联接。 CROSS 联接可通过 cross 方法 使用。

参数

  • other_rel : _duckdb.DuckDBPyRelation

    要与当前关系进行联接的另一个关系对象。

  • condition : object

    联接条件，通常是 SQL 表达式或用于联接的重复列名。

  • how : str, default: 'inner'

    要执行的联接类型：'inner', 'left', 'right', 'outer', 'semi' 和 'anti'。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel = rel.set_alias("rel").join(
    other_rel=rel.set_alias("other_rel"), 
    condition="rel.id = other_rel.id",
    how="left"
)

rel.count("*")
结果 
┌──────────────┐
│ count_star() │
│    int64     │
├──────────────┤
│            9 │
└──────────────┘

limit

签名 
limit(self: _duckdb.DuckDBPyRelation, n: typing.SupportsInt, offset: typing.SupportsInt = 0) -> _duckdb.DuckDBPyRelation
描述

仅检索该关系对象的前 n 行，从 offset 开始

参数

  • n : int

    要返回的最大行数。

  • offset : int, default: 0

    开始返回行之前跳过的行数。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.limit(1)
结果 
┌──────────────────────────────────────┬─────────────────┬───────┬────────────────────────────┐
│                  id                  │   description   │ value │     created_timestamp      │
│                 uuid                 │     varchar     │ int64 │  timestamp with time zone  │
├──────────────────────────────────────┼─────────────────┼───────┼────────────────────────────┤
│ 4135597b-29e7-4cb9-a443-41f3d54f25df │ value is uneven │     1 │ 2025-04-10 10:52:03.678+02 │
└──────────────────────────────────────┴─────────────────┴───────┴────────────────────────────┘

map

签名 
map(self: _duckdb.DuckDBPyRelation, map_function: collections.abc.Callable, *, schema: typing.Optional[object] = None) -> _duckdb.DuckDBPyRelation
描述

在关系对象上调用传入的函数

参数

  • map_function : Callable

    接收 DataFrame 并返回转换后的 DataFrame 的 Python 函数。

  • schema : object, default: None

    描述输出关系结构的可选模式。

示例 
import duckdb
from pandas import DataFrame

def multiply_by_2(df: DataFrame):
    df["id"] = df["id"] * 2
    return df

duckdb_conn = duckdb.connect()
rel = duckdb_conn.sql("select range as id, 'dummy' as text from range(1,3)")

rel.map(multiply_by_2, schema={"id": int, "text": str})
结果 
┌───────┬─────────┐
│  id   │  text   │
│ int64 │ varchar │
├───────┼─────────┤
│     2 │ dummy   │
│     4 │ dummy   │
└───────┴─────────┘

order

签名 
order(self: _duckdb.DuckDBPyRelation, order_expr: str) -> _duckdb.DuckDBPyRelation
描述

通过 order_expr 对关系对象进行重排序

参数

  • order_expr : str

    定义结果行排序的 SQL 表达式。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.order("value desc").limit(1, offset=4)
结果 
┌──────────────────────────────────────┬─────────────────┬───────┬────────────────────────────┐
│                  id                  │   description   │ value │     created_timestamp      │
│                 uuid                 │     varchar     │ int64 │  timestamp with time zone  │
├──────────────────────────────────────┼─────────────────┼───────┼────────────────────────────┤
│ 55899131-e3d3-463c-a215-f65cb8aef3bf │ value is uneven │     5 │ 2025-04-10 10:56:03.678+02 │
└──────────────────────────────────────┴─────────────────┴───────┴────────────────────────────┘

project

签名 
project(self: _duckdb.DuckDBPyRelation, *args, groups: str = '') -> _duckdb.DuckDBPyRelation
描述

通过 project_expr 中的投影表达式投影关系对象

别名: select

参数

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.project("description").limit(1)
结果 
┌─────────────────┐
│   description   │
│     varchar     │
├─────────────────┤
│ value is uneven │
└─────────────────┘

select

签名 
select(self: _duckdb.DuckDBPyRelation, *args, groups: str = '') -> _duckdb.DuckDBPyRelation
描述

通过 project_expr 中的投影表达式投影关系对象

别名: project

参数

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.select("description").limit(1)
结果 
┌─────────────────┐
│   description   │
│     varchar     │
├─────────────────┤
│ value is uneven │
└─────────────────┘

sort

签名 
sort(self: _duckdb.DuckDBPyRelation, *args) -> _duckdb.DuckDBPyRelation
描述

通过提供的表达式对关系对象进行重排序

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.sort("description")
结果 
┌──────────────────────────────────────┬─────────────────┬───────┬────────────────────────────┐
│                  id                  │   description   │ value │     created_timestamp      │
│                 uuid                 │     varchar     │ int64 │  timestamp with time zone  │
├──────────────────────────────────────┼─────────────────┼───────┼────────────────────────────┤
│ 5e0dfa8c-de4d-4ccd-8cff-450dabb86bde │ value is even   │     6 │ 2025-04-10 16:52:15.605+02 │
│ 95f1ad48-facf-4a84-a971-0a4fecce68c7 │ value is even   │     2 │ 2025-04-10 16:48:15.605+02 │
...

union

签名 
union(self: _duckdb.DuckDBPyRelation, union_rel: _duckdb.DuckDBPyRelation) -> _duckdb.DuckDBPyRelation
描述

创建当前关系对象与 other_rel 关系对象的并集 (Union)

此并集操作为 union all。若要获取去重后的值，请应用 distinct。

参数

  • union_rel : _duckdb.DuckDBPyRelation

    与当前关系进行并集运算的另一个关系对象（集合并集）。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel = rel.union(union_rel=rel)

rel.count("*")
结果 
┌──────────────┐
│ count_star() │
│    int64     │
├──────────────┤
│           18 │
└──────────────┘

update

签名 
update(self: _duckdb.DuckDBPyRelation, set: object, *, condition: object = None) -> None
描述

使用提供的表达式更新给定关系

参数

  • set : object

    更新操作中列到新值的映射。

  • condition : object, default: None

    过滤更新行的可选条件。

示例 
import duckdb

from duckdb import ColumnExpression

duckdb_conn = duckdb.connect()

duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
).to_table("code_example")

rel = duckdb_conn.table("code_example")

rel.update(set={"description":None}, condition=ColumnExpression("value") == 1)

# the update is executed on the table, but not reflected on the relationship
# the relationship has to be recreated to retrieve the modified data
rel = duckdb_conn.table("code_example")

rel.show()
结果 
┌──────────────────────────────────────┬─────────────────┬───────┬────────────────────────────┐
│                  id                  │   description   │ value │     created_timestamp      │
│                 uuid                 │     varchar     │ int64 │  timestamp with time zone  │
├──────────────────────────────────────┼─────────────────┼───────┼────────────────────────────┤
│ 66dcaa14-f4a6-4a55-af3b-7f6aa23ab4ad │ NULL            │     1 │ 2025-04-10 16:54:49.317+02 │
│ c6a18a42-67fb-4c95-827b-c966f2f95b88 │ value is even   │     2 │ 2025-04-10 16:55:49.317+02 │
...

函数

本节包含可应用于关系对象以获取（标量）结果的函数。这些函数均采用 惰性求值。

名称 描述
any_value 返回指定列中的第一个非空值
arg_max 查找值列中具有最大值的行，并返回该行中参数列的值
arg_min 查找值列中具有最小值的行，并返回该行中参数列的值
avg 计算给定列的平均值
bit_and 计算给定列中所有位的按位与 (AND)
bit_or 计算给定列中所有位的按位或 (OR)
bit_xor 计算给定列中所有位的按位异或 (XOR)
bitstring_agg 计算位串，其中每个位对应给定列中的不同值
bool_and 计算给定列中所有值的逻辑与 (AND)
bool_or 计算给定列中所有值的逻辑或 (OR)
count 计算给定列中存在的元素数量
cume_dist 计算分区内的累积分布
dense_rank 计算分区内的稠密排名 (dense rank)
distinct 从该关系对象中检索不同（去重）的行
favg 使用更精确的浮点求和算法 (Kahan Sum) 计算给定列的平均值
first 返回给定列的第一个值
first_value 计算组或分区内的第一个值
fsum 使用更精确的浮点求和算法 (Kahan Sum) 计算给定列的总和
geomean 计算给定列中所有值的几何平均值
histogram 计算给定列中所有值的直方图
lag 计算分区内的滞后值 (lag)
last 返回给定列的最后一个值
last_value 计算组或分区内的最后一个值
lead 计算分区内的超前值 (lead)
list 返回包含给定列中所有值的列表
max 返回给定列中的最大值
mean 计算给定列的平均值
median 计算给定列中所有值的中位数
min 返回给定列中的最小值
mode 计算给定列中所有值的众数
n_tile 将分区尽可能均匀地划分为 num_buckets 个桶
nth_value 计算分区内的第 n 个值
percent_rank 计算分区内的相对排名
product 返回给定列中所有值的乘积
quantile 计算给定列的精确分位数
quantile_cont 计算给定列的插值分位数
quantile_disc 计算给定列的精确分位数
rank 计算分区内的排名
rank_dense 计算分区内的稠密排名 (dense rank)
row_number 计算分区内的行号
select_dtypes 通过类型过滤从关系中选择列
select_types 通过类型过滤从关系中选择列
std 计算给定列的样本标准差
stddev 计算给定列的样本标准差
stddev_pop 计算给定列的总体标准差
stddev_samp 计算给定列的样本标准差
string_agg 使用分隔符连接给定列中的值
sum 计算给定列中所有值的总和
unique 返回一列中的不同值。
value_counts 计算给定列中元素的数量，并投影原始列
var 计算给定列的样本方差
var_pop 计算给定列的总体方差
var_samp 计算给定列的样本方差
variance 计算给定列的样本方差

any_value

签名 
any_value(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

返回指定列中的第一个非空值

参数

  • column : str

    用于检索任意值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，格式为 over (partition by ... order by ...)。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.any_value('id')
结果 
┌──────────────────────────────────────┐
│            any_value(id)             │
│                 uuid                 │
├──────────────────────────────────────┤
│ 642ea3d7-793d-4867-a759-91c1226c25a0 │
└──────────────────────────────────────┘

arg_max

签名 
arg_max(self: _duckdb.DuckDBPyRelation, arg_column: str, value_column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

查找值列中具有最大值的行，并返回该行中参数列的值

参数

  • arg_column : str

    用于查找最大值对应参数的列名。

  • value_column : str

    包含用于确定最大值的值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，格式为 over (partition by ... order by ...)。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.arg_max(arg_column="value", value_column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬───────────────────────────┐
│   description   │ arg_max("value", "value") │
│     varchar     │           int64           │
├─────────────────┼───────────────────────────┤
│ value is uneven │                         9 │
│ value is even   │                         8 │
└─────────────────┴───────────────────────────┘

arg_min

签名 
arg_min(self: _duckdb.DuckDBPyRelation, arg_column: str, value_column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

查找值列中具有最小值的行，并返回该行中参数列的值

参数

  • arg_column : str

    用于查找最小值对应参数的列名。

  • value_column : str

    包含用于确定最小值的值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.arg_min(arg_column="value", value_column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬───────────────────────────┐
│   description   │ arg_min("value", "value") │
│     varchar     │           int64           │
├─────────────────┼───────────────────────────┤
│ value is even   │                         2 │
│ value is uneven │                         1 │
└─────────────────┴───────────────────────────┘

avg

签名 
avg(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的平均值

参数

  • column : str

    用于计算平均值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.avg('value')
结果 
┌──────────────┐
│ avg("value") │
│    double    │
├──────────────┤
│          5.0 │
└──────────────┘

bit_and

签名 
bit_and(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有位的按位与 (AND)

参数

  • column : str

    用于执行按位与聚合的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel = rel.select("description, value::bit as value_bit")

rel.bit_and(column="value_bit", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────────────────────────────────────────────────┐
│   description   │                        bit_and(value_bit)                        │
│     varchar     │                               bit                                │
├─────────────────┼──────────────────────────────────────────────────────────────────┤
│ value is uneven │ 0000000000000000000000000000000000000000000000000000000000000001 │
│ value is even   │ 0000000000000000000000000000000000000000000000000000000000000000 │
└─────────────────┴──────────────────────────────────────────────────────────────────┘

bit_or

签名 
bit_or(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有位的按位或 (OR)

参数

  • column : str

    用于执行按位或聚合的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel = rel.select("description, value::bit as value_bit")

rel.bit_or(column="value_bit", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────────────────────────────────────────────────┐
│   description   │                        bit_or(value_bit)                         │
│     varchar     │                               bit                                │
├─────────────────┼──────────────────────────────────────────────────────────────────┤
│ value is uneven │ 0000000000000000000000000000000000000000000000000000000000001111 │
│ value is even   │ 0000000000000000000000000000000000000000000000000000000000001110 │
└─────────────────┴──────────────────────────────────────────────────────────────────┘

bit_xor

签名 
bit_xor(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有位的按位异或 (XOR)

参数

  • column : str

    用于执行按位异或聚合的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel = rel.select("description, value::bit as value_bit")

rel.bit_xor(column="value_bit", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────────────────────────────────────────────────┐
│   description   │                        bit_xor(value_bit)                        │
│     varchar     │                               bit                                │
├─────────────────┼──────────────────────────────────────────────────────────────────┤
│ value is even   │ 0000000000000000000000000000000000000000000000000000000000001000 │
│ value is uneven │ 0000000000000000000000000000000000000000000000000000000000001001 │
└─────────────────┴──────────────────────────────────────────────────────────────────┘

bitstring_agg

签名 
bitstring_agg(self: _duckdb.DuckDBPyRelation, column: str, min: typing.Optional[object] = None, max: typing.Optional[object] = None, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算位串，其中每个位对应给定列中的不同值

参数

  • column : str

    要作为位串聚合的列名。

  • min : object, default: None

    用于聚合的可选最小位串值。

  • max : object, default: None

    用于聚合的可选最大位串值。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.bitstring_agg(column="value", groups="description", projected_columns="description", min=1, max=9)
结果 
┌─────────────────┬────────────────────────┐
│   description   │ bitstring_agg("value") │
│     varchar     │          bit           │
├─────────────────┼────────────────────────┤
│ value is uneven │ 101010101              │
│ value is even   │ 010101010              │
└─────────────────┴────────────────────────┘

bool_and

签名 
bool_and(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有值的逻辑与 (AND)

参数

  • column : str

    用于执行逻辑与聚合的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel = rel.select("description, mod(value,2)::boolean as uneven")

rel.bool_and(column="uneven", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────┐
│   description   │ bool_and(uneven) │
│     varchar     │     boolean      │
├─────────────────┼──────────────────┤
│ value is even   │ false            │
│ value is uneven │ true             │
└─────────────────┴──────────────────┘

bool_or

签名 
bool_or(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有值的逻辑或 (OR)

参数

  • column : str

    用于执行逻辑或聚合的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel = rel.select("description, mod(value,2)::boolean as uneven")

rel.bool_or(column="uneven", groups="description", projected_columns="description")
结果 
┌─────────────────┬─────────────────┐
│   description   │ bool_or(uneven) │
│     varchar     │     boolean     │
├─────────────────┼─────────────────┤
│ value is even   │ false           │
│ value is uneven │ true            │
└─────────────────┴─────────────────┘

count

签名 
count(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中存在的元素数量

参数

  • column : str

    用于执行计数的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.count("id")
结果 
┌───────────┐
│ count(id) │
│   int64   │
├───────────┤
│         9 │
└───────────┘

cume_dist

签名 
cume_dist(self: _duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算分区内的累积分布

参数

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.cume_dist(window_spec="over (partition by description order by value)", projected_columns="description, value")
结果 
┌─────────────────┬───────┬──────────────────────────────────────────────────────────────┐
│   description   │ value │ cume_dist() OVER (PARTITION BY description ORDER BY "value") │
│     varchar     │ int64 │                            double                            │
├─────────────────┼───────┼──────────────────────────────────────────────────────────────┤
│ value is uneven │     1 │                                                          0.2 │
│ value is uneven │     3 │                                                          0.4 │
│ value is uneven │     5 │                                                          0.6 │
│ value is uneven │     7 │                                                          0.8 │
│ value is uneven │     9 │                                                          1.0 │
│ value is even   │     2 │                                                         0.25 │
│ value is even   │     4 │                                                          0.5 │
│ value is even   │     6 │                                                         0.75 │
│ value is even   │     8 │                                                          1.0 │
└─────────────────┴───────┴──────────────────────────────────────────────────────────────┘

dense_rank

签名 
dense_rank(self: _duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算分区内的稠密排名 (dense rank)

别名: rank_dense

参数

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

 rel.dense_rank(window_spec="over (partition by description order by value)", projected_columns="description, value")
结果 
┌─────────────────┬───────┬───────────────────────────────────────────────────────────────┐
│   description   │ value │ dense_rank() OVER (PARTITION BY description ORDER BY "value") │
│     varchar     │ int64 │                             int64                             │
├─────────────────┼───────┼───────────────────────────────────────────────────────────────┤
│ value is even   │     2 │                                                             1 │
│ value is even   │     4 │                                                             2 │
│ value is even   │     6 │                                                             3 │
│ value is even   │     8 │                                                             4 │
│ value is uneven │     1 │                                                             1 │
│ value is uneven │     3 │                                                             2 │
│ value is uneven │     5 │                                                             3 │
│ value is uneven │     7 │                                                             4 │
│ value is uneven │     9 │                                                             5 │
└─────────────────┴───────┴───────────────────────────────────────────────────────────────┘

distinct

签名 
distinct(self: _duckdb.DuckDBPyRelation) -> _duckdb.DuckDBPyRelation
描述

从该关系对象中检索不同（去重）的行

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("select range from range(1,4)")

rel = rel.union(union_rel=rel)

rel.distinct().order("range")
结果 
┌───────┐
│ range │
│ int64 │
├───────┤
│     1 │
│     2 │
│     3 │
└───────┘

favg

签名 
favg(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

使用更精确的浮点求和算法 (Kahan Sum) 计算给定列的平均值

参数

  • column : str

    用于计算平均值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.favg(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬───────────────┐
│   description   │ favg("value") │
│     varchar     │    double     │
├─────────────────┼───────────────┤
│ value is uneven │           5.0 │
│ value is even   │           5.0 │
└─────────────────┴───────────────┘

first

签名 
first(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

返回给定列的第一个值

参数

  • column : str

    用于检索第一个值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.first(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────┐
│   description   │ "first"("value") │
│     varchar     │      int64       │
├─────────────────┼──────────────────┤
│ value is even   │                2 │
│ value is uneven │                1 │
└─────────────────┴──────────────────┘

first_value

签名 
first_value(self: _duckdb.DuckDBPyRelation, column: str, window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算组或分区内的第一个值

参数

  • column : str

    用于检索第一个值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.first_value(column="value", window_spec="over (partition by description order by value)", projected_columns="description").distinct()
结果 
┌─────────────────┬───────────────────────────────────────────────────────────────────────┐
│   description   │ first_value("value") OVER (PARTITION BY description ORDER BY "value") │
│     varchar     │                                 int64                                 │
├─────────────────┼───────────────────────────────────────────────────────────────────────┤
│ value is even   │                                                                     2 │
│ value is uneven │                                                                     1 │
└─────────────────┴───────────────────────────────────────────────────────────────────────┘

fsum

签名 
fsum(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

使用更精确的浮点求和算法 (Kahan Sum) 计算给定列的总和

参数

  • column : str

    用于计算总和的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.fsum(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬───────────────┐
│   description   │ fsum("value") │
│     varchar     │    double     │
├─────────────────┼───────────────┤
│ value is even   │          20.0 │
│ value is uneven │          25.0 │
└─────────────────┴───────────────┘

geomean

签名 
geomean(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有值的几何平均值

参数

  • column : str

    用于计算几何平均值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.geomean(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬───────────────────┐
│   description   │ geomean("value")  │
│     varchar     │      double       │
├─────────────────┼───────────────────┤
│ value is uneven │ 3.936283427035351 │
│ value is even   │ 4.426727678801287 │
└─────────────────┴───────────────────┘

histogram

签名 
histogram(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有值的直方图

参数

  • column : str

    用于计算直方图的列名。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.histogram(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬───────────────────────────┐
│   description   │    histogram("value")     │
│     varchar     │   map(bigint, ubigint)    │
├─────────────────┼───────────────────────────┤
│ value is uneven │ {1=1, 3=1, 5=1, 7=1, 9=1} │
│ value is even   │ {2=1, 4=1, 6=1, 8=1}      │
└─────────────────┴───────────────────────────┘

lag

签名 
lag(self: _duckdb.DuckDBPyRelation, column: str, window_spec: str, offset: typing.SupportsInt = 1, default_value: str = 'NULL', ignore_nulls: bool = False, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算分区内的滞后值 (lag)

参数

  • column : str

    用于应用滞后函数的列名。

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • offset : int, default: 1

    滞后行数。

  • default_value : str, default: 'NULL'

    当滞后偏移超出范围时返回的默认值。

  • ignore_nulls : bool, default: False

    计算滞后值时是否忽略 NULL 值。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.lag(column="description", window_spec="over (order by value)", projected_columns="description, value")
结果 
┌─────────────────┬───────┬───────────────────────────────────────────────────┐
│   description   │ value │ lag(description, 1, NULL) OVER (ORDER BY "value") │
│     varchar     │ int64 │                      varchar                      │
├─────────────────┼───────┼───────────────────────────────────────────────────┤
│ value is uneven │     1 │ NULL                                              │
│ value is even   │     2 │ value is uneven                                   │
│ value is uneven │     3 │ value is even                                     │
│ value is even   │     4 │ value is uneven                                   │
│ value is uneven │     5 │ value is even                                     │
│ value is even   │     6 │ value is uneven                                   │
│ value is uneven │     7 │ value is even                                     │
│ value is even   │     8 │ value is uneven                                   │
│ value is uneven │     9 │ value is even                                     │
└─────────────────┴───────┴───────────────────────────────────────────────────┘

last

签名 
last(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

返回给定列的最后一个值

参数

  • column : str

    用于检索最后一个值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.last(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬─────────────────┐
│   description   │ "last"("value") │
│     varchar     │      int64      │
├─────────────────┼─────────────────┤
│ value is even   │               8 │
│ value is uneven │               9 │
└─────────────────┴─────────────────┘

last_value

签名 
last_value(self: _duckdb.DuckDBPyRelation, column: str, window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算组或分区内的最后一个值

参数

  • column : str

    用于检索窗口内最后一个值的列名。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.last_value(column="value", window_spec="over (order by description)", projected_columns="description").distinct()
结果 
┌─────────────────┬─────────────────────────────────────────────────┐
│   description   │ last_value("value") OVER (ORDER BY description) │
│     varchar     │                      int64                      │
├─────────────────┼─────────────────────────────────────────────────┤
│ value is uneven │                                               9 │
│ value is even   │                                               8 │
└─────────────────┴─────────────────────────────────────────────────┘

lead

签名 
lead(self: _duckdb.DuckDBPyRelation, column: str, window_spec: str, offset: typing.SupportsInt = 1, default_value: str = 'NULL', ignore_nulls: bool = False, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算分区内的超前值 (lead)

参数

  • column : str

    用于应用超前函数的列名。

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • offset : int, default: 1

    超前行数。

  • default_value : str, default: 'NULL'

    当超前偏移超出范围时返回的默认值。

  • ignore_nulls : bool, default: False

    计算超前值时是否忽略 NULL 值。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.lead(column="description", window_spec="over (order by value)", projected_columns="description, value")
结果 
┌─────────────────┬───────┬────────────────────────────────────────────────────┐
│   description   │ value │ lead(description, 1, NULL) OVER (ORDER BY "value") │
│     varchar     │ int64 │                      varchar                       │
├─────────────────┼───────┼────────────────────────────────────────────────────┤
│ value is uneven │     1 │ value is even                                      │
│ value is even   │     2 │ value is uneven                                    │
│ value is uneven │     3 │ value is even                                      │
│ value is even   │     4 │ value is uneven                                    │
│ value is uneven │     5 │ value is even                                      │
│ value is even   │     6 │ value is uneven                                    │
│ value is uneven │     7 │ value is even                                      │
│ value is even   │     8 │ value is uneven                                    │
│ value is uneven │     9 │ NULL                                               │
└─────────────────┴───────┴────────────────────────────────────────────────────┘

list

签名 
list(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

返回包含给定列中所有值的列表

参数

  • column : str

    用于将值聚合为列表的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.list(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬─────────────────┐
│   description   │  list("value")  │
│     varchar     │     int64[]     │
├─────────────────┼─────────────────┤
│ value is even   │ [2, 4, 6, 8]    │
│ value is uneven │ [1, 3, 5, 7, 9] │
└─────────────────┴─────────────────┘

max

签名 
max(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

返回给定列中的最大值

参数

  • column : str

    用于计算最大值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

 rel.max(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────┐
│   description   │ max("value") │
│     varchar     │    int64     │
├─────────────────┼──────────────┤
│ value is even   │            8 │
│ value is uneven │            9 │
└─────────────────┴──────────────┘

mean

签名 
mean(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的平均值

参数

  • column : str

    用于计算平均值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.mean(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────┐
│   description   │ avg("value") │
│     varchar     │    double    │
├─────────────────┼──────────────┤
│ value is even   │          5.0 │
│ value is uneven │          5.0 │
└─────────────────┴──────────────┘

median

签名 
median(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有值的中位数

参数

  • column : str

    用于计算中位数的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.median(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬─────────────────┐
│   description   │ median("value") │
│     varchar     │     double      │
├─────────────────┼─────────────────┤
│ value is even   │             5.0 │
│ value is uneven │             5.0 │
└─────────────────┴─────────────────┘

min

签名 
min(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

返回给定列中的最小值

参数

  • column : str

    用于计算最小值的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.min(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────┐
│   description   │ min("value") │
│     varchar     │    int64     │
├─────────────────┼──────────────┤
│ value is uneven │            1 │
│ value is even   │            2 │
└─────────────────┴──────────────┘

mode

签名 
mode(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有值的众数

参数

  • column : str

    用于计算众数（最频繁值）的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.mode(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬─────────────────┐
│   description   │ "mode"("value") │
│     varchar     │      int64      │
├─────────────────┼─────────────────┤
│ value is uneven │               1 │
│ value is even   │               2 │
└─────────────────┴─────────────────┘

n_tile

签名 
n_tile(self: _duckdb.DuckDBPyRelation, window_spec: str, num_buckets: typing.SupportsInt, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

将分区尽可能均匀地划分为 num_buckets 个桶

参数

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • num_buckets : int

    将行划分为的桶数。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.n_tile(window_spec="over (partition by description)", num_buckets=2, projected_columns="description, value")
结果 
┌─────────────────┬───────┬──────────────────────────────────────────┐
│   description   │ value │ ntile(2) OVER (PARTITION BY description) │
│     varchar     │ int64 │                  int64                   │
├─────────────────┼───────┼──────────────────────────────────────────┤
│ value is uneven │     1 │                                        1 │
│ value is uneven │     3 │                                        1 │
│ value is uneven │     5 │                                        1 │
│ value is uneven │     7 │                                        2 │
│ value is uneven │     9 │                                        2 │
│ value is even   │     2 │                                        1 │
│ value is even   │     4 │                                        1 │
│ value is even   │     6 │                                        2 │
│ value is even   │     8 │                                        2 │
└─────────────────┴───────┴──────────────────────────────────────────┘

nth_value

签名 
nth_value(self: _duckdb.DuckDBPyRelation, column: str, window_spec: str, offset: typing.SupportsInt, ignore_nulls: bool = False, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算分区内的第 n 个值

参数

  • column : str

    用于检索窗口内第 n 个值的列名。

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • offset : int

    窗口内要检索的值的位置（1-based 索引）。

  • ignore_nulls : bool, default: False

    计算第 n 个值时是否忽略 NULL 值。

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.nth_value(column="value", window_spec="over (partition by description)", projected_columns="description", offset=1)
结果 
┌─────────────────┬───────────────────────────────────────────────────────┐
│   description   │ nth_value("value", 1) OVER (PARTITION BY description) │
│     varchar     │                         int64                         │
├─────────────────┼───────────────────────────────────────────────────────┤
│ value is even   │                                                     2 │
│ value is even   │                                                     2 │
│ value is even   │                                                     2 │
│ value is even   │                                                     2 │
│ value is uneven │                                                     1 │
│ value is uneven │                                                     1 │
│ value is uneven │                                                     1 │
│ value is uneven │                                                     1 │
│ value is uneven │                                                     1 │
└─────────────────┴───────────────────────────────────────────────────────┘

percent_rank

签名 
percent_rank(self: _duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算分区内的相对排名

参数

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.percent_rank(window_spec="over (partition by description order by value)", projected_columns="description, value")
结果 
┌─────────────────┬───────┬─────────────────────────────────────────────────────────────────┐
│   description   │ value │ percent_rank() OVER (PARTITION BY description ORDER BY "value") │
│     varchar     │ int64 │                             double                              │
├─────────────────┼───────┼─────────────────────────────────────────────────────────────────┤
│ value is even   │     2 │                                                             0.0 │
│ value is even   │     4 │                                              0.3333333333333333 │
│ value is even   │     6 │                                              0.6666666666666666 │
│ value is even   │     8 │                                                             1.0 │
│ value is uneven │     1 │                                                             0.0 │
│ value is uneven │     3 │                                                            0.25 │
│ value is uneven │     5 │                                                             0.5 │
│ value is uneven │     7 │                                                            0.75 │
│ value is uneven │     9 │                                                             1.0 │
└─────────────────┴───────┴─────────────────────────────────────────────────────────────────┘

product

签名 
product(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

返回给定列中所有值的乘积

参数

  • column : str

    用于计算乘积的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.product(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────┐
│   description   │ product("value") │
│     varchar     │      double      │
├─────────────────┼──────────────────┤
│ value is uneven │            945.0 │
│ value is even   │            384.0 │
└─────────────────┴──────────────────┘

quantile

签名 
quantile(self: _duckdb.DuckDBPyRelation, column: str, q: object = 0.5, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的精确分位数

参数

  • column : str

    用于计算分位数的列名。

  • q : object, default: 0.5

    要计算的分位数（例如 0.5 为中位数）。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.quantile(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────────────────┐
│   description   │ quantile_disc("value", 0.500000) │
│     varchar     │              int64               │
├─────────────────┼──────────────────────────────────┤
│ value is uneven │                                5 │
│ value is even   │                                4 │
└─────────────────┴──────────────────────────────────┘

quantile_cont

签名 
quantile_cont(self: _duckdb.DuckDBPyRelation, column: str, q: object = 0.5, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的插值分位数

参数

  • column : str

    用于计算连续分位数的列名。

  • q : object, default: 0.5

    要计算的分位数（例如 0.5 为中位数）。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.quantile_cont(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────────────────┐
│   description   │ quantile_cont("value", 0.500000) │
│     varchar     │              double              │
├─────────────────┼──────────────────────────────────┤
│ value is even   │                              5.0 │
│ value is uneven │                              5.0 │
└─────────────────┴──────────────────────────────────┘

quantile_disc

签名 
quantile_disc(self: _duckdb.DuckDBPyRelation, column: str, q: object = 0.5, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的精确分位数

参数

  • column : str

    用于计算离散分位数的列名。

  • q : object, default: 0.5

    要计算的分位数（例如 0.5 为中位数）。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.quantile_disc(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────────────────┐
│   description   │ quantile_disc("value", 0.500000) │
│     varchar     │              int64               │
├─────────────────┼──────────────────────────────────┤
│ value is even   │                                4 │
│ value is uneven │                                5 │
└─────────────────┴──────────────────────────────────┘

rank

签名 
rank(self: _duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算分区内的排名

参数

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.rank(window_spec="over (partition by description order by value)", projected_columns="description, value")
结果 
┌─────────────────┬───────┬─────────────────────────────────────────────────────────┐
│   description   │ value │ rank() OVER (PARTITION BY description ORDER BY "value") │
│     varchar     │ int64 │                          int64                          │
├─────────────────┼───────┼─────────────────────────────────────────────────────────┤
│ value is uneven │     1 │                                                       1 │
│ value is uneven │     3 │                                                       2 │
│ value is uneven │     5 │                                                       3 │
│ value is uneven │     7 │                                                       4 │
│ value is uneven │     9 │                                                       5 │
│ value is even   │     2 │                                                       1 │
│ value is even   │     4 │                                                       2 │
│ value is even   │     6 │                                                       3 │
│ value is even   │     8 │                                                       4 │
└─────────────────┴───────┴─────────────────────────────────────────────────────────┘

rank_dense

签名 
rank_dense(self: _duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算分区内的稠密排名 (dense rank)

别名: dense_rank

参数

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

 rel.rank_dense(window_spec="over (partition by description order by value)", projected_columns="description, value")
结果 
┌─────────────────┬───────┬───────────────────────────────────────────────────────────────┐
│   description   │ value │ dense_rank() OVER (PARTITION BY description ORDER BY "value") │
│     varchar     │ int64 │                             int64                             │
├─────────────────┼───────┼───────────────────────────────────────────────────────────────┤
│ value is uneven │     1 │                                                             1 │
│ value is uneven │     3 │                                                             2 │
│ value is uneven │     5 │                                                             3 │
│ value is uneven │     7 │                                                             4 │
│ value is uneven │     9 │                                                             5 │
│ value is even   │     2 │                                                             1 │
│ value is even   │     4 │                                                             2 │
│ value is even   │     6 │                                                             3 │
│ value is even   │     8 │                                                             4 │
└─────────────────┴───────┴───────────────────────────────────────────────────────────────┘

row_number

签名 
row_number(self: _duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算分区内的行号

参数

  • window_spec : str

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.row_number(window_spec="over (partition by description order by value)", projected_columns="description, value")
结果 
┌─────────────────┬───────┬───────────────────────────────────────────────────────────────┐
│   description   │ value │ row_number() OVER (PARTITION BY description ORDER BY "value") │
│     varchar     │ int64 │                             int64                             │
├─────────────────┼───────┼───────────────────────────────────────────────────────────────┤
│ value is uneven │     1 │                                                             1 │
│ value is uneven │     3 │                                                             2 │
│ value is uneven │     5 │                                                             3 │
│ value is uneven │     7 │                                                             4 │
│ value is uneven │     9 │                                                             5 │
│ value is even   │     2 │                                                             1 │
│ value is even   │     4 │                                                             2 │
│ value is even   │     6 │                                                             3 │
│ value is even   │     8 │                                                             4 │
└─────────────────┴───────┴───────────────────────────────────────────────────────────────┘

select_dtypes

签名 
select_dtypes(self: _duckdb.DuckDBPyRelation, types: object) -> _duckdb.DuckDBPyRelation
描述

通过类型过滤从关系中选择列

别名: select_types

参数

  • types : object

    用于选择列的数据类型。可以是单个类型或类型的集合。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.select_dtypes(types=[duckdb.sqltypes.VARCHAR]).distinct()
结果 
┌─────────────────┐
│   description   │
│     varchar     │
├─────────────────┤
│ value is even   │
│ value is uneven │
└─────────────────┘

select_types

签名 
select_types(self: _duckdb.DuckDBPyRelation, types: object) -> _duckdb.DuckDBPyRelation
描述

通过类型过滤从关系中选择列

别名: select_dtypes

参数

  • types : object

    用于选择列的数据类型。可以是单个类型或类型的集合。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.select_types(types=[duckdb.sqltypes.VARCHAR]).distinct()
结果 
┌─────────────────┐
│   description   │
│     varchar     │
├─────────────────┤
│ value is even   │
│ value is uneven │
└─────────────────┘

std

签名 
std(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的样本标准差

别名: stddev, stddev_samp

参数

  • column : str

    用于计算标准差的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.std(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────┐
│   description   │ stddev_samp("value") │
│     varchar     │        double        │
├─────────────────┼──────────────────────┤
│ value is uneven │   3.1622776601683795 │
│ value is even   │    2.581988897471611 │
└─────────────────┴──────────────────────┘

stddev

签名 
stddev(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的样本标准差

别名: std, stddev_samp

参数

  • column : str

    用于计算标准差的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.stddev(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────┐
│   description   │ stddev_samp("value") │
│     varchar     │        double        │
├─────────────────┼──────────────────────┤
│ value is even   │    2.581988897471611 │
│ value is uneven │   3.1622776601683795 │
└─────────────────┴──────────────────────┘

stddev_pop

签名 
stddev_pop(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的总体标准差

参数

  • column : str

    用于计算标准差的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.stddev_pop(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬─────────────────────┐
│   description   │ stddev_pop("value") │
│     varchar     │       double        │
├─────────────────┼─────────────────────┤
│ value is even   │    2.23606797749979 │
│ value is uneven │  2.8284271247461903 │
└─────────────────┴─────────────────────┘

stddev_samp

签名 
stddev_samp(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的样本标准差

别名: stddev, std

参数

  • column : str

    用于计算标准差的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.stddev_samp(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────┐
│   description   │ stddev_samp("value") │
│     varchar     │        double        │
├─────────────────┼──────────────────────┤
│ value is even   │    2.581988897471611 │
│ value is uneven │   3.1622776601683795 │
└─────────────────┴──────────────────────┘

string_agg

签名 
string_agg(self: _duckdb.DuckDBPyRelation, column: str, sep: str = ',', groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

使用分隔符连接给定列中的值

参数

  • column : str

    用于连接值的列名。

  • sep : str, default: ','

    连接值之间使用的分隔符字符串。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.string_agg(column="value", sep=",", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────────────┐
│   description   │ string_agg("value", ',') │
│     varchar     │         varchar          │
├─────────────────┼──────────────────────────┤
│ value is even   │ 2,4,6,8                  │
│ value is uneven │ 1,3,5,7,9                │
└─────────────────┴──────────────────────────┘

sum

签名 
sum(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中所有值的总和

参数

  • column : str

    用于计算总和的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.sum(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────┐
│   description   │ sum("value") │
│     varchar     │    int128    │
├─────────────────┼──────────────┤
│ value is even   │           20 │
│ value is uneven │           25 │
└─────────────────┴──────────────┘

unique

签名 
unique(self: _duckdb.DuckDBPyRelation, unique_aggr: str) -> _duckdb.DuckDBPyRelation
描述

返回一列中的不同值。

参数

  • unique_aggr : str

    用于获取不同值的列。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.unique(unique_aggr="description")
结果 
┌─────────────────┐
│   description   │
│     varchar     │
├─────────────────┤
│ value is even   │
│ value is uneven │
└─────────────────┘

value_counts

签名 
value_counts(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列中元素的数量，并投影原始列

参数

  • column : str

    用于计算计数的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.value_counts(column="description", groups="description")
结果 
┌─────────────────┬────────────────────┐
│   description   │ count(description) │
│     varchar     │       int64        │
├─────────────────┼────────────────────┤
│ value is uneven │                  5 │
│ value is even   │                  4 │
└─────────────────┴────────────────────┘

var

签名 
var(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的样本方差

别名: variance, var_samp

参数

  • column : str

    用于计算样本方差的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.var(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬───────────────────┐
│   description   │ var_samp("value") │
│     varchar     │      double       │
├─────────────────┼───────────────────┤
│ value is even   │ 6.666666666666667 │
│ value is uneven │              10.0 │
└─────────────────┴───────────────────┘

var_pop

签名 
var_pop(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的总体方差

参数

  • column : str

    用于计算总体方差的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.var_pop(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬──────────────────┐
│   description   │ var_pop("value") │
│     varchar     │      double      │
├─────────────────┼──────────────────┤
│ value is even   │              5.0 │
│ value is uneven │              8.0 │
└─────────────────┴──────────────────┘

var_samp

签名 
var_samp(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的样本方差

别名: variance, var

参数

  • column : str

    用于计算样本方差的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.var_samp(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬───────────────────┐
│   description   │ var_samp("value") │
│     varchar     │      double       │
├─────────────────┼───────────────────┤
│ value is even   │ 6.666666666666667 │
│ value is uneven │              10.0 │
└─────────────────┴───────────────────┘

variance

签名 
variance(self: _duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') -> _duckdb.DuckDBPyRelation
描述

计算给定列的样本方差

别名: var, var_samp

参数

  • column : str

    用于计算样本方差的列名。

  • groups : str, default: ''

    包含在 group by 中的列逗号分隔列表。

  • window_spec : str, default: ''

    窗口函数的可选窗口规范，提供方式为 over (partition by ... order by ...)

  • projected_columns : str, default: ''

    结果中包含的列名逗号分隔列表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.variance(column="value", groups="description", projected_columns="description")
结果 
┌─────────────────┬───────────────────┐
│   description   │ var_samp("value") │
│     varchar     │      double       │
├─────────────────┼───────────────────┤
│ value is even   │ 6.666666666666667 │
│ value is uneven │              10.0 │
└─────────────────┴───────────────────┘

输出

本节包含触发 SQL 执行并检索数据的函数。

名称 描述
arrow 执行并返回产生所有行的 Arrow Record Batch Reader
close 关闭结果集
create 创建一个名为 table_name 的新表，内容为关系对象的结果
create_view 创建一个名为 view_name 的视图，指向该关系对象
df 执行并以 pandas DataFrame 格式获取所有行
execute 将关系对象转换为结果集
fetch_arrow_reader 执行并返回产生所有行的 Arrow Record Batch Reader
fetch_arrow_table 执行并以 Arrow 表格式获取所有行
fetch_df_chunk 执行并获取数据块
fetch_record_batch 执行并返回产生所有行的 Arrow Record Batch Reader
fetchall 执行并以元组列表格式获取所有行
fetchdf 执行并以 pandas DataFrame 格式获取所有行
fetchmany 执行并以元组列表格式获取下一批行
fetchnumpy 执行并获取所有行，返回一个将每一列映射到 numpy 数组的 Python 字典
fetchone 执行并以元组格式获取单行
pl 执行并以 Polars DataFrame 格式获取所有行
record_batch record_batch(self: object, batch_size: typing.SupportsInt = 1000000) -> object
tf 获取结果，返回 TensorFlow 张量的字典
to_arrow_table 执行并以 Arrow 表格式获取所有行
to_csv 将关系对象写入 'file_name' 的 CSV 文件
to_df 执行并以 pandas DataFrame 格式获取所有行
to_parquet 将关系对象写入 'file_name' 的 Parquet 文件
to_table 创建一个名为 table_name 的新表，内容为关系对象的结果
to_view 创建一个名为 view_name 的视图，指向该关系对象
torch 获取结果，返回 PyTorch 张量的字典
write_csv 将关系对象写入 'file_name' 的 CSV 文件
write_parquet 将关系对象写入 'file_name' 的 Parquet 文件

arrow

签名 
arrow(self: _duckdb.DuckDBPyRelation, batch_size: typing.SupportsInt = 1000000) -> pyarrow.lib.RecordBatchReader
描述

执行并返回产生所有行的 Arrow Record Batch Reader

别名: fetch_arrow_table, to_arrow_table

参数

  • batch_size : int, default: 1000000

    将数据写入 Arrow 表的批大小

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

pa_table = rel.arrow()

pa_table
结果 
pyarrow.Table
id: string
description: string
value: int64
created_timestamp: timestamp[us, tz=Europe/Amsterdam]
----
id: [["3ac9e0ba-8390-4a02-ad72-33b1caea6354","8b844392-1404-4bbc-b731-120f42c8ca27","ca5584ca-8e97-4fca-a295-ae3c16c32f5b","926d071e-5f64-488f-ae02-d19e315f9f5c","aabeedf0-5783-4eff-9963-b3967a6ea5d8","1f20db9a-bee8-4b65-b7e8-e7c36b5b8fee","795c678e-3524-4b52-96ec-7b48c24eeab1","9ffbd403-169f-4fe4-bc41-09751066f1f1","8fdb0a60-29f0-4f5b-afcc-c736a03cd083"]]
description: [["value is uneven","value is even","value is uneven","value is even","value is uneven","value is even","value is uneven","value is even","value is uneven"]]
value: [[1,2,3,4,5,6,7,8,9]]
created_timestamp: [[2025-04-10 09:07:12.614000Z,2025-04-10 09:08:12.614000Z,2025-04-10 09:09:12.614000Z,2025-04-10 09:10:12.614000Z,2025-04-10 09:11:12.614000Z,2025-04-10 09:12:12.614000Z,2025-04-10 09:13:12.614000Z,2025-04-10 09:14:12.614000Z,2025-04-10 09:15:12.614000Z]]

close

签名 
close(self: _duckdb.DuckDBPyRelation) -> None
描述

关闭结果集

create

签名 
create(self: _duckdb.DuckDBPyRelation, table_name: str) -> None
描述

创建一个名为 table_name 的新表，内容为关系对象的结果

别名: to_table

参数

  • table_name : str

    要创建的表名。不应存在同名表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.create("table_code_example")

duckdb_conn.table("table_code_example").limit(1)
结果 
┌──────────────────────────────────────┬─────────────────┬───────┬────────────────────────────┐
│                  id                  │   description   │ value │     created_timestamp      │
│                 uuid                 │     varchar     │ int64 │  timestamp with time zone  │
├──────────────────────────────────────┼─────────────────┼───────┼────────────────────────────┤
│ 3ac9e0ba-8390-4a02-ad72-33b1caea6354 │ value is uneven │     1 │ 2025-04-10 11:07:12.614+02 │
└──────────────────────────────────────┴─────────────────┴───────┴────────────────────────────┘

create_view

签名 
create_view(self: _duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) -> _duckdb.DuckDBPyRelation
描述

创建一个名为 view_name 的视图，指向该关系对象

别名: to_view

参数

  • view_name : str

    要创建的视图名称。

  • replace : bool, default: True

    是否使用 CREATE OR REPLACE 创建视图。当设为 False 时，不应存在其他同名视图。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.create_view("view_code_example", replace=True)

duckdb_conn.table("view_code_example").limit(1)
结果 
┌──────────────────────────────────────┬─────────────────┬───────┬────────────────────────────┐
│                  id                  │   description   │ value │     created_timestamp      │
│                 uuid                 │     varchar     │ int64 │  timestamp with time zone  │
├──────────────────────────────────────┼─────────────────┼───────┼────────────────────────────┤
│ 3ac9e0ba-8390-4a02-ad72-33b1caea6354 │ value is uneven │     1 │ 2025-04-10 11:07:12.614+02 │
└──────────────────────────────────────┴─────────────────┴───────┴────────────────────────────┘

df

签名 
df(self: _duckdb.DuckDBPyRelation, *, date_as_object: bool = False) -> pandas.DataFrame
描述

执行并以 pandas DataFrame 格式获取所有行

别名: fetchdf, to_df

参数

  • date_as_object : bool, default: False

    日期列是否应解释为 Python 日期对象。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.df()
结果 
                                     id      description  value                created_timestamp
0  3ac9e0ba-8390-4a02-ad72-33b1caea6354  value is uneven      1 2025-04-10 11:07:12.614000+02:00
1  8b844392-1404-4bbc-b731-120f42c8ca27    value is even      2 2025-04-10 11:08:12.614000+02:00
2  ca5584ca-8e97-4fca-a295-ae3c16c32f5b  value is uneven      3 2025-04-10 11:09:12.614000+02:00
...

execute

签名 
execute(self: _duckdb.DuckDBPyRelation) -> _duckdb.DuckDBPyRelation
描述

将关系对象转换为结果集

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.execute()
结果 
┌──────────────────────────────────────┬─────────────────┬───────┬────────────────────────────┐
│                  id                  │   description   │ value │     created_timestamp      │
│                 uuid                 │     varchar     │ int64 │  timestamp with time zone  │
├──────────────────────────────────────┼─────────────────┼───────┼────────────────────────────┤
│ 3ac9e0ba-8390-4a02-ad72-33b1caea6354 │ value is uneven │     1 │ 2025-04-10 11:07:12.614+02 │
│ 8b844392-1404-4bbc-b731-120f42c8ca27 │ value is even   │     2 │ 2025-04-10 11:08:12.614+02 │
│ ca5584ca-8e97-4fca-a295-ae3c16c32f5b │ value is uneven │     3 │ 2025-04-10 11:09:12.614+02 │

fetch_arrow_reader

签名 
fetch_arrow_reader(self: _duckdb.DuckDBPyRelation, batch_size: typing.SupportsInt = 1000000) -> pyarrow.lib.RecordBatchReader
描述

执行并返回产生所有行的 Arrow Record Batch Reader

参数

  • batch_size : int, default: 1000000

    获取数据的批大小。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

pa_reader = rel.fetch_arrow_reader(batch_size=1)

pa_reader.read_next_batch()
结果 
pyarrow.RecordBatch
id: string
description: string
value: int64
created_timestamp: timestamp[us, tz=Europe/Amsterdam]
----
id: ["e4ab8cb4-4609-40cb-ad7e-4304ed5ed4bd"]
description: ["value is even"]
value: [2]
created_timestamp: [2025-04-10 09:25:51.259000Z]

fetch_arrow_table

签名 
fetch_arrow_table(self: _duckdb.DuckDBPyRelation, batch_size: typing.SupportsInt = 1000000) -> pyarrow.lib.Table
描述

执行并以 Arrow 表格式获取所有行

别名: arrow, to_arrow_table

参数

  • batch_size : int, default: 1000000

    获取数据的批大小。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.fetch_arrow_table()
结果 
pyarrow.Table
id: string
description: string
value: int64
created_timestamp: timestamp[us, tz=Europe/Amsterdam]
----
id: [["1587b4b0-3023-49fe-82cf-06303ca136ac","e4ab8cb4-4609-40cb-ad7e-4304ed5ed4bd","3f8ad67a-290f-4a22-b41b-0173b8e45afa","9a4e37ef-d8bd-46dd-ab01-51cf4973549f","12baa624-ebc9-45ae-b73e-6f4029e31d2d","56d41292-53cc-48be-a1b8-e1f5d6ca5581","1accca18-c950-47c1-9108-aef8afbd5249","56d8db75-72c4-4d40-90d2-a3c840579c37","e19f6201-8646-401c-b019-e37c42c39632"]]
description: [["value is uneven","value is even","value is uneven","value is even","value is uneven","value is even","value is uneven","value is even","value is uneven"]]
value: [[1,2,3,4,5,6,7,8,9]]
created_timestamp: [[2025-04-10 09:24:51.259000Z,2025-04-10 09:25:51.259000Z,2025-04-10 09:26:51.259000Z,2025-04-10 09:27:51.259000Z,2025-04-10 09:28:51.259000Z,2025-04-10 09:29:51.259000Z,2025-04-10 09:30:51.259000Z,2025-04-10 09:31:51.259000Z,2025-04-10 09:32:51.259000Z]]

fetch_df_chunk

签名 
fetch_df_chunk(self: _duckdb.DuckDBPyRelation, vectors_per_chunk: typing.SupportsInt = 1, *, date_as_object: bool = False) -> pandas.DataFrame
描述

执行并获取数据块

参数

  • vectors_per_chunk : int, default: 1

    转换为数据框之前要处理的数据块数量。

  • date_as_object : bool, default: False

    日期列是否应解释为 Python 日期对象。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.fetch_df_chunk()
结果 
                                     id      description  value                created_timestamp
0  1587b4b0-3023-49fe-82cf-06303ca136ac  value is uneven      1 2025-04-10 11:24:51.259000+02:00
1  e4ab8cb4-4609-40cb-ad7e-4304ed5ed4bd    value is even      2 2025-04-10 11:25:51.259000+02:00
2  3f8ad67a-290f-4a22-b41b-0173b8e45afa  value is uneven      3 2025-04-10 11:26:51.259000+02:00
...

fetch_record_batch

签名 
fetch_record_batch(self: _duckdb.DuckDBPyRelation, rows_per_batch: typing.SupportsInt = 1000000) -> pyarrow.lib.RecordBatchReader
描述

执行并返回产生所有行的 Arrow Record Batch Reader

弃用提示：fetch_record_batch() 自 1.4.0 版本起已被弃用。请改用 record_batch()。

别名: record_batch

参数

  • rows_per_batch : int, default: 1000000

    每批的行数。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

pa_reader = rel.fetch_record_batch(rows_per_batch=1)

pa_reader.read_next_batch()
结果 
pyarrow.RecordBatch
id: string
description: string
value: int64
created_timestamp: timestamp[us, tz=Europe/Amsterdam]
----
id: ["908cf67c-a086-4b94-9017-2089a83e4a6c"]
description: ["value is uneven"]
value: [1]
created_timestamp: [2025-04-10 09:52:55.249000Z]

fetchall

签名 
fetchall(self: _duckdb.DuckDBPyRelation) -> list
描述

执行并以元组列表格式获取所有行

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.limit(1).fetchall()
结果 
[(UUID('1587b4b0-3023-49fe-82cf-06303ca136ac'),
  'value is uneven',
  1,
  datetime.datetime(2025, 4, 10, 11, 24, 51, 259000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]

fetchdf

签名 
fetchdf(self: _duckdb.DuckDBPyRelation, *, date_as_object: bool = False) -> pandas.DataFrame
描述

执行并以 pandas DataFrame 格式获取所有行

别名: df, to_df

参数

  • date_as_object : bool, default: False

    日期列是否应解释为 Python 日期对象。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.fetchdf()
结果 
                                     id      description  value                created_timestamp
0  1587b4b0-3023-49fe-82cf-06303ca136ac  value is uneven      1 2025-04-10 11:24:51.259000+02:00
1  e4ab8cb4-4609-40cb-ad7e-4304ed5ed4bd    value is even      2 2025-04-10 11:25:51.259000+02:00
2  3f8ad67a-290f-4a22-b41b-0173b8e45afa  value is uneven      3 2025-04-10 11:26:51.259000+02:00
...

fetchmany

签名 
fetchmany(self: _duckdb.DuckDBPyRelation, size: typing.SupportsInt = 1) -> list
描述

执行并以元组列表格式获取下一批行

警告：在从 聚合 关系检索数据期间执行任何操作都将关闭结果集。 

import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
      select 
          gen_random_uuid() as id, 
          concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
          range as value, 
          now() + concat(range,' ', 'minutes')::interval as created_timestamp
      from range(1, 10)
   """
)

agg_rel = rel.aggregate("value")

while res := agg_rel.fetchmany(size=1):
   print(res)
   rel.show()
参数

  • size : int, default: 1

    要获取的记录数。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

while res := rel.fetchmany(size=1):
    print(res)
结果 
[(UUID('cf4c5e32-d0aa-4699-a3ee-0092e900f263'), 'value is uneven', 1, datetime.datetime(2025, 4, 30, 16, 23, 5, 310000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]
[(UUID('cec335ac-24ac-49a3-ae9a-bb35f71fc88d'), 'value is even', 2, datetime.datetime(2025, 4, 30, 16, 24, 5, 310000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]
[(UUID('2423295d-9bb0-453c-a385-21bdacba03b6'), 'value is uneven', 3, datetime.datetime(2025, 4, 30, 16, 25, 5, 310000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]
[(UUID('88806b21-192d-41e7-a293-c789aad636ba'), 'value is even', 4, datetime.datetime(2025, 4, 30, 16, 26, 5, 310000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]
[(UUID('05837a28-dacf-4121-88a6-a374aefb8a07'), 'value is uneven', 5, datetime.datetime(2025, 4, 30, 16, 27, 5, 310000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]
[(UUID('b9c1f7e9-6156-4554-b80e-67d3b5d810bb'), 'value is even', 6, datetime.datetime(2025, 4, 30, 16, 28, 5, 310000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]
[(UUID('4709c7fa-d286-4864-bb48-69748b447157'), 'value is uneven', 7, datetime.datetime(2025, 4, 30, 16, 29, 5, 310000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]
[(UUID('30e48457-b103-4fa5-95cf-1c7f0143335b'), 'value is even', 8, datetime.datetime(2025, 4, 30, 16, 30, 5, 310000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]
[(UUID('036b7f4b-bd78-4ffb-a351-964d93f267b7'), 'value is uneven', 9, datetime.datetime(2025, 4, 30, 16, 31, 5, 310000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))]

fetchnumpy

签名 
fetchnumpy(self: _duckdb.DuckDBPyRelation) -> dict
描述

执行并获取所有行，返回一个将每一列映射到 numpy 数组的 Python 字典

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.fetchnumpy()
结果 
{'id': array([UUID('1587b4b0-3023-49fe-82cf-06303ca136ac'),
        UUID('e4ab8cb4-4609-40cb-ad7e-4304ed5ed4bd'),
        UUID('3f8ad67a-290f-4a22-b41b-0173b8e45afa'),
        UUID('9a4e37ef-d8bd-46dd-ab01-51cf4973549f'),
        UUID('12baa624-ebc9-45ae-b73e-6f4029e31d2d'),
        UUID('56d41292-53cc-48be-a1b8-e1f5d6ca5581'),
        UUID('1accca18-c950-47c1-9108-aef8afbd5249'),
        UUID('56d8db75-72c4-4d40-90d2-a3c840579c37'),
        UUID('e19f6201-8646-401c-b019-e37c42c39632')], dtype=object),
 'description': array(['value is uneven', 'value is even', 'value is uneven',
        'value is even', 'value is uneven', 'value is even',
        'value is uneven', 'value is even', 'value is uneven'],
       dtype=object),
 'value': array([1, 2, 3, 4, 5, 6, 7, 8, 9]),
 'created_timestamp': array(['2025-04-10T09:24:51.259000', '2025-04-10T09:25:51.259000',
        '2025-04-10T09:26:51.259000', '2025-04-10T09:27:51.259000',
        '2025-04-10T09:28:51.259000', '2025-04-10T09:29:51.259000',
        '2025-04-10T09:30:51.259000', '2025-04-10T09:31:51.259000',
        '2025-04-10T09:32:51.259000'], dtype='datetime64[us]')}

fetchone

签名 
fetchone(self: _duckdb.DuckDBPyRelation) -> typing.Optional[tuple]
描述

执行并以元组格式获取单行

警告：在从 聚合 关系检索数据期间执行任何操作都将关闭结果集。 

import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
      select 
          gen_random_uuid() as id, 
          concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
          range as value, 
          now() + concat(range,' ', 'minutes')::interval as created_timestamp
      from range(1, 10)
   """
)

agg_rel = rel.aggregate("value")

while res := agg_rel.fetchone():
   print(res)
   rel.show()
示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

while res := rel.fetchone():
    print(res)
结果 
(UUID('fe036411-f4c7-4f52-9ddd-80cd2bb56613'), 'value is uneven', 1, datetime.datetime(2025, 4, 30, 12, 59, 8, 912000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))
(UUID('466c9b43-e9f0-4237-8f26-155f259a5b59'), 'value is even', 2, datetime.datetime(2025, 4, 30, 13, 0, 8, 912000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))
(UUID('5755cf16-a94f-41ef-a16d-21e856d71f9f'), 'value is uneven', 3, datetime.datetime(2025, 4, 30, 13, 1, 8, 912000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))
(UUID('05b52c93-bd68-45e1-b02a-a08d682c33d5'), 'value is even', 4, datetime.datetime(2025, 4, 30, 13, 2, 8, 912000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))
(UUID('cf61ef13-2840-4541-900d-f493767d7622'), 'value is uneven', 5, datetime.datetime(2025, 4, 30, 13, 3, 8, 912000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))
(UUID('033e7c68-e800-4ee8-9787-6cf50aabc27b'), 'value is even', 6, datetime.datetime(2025, 4, 30, 13, 4, 8, 912000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))
(UUID('8b8d6545-ff54-45d6-b69a-97edb63dfe43'), 'value is uneven', 7, datetime.datetime(2025, 4, 30, 13, 5, 8, 912000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))
(UUID('7da79dfe-b29c-462b-a414-9d5e3cc80139'), 'value is even', 8, datetime.datetime(2025, 4, 30, 13, 6, 8, 912000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))
(UUID('f83ffff2-33b9-4f86-9d14-46974b546bab'), 'value is uneven', 9, datetime.datetime(2025, 4, 30, 13, 7, 8, 912000, tzinfo=<DstTzInfo 'Europe/Amsterdam' CEST+2:00:00 DST>))

pl

签名 
pl(self: _duckdb.DuckDBPyRelation, batch_size: typing.SupportsInt = 1000000, *, lazy: bool = False) -> duckdb::PolarsDataFrame
描述

执行并以 Polars DataFrame 格式获取所有行

参数

  • batch_size : int, default: 1000000

    每批获取的记录数。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.pl(batch_size=1)
结果 
shape: (9, 4)
┌─────────────────────────────────┬─────────────────┬───────┬────────────────────────────────┐
│ id                              ┆ description     ┆ value ┆ created_timestamp              │
│ ---                             ┆ ---             ┆ ---   ┆ ---                            │
│ str                             ┆ str             ┆ i64   ┆ datetime[μs, Europe/Amsterdam] │
╞═════════════════════════════════╪═════════════════╪═══════╪════════════════════════════════╡
│ b2f92c3c-9372-49f3-897f-2c86fc… ┆ value is uneven ┆ 1     ┆ 2025-04-10 11:49:51.886 CEST   │

record_batch

描述

record_batch(self: object, batch_size: typing.SupportsInt = 1000000) -> object

参数

  • batch_size : int, default: 1000000

    获取数据的批大小。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

pa_batch = rel.record_batch(batch_size=1)

pa_batch.read_next_batch()
结果 
pyarrow.RecordBatch
id: string
description: string
value: int64
created_timestamp: timestamp[us, tz=Europe/Amsterdam]
----
id: ["908cf67c-a086-4b94-9017-2089a83e4a6c"]
description: ["value is uneven"]
value: [1]
created_timestamp: [2025-04-10 09:52:55.249000Z]

tf

签名 
tf(self: _duckdb.DuckDBPyRelation) -> dict
描述

获取结果，返回 TensorFlow 张量的字典

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.select("description, value").tf()
结果 
{'description': <tf.Tensor: shape=(9,), dtype=string, numpy=
 array([b'value is uneven', b'value is even', b'value is uneven',
        b'value is even', b'value is uneven', b'value is even',
        b'value is uneven', b'value is even', b'value is uneven'],
       dtype=object)>,
 'value': <tf.Tensor: shape=(9,), dtype=int64, numpy=array([1, 2, 3, 4, 5, 6, 7, 8, 9])>}

to_arrow_table

签名 
to_arrow_table(self: _duckdb.DuckDBPyRelation, batch_size: typing.SupportsInt = 1000000) -> pyarrow.lib.Table
描述

执行并以 Arrow 表格式获取所有行

别名: fetch_arrow_table, arrow

参数

  • batch_size : int, default: 1000000

    获取数据的批大小。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.to_arrow_table()
结果 
pyarrow.Table
id: string
description: string
value: int64
created_timestamp: timestamp[us, tz=Europe/Amsterdam]
----
id: [["86b2011d-3818-426f-a41e-7cd5c7321f79","07fa4f89-0bba-4049-9acd-c933332a66d5","f2f1479e-f582-4fe4-b82f-9b753b69634c","529d3c63-5961-4adb-b0a8-8249188fc82a","aa9eea7d-7fac-4dcf-8f32-4a0b5d64f864","4852aa32-03f2-40d3-8006-b8213904775a","c0127203-f2e3-4925-9810-655bc02a3c19","2a1356ba-5707-44d6-a492-abd0a67e5efb","800a1c24-231c-4dae-bd68-627654c8a110"]]
description: [["value is uneven","value is even","value is uneven","value is even","value is uneven","value is even","value is uneven","value is even","value is uneven"]]
value: [[1,2,3,4,5,6,7,8,9]]
created_timestamp: [[2025-04-10 09:54:24.015000Z,2025-04-10 09:55:24.015000Z,2025-04-10 09:56:24.015000Z,2025-04-10 09:57:24.015000Z,2025-04-10 09:58:24.015000Z,2025-04-10 09:59:24.015000Z,2025-04-10 10:00:24.015000Z,2025-04-10 10:01:24.015000Z,2025-04-10 10:02:24.015000Z]]

to_csv

签名 
to_csv(self: _duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None, overwrite: object = None, per_thread_output: object = None, use_tmp_file: object = None, partition_by: object = None, write_partition_columns: object = None) -> None
描述

将关系对象写入 'file_name' 的 CSV 文件

别名: write_csv

参数

  • file_name : str

    输出 CSV 文件的名称。

  • sep : str, default: ','

    输出文件的字段分隔符。

  • na_rep : str, default: ''

    缺失数据的表示形式。

  • header : bool, default: True

    是否写入列标题。

  • quotechar : str, default: '"'

    用于引用包含特殊字符的字段的字符。

  • escapechar : str, default: None

    如果引用设置为 QUOTE_NONE，则用于转义分隔符的字符。

  • date_format : str, default: None

    DATE 值的自定义格式字符串。

  • timestamp_format : str, default: None

    TIMESTAMP 值的自定义格式字符串。

  • quoting : int, default: csv.QUOTE_MINIMAL

    控制字段引用行为（例如 QUOTE_MINIMAL, QUOTE_ALL）。

  • encoding : str, default: 'utf-8'

    输出文件的字符编码。

  • compression : str, default: auto

    压缩类型（例如 'gzip', 'bz2', 'zstd'）。

  • overwrite : bool, default: False

    为 True 时，目标目录内的所有现有文件将被删除（远程文件系统不支持）。仅在与 partition_by 一起使用时有效。

  • per_thread_output : bool, default: False

    为 true 时，按线程写入文件，而不是总共写一个文件。这允许更快的并行写入。

  • use_tmp_file : bool, default: False

    在重命名为最终名称之前写入临时文件，以避免部分写入。

  • partition_by : list[str], default: None

    用于对输出进行分区的列名列表（创建文件夹结构）。

  • write_partition_columns : bool, default: False

    是否将分区列写入文件。仅在与 partition_by 一起使用时有效。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.to_csv("code_example.csv")
结果 
The data is exported to a CSV file, named code_example.csv

to_df

签名 
to_df(self: _duckdb.DuckDBPyRelation, *, date_as_object: bool = False) -> pandas.DataFrame
描述

执行并以 pandas DataFrame 格式获取所有行

别名: fetchdf, df

参数

  • date_as_object : bool, default: False

    日期列是否应解释为 Python 日期对象。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.to_df()
结果 
                                     id      description  value                created_timestamp
0  e1f79925-60fd-4ee2-ae67-5eff6b0543d1  value is uneven      1 2025-04-10 11:56:04.452000+02:00
1  caa619d4-d79c-4c00-b82e-9319b086b6f8    value is even      2 2025-04-10 11:57:04.452000+02:00
2  64c68032-99b9-4e8f-b4a3-6c522d5419b3  value is uneven      3 2025-04-10 11:58:04.452000+02:00
...

to_parquet

签名 
to_parquet(self: _duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None, field_ids: object = None, row_group_size_bytes: object = None, row_group_size: object = None, overwrite: object = None, per_thread_output: object = None, use_tmp_file: object = None, partition_by: object = None, write_partition_columns: object = None, append: object = None, filename_pattern: object = None, file_size_bytes: object = None) -> None
描述

将关系对象写入 'file_name' 的 Parquet 文件

别名: write_parquet

参数

  • file_name : str

    输出 Parquet 文件的名称。

  • compression : str, default: 'snappy'

    使用的压缩格式 (uncompressed, snappy, gzip, zstd, brotli, lz4, lz4_raw)。

  • field_ids : STRUCT

    每列的 field_id。传递 auto 以尝试自动推断。

  • row_group_size_bytes : int, default: row_group_size * 1024

    每个行组的目标大小。可以传递人类可读的字符串（例如 2MB）或整数（字节数）。此选项仅在发出 SET preserve_insertion_order = false; 时使用，否则将被忽略。

  • row_group_size : int, default: 122880

    每个行组的目标大小，即行数。

  • overwrite : bool, default: False

    若为 True，则在文件存在时覆盖文件。

  • per_thread_output : bool, default: False

    当 True 时，按线程写入文件，而不是总共写一个文件。这允许更快的并行写入。

  • use_tmp_file : bool, default: False

    在重命名为最终名称之前写入临时文件，以避免部分写入。

  • partition_by : list[str], default: None

    用于对输出进行分区的列名列表（创建文件夹结构）。

  • write_partition_columns : bool, default: False

    是否将分区列写入文件。仅在与 partition_by 一起使用时有效。

  • append : bool, default: False

    若为 True，在生成的现有文件名模式的情况下，路径将重新生成以确保不覆盖现有文件。仅在与 partition_by 一起使用时有效。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.to_parquet("code_example.parquet")
结果 
The data is exported to a Parquet file, named code_example.parquet

to_table

签名 
to_table(self: _duckdb.DuckDBPyRelation, table_name: str) -> None
描述

创建一个名为 table_name 的新表，内容为关系对象的结果

别名: create

参数

  • table_name : str

    要创建的表名。不应存在同名表。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.to_table("table_code_example")
结果 
A table, named table_code_example, is created with the data of the relation

to_view

签名 
to_view(self: _duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) -> _duckdb.DuckDBPyRelation
描述

创建一个名为 view_name 的视图，指向该关系对象

别名: create_view

参数

  • view_name : str

    要创建的视图名称。

  • replace : bool, default: True

    是否使用 CREATE OR REPLACE 创建视图。当设为 False 时，不应存在其他同名视图。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.to_view("view_code_example", replace=True)
结果 
A view, named view_code_example, is created with the query definition of the relation

torch

签名 
torch(self: _duckdb.DuckDBPyRelation) -> dict
描述

获取结果，返回 PyTorch 张量的字典

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.select("value").torch()
结果 
{'value': tensor([1, 2, 3, 4, 5, 6, 7, 8, 9])}

write_csv

签名 
write_csv(self: _duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None, overwrite: object = None, per_thread_output: object = None, use_tmp_file: object = None, partition_by: object = None, write_partition_columns: object = None) -> None
描述

将关系对象写入 'file_name' 的 CSV 文件

别名: to_csv

参数

  • file_name : str

    输出 CSV 文件的名称。

  • sep : str, default: ','

    输出文件的字段分隔符。

  • na_rep : str, default: ''

    缺失数据的表示形式。

  • header : bool, default: True

    是否写入列标题。

  • quotechar : str, default: '"'

    用于引用包含特殊字符的字段的字符。

  • escapechar : str, default: None

    如果引用设置为 QUOTE_NONE，则用于转义分隔符的字符。

  • date_format : str, default: None

    DATE 值的自定义格式字符串。

  • timestamp_format : str, default: None

    TIMESTAMP 值的自定义格式字符串。

  • quoting : int, default: csv.QUOTE_MINIMAL

    控制字段引用行为（例如 QUOTE_MINIMAL, QUOTE_ALL）。

  • encoding : str, default: 'utf-8'

    输出文件的字符编码。

  • compression : str, default: auto

    压缩类型（例如 'gzip', 'bz2', 'zstd'）。

  • overwrite : bool, default: False

    为 True 时，目标目录内的所有现有文件将被删除（远程文件系统不支持）。仅在与 partition_by 一起使用时有效。

  • per_thread_output : bool, default: False

    为 true 时，按线程写入文件，而不是总共写一个文件。这允许更快的并行写入。

  • use_tmp_file : bool, default: False

    在重命名为最终名称之前写入临时文件，以避免部分写入。

  • partition_by : list[str], default: None

    用于对输出进行分区的列名列表（创建文件夹结构）。

  • write_partition_columns : bool, default: False

    是否将分区列写入文件。仅在与 partition_by 一起使用时有效。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.write_csv("code_example.csv")
结果 
The data is exported to a CSV file, named code_example.csv

write_parquet

签名 
write_parquet(self: _duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None, field_ids: object = None, row_group_size_bytes: object = None, row_group_size: object = None, overwrite: object = None, per_thread_output: object = None, use_tmp_file: object = None, partition_by: object = None, write_partition_columns: object = None, append: object = None, filename_pattern: object = None, file_size_bytes: object = None) -> None
描述

将关系对象写入 'file_name' 的 Parquet 文件

别名: to_parquet

参数

  • file_name : str

    输出 Parquet 文件的名称。

  • compression : str, default: 'snappy'

    使用的压缩格式 (uncompressed, snappy, gzip, zstd, brotli, lz4, lz4_raw)。

  • field_ids : STRUCT

    每列的 field_id。传递 auto 以尝试自动推断。

  • row_group_size_bytes : int, default: row_group_size * 1024

    每个行组的目标大小。可以传递人类可读的字符串（例如 2MB）或整数（字节数）。此选项仅在发出 SET preserve_insertion_order = false; 时使用，否则将被忽略。

  • row_group_size : int, default: 122880

    每个行组的目标大小，即行数。

  • overwrite : bool, default: False

    若为 True，则在文件存在时覆盖文件。

  • per_thread_output : bool, default: False

    当 True 时，按线程写入文件，而不是总共写一个文件。这允许更快的并行写入。

  • use_tmp_file : bool, default: False

    在重命名为最终名称之前写入临时文件，以避免部分写入。

  • partition_by : list[str], default: None

    用于对输出进行分区的列名列表（创建文件夹结构）。

  • write_partition_columns : bool, default: False

    是否将分区列写入文件。仅在与 partition_by 一起使用时有效。

  • append : bool, default: False

    若为 True，在生成的现有文件名模式的情况下，路径将重新生成以确保不覆盖现有文件。仅在与 partition_by 一起使用时有效。

示例 
import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("""
        select 
            gen_random_uuid() as id, 
            concat('value is ', case when mod(range,2)=0 then 'even' else 'uneven' end) as description,
            range as value, 
            now() + concat(range,' ', 'minutes')::interval as created_timestamp
        from range(1, 10)
    """
)

rel.write_parquet("code_example.parquet")
结果 
The data is exported to a Parquet file, named code_example.parquet
© 2025 DuckDB 基金会，阿姆斯特丹，荷兰