SQL und generische Funktionen

SQL-Funktionen werden über den func-Namensraum aufgerufen. Weitere Informationen zur Verwendung des func-Objekts zum Rendern von SQL-Funktionen in Anweisungen finden Sie im Tutorial unter Arbeiten mit SQL-Funktionen.

Siehe auch

Arbeiten mit SQL-Funktionen - im SQLAlchemy Unified Tutorial

Funktions-API

Die Basis-API für SQL-Funktionen, die den func-Namensraum sowie Klassen für Erweiterbarkeit bereitstellt.

Objektname	Beschreibung
AnsiFunction	Definiert eine Funktion im „ansi“-Format, die keine Klammern rendert.
Funktion	Beschreibt eine benannte SQL-Funktion.
FunctionElement	Basis für SQL-funktionsorientierte Konstrukte.
GenericFunction	Definiert eine „generische“ Funktion.
register_function(identifier, fn[, package])	Ordnet einen Aufrufbaren einem bestimmten func-Namen zu.

class sqlalchemy.sql.functions.AnsiFunction

Definiert eine Funktion im „ansi“-Format, die keine Klammern rendert.

Klassensignatur

class sqlalchemy.sql.functions.AnsiFunction (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.Function

Beschreibt eine benannte SQL-Funktion.

Das Function-Objekt wird typischerweise aus dem func-Generierungsobjekt erstellt.

Parameter:

• *clauses – Liste von Spaltenausdrücken, die die Argumente des SQL-Funktionsaufrufs bilden.

• type_ – optionales TypeEngine-Datentypobjekt, das als Rückgabewert des Spaltenausdrucks verwendet wird, der durch diesen Funktionsaufruf generiert wird.

• packagenames –

  Ein String, der Paketpräfixnamen angibt, die dem Funktionsnamen vorangestellt werden, wenn SQL generiert wird. Der func-Generator erstellt diese, wenn er im Punktformat aufgerufen wird, z. B.:

  func.mypackage.some_function(col1, col2)

Siehe auch

Arbeiten mit SQL-Funktionen - im SQLAlchemy Unified Tutorial

func - Namensraum, der registrierte oder Ad-hoc Function-Instanzen erzeugt.

GenericFunction - Ermöglicht die Erstellung registrierter Funktionstypen.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.sql.functions.Function (sqlalchemy.sql.functions.FunctionElement)

method sqlalchemy.sql.functions.Function.__init__(name: str, *clauses: _ColumnExpressionOrLiteralArgument[Any], type_: _TypeEngineArgument[_T] | None = None, packagenames: Tuple[str, ...] | None = None)

Konstruiert eine Function.

Der func-Konstrukt wird normalerweise verwendet, um neue Function-Instanzen zu erstellen.

class sqlalchemy.sql.functions.FunctionElement

Basis für SQL-funktionsorientierte Konstrukte.

Dies ist ein generischer Typ, was bedeutet, dass Typüberprüfer und IDEs über die zu erwartenden Typen in einem Result für diese Funktion instruiert werden können. Siehe GenericFunction für ein Beispiel, wie dies geschieht.

Siehe auch

Arbeiten mit SQL-Funktionen - im SQLAlchemy Unified Tutorial

Function - benannte SQL-Funktion.

func - Namensraum, der registrierte oder Ad-hoc Function-Instanzen erzeugt.

GenericFunction - Ermöglicht die Erstellung registrierter Funktionstypen.

Mitglieder

__init__(), alias(), as_comparison(), c, clauses, column_valued(), columns, entity_namespace, exported_columns, filter(), over(), scalar_table_valued(), select(), self_group(), table_valued(), within_group(), within_group_type()

Klassensignatur

class sqlalchemy.sql.functions.FunctionElement (sqlalchemy.sql.expression.Executable, sqlalchemy.sql.expression.ColumnElement, sqlalchemy.sql.expression.FromClause, sqlalchemy.sql.expression.Generative)

method sqlalchemy.sql.functions.FunctionElement.__init__(*clauses: _ColumnExpressionOrLiteralArgument[Any])

Konstruiert ein FunctionElement.

Parameter:

• *clauses – Liste von Spaltenausdrücken, die die Argumente des SQL-Funktionsaufrufs bilden.

• **kwargs – zusätzliche kwargs werden typischerweise von Unterklassen verbraucht.

Siehe auch

func

Funktion

method sqlalchemy.sql.functions.FunctionElement.alias(name: str | None = None, joins_implicitly: bool = False) → TableValuedAlias

Erzeugt eine Alias-Konstruktion für dieses FunctionElement.

Tipp

Die Methode FunctionElement.alias() ist Teil des Mechanismus, mit dem „tabellenwertige“ SQL-Funktionen erstellt werden. Die meisten Anwendungsfälle werden jedoch durch höherrangige Methoden von FunctionElement abgedeckt, einschließlich FunctionElement.table_valued() und FunctionElement.column_valued().

Diese Konstruktion umschließt die Funktion in einem benannten Alias, der für die FROM-Klausel geeignet ist, im Stil, wie er beispielsweise von PostgreSQL akzeptiert wird. Ein Spaltenausdruck wird auch über das spezielle Attribut .column bereitgestellt, mit dem auf die Ausgabe der Funktion als Skalarwert in den Spalten oder der WHERE-Klausel verwiesen werden kann, für ein Backend wie PostgreSQL.

Verwenden Sie für einen vollständigen tabellenwertigen Ausdruck zuerst die Methode FunctionElement.table_valued(), um benannte Spalten festzulegen.

z. B.

>>> from sqlalchemy import func, select, column
>>> data_view = func.unnest([1, 2, 3]).alias("data_view")
>>> print(select(data_view.column))
SELECT data_view
FROM unnest(:unnest_1) AS data_view

Die Methode FunctionElement.column_valued() bietet eine Abkürzung für das obige Muster.

>>> data_view = func.unnest([1, 2, 3]).column_valued("data_view")
>>> print(select(data_view))
SELECT data_view
FROM unnest(:unnest_1) AS data_view

Neu in Version 1.4.0b2: Der Akzessor .column wurde hinzugefügt.

Parameter:

• name – Alias-Name, wird in der FROM-Klausel als AS <name> gerendert.

• joins_implicitly –

  Wenn True, kann die tabellenwertige Funktion in der FROM-Klausel ohne expliziten JOIN zu anderen Tabellen in der SQL-Abfrage verwendet werden, und es wird keine Warnung wegen eines kartesischen Produkts ausgegeben. Kann für SQL-Funktionen wie func.json_each() nützlich sein.

  Neu in Version 1.4.33.

Siehe auch

Tabellenwertige Funktionen - im SQLAlchemy Unified Tutorial

FunctionElement.table_valued()

FunctionElement.scalar_table_valued()

FunctionElement.column_valued()

method sqlalchemy.sql.functions.FunctionElement.as_comparison(left_index: int, right_index: int) → FunctionAsBinary

Interpretiert diesen Ausdruck als booleschen Vergleich zwischen zwei Werten.

Diese Methode wird für einen ORM-Anwendungsfall verwendet, der unter Benutzerdefinierte Operatoren basierend auf SQL-Funktionen beschrieben wird.

Eine hypothetische SQL-Funktion „is_equal()“, die zwei Werte auf Gleichheit vergleicht, würde in der Core-Ausdruckssprache wie folgt geschrieben werden:

expr = func.is_equal("a", "b")

Wenn „is_equal()“ oben „a“ und „b“ auf Gleichheit vergleicht, würde die Methode FunctionElement.as_comparison() aufgerufen werden als:

expr = func.is_equal("a", "b").as_comparison(1, 2)

Wo oben der ganzzahlige Wert „1“ sich auf das erste Argument der Funktion „is_equal()“ und der ganzzahlige Wert „2“ sich auf das zweite bezieht.

Dies würde einen BinaryExpression erstellen, der äquivalent ist zu:

BinaryExpression("a", "b", operator=op.eq)

Auf SQL-Ebene würde dies jedoch immer noch als „is_equal(‚a‘, ‚b‘)“ gerendert werden.

Das ORM muss beim Laden eines verknüpften Objekts oder einer Sammlung in der Lage sein, die „linke“ und „rechte“ Seite der ON-Klausel eines JOIN-Ausdrucks zu manipulieren. Der Zweck dieser Methode ist es, eine SQL-Funktionskonstruktion bereitzustellen, die diese Informationen auch dem ORM liefern kann, wenn sie mit dem Parameter relationship.primaryjoin verwendet wird. Der Rückgabewert ist ein Containment-Objekt namens FunctionAsBinary.

Ein ORM-Beispiel sieht wie folgt aus:

class Venue(Base):
    __tablename__ = "venue"
    id = Column(Integer, primary_key=True)
    name = Column(String)

    descendants = relationship(
        "Venue",
        primaryjoin=func.instr(
            remote(foreign(name)), name + "/"
        ).as_comparison(1, 2)
        == 1,
        viewonly=True,
        order_by=name,
    )

Oben kann die Klasse „Venue“ nachfolgende „Venue“-Objekte laden, indem sie prüft, ob der Name der übergeordneten Venue im Anfang des Namens des nachfolgenden Werts enthalten ist, z. B. „parent1“ würde bis „parent1/child1“ passen, aber nicht zu „parent2/child1“.

Mögliche Anwendungsfälle sind das oben genannte Beispiel für den „materialisierten Pfad“ sowie die Nutzung spezieller SQL-Funktionen wie geometrischer Funktionen zur Erstellung von Join-Bedingungen.

Parameter:

• left_index – der ganzzahlige 1-basierte Index des Funktionsarguments, das als „linke“ Seite des Ausdrucks dient.

• right_index – der ganzzahlige 1-basierte Index des Funktionsarguments, das als „rechte“ Seite des Ausdrucks dient.

Neu in Version 1.3.

Siehe auch

Benutzerdefinierte Operatoren basierend auf SQL-Funktionen - Beispielhafte Verwendung im ORM

attribute sqlalchemy.sql.functions.FunctionElement.c

Synonym für FunctionElement.columns.

attribute sqlalchemy.sql.functions.FunctionElement.clauses

Gibt die zugrunde liegende ClauseList zurück, die die Argumente für dieses FunctionElement enthält.

method sqlalchemy.sql.functions.FunctionElement.column_valued(name: str | None = None, joins_implicitly: bool = False) → TableValuedColumn[_T]

Gibt dieses FunctionElement als Spaltenausdruck zurück, der aus sich selbst als FROM-Klausel auswählt.

Z. B.

>>> from sqlalchemy import select, func
>>> gs = func.generate_series(1, 5, -1).column_valued()
>>> print(select(gs))
SELECT anon_1
FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3) AS anon_1

Dies ist eine Abkürzung für:

gs = func.generate_series(1, 5, -1).alias().column

Parameter:

• name – optionaler Name, der dem generierten Aliasnamen zugewiesen wird. Wenn weggelassen, wird ein eindeutiger, anonymisierender Name verwendet.

• joins_implicitly –

  Wenn True, kann der „Tabellen“-Teil der spaltenwertigen Funktion Mitglied der FROM-Klausel sein, ohne dass ein expliziter JOIN zu anderen Tabellen in der SQL-Abfrage erforderlich ist, und es wird keine Warnung wegen eines kartesischen Produkts ausgegeben. Kann für SQL-Funktionen wie func.json_array_elements() nützlich sein.

  Neu in Version 1.4.46.

Siehe auch

Spaltenwertige Funktionen – Tabellenwertige Funktion als Skalarspalte - im SQLAlchemy Unified Tutorial

Spaltenwertige Funktionen - in der Dokumentation zu PostgreSQL

FunctionElement.table_valued()

attribute sqlalchemy.sql.functions.FunctionElement.columns

Die Menge der von diesem FunctionElement exportierten Spalten.

Dies ist eine Platzhalter-Sammlung, die es der Funktion ermöglicht, in die FROM-Klausel einer Anweisung platziert zu werden.

>>> from sqlalchemy import column, select, func
>>> stmt = select(column("x"), column("y")).select_from(func.myfunction())
>>> print(stmt)
SELECT x, y FROM myfunction()

Die obige Form ist ein Legacy-Feature, das nun durch die voll funktionsfähige Methode FunctionElement.table_valued() abgelöst wurde; siehe diese Methode für Details.

Siehe auch

FunctionElement.table_valued() - Generiert tabellenwertige SQL-Funktionsausdrücke.

attribute sqlalchemy.sql.functions.FunctionElement.entity_namespace

Überschreibt FromClause.entity_namespace, da Funktionen im Allgemeinen Spaltenausdrücke und keine FromClauses sind.

attribute sqlalchemy.sql.functions.FunctionElement.exported_columns

method sqlalchemy.sql.functions.FunctionElement.filter(*criterion: _ColumnExpressionArgument[bool]) → Self | FunctionFilter[_T]

Erzeugt eine FILTER-Klausel für diese Funktion.

Verwendet für Aggregat- und Fensterfunktionen für Datenbank-Backends, die die „FILTER“-Klausel unterstützen.

Der Ausdruck

func.count(1).filter(True)

ist eine Abkürzung für:

from sqlalchemy import funcfilter

funcfilter(func.count(1), True)

Siehe auch

Spezielle Modifikatoren WITHIN GROUP, FILTER - im SQLAlchemy Unified Tutorial

FunctionFilter

funcfilter()

method sqlalchemy.sql.functions.FunctionElement.over(*, partition_by: _ByArgument | None = None, order_by: _ByArgument | None = None, rows: Tuple[int | None, int | None] | None = None, range_: Tuple[int | None, int | None] | None = None) → Over[_T]

Erzeugt eine OVER-Klausel für diese Funktion.

Verwendet für Aggregat- oder sogenannte „Fenster“-Funktionen, für Datenbank-Backends, die Fensterfunktionen unterstützen.

Der Ausdruck

func.row_number().over(order_by="x")

ist eine Abkürzung für:

from sqlalchemy import over

over(func.row_number(), order_by="x")

Siehe over() für eine vollständige Beschreibung.

Siehe auch

over()

Verwendung von Fensterfunktionen - im SQLAlchemy Unified Tutorial

method sqlalchemy.sql.functions.FunctionElement.scalar_table_valued(name: str, type_: _TypeEngineArgument[_T] | None = None) → ScalarFunctionColumn[_T]

Gibt einen Spaltenausdruck zurück, der auf diesem FunctionElement als skalarer tabellenwertiger Ausdruck basiert.

Der zurückgegebene Ausdruck ähnelt dem, der von einer einzelnen Spalte zurückgegeben wird, die von einem FunctionElement.table_valued()-Konstrukt zugegriffen wird, jedoch wird keine FROM-Klausel generiert; die Funktion wird ähnlich wie eine skalare Unterabfrage gerendert.

Z. B.

>>> from sqlalchemy import func, select
>>> fn = func.jsonb_each("{'k', 'v'}").scalar_table_valued("key")
>>> print(select(fn))
SELECT (jsonb_each(:jsonb_each_1)).key

Neu ab Version 1.4.0b2.

Siehe auch

FunctionElement.table_valued()

FunctionElement.alias()

FunctionElement.column_valued()

method sqlalchemy.sql.functions.FunctionElement.select() → Select

Erzeugt ein select() Konstrukt für dieses FunctionElement.

Dies ist eine Abkürzung für:

s = select(function_element)

method sqlalchemy.sql.functions.FunctionElement.self_group(against: OperatorType | None = None) → ClauseElement

Wendet eine "Gruppierung" auf dieses ClauseElement an.

Diese Methode wird von Unterklassen überschrieben, um ein "Gruppierungs"-Konstrukt, d.h. Klammern, zurückzugeben. Insbesondere wird sie von "binären" Ausdrücken verwendet, um eine Gruppierung um sich selbst bereitzustellen, wenn sie in einen größeren Ausdruck eingefügt werden, sowie von select() Konstrukten, wenn sie in die FROM-Klausel eines anderen select() eingefügt werden. (Beachten Sie, dass Unterabfragen normalerweise mit der Methode Select.alias() erstellt werden sollten, da viele Plattformen benannte verschachtelte SELECT-Anweisungen erfordern).

Wenn Ausdrücke zusammengefügt werden, ist die Anwendung von self_group() automatisch - Endbenutzer-Code muss diese Methode niemals direkt verwenden. Beachten Sie, dass die Klauselkonstrukte von SQLAlchemy die Operatorrangfolge berücksichtigen - daher sind Klammern möglicherweise nicht erforderlich, z. B. in einem Ausdruck wie x OR (y AND z) - AND hat Vorrang vor OR.

Die Basis-Methode self_group() von ClauseElement gibt einfach self zurück.

method sqlalchemy.sql.functions.FunctionElement.table_valued(*expr: _ColumnExpressionOrStrLabelArgument[Any], **kw: Any) → TableValuedAlias

Gibt eine TableValuedAlias Darstellung dieses FunctionElement mit hinzugefügten tabellenwertigen Ausdrücken zurück.

z. B.

>>> fn = func.generate_series(1, 5).table_valued(
...     "value", "start", "stop", "step"
... )

>>> print(select(fn))
SELECT anon_1.value, anon_1.start, anon_1.stop, anon_1.step
FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1
>>> print(select(fn.c.value, fn.c.stop).where(fn.c.value > 2))
SELECT anon_1.value, anon_1.stop
FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1
WHERE anon_1.value > :value_1

Ein WITH ORDINALITY-Ausdruck kann durch Übergabe des Schlüsselwortarguments "with_ordinality" generiert werden.

>>> fn = func.generate_series(4, 1, -1).table_valued(
...     "gen", with_ordinality="ordinality"
... )
>>> print(select(fn))
SELECT anon_1.gen, anon_1.ordinality
FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3) WITH ORDINALITY AS anon_1

Parameter:

• *expr – Eine Reihe von String-Spaltennamen, die der `.c`-Sammlung des resultierenden TableValuedAlias Konstrukts als Spalten hinzugefügt werden. column() Objekte mit oder ohne Datentypen können ebenfalls verwendet werden.

• name – optionaler Name, der dem generierten Aliasnamen zugewiesen wird. Wenn weggelassen, wird ein eindeutiger, anonymisierender Name verwendet.

• with_ordinality – String-Name, der, wenn vorhanden, dazu führt, dass die Klausel `WITH ORDINALITY` zum Alias hinzugefügt wird, und der gegebene String-Name als Spalte zur .c-Sammlung des resultierenden TableValuedAlias hinzugefügt wird.

• joins_implicitly –

  Wenn True, kann die tabellenwertige Funktion in der FROM-Klausel ohne expliziten JOIN zu anderen Tabellen in der SQL-Abfrage verwendet werden, und es wird keine Warnung wegen eines kartesischen Produkts ausgegeben. Kann für SQL-Funktionen wie func.json_each() nützlich sein.

  Neu in Version 1.4.33.

Neu ab Version 1.4.0b2.

Siehe auch

Tabellenwertige Funktionen - im SQLAlchemy Unified Tutorial

Tabellenwertige Funktionen - in der PostgreSQL Dokumentation

FunctionElement.scalar_table_valued() - Variante von FunctionElement.table_valued(), die den vollständigen tabellenwertigen Ausdruck als Skalarspaltenausdruck liefert

FunctionElement.column_valued()

TableValuedAlias.render_derived() - rendert den Alias unter Verwendung einer abgeleiteten Spaltenklausel, z. B. AS name(col1, col2, ...)

method sqlalchemy.sql.functions.FunctionElement.within_group(*order_by: _ColumnExpressionArgument[Any]) → WithinGroup[_T]

Erzeugt eine WITHIN GROUP (ORDER BY expr) Klausel für diese Funktion.

Wird für sogenannte "ordered set aggregate" und "hypothetical set aggregate" Funktionen verwendet, einschließlich percentile_cont, rank, dense_rank, etc.

Siehe within_group() für eine vollständige Beschreibung.

Siehe auch

Spezielle Modifikatoren WITHIN GROUP, FILTER - im SQLAlchemy Unified Tutorial

method sqlalchemy.sql.functions.FunctionElement.within_group_type(within_group: WithinGroup[_S]) → TypeEngine | None

Für Typen, die ihren Rückgabetyp als basierend auf den Kriterien innerhalb eines WITHIN GROUP (ORDER BY) Ausdrucks definieren, aufgerufen vom WithinGroup Konstrukt.

Gibt standardmäßig None zurück, in welchem Fall der normale `.type` der Funktion verwendet wird.

class sqlalchemy.sql.functions.GenericFunction

Definiert eine „generische“ Funktion.

Eine generische Funktion ist eine vordefinierte Function-Klasse, die automatisch instanziiert wird, wenn sie namentlich über das `func`-Attribut aufgerufen wird. Beachten Sie, dass das Aufrufen eines beliebigen Namens aus `func` zur Folge hat, dass automatisch eine neue Function-Instanz mit diesem Namen erstellt wird. Der Hauptanwendungsfall für die Definition einer GenericFunction-Klasse besteht darin, einer Funktion eines bestimmten Namens einen festen Rückgabetyp zuzuweisen. Sie kann auch benutzerdefinierte Argumentparsing-Schemata sowie zusätzliche Methoden enthalten.

Unterklassen von GenericFunction werden automatisch unter dem Namen der Klasse registriert. Zum Beispiel wäre eine benutzerdefinierte Funktion as_utc() sofort verfügbar.

from sqlalchemy.sql.functions import GenericFunction
from sqlalchemy.types import DateTime


class as_utc(GenericFunction):
    type = DateTime()
    inherit_cache = True


print(select(func.as_utc()))

Benutzerdefinierte generische Funktionen können in Paketen organisiert werden, indem das Attribut "package" bei der Definition von GenericFunction angegeben wird. Drittanbieterbibliotheken, die viele Funktionen enthalten, möchten dies möglicherweise verwenden, um Namenskonflikte mit anderen Systemen zu vermeiden. Wenn unsere `as_utc()`-Funktion beispielsweise Teil eines Pakets "time" wäre.

class as_utc(GenericFunction):
    type = DateTime()
    package = "time"
    inherit_cache = True

Die obige Funktion wäre über `func` unter dem Paketnamen time verfügbar.

print(select(func.time.as_utc()))

Eine letzte Option ist, es der Funktion zu ermöglichen, über einen Namen in `func` aufgerufen zu werden, aber als ein anderer Name gerendert zu werden. Das Attribut `identifier` überschreibt den Namen, der für den Aufruf der Funktion verwendet wird, wie sie aus `func` geladen wird, behält aber die Verwendung von `name` als gerenderten Namen bei.

class GeoBuffer(GenericFunction):
    type = Geometry()
    package = "geo"
    name = "ST_Buffer"
    identifier = "buffer"
    inherit_cache = True

Die obige Funktion wird wie folgt gerendert.

>>> print(func.geo.buffer())
ST_Buffer()

Der Name wird so gerendert, wie er ist, jedoch ohne Anführungszeichen, es sei denn, der Name enthält Sonderzeichen, die Anführungszeichen erfordern. Um Anführungszeichen für den Namen zu erzwingen oder zu deaktivieren, verwenden Sie das Konstrukt `quoted_name`.

from sqlalchemy.sql import quoted_name


class GeoBuffer(GenericFunction):
    type = Geometry()
    package = "geo"
    name = quoted_name("ST_Buffer", True)
    identifier = "buffer"
    inherit_cache = True

Die obige Funktion wird wie folgt gerendert.

>>> print(func.geo.buffer())
"ST_Buffer"()

Typ-Parameter für diese Klasse als generischer Typ können übergeben werden und sollten mit dem Typ übereinstimmen, der in einem Result gesehen wird. Zum Beispiel.

class as_utc(GenericFunction[datetime.datetime]):
    type = DateTime()
    inherit_cache = True

Das Obige zeigt an, dass der folgende Ausdruck ein datetime Objekt zurückgibt.

connection.scalar(select(func.as_utc()))

Neu ab Version 1.3.13: Das Konstrukt quoted_name wird nun beim Verwenden mit dem "name"-Attribut des Objekts für Anführungszeichen erkannt, sodass Anführungszeichen für den Funktionsnamen erzwungen oder deaktiviert werden können.

Klassensignatur

class sqlalchemy.sql.functions.GenericFunction (sqlalchemy.sql.functions.Function)

function sqlalchemy.sql.functions.register_function(identifier: str, fn: Type[Function[Any]], package: str = '_default') → None

Ordnet einen Aufrufbaren einem bestimmten func-Namen zu.

Dies wird normalerweise von GenericFunction aufgerufen, ist aber auch selbst verfügbar, damit ein Nicht-Function-Konstrukt mit dem `func`-Accessor assoziiert werden kann (d. h. CAST, EXTRACT).

Ausgewählte "Bekannte" Funktionen

Dies sind GenericFunction-Implementierungen für eine ausgewählte Menge gängiger SQL-Funktionen, die automatisch den erwarteten Rückgabetyp für jede Funktion festlegen. Sie werden auf die gleiche Weise aufgerufen wie jedes andere Mitglied des `func`-Namespace.

select(func.count("*")).select_from(some_table)

Beachten Sie, dass jeder Name, der `func` nicht bekannt ist, den Funktionsnamen unverändert generiert - es gibt keine Einschränkung, welche SQL-Funktionen aufgerufen werden können, ob bekannt oder unbekannt für SQLAlchemy, eingebaut oder benutzerdefiniert. Der Abschnitt hier beschreibt nur diejenigen Funktionen, bei denen SQLAlchemy bereits weiß, welche Argument- und Rückgabetypen verwendet werden.

Objektname	Beschreibung
aggregate_strings	Implementiert eine generische String-Aggregationsfunktion.
array_agg	Unterstützung für die ARRAY_AGG Funktion.
char_length	Die CHAR_LENGTH() SQL-Funktion.
coalesce
concat	Die SQL CONCAT() Funktion, die Zeichenketten verknüpft.
count	Die ANSI COUNT Aggregatfunktion. Ohne Argumente wird COUNT * ausgegeben.
cube	Implementiert den `CUBE` Gruppierungsoperator.
cume_dist	Implementiert die `cume_dist` hypothetische Mengenaggregatfunktion.
current_date	Die CURRENT_DATE() SQL-Funktion.
current_time	Die CURRENT_TIME() SQL-Funktion.
current_timestamp	Die CURRENT_TIMESTAMP() SQL-Funktion.
current_user	Die CURRENT_USER() SQL-Funktion.
dense_rank	Implementiert die `dense_rank` hypothetische Mengenaggregatfunktion.
grouping_sets	Implementiert den `GROUPING SETS` Gruppierungsoperator.
localtime	Die localtime() SQL-Funktion.
localtimestamp	Die localtimestamp() SQL-Funktion.
max	Die SQL MAX() Aggregatfunktion.
min	Die SQL MIN() Aggregatfunktion.
mode	Implementiert die `mode` geordnete Mengenaggregatfunktion.
next_value	Repräsentiert den 'next value', gegeben eine Sequence als einziges Argument.
now	Die SQL now() Datums- und Zeitfunktion.
percent_rank	Implementiert die `percent_rank` hypothetische Mengenaggregatfunktion.
percentile_cont	Implementiert die `percentile_cont` geordnete Mengenaggregatfunktion.
percentile_disc	Implementiert die `percentile_disc` geordnete Mengenaggregatfunktion.
random	Die RANDOM() SQL-Funktion.
rank	Implementiert die `rank` hypothetische Mengenaggregatfunktion.
rollup	Implementiert den `ROLLUP` Gruppierungsoperator.
session_user	Die SESSION_USER() SQL-Funktion.
sum	Die SQL SUM() Aggregatfunktion.
sysdate	Die SYSDATE() SQL-Funktion.
user	Die USER() SQL-Funktion.

class sqlalchemy.sql.functions.aggregate_strings

Implementiert eine generische String-Aggregationsfunktion.

Diese Funktion verkettet Nicht-NULL-Werte zu einem String und trennt die Werte durch ein Trennzeichen.

Diese Funktion wird auf Backend-Basis in Funktionen wie `group_concat()`, `string_agg()` oder `LISTAGG()` kompiliert.

z.B. Beispielverwendung mit dem Trennzeichen '.'

stmt = select(func.aggregate_strings(table.c.str_col, "."))

Der Rückgabetyp dieser Funktion ist String.

Klassensignatur

class sqlalchemy.sql.functions.aggregate_strings (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.array_agg

Unterstützung für die ARRAY_AGG Funktion.

Das Konstrukt `func.array_agg(expr)` gibt einen Ausdruck vom Typ ARRAY zurück.

z. B.

stmt = select(func.array_agg(table.c.values)[2:5])

Siehe auch

array_agg() - PostgreSQL-spezifische Version, die ARRAY zurückgibt, die PG-spezifische Operatoren hinzugefügt hat.

Klassensignatur

class sqlalchemy.sql.functions.array_agg (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.char_length

Die CHAR_LENGTH() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.char_length (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.coalesce

Klassensignatur

class sqlalchemy.sql.functions.coalesce (sqlalchemy.sql.functions.ReturnTypeFromArgs)

class sqlalchemy.sql.functions.concat

Die SQL CONCAT() Funktion, die Zeichenketten verknüpft.

Z. B.

>>> print(select(func.concat("a", "b")))
SELECT concat(:concat_2, :concat_3) AS concat_1

Die Zeichenkettenverkettung in SQLAlchemy ist üblicherweise über den Python `+` Operator mit String-Datentypen verfügbar, der einen Backend-spezifischen Verkettungsoperator rendert, wie z. B.

>>> print(select(literal("a") + "b"))
SELECT :param_1 || :param_2 AS anon_1

Klassensignatur

class sqlalchemy.sql.functions.concat (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.count

Die ANSI COUNT Aggregatfunktion. Ohne Argumente wird COUNT * ausgegeben.

Z. B.

from sqlalchemy import func
from sqlalchemy import select
from sqlalchemy import table, column

my_table = table("some_table", column("id"))

stmt = select(func.count()).select_from(my_table)

Die Ausführung von `stmt` würde Folgendes ausgeben:

SELECT count(*) AS count_1
FROM some_table

Klassensignatur

class sqlalchemy.sql.functions.count (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.cube

Implementiert den `CUBE` Gruppierungsoperator.

Diese Funktion wird als Teil von GROUP BY einer Anweisung verwendet, z. B. Select.group_by()

stmt = select(
    func.sum(table.c.value), table.c.col_1, table.c.col_2
).group_by(func.cube(table.c.col_1, table.c.col_2))

Neu seit Version 1.2.

Klassensignatur

class sqlalchemy.sql.functions.cube (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.cume_dist

Implementiert die `cume_dist` hypothetische Mengenaggregatfunktion.

Diese Funktion muss mit dem Modifikator FunctionElement.within_group() verwendet werden, um einen Sortierausdruck bereitzustellen, auf den operiert werden kann.

Der Rückgabetyp dieser Funktion ist Numeric.

Klassensignatur

class sqlalchemy.sql.functions.cume_dist (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.current_date

Die CURRENT_DATE() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.current_date (sqlalchemy.sql.functions.AnsiFunction)

class sqlalchemy.sql.functions.current_time

Die CURRENT_TIME() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.current_time (sqlalchemy.sql.functions.AnsiFunction)

class sqlalchemy.sql.functions.current_timestamp

Die CURRENT_TIMESTAMP() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.current_timestamp (sqlalchemy.sql.functions.AnsiFunction)

class sqlalchemy.sql.functions.current_user

Die CURRENT_USER() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.current_user (sqlalchemy.sql.functions.AnsiFunction)

class sqlalchemy.sql.functions.dense_rank

Implementiert die `dense_rank` hypothetische Mengenaggregatfunktion.

Diese Funktion muss mit dem Modifikator FunctionElement.within_group() verwendet werden, um einen Sortierausdruck bereitzustellen, auf den operiert werden kann.

Der Rückgabetyp dieser Funktion ist Integer.

Klassensignatur

class sqlalchemy.sql.functions.dense_rank (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.grouping_sets

Implementiert den `GROUPING SETS` Gruppierungsoperator.

Diese Funktion wird als Teil von GROUP BY einer Anweisung verwendet, z. B. Select.group_by()

stmt = select(
    func.sum(table.c.value), table.c.col_1, table.c.col_2
).group_by(func.grouping_sets(table.c.col_1, table.c.col_2))

Um nach mehreren Sets zu gruppieren, verwenden Sie die tuple_()-Konstruktion

from sqlalchemy import tuple_

stmt = select(
    func.sum(table.c.value), table.c.col_1, table.c.col_2, table.c.col_3
).group_by(
    func.grouping_sets(
        tuple_(table.c.col_1, table.c.col_2),
        tuple_(table.c.value, table.c.col_3),
    )
)

Neu seit Version 1.2.

Klassensignatur

class sqlalchemy.sql.functions.grouping_sets (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.localtime

Die localtime() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.localtime (sqlalchemy.sql.functions.AnsiFunction)

class sqlalchemy.sql.functions.localtimestamp

Die localtimestamp() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.localtimestamp (sqlalchemy.sql.functions.AnsiFunction)

class sqlalchemy.sql.functions.max

Die SQL MAX() Aggregatfunktion.

Klassensignatur

class sqlalchemy.sql.functions.max (sqlalchemy.sql.functions.ReturnTypeFromArgs)

class sqlalchemy.sql.functions.min

Die SQL MIN() Aggregatfunktion.

Klassensignatur

class sqlalchemy.sql.functions.min (sqlalchemy.sql.functions.ReturnTypeFromArgs)

class sqlalchemy.sql.functions.mode

Implementiert die `mode` geordnete Mengenaggregatfunktion.

Diese Funktion muss mit dem Modifikator FunctionElement.within_group() verwendet werden, um einen Sortierausdruck bereitzustellen, auf den operiert werden kann.

Der Rückgabetyp dieser Funktion ist derselbe wie der Sortierausdruck.

Klassensignatur

class sqlalchemy.sql.functions.mode (sqlalchemy.sql.functions.OrderedSetAgg)

class sqlalchemy.sql.functions.next_value

Repräsentiert den 'next value', gegeben eine Sequence als einziges Argument.

Wird auf die entsprechende Funktion auf jedem Backend kompiliert oder löst NotImplementedError aus, wenn sie auf einem Backend verwendet wird, das keine Unterstützung für Sequenzen bietet.

Klassensignatur

class sqlalchemy.sql.functions.next_value (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.now

Die SQL now() Datums- und Zeitfunktion.

SQLAlchemy-Dialekte rendern diese spezielle Funktion normalerweise auf Backend-spezifische Weise, z. B. als CURRENT_TIMESTAMP.

Klassensignatur

class sqlalchemy.sql.functions.now (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.percent_rank

Implementiert die `percent_rank` hypothetische Mengenaggregatfunktion.

Diese Funktion muss mit dem Modifikator FunctionElement.within_group() verwendet werden, um einen Sortierausdruck bereitzustellen, auf den operiert werden kann.

Der Rückgabetyp dieser Funktion ist Numeric.

Klassensignatur

class sqlalchemy.sql.functions.percent_rank (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.percentile_cont

Implementiert die `percentile_cont` geordnete Mengenaggregatfunktion.

Diese Funktion muss mit dem Modifikator FunctionElement.within_group() verwendet werden, um einen Sortierausdruck bereitzustellen, auf den operiert werden kann.

Der Rückgabetyp dieser Funktion ist derselbe wie der Sortierausdruck, oder wenn die Argumente ein Array sind, ein ARRAY vom Typ des Sortierausdrucks.

Klassensignatur

class sqlalchemy.sql.functions.percentile_cont (sqlalchemy.sql.functions.OrderedSetAgg)

class sqlalchemy.sql.functions.percentile_disc

Implementiert die `percentile_disc` geordnete Mengenaggregatfunktion.

Diese Funktion muss mit dem Modifikator FunctionElement.within_group() verwendet werden, um einen Sortierausdruck bereitzustellen, auf den operiert werden kann.

Der Rückgabetyp dieser Funktion ist derselbe wie der Sortierausdruck, oder wenn die Argumente ein Array sind, ein ARRAY vom Typ des Sortierausdrucks.

Klassensignatur

class sqlalchemy.sql.functions.percentile_disc (sqlalchemy.sql.functions.OrderedSetAgg)

class sqlalchemy.sql.functions.random

Die RANDOM() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.random (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.rank

Implementiert die `rank` hypothetische Mengenaggregatfunktion.

Diese Funktion muss mit dem Modifikator FunctionElement.within_group() verwendet werden, um einen Sortierausdruck bereitzustellen, auf den operiert werden kann.

Der Rückgabetyp dieser Funktion ist Integer.

Klassensignatur

class sqlalchemy.sql.functions.rank (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.rollup

Implementiert den `ROLLUP` Gruppierungsoperator.

Diese Funktion wird als Teil von GROUP BY einer Anweisung verwendet, z. B. Select.group_by()

stmt = select(
    func.sum(table.c.value), table.c.col_1, table.c.col_2
).group_by(func.rollup(table.c.col_1, table.c.col_2))

Neu seit Version 1.2.

Klassensignatur

class sqlalchemy.sql.functions.rollup (sqlalchemy.sql.functions.GenericFunction)

class sqlalchemy.sql.functions.session_user

Die SESSION_USER() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.session_user (sqlalchemy.sql.functions.AnsiFunction)

class sqlalchemy.sql.functions.sum

Die SQL SUM() Aggregatfunktion.

Klassensignatur

class sqlalchemy.sql.functions.sum (sqlalchemy.sql.functions.ReturnTypeFromArgs)

class sqlalchemy.sql.functions.sysdate

Die SYSDATE() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.sysdate (sqlalchemy.sql.functions.AnsiFunction)

class sqlalchemy.sql.functions.user

Die USER() SQL-Funktion.

Klassensignatur

class sqlalchemy.sql.functions.user (sqlalchemy.sql.functions.AnsiFunction)