Einfügen, Aktualisieren, Löschen

INSERT-, UPDATE- und DELETE-Anweisungen bauen auf einer Hierarchie auf, die mit UpdateBase beginnt. Die Konstrukte Insert und Update bauen auf der intermediären ValuesBase auf.

DML Grundlegende Konstruktoren

Obere Ebene „INSERT“, „UPDATE“, „DELETE“ Konstruktoren.

Objektname Beschreibung

delete(tabelle)

Konstruiere ein Delete Objekt.

insert(tabelle)

Konstruiere ein Insert Objekt.

update(tabelle)

Konstruiere ein Update Objekt.
Funktion sqlalchemy.sql.expression.delete(tabelle: _DMLTableArgument) → Delete

Konstruiere ein Delete Objekt.

Z. B.

from sqlalchemy import delete

stmt = delete(user_table).where(user_table.c.id == 5)

Ähnliche Funktionalität ist über die Methode TableClause.delete() auf Table verfügbar.

Parameter:

Tabelle – Die Tabelle, aus der Zeilen gelöscht werden sollen.

Siehe auch

Verwendung von UPDATE- und DELETE-Anweisungen - im SQLAlchemy Unified Tutorial

Funktion sqlalchemy.sql.expression.insert(tabelle: _DMLTableArgument) → Insert

Konstruiere ein Insert Objekt.

Z. B.

from sqlalchemy import insert

stmt = insert(user_table).values(name="username", fullname="Full Username")

Ähnliche Funktionalität ist über die Methode TableClause.insert() auf Table verfügbar.

Siehe auch

Verwendung von INSERT-Anweisungen - im SQLAlchemy Unified Tutorial

Parameter:

  • Tabelle – Ein TableClause Objekt, das das Subjekt des Einfügens ist.

  • Werte – Sammlung von einzufügenden Werten; siehe Insert.values() für eine Beschreibung der hier zulässigen Formate. Kann weggelassen werden; ein Insert Konstrukt rendert die VALUES-Klausel zur Ausführungszeit dynamisch basierend auf den Parametern, die an Connection.execute() übergeben werden.

  • inline – Wenn True, wird keine Anstrengung unternommen, die SQL-generierten Standardwerte abzurufen, die innerhalb der Anweisung bereitgestellt werden sollen; insbesondere erlaubt dies, dass SQL-Ausdrücke "inline" innerhalb der Anweisung gerendert werden, ohne dass sie vorher ausgeführt werden müssen; für Backends, die "returning" unterstützen, deaktiviert dies die "implizite returning"-Funktion für die Anweisung.

Wenn sowohl insert.values als auch Compile-Zeit-Bindungsparameter vorhanden sind, überschreiben die Compile-Zeit-Bindungsparameter die in insert.values angegebenen Informationen pro Schlüssel.

Die Schlüssel in Insert.values können entweder Column-Objekte oder deren String-Identifikatoren sein. Jeder Schlüssel kann auf eines der folgenden Elemente verweisen:

  • ein literaler Datenwert (d.h. String, Zahl usw.);

  • ein Spaltenobjekt;

  • eine SELECT-Anweisung.

Wenn eine SELECT-Anweisung angegeben wird, die auf die Tabelle dieser INSERT-Anweisung verweist, wird die Anweisung gegen die INSERT-Anweisung korreliert.

Siehe auch

Verwendung von INSERT-Anweisungen - im SQLAlchemy Unified Tutorial

Funktion sqlalchemy.sql.expression.update(tabelle: _DMLTableArgument) → Update

Konstruiere ein Update Objekt.

Z. B.

from sqlalchemy import update

stmt = (
    update(user_table).where(user_table.c.id == 5).values(name="user #5")
)

Ähnliche Funktionalität ist über die Methode TableClause.update() auf Table verfügbar.

Parameter:

Tabelle – Ein Table Objekt, das die zu aktualisierende Datenbanktabelle darstellt.

Siehe auch

Verwendung von UPDATE- und DELETE-Anweisungen - im SQLAlchemy Unified Tutorial

DML Klassen-Dokumentationskonstruktoren

Klassendokumentation für die unter DML Grundlegende Konstruktoren aufgeführten Konstruktoren.

Objektname Beschreibung

Delete

Stellt ein DELETE-Konstrukt dar.

Insert

Stellt ein INSERT-Konstrukt dar.

Update

Stellt ein Update-Konstrukt dar.

AktualisierenBasis

Bildet die Basis für INSERT-, UPDATE- und DELETE-Anweisungen.

WerteBasis

Bietet Unterstützung für ValuesBase.values() für INSERT- und UPDATE-Konstrukte.
Klasse sqlalchemy.sql.expression.Delete

Stellt ein DELETE-Konstrukt dar.

Das Delete-Objekt wird mit der Funktion delete() erstellt.

Mitglieder

where(), with_dialect_options(), returning()

Klassensignatur

Klasse sqlalchemy.sql.expression.Delete (sqlalchemy.sql.expression.DMLWhereBase, sqlalchemy.sql.expression.UpdateBase)

Methode sqlalchemy.sql.expression.Delete.where(*whereclause: _ColumnExpressionArgument[bool]) → Self

vererbt von der DMLWhereBase.where() Methode von DMLWhereBase

Gibt ein neues Konstrukt mit dem/den gegebenen Ausdruck/Ausdrücken zurück, der/die zur WHERE-Klausel hinzugefügt wird/werden, verbunden mit der vorhandenen Klausel über AND, falls vorhanden.

Sowohl Update.where() als auch Delete.where() unterstützen Mehrfach-Tabellen-Formen, einschließlich datenbankspezifischer UPDATE...FROM sowie DELETE..USING. Für Backends, die keine Mehrfach-Tabellen-Unterstützung haben, ist ein Backend-agnostischer Ansatz zur Verwendung mehrerer Tabellen die Nutzung von korrelierten Unterabfragen. Siehe die unten verlinkten Tutorial-Abschnitte für Beispiele.

Siehe auch

Korrelierte Updates

UPDATE..FROM

Mehrfach-Tabellen-Löschungen

Methode sqlalchemy.sql.expression.Delete.with_dialect_options(**opt: Any) → Self

vererbt von der UpdateBase.with_dialect_options() Methode von UpdateBase

Fügt diesem INSERT/UPDATE/DELETE-Objekt Dialektoptionen hinzu.

z. B.

upd = table.update().dialect_options(mysql_limit=10)
Methode sqlalchemy.sql.expression.Delete.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase

vererbt von der UpdateBase.returning() Methode von UpdateBase

Fügt dieser Anweisung eine RETURNING oder eine äquivalente Klausel hinzu.

z. B.

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)

UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

Die Methode kann mehrmals aufgerufen werden, um der Liste der zurückzugebenden Ausdrücke neue Einträge hinzuzufügen.

Neu in Version 1.4.0b2: Die Methode kann mehrmals aufgerufen werden, um der Liste der zurückzugebenden Ausdrücke neue Einträge hinzuzufügen.

Die gegebene Sammlung von Spaltenausdrücken sollte von der Tabelle abgeleitet sein, die das Ziel von INSERT, UPDATE oder DELETE ist. Obwohl Column-Objekte typisch sind, können die Elemente auch Ausdrücke sein

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)

INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

Bei der Kompilierung wird eine RETURNING-Klausel oder ein Datenbankäquivalent in die Anweisung gerendert. Für INSERT und UPDATE sind die Werte die neu eingefügten/aktualisierten Werte. Für DELETE sind die Werte die der gelöschten Zeilen.

Bei der Ausführung sind die Werte der zurückzugebenden Spalten über das Ergebnisset verfügbar und können mit CursorResult.fetchone() und ähnlichen Methoden iteriert werden. Für DBAPIs, die das Zurückgeben von Werten nicht nativ unterstützen (z. B. cx_oracle), wird SQLAlchemy dieses Verhalten auf Ergebnisebene annähern, um ein angemessenes Maß an Verhaltensneutralität zu gewährleisten.

Beachten Sie, dass nicht alle Datenbanken/DBAPIs RETURNING unterstützen. Für Backends ohne Unterstützung wird bei der Kompilierung und/oder Ausführung eine Ausnahme ausgelöst. Für diejenigen, die es unterstützen, variiert die Funktionalität zwischen den Backends stark, einschließlich Einschränkungen bei executemany() und anderen Anweisungen, die mehrere Zeilen zurückgeben. Bitte lesen Sie die Dokumentation für die verwendete Datenbank, um die Verfügbarkeit von RETURNING zu ermitteln.

Parameter:

Siehe auch

UpdateBase.return_defaults() - eine alternative Methode, die auf effizientes Abrufen von serverseitigen Standardwerten und Triggern für Single-Row-INSERTs oder UPDATEs zugeschnitten ist.

INSERT…RETURNING - im SQLAlchemy Unified Tutorial

Klasse sqlalchemy.sql.expression.Insert

Stellt ein INSERT-Konstrukt dar.

Das Insert-Objekt wird mit der Funktion insert() erstellt.

Mitglieder

with_dialect_options(), values(), returning(), from_select(), inline(), select

Klassensignatur

Klasse sqlalchemy.sql.expression.Insert (sqlalchemy.sql.expression.ValuesBase)

Methode sqlalchemy.sql.expression.Insert.with_dialect_options(**opt: Any) → Self

vererbt von der UpdateBase.with_dialect_options() Methode von UpdateBase

Fügt diesem INSERT/UPDATE/DELETE-Objekt Dialektoptionen hinzu.

z. B.

upd = table.update().dialect_options(mysql_limit=10)
Methode sqlalchemy.sql.expression.Insert.values(*args: _DMLColumnKeyMapping[Any] | Sequence[Any], **kwargs: Any) → Self

vererbt von der ValuesBase.values() Methode von ValuesBase

Gibt eine feste VALUES-Klausel für eine INSERT-Anweisung oder die SET-Klausel für ein UPDATE an.

Beachten Sie, dass die Konstrukte Insert und Update eine pro-Ausführungszeit-Formatierung der VALUES- und/oder SET-Klauseln unterstützen, basierend auf den Argumenten, die an Connection.execute() übergeben werden. Die Methode ValuesBase.values() kann jedoch verwendet werden, um einen bestimmten Parametersatz in die Anweisung zu "fixieren".

Mehrere Aufrufe von ValuesBase.values() erzeugen ein neues Konstrukt, wobei jede mit der modifizierten Parameterliste die neuen Parameter enthält, die gesendet wurden. Im typischen Fall eines einzelnen Parameter-Wörterbuchs ersetzen die neu übergebenen Schlüssel dieselben Schlüssel im vorherigen Konstrukt. Im Fall eines listenbasierten "Mehrfachwerte"-Konstrukts wird jede neue Werteliste an die bestehende Liste von Werten angehängt.

Parameter:

  • **kwargs –

    Schlüssel-Wert-Paare, die den String-Schlüssel einer Column, zugeordnet dem Wert, der in die VALUES- oder SET-Klausel gerendert werden soll.

    users.insert().values(name="some name")

users.update().where(users.c.id == 5).values(name="some name")

  • *args –

    Als Alternative zur Übergabe von Schlüssel/Wert-Paaren kann ein Wörterbuch, ein Tupel oder eine Liste von Wörterbüchern oder Tupeln als einzelnes positionsgebundenes Argument übergeben werden, um die VALUES- oder SET-Klausel der Anweisung zu bilden. Die akzeptierten Formen variieren je nachdem, ob es sich um ein Insert- oder ein Update-Konstrukt handelt.

    Für ein Insert- oder Update-Konstrukt kann ein einzelnes Wörterbuch übergeben werden, das sich genauso verhält wie die kwargs-Form.

    users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})

    Ebenso für beide Formen, aber typischer für das Insert-Konstrukt, wird auch ein Tupel akzeptiert, das einen Eintrag für jede Spalte in der Tabelle enthält.

    users.insert().values((5, "some name"))

    Das Insert-Konstrukt unterstützt auch die Übergabe einer Liste von Wörterbüchern oder vollständigen Tabellen-Tupeln, was auf dem Server die weniger gebräuchliche SQL-Syntax von "mehreren Werten" rendert - diese Syntax wird von Backends wie SQLite, PostgreSQL, MySQL unterstützt, aber nicht unbedingt von anderen.

    users.insert().values(
    [
        {"name": "some name"},
        {"name": "some other name"},
        {"name": "yet another name"},
    ]
)

    Die obige Form würde eine Anweisung mit mehreren VALUES rendern, ähnlich wie

    INSERT INTO users (name) VALUES
                (:name_1),
                (:name_2),
                (:name_3)

    Es ist wichtig zu beachten, dass **die Übergabe mehrerer Werte NICHT dasselbe ist wie die Verwendung des traditionellen executemany()-Formats**. Die obige Syntax ist eine **spezielle** Syntax, die nicht üblicherweise verwendet wird. Um eine INSERT-Anweisung gegen mehrere Zeilen auszugeben, ist die normale Methode, eine Liste mit mehreren Werten an die Methode Connection.execute() zu übergeben, die von allen Datenbank-Backends unterstützt wird und im Allgemeinen effizienter für eine sehr große Anzahl von Parametern ist.

    Siehe auch

    Senden mehrerer Parameter - eine Einführung in die traditionelle Core-Methode des Aufrufs mehrerer Parametersätze für INSERTs und andere Anweisungen.

    Der UPDATE-Konstrukt unterstützt auch das Rendern der SET-Parameter in einer bestimmten Reihenfolge. Für diese Funktion verweisen Sie auf die Methode Update.ordered_values().

methode sqlalchemy.sql.expression.Insert.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase

vererbt von der UpdateBase.returning() Methode von UpdateBase

Fügt dieser Anweisung eine RETURNING oder eine äquivalente Klausel hinzu.

z. B.

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)

UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

Die Methode kann mehrmals aufgerufen werden, um der Liste der zurückzugebenden Ausdrücke neue Einträge hinzuzufügen.

Neu in Version 1.4.0b2: Die Methode kann mehrmals aufgerufen werden, um der Liste der zurückzugebenden Ausdrücke neue Einträge hinzuzufügen.

Die gegebene Sammlung von Spaltenausdrücken sollte von der Tabelle abgeleitet sein, die das Ziel von INSERT, UPDATE oder DELETE ist. Obwohl Column-Objekte typisch sind, können die Elemente auch Ausdrücke sein

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)

INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

Bei der Kompilierung wird eine RETURNING-Klausel oder ein Datenbankäquivalent in die Anweisung gerendert. Für INSERT und UPDATE sind die Werte die neu eingefügten/aktualisierten Werte. Für DELETE sind die Werte die der gelöschten Zeilen.

Bei der Ausführung sind die Werte der zurückzugebenden Spalten über das Ergebnisset verfügbar und können mit CursorResult.fetchone() und ähnlichen Methoden iteriert werden. Für DBAPIs, die das Zurückgeben von Werten nicht nativ unterstützen (z. B. cx_oracle), wird SQLAlchemy dieses Verhalten auf Ergebnisebene annähern, um ein angemessenes Maß an Verhaltensneutralität zu gewährleisten.

Beachten Sie, dass nicht alle Datenbanken/DBAPIs RETURNING unterstützen. Für Backends ohne Unterstützung wird bei der Kompilierung und/oder Ausführung eine Ausnahme ausgelöst. Für diejenigen, die es unterstützen, variiert die Funktionalität zwischen den Backends stark, einschließlich Einschränkungen bei executemany() und anderen Anweisungen, die mehrere Zeilen zurückgeben. Bitte lesen Sie die Dokumentation für die verwendete Datenbank, um die Verfügbarkeit von RETURNING zu ermitteln.

Parameter:

Siehe auch

UpdateBase.return_defaults() - eine alternative Methode, die auf effizientes Abrufen von serverseitigen Standardwerten und Triggern für Single-Row-INSERTs oder UPDATEs zugeschnitten ist.

INSERT…RETURNING - im SQLAlchemy Unified Tutorial

methode sqlalchemy.sql.expression.Insert.from_select(names: Sequence[_DMLColumnArgument], select: Selectable, include_defaults: bool = True) → Self

Gibt einen neuen Insert-Konstrukt zurück, der eine INSERT...FROM SELECT-Anweisung darstellt.

z. B.

sel = select(table1.c.a, table1.c.b).where(table1.c.c > 5)
ins = table2.insert().from_select(["a", "b"], sel)
Parameter:

  • names – eine Sequenz von Zeichenfolgen-Spaltennamen oder Column-Objekten, die die Zielspalten darstellen.

  • select – ein select()-Konstrukt, FromClause oder ein anderes Konstrukt, das sich zu einer FromClause auflöst, wie z. B. ein ORM Query-Objekt usw. Die Reihenfolge der Spalten, die von dieser FROM-Klausel zurückgegeben werden, sollte der Reihenfolge der Spalten entsprechen, die als names-Parameter übergeben werden; obwohl dies vor der Übergabe an die Datenbank nicht geprüft wird, würde die Datenbank normalerweise eine Ausnahme auslösen, wenn diese Spaltenlisten nicht übereinstimmen.

  • include_defaults –

    Wenn True, werden serverseitige Standardwerte und SQL-Ausdrücke, wie auf Column-Objekten angegeben (wie in Spalten INSERT/UPDATE-Standardwerte dokumentiert) und die nicht anderweitig in der Liste der Namen angegeben sind, in die INSERT- und SELECT-Anweisungen gerendert, sodass diese Werte ebenfalls in die einzufügenden Daten aufgenommen werden.

    Hinweis

    Ein Python-seitiger Standardwert, der eine Python-Callable-Funktion verwendet, wird **einmal** für die gesamte Anweisung aufgerufen und **nicht pro Zeile**.

methode sqlalchemy.sql.expression.Insert.inline() → Self

Machen Sie diesen Insert-Konstrukt "inline".

Wenn dies eingestellt ist, wird kein Versuch unternommen, die SQL-generierten Standardwerte abzurufen, die innerhalb der Anweisung bereitgestellt werden sollen; insbesondere ermöglicht dies, dass SQL-Ausdrücke "inline" innerhalb der Anweisung gerendert werden, ohne dass sie vorher ausgeführt werden müssen; für Backends, die "returning" unterstützen, wird die Funktion "implizites returning" für die Anweisung deaktiviert.

Geändert in Version 1.4: Der Parameter Insert.inline wird jetzt von der Methode Insert.inline() abgelöst.

attribut sqlalchemy.sql.expression.Insert.select: Select[Any] | None = None

SELECT-Anweisung für INSERT .. FROM SELECT

klasse sqlalchemy.sql.expression.Update

Stellt ein Update-Konstrukt dar.

Das Update-Objekt wird mit der Funktion update() erstellt.

Mitglieder

returning(), where(), with_dialect_options(), values(), inline(), ordered_values()

Klassensignatur

klasse sqlalchemy.sql.expression.Update (sqlalchemy.sql.expression.DMLWhereBase, sqlalchemy.sql.expression.ValuesBase)

methode sqlalchemy.sql.expression.Update.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase

vererbt von der UpdateBase.returning() Methode von UpdateBase

Fügt dieser Anweisung eine RETURNING oder eine äquivalente Klausel hinzu.

z. B.

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)

UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

Die Methode kann mehrmals aufgerufen werden, um der Liste der zurückzugebenden Ausdrücke neue Einträge hinzuzufügen.

Neu in Version 1.4.0b2: Die Methode kann mehrmals aufgerufen werden, um der Liste der zurückzugebenden Ausdrücke neue Einträge hinzuzufügen.

Die gegebene Sammlung von Spaltenausdrücken sollte von der Tabelle abgeleitet sein, die das Ziel von INSERT, UPDATE oder DELETE ist. Obwohl Column-Objekte typisch sind, können die Elemente auch Ausdrücke sein

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)

INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

Bei der Kompilierung wird eine RETURNING-Klausel oder ein Datenbankäquivalent in die Anweisung gerendert. Für INSERT und UPDATE sind die Werte die neu eingefügten/aktualisierten Werte. Für DELETE sind die Werte die der gelöschten Zeilen.

Bei der Ausführung sind die Werte der zurückzugebenden Spalten über das Ergebnisset verfügbar und können mit CursorResult.fetchone() und ähnlichen Methoden iteriert werden. Für DBAPIs, die das Zurückgeben von Werten nicht nativ unterstützen (z. B. cx_oracle), wird SQLAlchemy dieses Verhalten auf Ergebnisebene annähern, um ein angemessenes Maß an Verhaltensneutralität zu gewährleisten.

Beachten Sie, dass nicht alle Datenbanken/DBAPIs RETURNING unterstützen. Für Backends ohne Unterstützung wird bei der Kompilierung und/oder Ausführung eine Ausnahme ausgelöst. Für diejenigen, die es unterstützen, variiert die Funktionalität zwischen den Backends stark, einschließlich Einschränkungen bei executemany() und anderen Anweisungen, die mehrere Zeilen zurückgeben. Bitte lesen Sie die Dokumentation für die verwendete Datenbank, um die Verfügbarkeit von RETURNING zu ermitteln.

Parameter:

Siehe auch

UpdateBase.return_defaults() - eine alternative Methode, die auf effizientes Abrufen von serverseitigen Standardwerten und Triggern für Single-Row-INSERTs oder UPDATEs zugeschnitten ist.

INSERT…RETURNING - im SQLAlchemy Unified Tutorial

methode sqlalchemy.sql.expression.Update.where(*whereclause: _ColumnExpressionArgument[bool]) → Self

vererbt von der DMLWhereBase.where() Methode von DMLWhereBase

Gibt ein neues Konstrukt mit dem/den gegebenen Ausdruck/Ausdrücken zurück, der/die zur WHERE-Klausel hinzugefügt wird/werden, verbunden mit der vorhandenen Klausel über AND, falls vorhanden.

Sowohl Update.where() als auch Delete.where() unterstützen Mehrfach-Tabellen-Formen, einschließlich datenbankspezifischer UPDATE...FROM sowie DELETE..USING. Für Backends, die keine Mehrfach-Tabellen-Unterstützung haben, ist ein Backend-agnostischer Ansatz zur Verwendung mehrerer Tabellen die Nutzung von korrelierten Unterabfragen. Siehe die unten verlinkten Tutorial-Abschnitte für Beispiele.

Siehe auch

Korrelierte Updates

UPDATE..FROM

Mehrfach-Tabellen-Löschungen

methode sqlalchemy.sql.expression.Update.with_dialect_options(**opt: Any) → Self

vererbt von der UpdateBase.with_dialect_options() Methode von UpdateBase

Fügt diesem INSERT/UPDATE/DELETE-Objekt Dialektoptionen hinzu.

z. B.

upd = table.update().dialect_options(mysql_limit=10)
methode sqlalchemy.sql.expression.Update.values(*args: _DMLColumnKeyMapping[Any] | Sequence[Any], **kwargs: Any) → Self

vererbt von der ValuesBase.values() Methode von ValuesBase

Gibt eine feste VALUES-Klausel für eine INSERT-Anweisung oder die SET-Klausel für ein UPDATE an.

Beachten Sie, dass die Konstrukte Insert und Update eine pro-Ausführungszeit-Formatierung der VALUES- und/oder SET-Klauseln unterstützen, basierend auf den Argumenten, die an Connection.execute() übergeben werden. Die Methode ValuesBase.values() kann jedoch verwendet werden, um einen bestimmten Parametersatz in die Anweisung zu "fixieren".

Mehrere Aufrufe von ValuesBase.values() erzeugen ein neues Konstrukt, wobei jede mit der modifizierten Parameterliste die neuen Parameter enthält, die gesendet wurden. Im typischen Fall eines einzelnen Parameter-Wörterbuchs ersetzen die neu übergebenen Schlüssel dieselben Schlüssel im vorherigen Konstrukt. Im Fall eines listenbasierten "Mehrfachwerte"-Konstrukts wird jede neue Werteliste an die bestehende Liste von Werten angehängt.

Parameter:

  • **kwargs –

    Schlüssel-Wert-Paare, die den String-Schlüssel einer Column, zugeordnet dem Wert, der in die VALUES- oder SET-Klausel gerendert werden soll.

    users.insert().values(name="some name")

users.update().where(users.c.id == 5).values(name="some name")

  • *args –

    Als Alternative zur Übergabe von Schlüssel/Wert-Paaren kann ein Wörterbuch, ein Tupel oder eine Liste von Wörterbüchern oder Tupeln als einzelnes positionsgebundenes Argument übergeben werden, um die VALUES- oder SET-Klausel der Anweisung zu bilden. Die akzeptierten Formen variieren je nachdem, ob es sich um ein Insert- oder ein Update-Konstrukt handelt.

    Für ein Insert- oder Update-Konstrukt kann ein einzelnes Wörterbuch übergeben werden, das sich genauso verhält wie die kwargs-Form.

    users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})

    Ebenso für beide Formen, aber typischer für das Insert-Konstrukt, wird auch ein Tupel akzeptiert, das einen Eintrag für jede Spalte in der Tabelle enthält.

    users.insert().values((5, "some name"))

    Das Insert-Konstrukt unterstützt auch die Übergabe einer Liste von Wörterbüchern oder vollständigen Tabellen-Tupeln, was auf dem Server die weniger gebräuchliche SQL-Syntax von "mehreren Werten" rendert - diese Syntax wird von Backends wie SQLite, PostgreSQL, MySQL unterstützt, aber nicht unbedingt von anderen.

    users.insert().values(
    [
        {"name": "some name"},
        {"name": "some other name"},
        {"name": "yet another name"},
    ]
)

    Die obige Form würde eine Anweisung mit mehreren VALUES rendern, ähnlich wie

    INSERT INTO users (name) VALUES
                (:name_1),
                (:name_2),
                (:name_3)

    Es ist wichtig zu beachten, dass **die Übergabe mehrerer Werte NICHT dasselbe ist wie die Verwendung des traditionellen executemany()-Formats**. Die obige Syntax ist eine **spezielle** Syntax, die nicht üblicherweise verwendet wird. Um eine INSERT-Anweisung gegen mehrere Zeilen auszugeben, ist die normale Methode, eine Liste mit mehreren Werten an die Methode Connection.execute() zu übergeben, die von allen Datenbank-Backends unterstützt wird und im Allgemeinen effizienter für eine sehr große Anzahl von Parametern ist.

    Siehe auch

    Senden mehrerer Parameter - eine Einführung in die traditionelle Core-Methode des Aufrufs mehrerer Parametersätze für INSERTs und andere Anweisungen.

    Der UPDATE-Konstrukt unterstützt auch das Rendern der SET-Parameter in einer bestimmten Reihenfolge. Für diese Funktion verweisen Sie auf die Methode Update.ordered_values().

methode sqlalchemy.sql.expression.Update.inline() → Self

Machen Sie diesen Update-Konstrukt "inline".

Wenn dies eingestellt ist, werden serverseitige Standardwerte, die auf Column-Objekten über das Schlüsselwort default vorhanden sind, "inline" in die Anweisung kompiliert und nicht vorab ausgeführt. Das bedeutet, dass ihre Werte nicht im aus CursorResult.last_updated_params() zurückgegebenen Wörterbuch verfügbar sind.

Geändert in Version 1.4: Der Parameter update.inline wird jetzt von der Methode Update.inline() abgelöst.

methode sqlalchemy.sql.expression.Update.ordered_values(*args: Tuple[_DMLColumnArgument, Any]) → Self

Gibt die VALUES-Klausel dieser UPDATE-Anweisung mit einer expliziten Parameterreihenfolge an, die in der SET-Klausel der resultierenden UPDATE-Anweisung beibehalten wird.

Z. B.

stmt = table.update().ordered_values(("name", "ed"), ("ident", "foo"))

Siehe auch

Parametergesteuerte Updates - Vollständiges Beispiel für die Methode Update.ordered_values().

Geändert in Version 1.4: Die Methode Update.ordered_values() löst den Parameter update.preserve_parameter_order ab, der in SQLAlchemy 2.0 entfernt wird.

klasse sqlalchemy.sql.expression.UpdateBase

Bildet die Basis für INSERT-, UPDATE- und DELETE-Anweisungen.

Mitglieder

entity_description, exported_columns, is_derived_from(), params(), return_defaults(), returning(), returning_column_descriptions, with_dialect_options(), with_hint()

Klassensignatur

klasse sqlalchemy.sql.expression.UpdateBase (sqlalchemy.sql.roles.DMLRole, sqlalchemy.sql.expression.HasCTE, sqlalchemy.sql.expression.HasCompileState, sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.sql.expression.HasPrefixes, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.ExecutableReturnsRows, sqlalchemy.sql.expression.ClauseElement)

attribut sqlalchemy.sql.expression.UpdateBase.entity_description

Gibt eine Plugin-fähige Beschreibung der Tabelle und/oder Entität zurück, gegen die dieser DML-Konstrukt operiert.

Dieses Attribut ist generell nützlich bei der Verwendung des ORM, da eine erweiterte Struktur, die Informationen über zugeordnete Entitäten enthält, zurückgegeben wird. Der Abschnitt Entitäten und Spalten aus ORM-fähigen SELECT- und DML-Anweisungen inspizieren enthält weitere Hintergründe.

Für eine Core-Anweisung wird die von diesem Zugriffsoperator zurückgegebene Struktur vom Attribut UpdateBase.table abgeleitet und bezieht sich auf die Table, die eingefügt, aktualisiert oder gelöscht wird.

>>> stmt = insert(user_table)
>>> stmt.entity_description
{
    "name": "user_table",
    "table": Table("user_table", ...)
}

Neu in Version 1.4.33.

Siehe auch

AktualisierenBasis.zurückgegebene_spaltenbeschreibungen

Select.column_descriptions - Entitätsinformationen für einen select()-Konstrukt

Entitäten und Spalten aus ORM-fähigen SELECT- und DML-Anweisungen inspizieren - ORM-Hintergrund

attribut sqlalchemy.sql.expression.UpdateBase.exported_columns

Gibt die RETURNING-Spalten als Spaltensammlung für diese Anweisung zurück.

Neu in Version 1.4.

methode sqlalchemy.sql.expression.UpdateBase.is_derived_from(fromclause: FromClause | None) → bool

Gibt True zurück, wenn dieses ReturnsRows von der gegebenen FromClause abgeleitet ist.

Da es sich hierbei um DMLs handelt, möchten wir nicht, dass solche Anweisungen jemals angepasst werden, daher geben wir für Derivate False zurück.

methode sqlalchemy.sql.expression.UpdateBase.params(*arg: Any, **kw: Any) → NoReturn

Setzt die Parameter für die Anweisung.

Diese Methode löst auf der Basisklasse NotImplementedError aus und wird von ValuesBase überschrieben, um die SET/VALUES-Klausel von UPDATE und INSERT bereitzustellen.

methode sqlalchemy.sql.expression.UpdateBase.return_defaults(*cols: _DMLColumnArgument, supplemental_cols: Iterable[_DMLColumnArgument] | None = None, sort_by_parameter_order: bool = False) → Self

Nutzt eine RETURNING-Klausel, um serverseitige Ausdrücke und Standardwerte abzurufen, nur für unterstützte Backends.

Deep Alchemy

Die Methode UpdateBase.return_defaults() wird vom ORM für seine internen Arbeiten zum Abrufen neu generierter Primärschlüssel- und serverseitiger Standardwerte verwendet, insbesondere zur Bereitstellung der zugrunde liegenden Implementierung des ORM-Features Mapper.eager_defaults und zur Ermöglichung der RETURNING-Unterstützung bei Massen-ORM-Einfügungen. Ihr Verhalten ist ziemlich eigenartig und nicht für den allgemeinen Gebrauch bestimmt. Endbenutzer sollten weiterhin UpdateBase.returning() verwenden, um RETURNING-Klauseln zu ihren INSERT-, UPDATE- und DELETE-Anweisungen hinzuzufügen.

Normalerweise füllt eine einzeilige INSERT-Anweisung automatisch das Attribut CursorResult.inserted_primary_key aus, das den Primärschlüssel der gerade eingefügten Zeile in Form eines Row-Objekts mit Spaltennamen als benannte Tupel-Schlüssel (und die Row._mapping-Ansicht vollständig ausgefüllt) speichert. Der verwendete Dialekt wählt die Strategie zur Populatierung dieser Daten aus; wenn sie mithilfe serverseitiger Standardwerte und/oder SQL-Ausdrücke generiert wurde, werden typischerweise dialektspezifische Ansätze wie cursor.lastrowid oder RETURNING verwendet, um den neuen Primärschlüsselwert zu erhalten.

Wenn die Anweisung jedoch modifiziert wird, indem UpdateBase.return_defaults() vor der Ausführung der Anweisung aufgerufen wird, treten **nur** für Backends, die RETURNING unterstützen, und für Table-Objekte, die den Parameter Table.implicit_returning bei seinem Standardwert von True beibehalten, zusätzliche Verhaltensweisen auf. In diesen Fällen wird, wenn das CursorResult aus der Ausführung der Anweisung zurückgegeben wird, nicht nur CursorResult.inserted_primary_key wie immer ausgefüllt, sondern auch das Attribut CursorResult.returned_defaults mit einem Row-Named-Tuple gefüllt, das den vollen Bereich der serverseitig generierten Werte aus dieser einzelnen Zeile darstellt, einschließlich Werten für alle Spalten, die Column.server_default angeben oder die Column.default unter Verwendung eines SQL-Ausdrucks verwenden.

Beim Aufrufen von INSERT-Anweisungen mit mehreren Zeilen unter Verwendung von insertmanyvalues hat der Modifikator UpdateBase.return_defaults() die Auswirkung, dass die Attribute CursorResult.inserted_primary_key_rows und CursorResult.returned_defaults_rows vollständig mit Listen von Row-Objekten gefüllt werden, die neu eingefügte Primärschlüsselwerte sowie neu eingefügte serverseitig generierte Werte für jede eingefügte Zeile darstellen. Die Attribute CursorResult.inserted_primary_key und CursorResult.returned_defaults werden weiterhin mit der ersten Zeile dieser beiden Sammlungen gefüllt.

Wenn das Backend RETURNING nicht unterstützt oder die verwendete Table Table.implicit_returning deaktiviert hat, wird keine RETURNING-Klausel hinzugefügt und keine zusätzlichen Daten abgerufen. Die INSERT-, UPDATE- oder DELETE-Anweisung wird jedoch normal fortgesetzt.

Z. B.

stmt = table.insert().values(data="newdata").return_defaults()

result = connection.execute(stmt)

server_created_at = result.returned_defaults["created_at"]

Wenn UpdateBase.return_defaults() gegen eine UPDATE-Anweisung verwendet wird, sucht es stattdessen nach Spalten, die mit den Parametern Column.onupdate oder Column.server_onupdate zugewiesen sind, wenn die Spalten konstruiert werden, die standardmäßig in die RETURNING-Klausel aufgenommen werden, falls keine expliziten Spalten angegeben wurden. Bei Verwendung gegen eine DELETE-Anweisung werden standardmäßig keine Spalten in RETURNING aufgenommen; sie müssen stattdessen explizit angegeben werden, da beim Fortfahren einer DELETE-Anweisung normalerweise keine Spalten geändert werden.

Neu in Version 2.0: UpdateBase.return_defaults() wird auch für DELETE-Anweisungen unterstützt und wurde von ValuesBase in UpdateBase verschoben.

Die Methode UpdateBase.return_defaults() ist gegenseitig exklusiv zur Methode UpdateBase.returning() und es werden Fehler während des SQL-Kompilierungsprozesses ausgelöst, wenn beide gleichzeitig für eine Anweisung verwendet werden. Die RETURNING-Klausel der INSERT-, UPDATE- oder DELETE-Anweisung wird daher immer nur von einer dieser Methoden gesteuert.

Die Methode UpdateBase.return_defaults() unterscheidet sich in folgenden Punkten von UpdateBase.returning()

  1. Die Methode UpdateBase.return_defaults() bewirkt, dass die Sammlung CursorResult.returned_defaults mit der ersten Zeile aus dem RETURNING-Ergebnis gefüllt wird. Dieses Attribut wird nicht gefüllt, wenn UpdateBase.returning() verwendet wird.

  2. UpdateBase.return_defaults() ist mit der bestehenden Logik zur Abfrage von automatisch generierten Primärschlüsselwerten kompatibel, die dann in das Attribut CursorResult.inserted_primary_key eingetragen werden. Im Gegensatz dazu hat die Verwendung von UpdateBase.returning() zur Folge, dass das Attribut CursorResult.inserted_primary_key nicht gefüllt wird.

  3. UpdateBase.return_defaults() kann gegen jedes Backend aufgerufen werden. Backends, die RETURNING nicht unterstützen, überspringen die Verwendung des Features, anstatt eine Ausnahme auszulösen, *es sei denn*, supplemental_cols wird übergeben. Der Rückgabewert von CursorResult.returned_defaults ist None für Backends, die RETURNING nicht unterstützen oder für die die Ziel-Table Table.implicit_returning auf False setzt.

  4. Eine INSERT-Anweisung, die mit executemany() aufgerufen wird, wird unterstützt, wenn der Backend-Datenbanktreiber die insertmanyvalues-Funktion unterstützt, die jetzt von den meisten in SQLAlchemy enthaltenen Backends unterstützt wird. Wenn executemany verwendet wird, geben die Accessoren CursorResult.returned_defaults_rows und CursorResult.inserted_primary_key_rows die eingefügten Standardwerte und Primärschlüssel zurück.

    Neu in Version 1.4: Hinzugefügt wurden die Accessoren CursorResult.returned_defaults_rows und CursorResult.inserted_primary_key_rows. In Version 2.0 wurde die zugrunde liegende Implementierung, die die Daten für diese Attribute abruft und befüllt, verallgemeinert, um von den meisten Backends unterstützt zu werden, während sie in 1.4 nur vom psycopg2-Treiber unterstützt wurde.

Parameter:

  • cols – optionale Liste von Spaltenschlüsselnamen oder Column, die als Filter für die abzurufenden Spalten dient.

  • supplemental_cols –

    optionale Liste von RETURNING-Ausdrücken, im gleichen Format, wie sie an die Methode UpdateBase.returning() übergeben würden. Wenn vorhanden, werden die zusätzlichen Spalten in die RETURNING-Klausel aufgenommen, und das CursorResult-Objekt wird beim Zurückgeben „zurückgespult“, sodass Methoden wie CursorResult.all() neue Zeilen zurückgeben, fast so, als ob die Anweisung direkt UpdateBase.returning() verwendet hätte. Im Gegensatz zur direkten Verwendung von UpdateBase.returning() ist jedoch die **Reihenfolge der Spalten undefiniert**, sodass sie nur über Namen oder Row._mapping-Schlüssel angesprochen werden können; sie können nicht zuverlässig positionsbasiert angesprochen werden.

    Neu in Version 2.0.

  • sort_by_parameter_order –

    Für ein Batch-INSERT, das gegen mehrere Parametersätze ausgeführt wird, organisieren Sie die Ergebnisse von RETURNING so, dass die zurückgegebenen Zeilen der Reihenfolge der übergebenen Parametersätze entsprechen. Dies gilt nur für eine executemany-Ausführung für unterstützte Dialekte und nutzt typischerweise die insertmanyvalues-Funktion.

    Neu in Version 2.0.10.

    Siehe auch

    RETURNING-Zeilen mit Parametersätzen korrelieren - Hintergrund zur Sortierung von RETURNING-Zeilen für Bulk-INSERT

Siehe auch

AktualisierenBasis.zurückgeben()

CursorResult.returned_defaults

CursorResult.returned_defaults_rows

CursorResult.inserted_primary_key

CursorResult.inserted_primary_key_rows

methode sqlalchemy.sql.expression.UpdateBase.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase

Fügt dieser Anweisung eine RETURNING oder eine äquivalente Klausel hinzu.

z. B.

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)

UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

Die Methode kann mehrmals aufgerufen werden, um der Liste der zurückzugebenden Ausdrücke neue Einträge hinzuzufügen.

Neu in Version 1.4.0b2: Die Methode kann mehrmals aufgerufen werden, um der Liste der zurückzugebenden Ausdrücke neue Einträge hinzuzufügen.

Die gegebene Sammlung von Spaltenausdrücken sollte von der Tabelle abgeleitet sein, die das Ziel von INSERT, UPDATE oder DELETE ist. Obwohl Column-Objekte typisch sind, können die Elemente auch Ausdrücke sein

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)

INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

Bei der Kompilierung wird eine RETURNING-Klausel oder ein Datenbankäquivalent in die Anweisung gerendert. Für INSERT und UPDATE sind die Werte die neu eingefügten/aktualisierten Werte. Für DELETE sind die Werte die der gelöschten Zeilen.

Bei der Ausführung sind die Werte der zurückzugebenden Spalten über das Ergebnisset verfügbar und können mit CursorResult.fetchone() und ähnlichen Methoden iteriert werden. Für DBAPIs, die das Zurückgeben von Werten nicht nativ unterstützen (z. B. cx_oracle), wird SQLAlchemy dieses Verhalten auf Ergebnisebene annähern, um ein angemessenes Maß an Verhaltensneutralität zu gewährleisten.

Beachten Sie, dass nicht alle Datenbanken/DBAPIs RETURNING unterstützen. Für Backends ohne Unterstützung wird bei der Kompilierung und/oder Ausführung eine Ausnahme ausgelöst. Für diejenigen, die es unterstützen, variiert die Funktionalität zwischen den Backends stark, einschließlich Einschränkungen bei executemany() und anderen Anweisungen, die mehrere Zeilen zurückgeben. Bitte lesen Sie die Dokumentation für die verwendete Datenbank, um die Verfügbarkeit von RETURNING zu ermitteln.

Parameter:

Siehe auch

UpdateBase.return_defaults() - eine alternative Methode, die auf effizientes Abrufen von serverseitigen Standardwerten und Triggern für Single-Row-INSERTs oder UPDATEs zugeschnitten ist.

INSERT…RETURNING - im SQLAlchemy Unified Tutorial

attribut sqlalchemy.sql.expression.UpdateBase.returning_column_descriptions

Gibt eine plugin-fähige Beschreibung der Spalten zurück, die von diesem DML-Konstrukt gegen RETURNING abgefragt werden, d.h. der Ausdrücke, die als Teil von UpdateBase.returning() festgelegt wurden.

Dieses Attribut ist generell nützlich bei der Verwendung des ORM, da eine erweiterte Struktur, die Informationen über zugeordnete Entitäten enthält, zurückgegeben wird. Der Abschnitt Entitäten und Spalten aus ORM-fähigen SELECT- und DML-Anweisungen inspizieren enthält weitere Hintergründe.

Für eine Core-Anweisung wird die von diesem Accessor zurückgegebene Struktur aus denselben Objekten abgeleitet, die auch vom UpdateBase.exported_columns-Accessor zurückgegeben werden.

>>> stmt = insert(user_table).returning(user_table.c.id, user_table.c.name)
>>> stmt.entity_description
[
    {
        "name": "id",
        "type": Integer,
        "expr": Column("id", Integer(), table=<user>, ...)
    },
    {
        "name": "name",
        "type": String(),
        "expr": Column("name", String(), table=<user>, ...)
    },
]

Neu in Version 1.4.33.

Siehe auch

AktualisierenBasis.entitätsbeschreibung

Select.column_descriptions - Entitätsinformationen für einen select()-Konstrukt

Entitäten und Spalten aus ORM-fähigen SELECT- und DML-Anweisungen inspizieren - ORM-Hintergrund

methode sqlalchemy.sql.expression.UpdateBase.with_dialect_options(**opt: Any) → Self

Fügt diesem INSERT/UPDATE/DELETE-Objekt Dialektoptionen hinzu.

z. B.

upd = table.update().dialect_options(mysql_limit=10)
methode sqlalchemy.sql.expression.UpdateBase.with_hint(text: str, selectable: _DMLTableArgument | None = None, dialect_name: str = '*') → Self

Fügt einen Tabellenhinweis für eine einzelne Tabelle zu dieser INSERT/UPDATE/DELETE-Anweisung hinzu.

Hinweis

UpdateBase.with_hint() gilt derzeit nur für Microsoft SQL Server. Für MySQL INSERT/UPDATE/DELETE-Hinweise verwenden Sie UpdateBase.prefix_with().

Der Text des Hinweises wird an der entsprechenden Stelle für das verwendete Datenbank-Backend gerendert, relativ zu der Table, die Gegenstand dieser Anweisung ist, oder optional zu der angegebenen Table, die als selectable-Argument übergeben wird.

Die Option dialect_name beschränkt die Wiedergabe eines bestimmten Hinweises auf ein bestimmtes Backend. Zum Beispiel, um einen Hinweis hinzuzufügen, der nur für SQL Server wirksam ist

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
Parameter:

  • text – Text des Hinweises.

  • selectable – optionale Table, die ein Element der FROM-Klausel innerhalb eines UPDATE oder DELETE angibt, das Gegenstand des Hinweises ist - gilt nur für bestimmte Backends.

  • dialect_name – Standardmäßig *. Wenn als Name eines bestimmten Dialekts angegeben, werden diese Hinweise nur angewendet, wenn dieser Dialekt verwendet wird.

klasse sqlalchemy.sql.expression.ValuesBase

Bietet Unterstützung für ValuesBase.values() für INSERT- und UPDATE-Konstrukte.

Mitglieder

select, values()

Klassensignatur

class sqlalchemy.sql.expression.ValuesBase (sqlalchemy.sql.expression.UpdateBase)

attribut sqlalchemy.sql.expression.ValuesBase.select: Select[Any] | None = None

SELECT-Anweisung für INSERT .. FROM SELECT

methode sqlalchemy.sql.expression.ValuesBase.values(*args: _DMLColumnKeyMapping[Any] | Sequence[Any], **kwargs: Any) → Self

Gibt eine feste VALUES-Klausel für eine INSERT-Anweisung oder die SET-Klausel für ein UPDATE an.

Beachten Sie, dass die Konstrukte Insert und Update eine pro-Ausführungszeit-Formatierung der VALUES- und/oder SET-Klauseln unterstützen, basierend auf den Argumenten, die an Connection.execute() übergeben werden. Die Methode ValuesBase.values() kann jedoch verwendet werden, um einen bestimmten Parametersatz in die Anweisung zu "fixieren".

Mehrere Aufrufe von ValuesBase.values() erzeugen ein neues Konstrukt, wobei jede mit der modifizierten Parameterliste die neuen Parameter enthält, die gesendet wurden. Im typischen Fall eines einzelnen Parameter-Wörterbuchs ersetzen die neu übergebenen Schlüssel dieselben Schlüssel im vorherigen Konstrukt. Im Fall eines listenbasierten "Mehrfachwerte"-Konstrukts wird jede neue Werteliste an die bestehende Liste von Werten angehängt.

Parameter:

  • **kwargs –

    Schlüssel-Wert-Paare, die den String-Schlüssel einer Column, zugeordnet dem Wert, der in die VALUES- oder SET-Klausel gerendert werden soll.

    users.insert().values(name="some name")

users.update().where(users.c.id == 5).values(name="some name")

  • *args –

    Als Alternative zur Übergabe von Schlüssel/Wert-Paaren kann ein Wörterbuch, ein Tupel oder eine Liste von Wörterbüchern oder Tupeln als einzelnes positionsgebundenes Argument übergeben werden, um die VALUES- oder SET-Klausel der Anweisung zu bilden. Die akzeptierten Formen variieren je nachdem, ob es sich um ein Insert- oder ein Update-Konstrukt handelt.

    Für ein Insert- oder Update-Konstrukt kann ein einzelnes Wörterbuch übergeben werden, das sich genauso verhält wie die kwargs-Form.

    users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})

    Ebenso für beide Formen, aber typischer für das Insert-Konstrukt, wird auch ein Tupel akzeptiert, das einen Eintrag für jede Spalte in der Tabelle enthält.

    users.insert().values((5, "some name"))

    Das Insert-Konstrukt unterstützt auch die Übergabe einer Liste von Wörterbüchern oder vollständigen Tabellen-Tupeln, was auf dem Server die weniger gebräuchliche SQL-Syntax von "mehreren Werten" rendert - diese Syntax wird von Backends wie SQLite, PostgreSQL, MySQL unterstützt, aber nicht unbedingt von anderen.

    users.insert().values(
    [
        {"name": "some name"},
        {"name": "some other name"},
        {"name": "yet another name"},
    ]
)

    Die obige Form würde eine Anweisung mit mehreren VALUES rendern, ähnlich wie

    INSERT INTO users (name) VALUES
                (:name_1),
                (:name_2),
                (:name_3)

    Es ist wichtig zu beachten, dass **die Übergabe mehrerer Werte NICHT dasselbe ist wie die Verwendung des traditionellen executemany()-Formats**. Die obige Syntax ist eine **spezielle** Syntax, die nicht üblicherweise verwendet wird. Um eine INSERT-Anweisung gegen mehrere Zeilen auszugeben, ist die normale Methode, eine Liste mit mehreren Werten an die Methode Connection.execute() zu übergeben, die von allen Datenbank-Backends unterstützt wird und im Allgemeinen effizienter für eine sehr große Anzahl von Parametern ist.

    Siehe auch

    Senden mehrerer Parameter - eine Einführung in die traditionelle Core-Methode des Aufrufs mehrerer Parametersätze für INSERTs und andere Anweisungen.

    Der UPDATE-Konstrukt unterstützt auch das Rendern der SET-Parameter in einer bestimmten Reihenfolge. Für diese Funktion verweisen Sie auf die Methode Update.ordered_values().