Expression-API

Die Klasse Expression steht für eine Instanz eines Ausdrucks.

Warum sollte ich die Expression-API verwenden?

Mit dieser API können Ausdrücke dynamisch aufgebaut werden, die normalerweise vom Parser aus dem Abfragestring erzeugt werden. Dadurch können Sie diesen Schritt überspringen und die verwendeten Ausdrücke feiner steuern.

Im Folgenden finden Sie eine Liste der derzeit unterstützten Ausdrücke, die über die API erstellt werden können.

Spaltenausdruck

Dieser Ausdruck referenziert eine Spalte anhand ihres Namens.

import duckdb
import pandas as pd

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

Eine einzelne Spalte auswählen:

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

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

Mehrere Spalten auswählen:

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

Stern-Ausdruck

Dieser Ausdruck wählt alle Spalten der Eingabequelle aus.

Optional können Sie eine exclude-Liste angeben, um Spalten der Tabelle herauszufiltern. Diese exclude-Liste kann entweder Zeichenketten oder Expressions enthalten.

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

Konstantenausdruck

Dieser Ausdruck enthält einen einzelnen Wert.

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-Ausdruck

Dieser Ausdruck enthält einen Ausdruck CASE WHEN (...) THEN (...) ELSE (...) END. Standardmäßig ist ELSE NULL und kann mit .else(value = ...) gesetzt werden. Weitere Blöcke WHEN (...) THEN (...) können mit .when(condition = ..., value = ...) hinzugefügt werden.

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

Funktionsausdruck

Dieser Ausdruck enthält einen Funktionsaufruf. Er wird durch Angabe des Funktionsnamens und einer beliebigen Anzahl von Expressions als Argumente erzeugt.

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-Ausdruck

Dieser Ausdruck enthält einen beliebigen gültigen SQL-Ausdruck.

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

Gemeinsame Operationen

Die Klasse Expression enthält außerdem viele Operationen, die auf jeden Expression-Typ angewendet werden können.

Operation	Beschreibung
`.alias(name: str)`	Wendet einen Alias auf den Ausdruck an
`.cast(type: DuckDBPyType)`	Wandelt den Ausdruck in den angegebenen Typ um
`.isin(*exprs: Expression)`	Erzeugt einen `IN`-Ausdruck mit den angegebenen Ausdrücken als Liste
`.isnotin(*exprs: Expression)`	Erzeugt einen `NOT IN`-Ausdruck mit den angegebenen Ausdrücken als Liste
`.isnotnull()`	Prüft, ob der Ausdruck nicht `NULL` ist
`.isnull()`	Prüft, ob der Ausdruck `NULL` ist

Sortieroperationen

Wenn Ausdrücke an DuckDBPyRelation.order() übergeben werden, können die folgenden Sortieroperationen angewendet werden.

Operation	Beschreibung
`.asc()`	Gibt an, dass dieser Ausdruck aufsteigend sortiert werden soll
`.desc()`	Gibt an, dass dieser Ausdruck absteigend sortiert werden soll
`.nulls_first()`	Gibt an, dass die Nullwerte in diesem Ausdruck den Nicht-Nullwerten vorausgehen sollen
`.nulls_last()`	Gibt an, dass die Nullwerte in diesem Ausdruck nach den Nicht-Nullwerten stehen sollen