表达式 API – DuckDB - DuckDB 数据库

搜索快捷键 cmd + k | ctrl + k

文档 / 客户端API / Python

表达式 API

Expression 类代表一个表达式的实例。

为什么要使用表达式 API？

使用此 API 可以动态构建表达式，这些表达式通常是由解析器从查询字符串中创建的。通过这种方式，您可以跳过解析过程，并对所使用的表达式进行更细粒度的控制。

以下是目前可以通过该 API 创建并支持的表达式列表。

列表达式 (Column Expression)

此表达式通过名称引用一列。

import duckdb
import pandas as pd

df = pd.DataFrame({
    'a': [1, 2, 3, 4],
    'b': [True, None, False, True],
    'c': [42, 21, 13, 14]
})

选择单列

col = duckdb.ColumnExpression('a')
duckdb.df(df).select(col).show()

┌───────┐
│   a   │
│ int64 │
├───────┤
│     1 │
│     2 │
│     3 │
│     4 │
└───────┘

选择多列

col_list = [
        duckdb.ColumnExpression('a') * 10,
        duckdb.ColumnExpression('b').isnull(),
        duckdb.ColumnExpression('c') + 5
    ]
duckdb.df(df).select(*col_list).show()

┌──────────┬─────────────┬─────────┐
│ (a * 10) │ (b IS NULL) │ (c + 5) │
│  int64   │   boolean   │  int64  │
├──────────┼─────────────┼─────────┤
│       10 │ false       │      47 │
│       20 │ true        │      26 │
│       30 │ false       │      18 │
│       40 │ false       │      19 │
└──────────┴─────────────┴─────────┘

星号表达式

此表达式选择输入源的所有列。

可以选择性地提供一个 exclude 列表来过滤掉表中的某些列。该 exclude 列表可以包含字符串或表达式。

import duckdb
import pandas as pd

df = pd.DataFrame({
    'a': [1, 2, 3, 4],
    'b': [True, None, False, True],
    'c': [42, 21, 13, 14]
})

star = duckdb.StarExpression(exclude = ['b'])
duckdb.df(df).select(star).show()

┌───────┬───────┐
│   a   │   c   │
│ int64 │ int64 │
├───────┼───────┤
│     1 │    42 │
│     2 │    21 │
│     3 │    13 │
│     4 │    14 │
└───────┴───────┘

常量表达式 (Constant Expression)

此表达式包含一个单一值。

import duckdb
import pandas as pd

df = pd.DataFrame({
    'a': [1, 2, 3, 4],
    'b': [True, None, False, True],
    'c': [42, 21, 13, 14]
})

const = duckdb.ConstantExpression('hello')
duckdb.df(df).select(const).show()

┌─────────┐
│ 'hello' │
│ varchar │
├─────────┤
│ hello   │
│ hello   │
│ hello   │
│ hello   │
└─────────┘

Case 表达式 (Case Expression)

此表达式包含一个 CASE WHEN (...) THEN (...) ELSE (...) END 表达式。默认情况下 ELSE 为 NULL，可以通过 .else(value = ...) 进行设置。可以使用 .when(condition = ..., value = ...) 添加额外的 WHEN (...) THEN (...) 代码块。

import duckdb
import pandas as pd
from duckdb import (
    ConstantExpression,
    ColumnExpression,
    CaseExpression
)

df = pd.DataFrame({
    'a': [1, 2, 3, 4],
    'b': [True, None, False, True],
    'c': [42, 21, 13, 14]
})

hello = ConstantExpression('hello')
world = ConstantExpression('world')

case = \
    CaseExpression(condition = ColumnExpression('b') == False, value = world) \
    .otherwise(hello)
duckdb.df(df).select(case).show()

┌──────────────────────────────────────────────────────────┐
│ CASE  WHEN ((b = false)) THEN ('world') ELSE 'hello' END │
│                         varchar                          │
├──────────────────────────────────────────────────────────┤
│ hello                                                    │
│ hello                                                    │
│ world                                                    │
│ hello                                                    │
└──────────────────────────────────────────────────────────┘

函数表达式 (Function Expression)

此表达式包含一个函数调用。它可以通过提供函数名称和任意数量的表达式作为参数来构建。

import duckdb
import pandas as pd
from duckdb import (
    ConstantExpression,
    ColumnExpression,
    FunctionExpression
)

df = pd.DataFrame({
    'a': [1, 2, 3, 4],
    'b': [True, None, False, True],
    'c': [42, 21, 13, 14]
})

multiply_by_2 = FunctionExpression('multiply', ColumnExpression('a'), ConstantExpression(2))
duckdb.df(df).select(multiply_by_2).show()

┌────────────────┐
│ multiply(a, 2) │
│     int64      │
├────────────────┤
│              2 │
│              4 │
│              6 │
│              8 │
└────────────────┘

SQL 表达式 (SQL Expression)

此表达式包含任何有效的 SQL 表达式。

import duckdb
import pandas as pd

from duckdb import SQLExpression

df = pd.DataFrame({
    'a': [1, 2, 3, 4],
    'b': [True, None, False, True],
    'c': [42, 21, 13, 14]
})

duckdb.df(df).filter(
    SQLExpression("b is true")
).select(
    SQLExpression("a").alias("selecting_column_a"),
    SQLExpression("case when a = 1 then 1 else 0 end").alias("selecting_case_expression"),
    SQLExpression("1").alias("constant_numeric_column"),
    SQLExpression("'hello'").alias("constant_text_column")
).aggregate(
    aggr_expr=[
        SQLExpression("SUM(selecting_column_a)").alias("sum_a"), 
        "selecting_case_expression" , 
        "constant_numeric_column", 
        "constant_text_column"
    ],
).show()

┌────────┬───────────────────────────┬─────────────────────────┬──────────────────────┐
│ sum_a  │ selecting_case_expression │ constant_numeric_column │ constant_text_column │
│ int128 │           int32           │          int32          │       varchar        │
├────────┼───────────────────────────┼─────────────────────────┼──────────────────────┤
│      4 │                         0 │                       1 │ hello                │
│      1 │                         1 │                       1 │ hello                │
└────────┴───────────────────────────┴─────────────────────────┴──────────────────────┘

常见操作

Expression 类还包含许多可以应用于任何表达式类型的操作。

操作	描述
`.alias(name: str)`	为表达式应用别名
`.cast(type: DuckDBPyType)`	将表达式转换为提供的类型
`.isin(*exprs: Expression)`	针对提供的表达式列表创建一个 `IN` 表达式
`.isnotin(*exprs: Expression)`	针对提供的表达式列表创建一个 `NOT IN` 表达式
`.isnotnull()`	检查表达式是否不为 `NULL`
`.isnull()`	检查表达式是否为 `NULL`

排序操作

当将表达式提供给 DuckDBPyRelation.order() 时，可以应用以下排序操作。

操作	描述
`.asc()`	指示该表达式应按升序排序
`.desc()`	指示该表达式应按降序排序
`.nulls_first()`	指示该表达式中的空值应排在非空值之前
`.nulls_last()`	指示该表达式中的空值应排在非空值之后

关于此页面

行为准则商标使用指南

关于此页面

本文中