⌘+k ctrl+k
1.3 (稳定版)
搜索快捷键 cmd + k | ctrl + k
表达式 API

Expression 类表示一个 表达式 实例。

为什么要使用表达式 API？

使用此 API 可以动态构建表达式，这些表达式通常由解析器从查询字符串中创建。这使您可以跳过该步骤，并对所使用的表达式拥有更精细的控制。

下面列出了当前支持的、可以通过 API 创建的表达式。

列表达式

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

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 │
└───────┴───────┘

常量表达式

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

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 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                                                    │
└──────────────────────────────────────────────────────────┘

函数表达式

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

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 表达式。

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 类还包含许多可以应用于任何 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() 表示此表达式中的 NULL 值应在非 NULL 值之前
.nulls_last() 表示此表达式中的 NULL 值应在非 NULL 值之后
关于此页面