⌘+k ctrl+k
1.1.3 (stable)
Search Shortcut cmd + k | ctrl + k
Expression API

Expression 类表示一个 expression 的实例。

为什么我会使用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')
res = duckdb.df(df).select(col).fetchall()
print(res)

[(1,), (2,), (3,), (4,)]

选择多列：

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

[(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'])
res = duckdb.df(df).select(star).fetchall()
print(res)

[(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')
res = duckdb.df(df).select(const).fetchall()
print(res)

[('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)
res = duckdb.df(df).select(case).fetchall()
print(res)

[('hello',), ('hello',), ('world',), ('hello',)]

函数表达式

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

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

df = pd.DataFrame({
    'a': [
        'test',
        'pest',
        'text',
        'rest',
    ]
})

ends_with = FunctionExpression('ends_with', ColumnExpression('a'), ConstantExpression('est'))
res = duckdb.df(df).select(ends_with).fetchall()
print(res)

[(True,), (True,), (False,), (True,)]

Common Operations

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() 表示此表达式中的空值应位于非空值之前。
.nulls_last() 表示此表达式中的空值应排在非空值之后。
关于此页面