跳到主要内容

Expression API

The Expression class represents an instance of an expression. Expression 类表示一个表达式实例。

为什么要使用 Expression API？​

使用该 API 可以动态构建表达式，而这些表达式通常由解析器从查询字符串中生成。 这样你可以跳过解析步骤，并对所使用的表达式进行更细粒度的控制。

下面列出了当前可通过该 API 创建的表达式类型。

列表达式​

该表达式通过名称引用列。

import goose
import pandas as pd

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

选择单列：

col = goose.ColumnExpression('a')
goose.df(df).select(col).show()
┌───────┐
│   a   │
│ int64 │
├───────┤
│     1 │
│     2 │
│     3 │
│     4 │
└───────┘

选择多列：

col_list = [
        goose.ColumnExpression('a') * 10,
        goose.ColumnExpression('b').isnull(),
        goose.ColumnExpression('c') + 5
    ]
goose.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 列表可以包含字符串或 Expression。

import goose
import pandas as pd

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

star = goose.StarExpression(exclude = ['b'])
goose.df(df).select(star).show()
┌───────┬───────┐
│   a   │   c   │
│ int64 │ int64 │
├───────┼───────┤
│     1 │    42 │
│     2 │    21 │
│     3 │    13 │
│     4 │    14 │
└───────┴───────┘

常量表达式​

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

import goose
import pandas as pd

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

const = goose.ConstantExpression('hello')
goose.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 goose
import pandas as pd
from goose 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)
goose.df(df).select(case).show()
┌──────────────────────────────────────────────────────────┐
│ CASE  WHEN ((b = false)) THEN ('world') ELSE 'hello' END │
│                         varchar                          │
├──────────────────────────────────────────────────────────┤
│ hello                                                    │
│ hello                                                    │
│ world                                                    │
│ hello                                                    │
└──────────────────────────────────────────────────────────┘

函数表达式​

该表达式表示函数调用。 你可以通过提供函数名以及任意数量的 Expression 参数来构建它。

import goose
import pandas as pd
from goose 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))
goose.df(df).select(multiply_by_2).show()
┌────────────────┐
│ multiply(a, 2) │
│     int64      │
├────────────────┤
│              2 │
│              4 │
│              6 │
│              8 │
└────────────────┘

SQL 表达式​

该表达式可包含任意合法的 SQL 表达式。

import goose
import pandas as pd

from goose import SQLExpression

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

goose.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: GoosePyType)将表达式转换为给定类型
.isin(*exprs: Expression)以给定表达式列表创建 IN 表达式
.isnotin(*exprs: Expression)以给定表达式列表创建 NOT IN 表达式
.isnotnull()检查表达式是否不为 NULL
.isnull()检查表达式是否为 NULL

排序操作​

当将表达式传给 GoosePyRelation.order() 时，可使用以下排序操作。

操作说明
.asc()指定该表达式按升序排序
.desc()指定该表达式按降序排序
.nulls_first()指定该表达式中的空值排在非空值之前
.nulls_last()指定该表达式中的空值排在非空值之后