ORM Abfragehandbuch

Diese Seite ist Teil des ORM Querying Guide.

Vorher: ORM API Features für Abfragen

Legacy Query API

Über die Legacy Query API

Diese Seite enthält die Python-generierte Dokumentation für das Konstrukt Query, das viele Jahre lang die einzige SQL-Schnittstelle bei der Arbeit mit SQLAlchemy ORM war. Ab Version 2.0 ist ein völlig neuer Arbeitsansatz der Standard, bei dem das gleiche select()-Konstrukt, das für Core funktioniert, auch für ORM gut funktioniert und eine konsistente Schnittstelle zum Erstellen von Abfragen bietet.

Für jede Anwendung, die vor der API von Version 2.0 auf SQLAlchemy ORM aufgebaut ist, stellt die Query API normalerweise den Großteil des Datenbankzugriffscodes innerhalb einer Anwendung dar. Daher wird der Großteil der Query API **nicht aus SQLAlchemy entfernt**. Das Query-Objekt übersetzt sich im Hintergrund selbst in ein select()-Objekt im Stil von 2.0, wenn das Query-Objekt ausgeführt wird, sodass es jetzt nur noch eine sehr dünne Adapter-API ist.

Einen Leitfaden zur Migration einer auf Query basierenden Anwendung auf den Stil von 2.0 finden Sie unter 2.0 Migration - ORM-Nutzung.

Für eine Einführung in das Schreiben von SQL für ORM-Objekte im Stil von 2.0 beginnen Sie mit dem SQLAlchemy Unified Tutorial. Zusätzliche Referenzen für Abfragen im Stil von 2.0 finden Sie unter ORM Querying Guide.

Das Query-Objekt

Query wird im Kontext einer gegebenen Session mithilfe der Methode Session.query() erstellt.

q = session.query(SomeMappedClass)

Im Folgenden finden Sie die vollständige Schnittstelle für das Query-Objekt.

Objektname	Beschreibung
Query	SQL-Konstruktionsobjekt auf ORM-Ebene.

class sqlalchemy.orm.Query

SQL-Konstruktionsobjekt auf ORM-Ebene.

Legacy-Funktion

Das ORM Query-Objekt ist ab SQLAlchemy 2.0 ein Legacy-Konstrukt. Sehen Sie die Hinweise oben auf Legacy Query API für einen Überblick, einschließlich Links zur Migrationsdokumentation.

Query-Objekte werden normalerweise zunächst über die Methode Session.query() einer Session generiert, und in selteneren Fällen durch direkte Instanziierung von Query und Verknüpfung mit einer Session über die Methode Query.with_session().

Mitglieder

__init__(), add_column(), add_columns(), add_entity(), all(), apply_labels(), as_scalar(), autoflush(), column_descriptions, correlate(), count(), cte(), delete(), distinct(), enable_assertions(), enable_eagerloads(), except_(), except_all(), execution_options(), exists(), filter(), filter_by(), first(), from_statement(), get(), get_children(), get_execution_options(), get_label_style, group_by(), having(), instances(), intersect(), intersect_all(), is_single_entity, join(), label(), lazy_loaded_from, limit(), merge_result(), offset(), one(), one_or_none(), only_return_tuples(), options(), order_by(), outerjoin(), params(), populate_existing(), prefix_with(), reset_joinpoint(), scalar(), scalar_subquery(), select_from(), selectable, set_label_style(), slice(), statement, subquery(), suffix_with(), tuples(), union(), union_all(), update(), value(), values(), where(), whereclause, with_entities(), with_for_update(), with_hint(), with_labels(), with_parent(), with_session(), with_statement_hint(), with_transformation(), yield_per()

Klassensignatur

class sqlalchemy.orm.Query (sqlalchemy.sql.expression._SelectFromElements, sqlalchemy.sql.annotation.SupportsCloneAnnotations, sqlalchemy.sql.expression.HasPrefixes, sqlalchemy.sql.expression.HasSuffixes, sqlalchemy.sql.expression.HasHints, sqlalchemy.event.registry.EventTarget, sqlalchemy.log.Identified, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.Executable, typing.Generic)

method sqlalchemy.orm.Query.__init__(entities: _ColumnsClauseArgument[Any] | Sequence[_ColumnsClauseArgument[Any]], session: Session | None = None)

Erstellen Sie eine Query direkt.

Z. B.

q = Query([User, Address], session=some_session)

Das Obige ist äquivalent zu

q = some_session.query(User, Address)

Parameter:

• entities – Eine Sequenz von Entitäten und/oder SQL-Ausdrücken.

• session – Eine Session, mit der die Query verknüpft wird. Optional; eine Query kann auch generativ über die Methode Query.with_session() mit einer Session verknüpft werden.

Siehe auch

Session.query()

Query.with_session()

method sqlalchemy.orm.Query.add_column(column: _ColumnExpressionArgument[Any]) → Query[Any]

Fügt einen Spaltenausdruck zur Liste der zurückzugebenden Ergebnisspalten hinzu.

Veraltet seit Version 1.4: Query.add_column() ist veraltet und wird in einer zukünftigen Version entfernt. Bitte verwenden Sie Query.add_columns()

method sqlalchemy.orm.Query.add_columns(*column: _ColumnExpressionArgument[Any]) → Query[Any]

Fügt einen oder mehrere Spaltenausdrücke zur Liste der zurückzugebenden Ergebnisspalten hinzu.

Siehe auch

Select.add_columns() - mit Version 2 vergleichbare Methode.

method sqlalchemy.orm.Query.add_entity(entity: _EntityType[Any], alias: Alias | Subquery | None = None) → Query[Any]

Fügt eine gemappte Entität zur Liste der zurückzugebenden Ergebnisspalten hinzu.

Siehe auch

Select.add_columns() - mit Version 2 vergleichbare Methode.

method sqlalchemy.orm.Query.all() → List[_T]

Gibt die von dieser Query dargestellten Ergebnisse als Liste zurück.

Dies führt zur Ausführung der zugrunde liegenden SQL-Anweisung.

Warnung

Das Query-Objekt wird, wenn es gebeten wird, eine Sequenz oder einen Iterator zurückzugeben, der vollständige ORM-gemappte Entitäten enthält, **Einträge anhand des Primärschlüssels deduplizieren**. Weitere Details finden Sie in den FAQs.

Siehe auch

Meine Abfrage gibt nicht die gleiche Anzahl von Objekten zurück wie query.count() mir mitteilt - warum?

Siehe auch

Result.all() - mit Version 2 vergleichbare Methode.

Result.scalars() - mit Version 2 vergleichbare Methode.

method sqlalchemy.orm.Query.apply_labels() → Self

Veraltet seit Version 2.0: Die Methoden Query.with_labels() und Query.apply_labels() gelten seit der 1.x-Reihe von SQLAlchemy als Legacy und werden in 2.0 zu Legacy-Konstrukten. Verwenden Sie stattdessen set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL).

method sqlalchemy.orm.Query.as_scalar() → ScalarSelect[Any]

Gibt die vollständige SELECT-Anweisung, die von dieser Query repräsentiert wird, als skalare Unterabfrage zurück.

Veraltet seit Version 1.4: Die Methode Query.as_scalar() ist veraltet und wird in einer zukünftigen Version entfernt. Bitte beachten Sie Query.scalar_subquery().

method sqlalchemy.orm.Query.autoflush(setting: bool) → Self

Gibt eine Query mit einer bestimmten „autoflush“-Einstellung zurück.

Ab SQLAlchemy 1.4 ist die Methode Query.autoflush() äquivalent zur Verwendung der Ausführungsoption autoflush auf ORM-Ebene. Weitere Informationen zu dieser Option finden Sie im Abschnitt Autoflush.

attribute sqlalchemy.orm.Query.column_descriptions

Gibt Metadaten zu den Spalten zurück, die von dieser Query zurückgegeben würden.

Das Format ist eine Liste von Dictionaries.

user_alias = aliased(User, name="user2")
q = sess.query(User, User.id, user_alias)

# this expression:
q.column_descriptions

# would return:
[
    {
        "name": "User",
        "type": User,
        "aliased": False,
        "expr": User,
        "entity": User,
    },
    {
        "name": "id",
        "type": Integer(),
        "aliased": False,
        "expr": User.id,
        "entity": User,
    },
    {
        "name": "user2",
        "type": User,
        "aliased": True,
        "expr": user_alias,
        "entity": user_alias,
    },
]

Siehe auch

Diese API ist auch mit Abfragen im Stil von 2.0 verfügbar, dokumentiert unter

• Inspektion von Entitäten und Spalten aus ORM-fähigen SELECT- und DML-Anweisungen

• Select.column_descriptions

method sqlalchemy.orm.Query.correlate(*fromclauses: Literal[None, False] | FromClauseRole | Type[Any] | Inspectable[_HasClauseElement[Any]] | _HasClauseElement[Any]) → Self

Gibt ein Query-Konstrukt zurück, das die gegebenen FROM-Klauseln mit denen einer umschließenden Query oder select() korreliert.

Die Methode hier akzeptiert zugeordnete Klassen, aliased()-Konstrukte und Mapper-Konstrukte als Argumente, die in Ausdruckskonstrukte aufgelöst werden, zusätzlich zu entsprechenden Ausdruckskonstrukten.

Die Korrelationsargumente werden letztendlich an Select.correlate() übergeben, nachdem sie in Ausdruckskonstrukte umgewandelt wurden.

Die Korrelationsargumente werden wirksam in Fällen, in denen Query.from_self() verwendet wird, oder wenn eine Unterabfrage, wie sie von Query.subquery() zurückgegeben wird, in ein anderes select()-Konstrukt eingebettet ist.

Siehe auch

Select.correlate() - V2-äquivalente Methode.

method sqlalchemy.orm.Query.count() → int

Gibt die Anzahl der Zeilen zurück, die die von dieser Query gebildete SQL-Abfrage zurückgeben würde.

Dies generiert die SQL für diese Query wie folgt

SELECT count(1) AS count_1 FROM (
    SELECT <rest of query follows...>
) AS anon_1

Die obige SQL-Abfrage gibt eine einzelne Zeile zurück, die den aggregierten Wert der COUNT-Funktion darstellt; die Methode Query.count() gibt dann diesen einzelnen ganzzahligen Wert zurück.

Warnung

Es ist wichtig zu beachten, dass der von count() zurückgegebene Wert *nicht dasselbe ist wie die Anzahl der ORM-Objekte, die diese Query mit einer Methode wie .all() zurückgeben würde*. Das Query-Objekt dedupliziert Einträge basierend auf dem Primärschlüssel, wenn es angewiesen wird, vollständige Entitäten zurückzugeben, was bedeutet, dass, wenn derselbe Primärschlüsselwert mehrmals in den Ergebnissen vorkommt, nur ein Objekt dieses Primärschlüssels vorhanden ist. Dies gilt nicht für Abfragen, die auf einzelne Spalten abzielen.

Siehe auch

Meine Abfrage gibt nicht die gleiche Anzahl von Objekten zurück wie query.count() mir mitteilt - warum?

Für eine detaillierte Steuerung spezifischer Spalten zum Zählen, um die Verwendung einer Unterabfrage zu überspringen oder die FROM-Klausel anderweitig zu steuern, oder um andere Aggregatfunktionen zu verwenden, verwenden Sie expression.func-Ausdrücke in Verbindung mit Session.query(), d. h.

from sqlalchemy import func

# count User records, without
# using a subquery.
session.query(func.count(User.id))

# return count of user "id" grouped
# by "name"
session.query(func.count(User.id)).group_by(User.name)

from sqlalchemy import distinct

# count distinct "name" values
session.query(func.count(distinct(User.name)))

Siehe auch

Migration 2.0 - ORM-Nutzung

method sqlalchemy.orm.Query.cte(name: str | None = None, recursive: bool = False, nesting: bool = False) → CTE

Gibt die vollständige SELECT-Anweisung, die von dieser Query dargestellt wird, als Common Table Expression (CTE) zurück.

Parameter und Verwendung sind identisch mit denen der Methode SelectBase.cte(). Weitere Details finden Sie dort.

Hier ist das PostgreSQL WITH RECURSIVE Beispiel. Beachten Sie, dass in diesem Beispiel die CTE included_parts und ihr Alias incl_alias Core-Selectables sind, was bedeutet, dass auf die Spalten über das Attribut .c. zugegriffen wird. Das Objekt parts_alias ist eine Instanz von aliased() der Entität Part, sodass spaltenzugeordnete Attribute direkt verfügbar sind.

from sqlalchemy.orm import aliased


class Part(Base):
    __tablename__ = "part"
    part = Column(String, primary_key=True)
    sub_part = Column(String, primary_key=True)
    quantity = Column(Integer)


included_parts = (
    session.query(Part.sub_part, Part.part, Part.quantity)
    .filter(Part.part == "our part")
    .cte(name="included_parts", recursive=True)
)

incl_alias = aliased(included_parts, name="pr")
parts_alias = aliased(Part, name="p")
included_parts = included_parts.union_all(
    session.query(
        parts_alias.sub_part, parts_alias.part, parts_alias.quantity
    ).filter(parts_alias.part == incl_alias.c.sub_part)
)

q = session.query(
    included_parts.c.sub_part,
    func.sum(included_parts.c.quantity).label("total_quantity"),
).group_by(included_parts.c.sub_part)

Siehe auch

Select.cte() - V2-äquivalente Methode.

method sqlalchemy.orm.Query.delete(synchronize_session: SynchronizeSessionArgument = 'auto', delete_args: Dict[Any, Any] | None = None) → int

Führt ein DELETE mit einer beliebigen WHERE-Klausel durch.

Löscht Zeilen, die von dieser Abfrage gefunden wurden, aus der Datenbank.

Z. B.

sess.query(User).filter(User.age == 25).delete(synchronize_session=False)

sess.query(User).filter(User.age == 25).delete(
    synchronize_session="evaluate"
)

Warnung

Siehe den Abschnitt ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen für wichtige Hinweise und Warnungen, einschließlich Einschränkungen bei der Verwendung von Massen-UPDATEs und -DELETEs mit Mapper-Vererbungskonfigurationen.

Parameter:

• synchronize_session – wählt die Strategie zur Aktualisierung der Attribute von Objekten in der Sitzung. Siehe den Abschnitt ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen für eine Erörterung dieser Strategien.

• delete_args –

  Optionales Wörterbuch, das, falls vorhanden, an das zugrunde liegende delete()-Konstrukt als **kw für das Objekt übergeben wird. Kann verwendet werden, um dialektspezifische Argumente wie mysql_limit zu übergeben.

  Neu in Version 2.0.37.

Gibt zurück:

die Anzahl der gefundenen Zeilen, wie sie von der „Zeilenanzahl“-Funktion der Datenbank zurückgegeben wird.

Siehe auch

ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen

method sqlalchemy.orm.Query.distinct(*expr: _ColumnExpressionArgument[Any]) → Self

Wendet ein DISTINCT auf die Abfrage an und gibt die neu resultierende Query zurück.

Hinweis

Der distinct()-Aufruf auf ORM-Ebene enthält Logik, die automatisch Spalten aus der ORDER BY-Klausel der Abfrage zur Spaltenklausel der SELECT-Anweisung hinzufügt, um den gängigen Bedarf des Datenbank-Backends zu erfüllen, dass ORDER BY-Spalten Teil der SELECT-Liste sind, wenn DISTINCT verwendet wird. Diese Spalten werden jedoch *nicht* zur Liste der tatsächlich von der Query abgerufenen Spalten hinzugefügt, beeinflussen also die Ergebnisse nicht. Die Spalten werden jedoch bei Verwendung des Query.statement-Accessors weitergegeben.

Veraltet seit Version 2.0: Diese Logik ist veraltet und wird in SQLAlchemy 2.0 entfernt. Siehe Verwendung von DISTINCT mit zusätzlichen Spalten, aber nur die Entität auswählen für eine Beschreibung dieses Anwendungsfalls in 2.0.

Siehe auch

Select.distinct() - V2-äquivalente Methode.

Parameter:

*expr –

optionale Spaltenausdrücke. Wenn vorhanden, rendert der PostgreSQL-Dialekt ein DISTINCT ON (<expressions>)-Konstrukt.

Veraltet seit Version 1.4: Die Verwendung von *expr in anderen Dialekten ist veraltet und wird in einer zukünftigen Version CompileError auslösen.

method sqlalchemy.orm.Query.enable_assertions(value: bool) → Self

Steuert, ob Assertions generiert werden.

Wenn auf False gesetzt, wird die zurückgegebene Query ihren Zustand vor bestimmten Operationen nicht überprüfen, einschließlich, dass LIMIT/OFFSET nicht angewendet wurde, wenn filter() aufgerufen wird, kein Kriterium vorhanden ist, wenn get() aufgerufen wird, und keine „from_statement()“ existiert, wenn filter()/order_by()/group_by() etc. aufgerufen wird. Dieser permissivere Modus wird von benutzerdefinierten Query-Unterklassen verwendet, um Kriterien oder andere Modifikatoren außerhalb der üblichen Nutzungsmuster anzugeben.

Es sollte darauf geachtet werden, dass das Nutzungsmuster überhaupt möglich ist. Eine durch from_statement() angewendete Anweisung überschreibt beispielsweise alle durch filter() oder order_by() festgelegten Kriterien.

method sqlalchemy.orm.Query.enable_eagerloads(value: bool) → Self

Steuert, ob Eager-Joins und Unterabfragen gerendert werden.

Wenn auf False gesetzt, rendert die zurückgegebene Query keine Eager-Joins, unabhängig von den Optionen joinedload(), subqueryload() oder den Mapper-Level-Konfigurationen lazy='joined'/lazy='subquery'.

Dies wird hauptsächlich beim Einbetten der Anweisung der Query in eine Unterabfrage oder ein anderes auswählbares Element verwendet, oder bei der Verwendung von Query.yield_per().

method sqlalchemy.orm.Query.except_(*q: Query) → Self

Erzeugt ein EXCEPT dieser Query gegen eine oder mehrere Queries.

Funktioniert genauso wie Query.union(). Siehe diese Methode für Anwendungsbeispiele.

Siehe auch

Select.except_() - V2-äquivalente Methode.

method sqlalchemy.orm.Query.except_all(*q: Query) → Self

Erzeugt ein EXCEPT ALL dieser Query gegen eine oder mehrere Queries.

Funktioniert genauso wie Query.union(). Siehe diese Methode für Anwendungsbeispiele.

Siehe auch

Select.except_all() - V2-äquivalente Methode.

method sqlalchemy.orm.Query.execution_options(**kwargs: Any) → Self

Legt nicht-SQL-Optionen fest, die während der Ausführung wirksam werden.

Hier zulässige Optionen umfassen alle, die von Connection.execution_options() akzeptiert werden, sowie eine Reihe von ORM-spezifischen Optionen

populate_existing=True - entspricht der Verwendung von Query.populate_existing()

autoflush=True|False - entspricht der Verwendung von Query.autoflush()

yield_per=<value> - entspricht der Verwendung von Query.yield_per()

Beachten Sie, dass die Ausführungsoption stream_results automatisch aktiviert wird, wenn die Methode oder Ausführungsoption Query.yield_per() verwendet wird.

Neu in Version 1.4: - ORM-Optionen zu Query.execution_options() hinzugefügt

Die Ausführungsoptionen können auch auf einer pro Ausführungsebene festgelegt werden, wenn 2.0-Stil-Queries über den Parameter Session.execution_options verwendet werden.

Warnung

Der Parameter Connection.execution_options.stream_results sollte nicht auf der Ebene einzelner ORM-Anweisungsausführungen verwendet werden, da die Session keine Objekte aus verschiedenen Schema-Translate-Maps innerhalb einer einzelnen Sitzung verfolgen wird. Für mehrere Schema-Translate-Maps innerhalb des Geltungsbereichs einer einzelnen Session siehe Horizontales Sharding.

Siehe auch

Verwendung von serverseitigen Cursern (auch bekannt als Stream-Ergebnisse)

Query.get_execution_options()

Select.execution_options() - V2-äquivalente Methode.

method sqlalchemy.orm.Query.exists() → Exists

Eine Komfortmethode, die eine Abfrage in eine EXISTS-Unterabfrage vom Typ EXISTS (SELECT 1 FROM ... WHERE ...) umwandelt.

z. B.

q = session.query(User).filter(User.name == "fred")
session.query(q.exists())

SQL, ähnlich wie

SELECT EXISTS (
    SELECT 1 FROM users WHERE users.name = :name_1
) AS anon_1

Der EXISTS-Konstrukt wird normalerweise in der WHERE-Klausel verwendet

session.query(User.id).filter(q.exists()).scalar()

Beachten Sie, dass einige Datenbanken wie SQL Server einen EXISTS-Ausdruck nicht in der Spaltenklausel eines SELECT zulassen. Um einen einfachen booleschen Wert basierend auf EXISTS als WHERE auszuwählen, verwenden Sie literal()

from sqlalchemy import literal

session.query(literal(True)).filter(q.exists()).scalar()

Siehe auch

Select.exists() - V2 vergleichbare Methode.

method sqlalchemy.orm.Query.filter(*criterion: _ColumnExpressionArgument[bool]) → Self

Wendet das gegebene Filterkriterium auf eine Kopie dieser Query unter Verwendung von SQL-Ausdrücken an.

z. B.

session.query(MyClass).filter(MyClass.name == "some name")

Mehrere Kriterien können durch Kommas getrennt angegeben werden; der Effekt ist, dass sie mit der Funktion and_() verbunden werden.

session.query(MyClass).filter(MyClass.name == "some name", MyClass.id > 5)

Das Kriterium ist jedes SQL-Ausdrucksobjekt, das für die WHERE-Klausel eines SELECT anwendbar ist. String-Ausdrücke werden über das text()-Konstrukt in SQL-Ausdruckskonstrukte umgewandelt.

Siehe auch

Query.filter_by() - Filtern nach Schlüsselwortausdrücken.

Select.where() - V2-äquivalente Methode.

method sqlalchemy.orm.Query.filter_by(**kwargs: Any) → Self

Wendet das gegebene Filterkriterium auf eine Kopie dieser Query unter Verwendung von Schlüsselwortausdrücken an.

z. B.

session.query(MyClass).filter_by(name="some name")

Mehrere Kriterien können durch Kommas getrennt angegeben werden; der Effekt ist, dass sie mit der Funktion and_() verbunden werden.

session.query(MyClass).filter_by(name="some name", id=5)

Die Schlüsselwortausdrücke werden aus der primären Entität der Abfrage oder der letzten Entität, die das Ziel eines Aufrufs von Query.join() war, extrahiert.

Siehe auch

Query.filter() - Filtern nach SQL-Ausdrücken.

Select.filter_by() - V2 vergleichbare Methode.

method sqlalchemy.orm.Query.first() → _T | None

Gibt das erste Ergebnis dieser Query zurück oder None, wenn das Ergebnis keine Zeile enthält.

first() wendet ein Limit von eins innerhalb der generierten SQL an, sodass auf der Serverseite nur eine primäre Entitätszeile generiert wird (beachten Sie, dass diese aus mehreren Ergebniszeilen bestehen kann, wenn joined-loaded Collections vorhanden sind).

Der Aufruf von Query.first() führt zur Ausführung der zugrunde liegenden Abfrage.

Siehe auch

Query.one()

Query.one_or_none()

Result.first() - V2 vergleichbare Methode.

Result.scalars() - mit Version 2 vergleichbare Methode.

method sqlalchemy.orm.Query.from_statement(statement: ExecutableReturnsRows) → Self

Führt die gegebene SELECT-Anweisung aus und gibt die Ergebnisse zurück.

Diese Methode umgeht die gesamte interne Anweisungsübersetzung, und die Anweisung wird ohne Änderung ausgeführt.

Die Anweisung ist typischerweise entweder ein text()- oder select()-Konstrukt und sollte die für die von dieser Query dargestellte Entitätsklasse geeignete Menge an Spalten zurückgeben.

Siehe auch

Select.from_statement() - V2 vergleichbare Methode.

method sqlalchemy.orm.Query.get(ident: _PKIdentityArgument) → Any | None

Gibt eine Instanz basierend auf der angegebenen Primärschlüssel-ID zurück, oder None, wenn sie nicht gefunden wurde.

Veraltet seit Version 2.0: Die Methode Query.get() gilt ab der 1.x-Serie von SQLAlchemy als Legacy und wird in 2.0 zu einem Legacy-Konstrukt. Die Methode ist jetzt verfügbar als Session.get() (Hintergrund zu SQLAlchemy 2.0 unter: SQLAlchemy 2.0 - Hauptmigrationsleitfaden)

Z. B.

my_user = session.query(User).get(5)

some_object = session.query(VersionedFoo).get((5, 10))

some_object = session.query(VersionedFoo).get({"id": 5, "version_id": 10})

Query.get() ist besonders, da sie direkten Zugriff auf die Identitätskarte der besitzenden Session bietet. Wenn die gegebene Primärschlüsselkennung in der lokalen Identitätskarte vorhanden ist, wird das Objekt direkt aus dieser Sammlung zurückgegeben und keine SQL-Anweisung ausgegeben, es sei denn, das Objekt wurde vollständig als abgelaufen markiert. Wenn nicht vorhanden, wird ein SELECT ausgeführt, um das Objekt zu finden.

Query.get() führt auch eine Prüfung durch, ob das Objekt in der Identitätskarte vorhanden und als abgelaufen markiert ist – ein SELECT wird ausgegeben, um das Objekt zu aktualisieren und sicherzustellen, dass die Zeile noch vorhanden ist. Wenn nicht, wird ObjectDeletedError ausgelöst.

Query.get() wird nur verwendet, um eine einzelne zugeordnete Instanz zurückzugeben, nicht mehrere Instanzen oder einzelne Spaltenkonstrukte, und streng genommen auf einen einzelnen Primärschlüsselwert. Die ursprüngliche Query muss auf diese Weise konstruiert werden, d. h. gegen eine einzelne zugeordnete Entität, ohne zusätzliche Filterkriterien. Ladeoptionen über Query.options() können jedoch angewendet werden und werden verwendet, wenn das Objekt noch nicht lokal vorhanden ist.

Parameter:

ident –

Ein Skalar, Tupel oder Wörterbuch, das den Primärschlüssel darstellt. Für einen zusammengesetzten (z. B. mehrspaltigen) Primärschlüssel sollte ein Tupel oder Wörterbuch übergeben werden.

Für einen einspaltigen Primärschlüssel ist die skalare Aufrufform in der Regel die praktikabelste. Wenn der Primärschlüssel einer Zeile der Wert „5“ ist, sieht der Aufruf wie folgt aus

my_object = query.get(5)

Das Tupel-Format enthält Primärschlüsselwerte, typischerweise in der Reihenfolge, in der sie den zugeordneten Spalten des Table-Objekts entsprechen, oder, falls der Mapper.primary_key-Konfigurationsparameter verwendet wurde, in der Reihenfolge, die für diesen Parameter verwendet wurde. Wenn beispielsweise der Primärschlüssel einer Zeile durch die Ganzzahlen "5, 10" dargestellt wird, würde der Aufruf wie folgt aussehen

my_object = query.get((5, 10))

Die Wörterbuchform sollte als Schlüssel die zugeordneten Attributnamen enthalten, die jedem Element des Primärschlüssels entsprechen. Wenn die zugeordnete Klasse die Attribute id und version_id als Attribute hat, die den Primärschlüsselwert des Objekts speichern, sähe der Aufruf wie folgt aus

my_object = query.get({"id": 5, "version_id": 10})

Neu in Version 1.3: Die Methode Query.get() akzeptiert nun optional ein Wörterbuch von Attributnamen zu Werten, um einen Primärschlüsselidentifikator anzugeben.

Gibt zurück:

Die Objektinstanz oder None.

Methode sqlalchemy.orm.Query.get_children(*, omit_attrs: Tuple[str, ...] = (), **kw: Any) → Iterable[HasTraverseInternals]

geerbt von der HasTraverseInternals.get_children() Methode von HasTraverseInternals

Gibt direkte Kind-Elemente HasTraverseInternals dieses HasTraverseInternals zurück.

Dies wird für die Besuchs-Traversal verwendet.

**kw kann Flags enthalten, die die zurückgegebene Sammlung ändern, z. B. um eine Teilmenge von Elementen zurückzugeben, um größere Traversierungen zu reduzieren, oder um Kind-Elemente aus einem anderen Kontext zurückzugeben (z. B. Schema-Ebene Sammlungen anstelle von Klausel-Ebene).

Methode sqlalchemy.orm.Query.get_execution_options() → _ImmutableExecuteOptions

Ruft die nicht-SQL-Optionen ab, die während der Ausführung wirksam werden.

Neu in Version 1.3.

Siehe auch

Query.execution_options()

Select.get_execution_options() - mit v2 vergleichbare Methode.

Attribut sqlalchemy.orm.Query.get_label_style

Ruft den aktuellen Label-Stil ab.

Neu in Version 1.4.

Siehe auch

Select.get_label_style() - mit v2 vergleichbare Methode.

Methode sqlalchemy.orm.Query.group_by(_Query__first: Literal[None, False, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self

Wendet ein oder mehrere GROUP BY-Kriterien auf die Abfrage an und gibt die neu resultierende Query zurück.

Alle vorhandenen GROUP BY-Einstellungen können durch Übergabe von None unterdrückt werden - dies unterdrückt auch jede auf den Mappern konfigurierte GROUP BY-Anweisung.

Siehe auch

Diese Abschnitte beschreiben GROUP BY in Bezug auf die 2.0-Style-Aufrufe, gelten aber auch für Query.

Aggregatfunktionen mit GROUP BY / HAVING - im SQLAlchemy Unified Tutorial

Sortieren oder Gruppieren nach einem Label - im SQLAlchemy Unified Tutorial

Select.group_by() - mit v2 vergleichbare Methode.

Methode sqlalchemy.orm.Query.having(*having: _ColumnExpressionArgument[bool]) → Self

Wendet ein HAVING-Kriterium auf die Abfrage an und gibt die neu resultierende Query zurück.

Query.having() wird in Verbindung mit Query.group_by() verwendet.

HAVING-Kriterien ermöglichen Filter für Aggregatfunktionen wie COUNT, SUM, AVG, MAX und MIN, z. B.

q = (
    session.query(User.id)
    .join(User.addresses)
    .group_by(User.id)
    .having(func.count(Address.id) > 2)
)

Siehe auch

Select.having() - mit v2 vergleichbare Methode.

Methode sqlalchemy.orm.Query.instances(result_proxy: CursorResult[Any], context: QueryContext | None = None) → Any

Gibt ein ORM-Ergebnis zurück, das aus einem CursorResult und einem QueryContext besteht.

Seit Version 2.0 veraltet: Die Methode Query.instances() ist veraltet und wird in einer zukünftigen Version entfernt. Verwenden Sie stattdessen die Methode Select.from_statement() oder den Konstruktor aliased() in Verbindung mit Session.execute().

Methode sqlalchemy.orm.Query.intersect(*q: Query) → Self

Erzeugt einen INTERSECT dieser Abfrage gegen eine oder mehrere Abfragen.

Funktioniert genauso wie Query.union(). Siehe diese Methode für Anwendungsbeispiele.

Siehe auch

Select.intersect() - mit v2 vergleichbare Methode.

Methode sqlalchemy.orm.Query.intersect_all(*q: Query) → Self

Erzeugt einen INTERSECT ALL dieser Abfrage gegen eine oder mehrere Abfragen.

Funktioniert genauso wie Query.union(). Siehe diese Methode für Anwendungsbeispiele.

Siehe auch

Select.intersect_all() - mit v2 vergleichbare Methode.

Attribut sqlalchemy.orm.Query.is_single_entity

Gibt an, ob diese Query Tupel oder einzelne Entitäten zurückgibt.

Gibt True zurück, wenn diese Abfrage für jede Instanz in ihrer Ergebnisliste eine einzelne Entität zurückgibt, und False, wenn diese Abfrage für jedes Ergebnis ein Tupel von Entitäten zurückgibt.

Neu ab Version 1.3.11.

Siehe auch

Query.only_return_tuples()

Methode sqlalchemy.orm.Query.join(target: _JoinTargetArgument, onclause: _OnClauseArgument | None = None, *, isouter: bool = False, full: bool = False) → Self

Erstellt einen SQL JOIN gegen das Kriterium eines Query-Objekts und wendet es generativ an, wobei die neu resultierende Query zurückgegeben wird.

Einfache Beziehungs-Joins

Betrachten Sie eine Zuordnung zwischen zwei Klassen User und Address, mit einer Beziehung User.addresses, die eine Sammlung von Address-Objekten darstellt, die jedem User zugeordnet sind. Die häufigste Verwendung von Query.join() besteht darin, einen JOIN entlang dieser Beziehung zu erstellen, wobei das Attribut User.addresses als Indikator dafür verwendet wird, wie dies geschehen soll.

q = session.query(User).join(User.addresses)

Wo oben der Aufruf von Query.join() entlang User.addresses zu SQL führt, die ungefähr dem Folgenden entspricht:

SELECT user.id, user.name
FROM user JOIN address ON user.id = address.user_id

Im obigen Beispiel beziehen wir uns auf User.addresses, wie es an Query.join() übergeben wird, als die "ON-Klausel", d.h. es gibt an, wie der "ON"-Teil des JOIN konstruiert werden soll.

Um eine Kette von Joins zu erstellen, können mehrere Aufrufe von Query.join() verwendet werden. Das beziehungsgebundene Attribut impliziert sowohl die linke als auch die rechte Seite des Joins gleichzeitig.

q = (
    session.query(User)
    .join(User.orders)
    .join(Order.items)
    .join(Item.keywords)
)

Hinweis

Wie im obigen Beispiel zu sehen ist, **ist die Reihenfolge, in der jeder Aufruf der join()-Methode erfolgt, wichtig**. Query wüsste beispielsweise nicht, wie es korrekt verbinden soll, wenn wir User, dann Item und dann Order in unserer Join-Kette angeben würden; in einem solchen Fall kann es, abhängig von den übergebenen Argumenten, einen Fehler ausgeben, dass es nicht weiß, wie es verbinden soll, oder es kann ungültiges SQL erzeugen, in welchem Fall die Datenbank einen Fehler ausgeben wird. In korrekter Praxis wird die Methode Query.join() so aufgerufen, dass sie mit dem übereinstimmt, wie wir die JOIN-Klauseln in SQL rendern möchten, und jeder Aufruf sollte eine klare Verbindung zu dem darstellen, was ihm vorausgeht.

Joins zu einer Zielentität oder wählbar

Eine zweite Form von Query.join() erlaubt jede gemappte Entität oder jeden CORE-selektierbaren Konstruktor als Ziel. Bei dieser Verwendung versucht Query.join(), einen JOIN entlang der natürlichen Fremdschlüsselbeziehung zwischen zwei Entitäten zu erstellen.

q = session.query(User).join(Address)

In der obigen Aufrufform wird Query.join() aufgerufen, um die "ON-Klausel" automatisch für uns zu erstellen. Diese Aufrufform gibt letztendlich einen Fehler aus, wenn entweder keine Fremdschlüssel zwischen den beiden Entitäten vorhanden sind oder wenn mehrere Fremdschlüssellinks zwischen der Zielentität und der Entität oder den bereits auf der linken Seite vorhandenen Entitäten bestehen, so dass die Erstellung eines Joins mehr Informationen erfordert. Beachten Sie, dass bei Angabe eines Joins zu einem Ziel ohne ON-Klausel ORM-konfigurierte Beziehungen nicht berücksichtigt werden.

Joins zu einem Ziel mit einer ON-Klausel

Die dritte Aufrufform erlaubt sowohl die Angabe der Zielentität als auch der ON-Klausel. Ein Beispiel, das einen SQL-Ausdruck als ON-Klausel enthält, ist wie folgt:

q = session.query(User).join(Address, User.id == Address.user_id)

Die obige Form kann auch ein beziehungsgebundenes Attribut als ON-Klausel verwenden.

q = session.query(User).join(Address, User.addresses)

Die obige Syntax kann für den Fall nützlich sein, dass wir zu einem Alias einer bestimmten Zielentität verbinden möchten. Wenn wir zweimal mit Address verbinden möchten, könnte dies durch die Verwendung von zwei Aliasen erreicht werden, die mit der Funktion aliased() eingerichtet wurden.

a1 = aliased(Address)
a2 = aliased(Address)

q = (
    session.query(User)
    .join(a1, User.addresses)
    .join(a2, User.addresses)
    .filter(a1.email_address == "ed@foo.com")
    .filter(a2.email_address == "ed@bar.com")
)

Die beziehungsgebundene Aufrufform kann auch eine Zielentität über die Methode PropComparator.of_type() angeben; eine Abfrage, die mit der obigen identisch ist, wäre:

a1 = aliased(Address)
a2 = aliased(Address)

q = (
    session.query(User)
    .join(User.addresses.of_type(a1))
    .join(User.addresses.of_type(a2))
    .filter(a1.email_address == "ed@foo.com")
    .filter(a2.email_address == "ed@bar.com")
)

Erweiterung von integrierten ON-Klauseln

Als Ersatz für die Bereitstellung einer vollständigen benutzerdefinierten ON-Bedingung für eine vorhandene Beziehung kann die Funktion PropComparator.and_() auf ein Beziehungsattribut angewendet werden, um zusätzliche Kriterien in die ON-Klausel einzufügen. Die zusätzlichen Kriterien werden mit den Standardkriterien über AND kombiniert.

q = session.query(User).join(
    User.addresses.and_(Address.email_address != "foo@bar.com")
)

Neu in Version 1.4.

Verbinden von Tabellen und Unterabfragen

Das Ziel eines Joins kann auch jede Tabelle oder jede SELECT-Anweisung sein, die mit einer Zielentität verbunden ist oder nicht. Verwenden Sie die entsprechende Methode .subquery(), um eine Abfrage in eine Unterabfrage umzuwandeln.

subq = (
    session.query(Address)
    .filter(Address.email_address == "ed@foo.com")
    .subquery()
)


q = session.query(User).join(subq, User.id == subq.c.user_id)

Die Verbindung zu einer Unterabfrage in Bezug auf eine bestimmte Beziehung und/oder Zielentität kann durch Verknüpfung der Unterabfrage mit der Entität mittels aliased() erreicht werden.

subq = (
    session.query(Address)
    .filter(Address.email_address == "ed@foo.com")
    .subquery()
)

address_subq = aliased(Address, subq)

q = session.query(User).join(User.addresses.of_type(address_subq))

Steuerung, von wo verbunden werden soll

In Fällen, in denen die linke Seite des aktuellen Zustands von Query nicht mit dem übereinstimmt, von wo aus wir verbinden möchten, kann die Methode Query.select_from() verwendet werden.

q = (
    session.query(Address)
    .select_from(User)
    .join(User.addresses)
    .filter(User.name == "ed")
)

Was zu ähnlichem SQL führt wie

SELECT address.* FROM user
    JOIN address ON user.id=address.user_id
    WHERE user.name = :name_1

Siehe auch

Select.join() - mit v2 vergleichbare Methode.

Parameter:

• *props – Eingehende Argumente für Query.join(). Die Props-Sammlung sollte im modernen Gebrauch als ein- oder zweistelliges Format betrachtet werden, entweder als einzelne "Ziel"-Entität oder ORM-attributgebundene Beziehung oder als Zielentität plus eine "ON-Klausel", die ein SQL-Ausdruck oder eine ORM-attributgebundene Beziehung sein kann.

• isouter=False – Wenn True, ist der verwendete Join ein OUTER JOIN (LEFT OUTER JOIN), so als ob die Methode Query.outerjoin() aufgerufen worden wäre.

• full=False – Rendert FULL OUTER JOIN; impliziert isouter.

Methode sqlalchemy.orm.Query.label(name: str | None) → Label[Any]

Gibt die vollständige SELECT-Anweisung zurück, die von dieser Query repräsentiert wird, konvertiert in eine skalare Unterabfrage mit einem Label des angegebenen Namens.

Siehe auch

Select.label() - mit v2 vergleichbare Methode.

Attribut sqlalchemy.orm.Query.lazy_loaded_from

Eine InstanceState, die diese Query für eine Lazy-Load-Operation verwendet.

Seit Version 1.4 veraltet: Dieses Attribut sollte über das Attribut ORMExecuteState.lazy_loaded_from im Kontext des Ereignisses SessionEvents.do_orm_execute() aufgerufen werden.

Siehe auch

ORMExecuteState.lazy_loaded_from

Methode sqlalchemy.orm.Query.limit(limit: _LimitOffsetType) → Self

Wendet eine LIMIT-Klausel auf die Abfrage an und gibt die neu resultierende Query zurück.

Siehe auch

Select.limit() - mit v2 vergleichbare Methode.

Methode sqlalchemy.orm.Query.merge_result(iterator: FrozenResult[Any] | Iterable[Sequence[Any]] | Iterable[object], load: bool = True) → FrozenResult[Any] | Iterable[Any]

Fügt ein Ergebnis in die Session dieses Query-Objekts ein.

Seit Version 2.0 veraltet: Die Methode Query.merge_result() gilt ab der 1.x-Serie von SQLAlchemy als veraltet und wird in 2.0 zu einem veralteten Konstrukt. Die Methode wird durch die Funktion merge_frozen_result() ersetzt. (Hintergrund zu SQLAlchemy 2.0 unter: SQLAlchemy 2.0 - Hauptmigrationsanleitung)

Gibt einen identischen Iterator von Ergebnissen zurück, indem ein Iterator, der von einer Query mit derselben Struktur wie diese zurückgegeben wird, mit allen gemappten Instanzen zusammengeführt wird, die mithilfe von Session.merge() in die Session gemergt werden. Dies ist eine optimierte Methode, die alle gemappten Instanzen zusammenführt und die Struktur der Zeilen und nicht zugeordneten Spalten mit weniger Methoden-Overhead als das explizite Aufrufen von Session.merge() für jeden Wert beibehält.

Die Struktur der Ergebnisse wird basierend auf der Spaltenliste dieser Query bestimmt. Wenn diese nicht übereinstimmen, treten nicht geprüfte Fehler auf.

Das Argument "load" ist dasselbe wie bei Session.merge().

Ein Beispiel dafür, wie Query.merge_result() verwendet wird, finden Sie im Quellcode des Beispiels Dogpile Caching, wo Query.merge_result() verwendet wird, um Zustände effizient aus einem Cache zurück in eine Ziel- Session wiederherzustellen.

Methode sqlalchemy.orm.Query.offset(offset: _LimitOffsetType) → Self

Wendet eine OFFSET-Klausel auf die Abfrage an und gibt die neu resultierende Query zurück.

Siehe auch

Select.offset() - mit v2 vergleichbare Methode.

Methode sqlalchemy.orm.Query.one() → _T

Gibt genau ein Ergebnis zurück oder löst eine Ausnahme aus.

Löst sqlalchemy.orm.exc.NoResultFound aus, wenn die Abfrage keine Zeilen auswählt. Löst sqlalchemy.orm.exc.MultipleResultsFound aus, wenn mehrere Objektidentitäten zurückgegeben werden oder wenn mehrere Zeilen für eine Abfrage zurückgegeben werden, die nur skalare Werte anstelle von vollständig identitätsgemappten Entitäten zurückgibt.

Der Aufruf von one() führt zur Ausführung der zugrundeliegenden Abfrage.

Siehe auch

Query.first()

Query.one_or_none()

Result.one() - mit v2 vergleichbare Methode.

Result.scalar_one() - mit v2 vergleichbare Methode.

Methode sqlalchemy.orm.Query.one_or_none() → _T | None

Gibt maximal ein Ergebnis zurück oder löst eine Ausnahme aus.

Gibt None zurück, wenn die Abfrage keine Zeilen auswählt. Löst sqlalchemy.orm.exc.MultipleResultsFound aus, wenn mehrere Objektidentitäten zurückgegeben werden oder wenn mehrere Zeilen für eine Abfrage zurückgegeben werden, die nur skalare Werte im Gegensatz zu vollständig identitätsgemappten Entitäten zurückgibt.

Der Aufruf von Query.one_or_none() führt zur Ausführung der zugrundeliegenden Abfrage.

Siehe auch

Query.first()

Query.one()

Result.one_or_none() - vergleichbare Methode für v2.

Result.scalar_one_or_none() - vergleichbare Methode für v2.

Methode sqlalchemy.orm.Query.only_return_tuples(value: bool) → Query

Wenn auf True gesetzt, sind die Abfrageergebnisse immer ein Row-Objekt.

Dies kann eine Abfrage ändern, die normalerweise eine einzelne Entität als Skalar zurückgibt, so dass sie in allen Fällen ein Row-Ergebnis zurückgibt.

Siehe auch

Query.tuples() - gibt Tupel zurück, typisiert aber auf Typenebene Ergebnisse auch als Tuple.

Query.is_single_entity()

Result.tuples() - vergleichbare Methode für v2.

Methode sqlalchemy.orm.Query.options(*args: ExecutableOption) → Self

Gibt ein neues Query-Objekt zurück, das die angegebene Liste von Mapper-Optionen anwendet.

Die meisten bereitgestellten Optionen beziehen sich auf die Änderung der Ladeweise von spalten- und beziehungsweise gemappten Attributen.

Siehe auch

Spaltenladeoptionen

Relationship Loading mit Loader-Optionen

Methode sqlalchemy.orm.Query.order_by(_Query__first: Literal[None, False, _NoArg.NO_ARG] | _ColumnExpressionOrStrLabelArgument[Any] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self

Wendet ein oder mehrere ORDER BY-Kriterien auf die Abfrage an und gibt die neu resultierende Query zurück.

z. B.

q = session.query(Entity).order_by(Entity.id, Entity.name)

Das mehrmalige Aufrufen dieser Methode ist äquivalent zum einmaligen Aufruf mit allen verketteten Klauseln. Alle vorhandenen ORDER BY-Kriterien können durch Übergabe von None allein abgebrochen werden. Neue ORDER BY-Kriterien können dann durch erneuten Aufruf von Query.order_by() hinzugefügt werden, z.B.

# will erase all ORDER BY and ORDER BY new_col alone
q = q.order_by(None).order_by(new_col)

Siehe auch

Diese Abschnitte beschreiben ORDER BY in Bezug auf die 2.0-Stil-Aufrufe, gelten aber auch für Query.

ORDER BY - im SQLAlchemy Unified Tutorial

Sortieren oder Gruppieren nach einem Label - im SQLAlchemy Unified Tutorial

Select.order_by() - vergleichbare Methode für v2.

Methode sqlalchemy.orm.Query.outerjoin(target: _JoinTargetArgument, onclause: _OnClauseArgument | None = None, *, full: bool = False) → Self

Erstellt einen linken äußeren Join gegen das Kriterium des Query-Objekts und wendet ihn generativ an, wobei die neu resultierende Query zurückgegeben wird.

Die Verwendung ist dieselbe wie bei der join()-Methode.

Siehe auch

Select.outerjoin() - vergleichbare Methode für v2.

Methode sqlalchemy.orm.Query.params(_Query__params: Dict[str, Any] | None = None, **kw: Any) → Self

Fügt Werte für Bindungsparameter hinzu, die möglicherweise in filter() angegeben wurden.

Parameter können entweder über **kwargs oder optional ein einzelnes Dictionary als erstes positionelles Argument angegeben werden. Der Grund für beides ist, dass **kwargs praktisch ist, aber einige Parameter-Dictionaries Unicode-Schlüssel enthalten, in welchen Fällen **kwargs nicht verwendet werden kann.

Methode sqlalchemy.orm.Query.populate_existing() → Self

Gibt eine Query zurück, die alle geladenen Instanzen verfallen lässt und neu lädt, oder aus der aktuellen Session wiederverwendet.

Seit SQLAlchemy 1.4 ist die Methode Query.populate_existing() äquivalent zur Verwendung der Ausführungsoption populate_existing auf ORM-Ebene. Weitere Hintergrundinformationen zu dieser Option finden Sie im Abschnitt Populate Existing.

Methode sqlalchemy.orm.Query.prefix_with(*prefixes: _TextCoercedExpressionArgument[Any], dialect: str = '*') → Self

geerbt von der HasPrefixes.prefix_with() Methode von HasPrefixes

Fügt ein oder mehrere Ausdrücke nach dem Anweisungs-Schlüsselwort hinzu, d.h. SELECT, INSERT, UPDATE oder DELETE. Generativ.

Dies wird verwendet, um Backend-spezifische Präfix-Schlüsselwörter zu unterstützen, wie sie von MySQL bereitgestellt werden.

Z. B.

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

# MySQL 5.7 optimizer hints
stmt = select(table).prefix_with("/*+ BKA(t1) */", dialect="mysql")

Mehrere Präfixe können durch mehrfache Aufrufe von HasPrefixes.prefix_with() angegeben werden.

Parameter:

• *prefixes – textueller Ausdruck oder ClauseElement-Konstrukt, das nach dem INSERT-, UPDATE- oder DELETE-Schlüsselwort gerendert wird.

• dialect – optionaler String mit dem Dialektnamen, der die Renderung dieses Präfixes nur für diesen Dialekt beschränkt.

Methode sqlalchemy.orm.Query.reset_joinpoint() → Self

Gibt eine neue Query zurück, bei der der „Joinpunkt“ auf die Basis-FROM-Entitäten der Abfrage zurückgesetzt wurde.

Diese Methode wird normalerweise in Verbindung mit dem Feature aliased=True der Methode Query.join() verwendet. Siehe das Beispiel in Query.join(), wie dies verwendet wird.

Methode sqlalchemy.orm.Query.scalar() → Any

Gibt das erste Element des ersten Ergebnisses zurück oder None, wenn keine Zeilen vorhanden sind. Wenn mehrere Zeilen zurückgegeben werden, wird MultipleResultsFound ausgelöst.

>>> session.query(Item).scalar()
<Item>
>>> session.query(Item.id).scalar()
1
>>> session.query(Item.id).filter(Item.id < 0).scalar()
None
>>> session.query(Item.id, Item.name).scalar()
1
>>> session.query(func.count(Parent.id)).scalar()
20

Dies führt zur Ausführung der zugrundeliegenden Abfrage.

Siehe auch

Result.scalar() - vergleichbare Methode für v2.

Methode sqlalchemy.orm.Query.scalar_subquery() → ScalarSelect[Any]

Gibt die vollständige SELECT-Anweisung, die von dieser Query repräsentiert wird, als skalare Unterabfrage zurück.

Analog zu SelectBase.scalar_subquery().

Geändert in Version 1.4: Die Methode Query.scalar_subquery() ersetzt die Methode Query.as_scalar().

Siehe auch

Select.scalar_subquery() - vergleichbare Methode für v2.

Methode sqlalchemy.orm.Query.select_from(*from_obj: FromClauseRole | Type[Any] | Inspectable[_HasClauseElement[Any]] | _HasClauseElement[Any]) → Self

Legt die FROM-Klausel dieser Query explizit fest.

Query.select_from() wird oft in Verbindung mit Query.join() verwendet, um zu steuern, von welcher Entität auf der „linken“ Seite des Joins ausgewählt wird.

Die hier angegebene Entität oder das wählbare Objekt ersetzt effektiv den „linken Rand“ aller Aufrufe von Query.join(), wenn kein Joinpunkt anderweitig festgelegt ist – normalerweise ist der Standard-„Joinpunkt“ die linkeste Entität in der Liste der auszuwählenenden Entitäten des Query-Objekts.

Ein typisches Beispiel

q = (
    session.query(Address)
    .select_from(User)
    .join(User.addresses)
    .filter(User.name == "ed")
)

Das SQL erzeugt, das äquivalent zu

SELECT address.* FROM user
JOIN address ON user.id=address.user_id
WHERE user.name = :name_1

Parameter:

*from_obj – Sammlung einer oder mehrerer Entitäten, die auf die FROM-Klausel angewendet werden sollen. Entitäten können gemappte Klassen, AliasedClass-Objekte, Mapper-Objekte sowie Kern-FromClause-Elemente wie Subabfragen sein.

Siehe auch

Query.join()

Query.select_entity_from()

Select.select_from() - vergleichbare Methode für v2.

Attribut sqlalchemy.orm.Query.selectable

Gibt das von dieser Query ausgegebene Select-Objekt zurück.

Verwendet für inspect() Kompatibilität, dies ist äquivalent zu

query.enable_eagerloads(False).with_labels().statement

Methode sqlalchemy.orm.Query.set_label_style(style: SelectLabelStyle) → Self

Wendet Spalten-Labels auf den Rückgabewert von Query.statement an.

Gibt an, dass der `statement`-Accessor dieser Query eine SELECT-Anweisung zurückgeben soll, die allen Spalten Labels im Format <tabellenname>_<spaltenname> zuweist; dies wird häufig verwendet, um Spalten aus mehreren Tabellen zu disambiguieren, die denselben Namen haben.

Wenn die `Query` tatsächlich SQL ausgibt, um Zeilen zu laden, verwendet sie immer Spalten-Labeling.

Hinweis

Die Methode Query.set_label_style() wendet die Ausgabe von Query.statement an und nicht auf die Ergebniszeilen-aufrufenden Systeme von Query selbst, z.B. Query.first(), Query.all(), usw. Um eine Abfrage mit Query.set_label_style() auszuführen, rufen Sie Query.statement mit Session.execute() auf.

result = session.execute(
    query.set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL).statement
)

Neu in Version 1.4.

Siehe auch

Select.set_label_style() - vergleichbare Methode für v2.

Methode sqlalchemy.orm.Query.slice(start: int, stop: int) → Self

Berechnet den „Slice“ der durch die angegebenen Indizes repräsentierten Query und gibt die resultierende Query zurück.

Die Start- und Stoppindizes verhalten sich wie die Argumente für die integrierte Funktion range() von Python. Diese Methode bietet eine Alternative zur Verwendung von LIMIT/OFFSET, um einen Slice der Abfrage zu erhalten.

Zum Beispiel,

session.query(User).order_by(User.id).slice(1, 3)

wird gerendert als

SELECT users.id AS users_id,
       users.name AS users_name
FROM users ORDER BY users.id
LIMIT ? OFFSET ?
(2, 1)

Siehe auch

Query.limit()

Query.offset()

Select.slice() - vergleichbare Methode für v2.

Attribut sqlalchemy.orm.Query.statement

Die vollständige SELECT-Anweisung, die von dieser Query repräsentiert wird.

Die Anweisung hat standardmäßig keine disambiguierenden Labels, die auf das Konstrukt angewendet werden, es sei denn, `with_labels(True)` wird zuerst aufgerufen.

Methode sqlalchemy.orm.Query.subquery(name: str | None = None, with_labels: bool = False, reduce_columns: bool = False) → Subquery

Gibt die vollständige SELECT-Anweisung, die von dieser Query repräsentiert wird, eingebettet in einen Alias zurück.

Eager JOIN-Generierung innerhalb der Abfrage ist deaktiviert.

Siehe auch

Select.subquery() - vergleichbare Methode für v2.

Parameter:

• name – String-Name, der als Alias zugewiesen werden soll; dies wird an FromClause.alias() weitergegeben. Wenn None, wird zur Kompilierungszeit ein Name deterministisch generiert.

• with_labels – wenn True, wird `with_labels()` auf der Query zuerst aufgerufen, um tabellenqualifizierte Labels auf alle Spalten anzuwenden.

• reduce_columns – wenn True, wird `Select.reduce_columns()` auf dem resultierenden `select()`-Konstrukt aufgerufen, um Spalten mit demselben Namen zu entfernen, bei denen eine andere über einen Fremdschlüssel oder eine WHERE-Klausel-Äquivalenz verweist.

method sqlalchemy.orm.Query.suffix_with(*suffixes: _TextCoercedExpressionArgument[Any], dialect: str = '*') → Self

geerbt von der HasSuffixes.suffix_with() Methode von HasSuffixes

Fügt dem gesamten Statement einen oder mehrere Ausdrücke hinzu.

Dies dient zur Unterstützung backend-spezifischer Suffix-Schlüsselwörter für bestimmte Konstrukte.

Z. B.

stmt = (
    select(col1, col2)
    .cte()
    .suffix_with(
        "cycle empno set y_cycle to 1 default 0", dialect="oracle"
    )
)

Mehrere Suffixe können durch mehrfache Aufrufe von HasSuffixes.suffix_with() angegeben werden.

Parameter:

• *suffixes – Textuelle oder ClauseElement Konstrukt, das nach der Zielklausel gerendert wird.

• dialect – Optionaler Dialektname als Zeichenkette, der die Wiedergabe dieses Suffixes nur auf diesen Dialekt beschränkt.

method sqlalchemy.orm.Query.tuples() → Query

Gibt eine Tupel-typisierte Form dieser Query zurück.

Diese Methode ruft die Methode Query.only_return_tuples() mit dem Wert True auf, was selbst sicherstellt, dass diese Query immer Row-Objekte zurückgibt, auch wenn die Abfrage gegen eine einzelne Entität durchgeführt wird. Anschließend gibt sie auf Typenebene auch eine "typisierte" Abfrage zurück, falls möglich, die Ergebniszeilen als Tuple-Objekte mit typisierten Elementen typisiert.

Diese Methode kann mit der Methode Result.tuples() verglichen werden, die "self" zurückgibt, aber aus Typisierungsgesichtspunkten ein Objekt zurückgibt, das typisierte Tuple-Objekte für Ergebnisse liefert. Die Typisierung wirkt sich nur aus, wenn dieses Query-Objekt bereits ein typisiertes Query-Objekt ist.

Neu in Version 2.0.

Siehe auch

Result.tuples() - v2 äquivalente Methode.

method sqlalchemy.orm.Query.union(*q: Query) → Self

Erzeugt eine UNION dieser Abfrage gegen eine oder mehrere Abfragen.

z. B.

q1 = sess.query(SomeClass).filter(SomeClass.foo == "bar")
q2 = sess.query(SomeClass).filter(SomeClass.bar == "foo")

q3 = q1.union(q2)

Die Methode akzeptiert mehrere Query-Objekte, um die Verschachtelungsebene zu steuern. Eine Reihe von union()-Aufrufen wie

x.union(y).union(z).all()

werden bei jedem union() verschachtelt und erzeugen

SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION
                SELECT * FROM y) UNION SELECT * FROM Z)

Während

x.union(y, z).all()

produziert

SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION
                SELECT * FROM Z)

Beachten Sie, dass viele Datenbank-Backends ORDER BY nicht auf einer Abfrage rendern, die innerhalb von UNION, EXCEPT usw. aufgerufen wird. Um alle ORDER BY-Klauseln zu deaktivieren, einschließlich derjenigen, die auf Mappern konfiguriert sind, geben Sie query.order_by(None) an – das resultierende Query-Objekt rendert ORDER BY nicht innerhalb seiner SELECT-Anweisung.

Siehe auch

Select.union() - v2 äquivalente Methode.

method sqlalchemy.orm.Query.union_all(*q: Query) → Self

Erzeugt eine UNION ALL dieser Abfrage gegen eine oder mehrere Abfragen.

Funktioniert genauso wie Query.union(). Siehe diese Methode für Anwendungsbeispiele.

Siehe auch

Select.union_all() - v2 äquivalente Methode.

method sqlalchemy.orm.Query.update(values: Dict[_DMLColumnArgument, Any], synchronize_session: SynchronizeSessionArgument = 'auto', update_args: Dict[Any, Any] | None = None) → int

Führt ein UPDATE mit einer beliebigen WHERE-Klausel durch.

Aktualisiert Zeilen, die von dieser Abfrage in der Datenbank gefunden wurden.

Z. B.

sess.query(User).filter(User.age == 25).update(
    {User.age: User.age - 10}, synchronize_session=False
)

sess.query(User).filter(User.age == 25).update(
    {"age": User.age - 10}, synchronize_session="evaluate"
)

Warnung

Siehe den Abschnitt ORM-fähige INSERT-, UPDATE- und DELETE-Anweisungen für wichtige Vorbehalte und Warnungen, einschließlich Einschränkungen bei der Verwendung von beliebigen UPDATE und DELETE mit Mapper-Vererbungskonfigurationen.

Parameter:

• values – ein Wörterbuch mit Attributnamen oder alternativ zugeordneten Attributen oder SQL-Ausdrücken als Schlüssel und literalen Werten oder SQL-Ausdrücken als Werten. Wenn der parameter-orientierte Modus gewünscht ist, können die Werte als Liste von 2-Tupeln übergeben werden; dies erfordert, dass das Flag update.preserve_parameter_order ebenfalls an das Wörterbuch Query.update.update_args übergeben wird.

• synchronize_session – wählt die Strategie zur Aktualisierung der Attribute von Objekten in der Sitzung. Siehe den Abschnitt ORM-fähige INSERT-, UPDATE- und DELETE-Anweisungen für eine Diskussion dieser Strategien.

• update_args – Optionales Wörterbuch, das, wenn vorhanden, an das zugrunde liegende update()-Konstrukt als **kw für das Objekt übergeben wird. Kann verwendet werden, um dialektspezifische Argumente wie mysql_limit sowie andere spezielle Argumente wie update.preserve_parameter_order zu übergeben.

Gibt zurück:

die Anzahl der gefundenen Zeilen, wie sie von der „Zeilenanzahl“-Funktion der Datenbank zurückgegeben wird.

Siehe auch

ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen

method sqlalchemy.orm.Query.value(column: _ColumnExpressionArgument[Any]) → Any

Gibt ein skolares Ergebnis zurück, das dem angegebenen Spaltenausdruck entspricht.

Veraltet seit Version 1.4: Query.value() ist veraltet und wird in einer zukünftigen Version entfernt. Bitte verwenden Sie Query.with_entities() in Kombination mit Query.scalar()

method sqlalchemy.orm.Query.values(*columns: _ColumnsClauseArgument[Any]) → Iterable[Any]

Gibt einen Iterator zurück, der Tupel-Ergebnisse liefert, die den angegebenen Spalten entsprechen

Veraltet seit Version 1.4: Query.values() ist veraltet und wird in einer zukünftigen Version entfernt. Bitte verwenden Sie Query.with_entities()

method sqlalchemy.orm.Query.where(*criterion: _ColumnExpressionArgument[bool]) → Self

Ein Synonym für Query.filter().

Neu in Version 1.4.

Siehe auch

Select.where() - V2-äquivalente Methode.

attribute sqlalchemy.orm.Query.whereclause

Ein schreibgeschütztes Attribut, das das aktuelle WHERE-Kriterium für diese Abfrage zurückgibt.

Der zurückgegebene Wert ist ein SQL-Ausdruckkonstrukt oder None, wenn kein Kriterium festgelegt wurde.

Siehe auch

Select.whereclause - v2 äquivalente Eigenschaft.

method sqlalchemy.orm.Query.with_entities(*entities: _ColumnsClauseArgument[Any], **_Query__kw: Any) → Query[Any]

Gibt eine neue Query zurück, die die SELECT-Liste durch die angegebenen Entitäten ersetzt.

z. B.

# Users, filtered on some arbitrary criterion
# and then ordered by related email address
q = (
    session.query(User)
    .join(User.address)
    .filter(User.name.like("%ed%"))
    .order_by(Address.email)
)

# given *only* User.id==5, Address.email, and 'q', what
# would the *next* User in the result be ?
subq = (
    q.with_entities(Address.email)
    .order_by(None)
    .filter(User.id == 5)
    .subquery()
)
q = q.join((subq, subq.c.email < Address.email)).limit(1)

Siehe auch

Select.with_only_columns() - v2 vergleichbare Methode.

method sqlalchemy.orm.Query.with_for_update(*, nowait: bool = False, read: bool = False, of: _ForUpdateOfArgument | None = None, skip_locked: bool = False, key_share: bool = False) → Self

Gibt eine neue Query mit den angegebenen Optionen für die FOR UPDATE-Klausel zurück.

Das Verhalten dieser Methode ist identisch mit dem von GenerativeSelect.with_for_update(). Wenn sie ohne Argumente aufgerufen wird, wird der resultierenden SELECT-Anweisung eine FOR UPDATE-Klausel angehängt. Wenn zusätzliche Argumente angegeben werden, können backend-spezifische Optionen wie FOR UPDATE NOWAIT oder LOCK IN SHARE MODE wirksam werden.

Z. B.

q = (
    sess.query(User)
    .populate_existing()
    .with_for_update(nowait=True, of=User)
)

Die obige Abfrage auf einem PostgreSQL-Backend wird gerendert wie

SELECT users.id AS users_id FROM users FOR UPDATE OF users NOWAIT

Warnung

Die Verwendung von with_for_update im Kontext des Eager Loadings von Beziehungen wird von SQLAlchemy nicht offiziell unterstützt oder empfohlen und funktioniert möglicherweise nicht mit bestimmten Abfragen auf verschiedenen Datenbank-Backends. Wenn with_for_update erfolgreich mit einer Abfrage verwendet wird, die joinedload() enthält, wird SQLAlchemy versuchen, SQL zu emittieren, das alle beteiligten Tabellen sperrt.

Hinweis

Es ist im Allgemeinen eine gute Idee, die Verwendung der Methode Query.populate_existing() in Kombination mit der Methode Query.with_for_update() zu verwenden. Der Zweck von Query.populate_existing() ist es, alle aus der SELECT-Anweisung gelesenen Daten in die zurückgegebenen ORM-Objekte zu schreiben, auch wenn diese Objekte bereits im Identitäts-Map vorhanden sind.

Siehe auch

GenerativeSelect.with_for_update() - Kern-Methode mit vollständiger Argument- und Verhaltensbeschreibung.

Query.populate_existing() - überschreibt Attribute von Objekten, die bereits in der Identitäts-Map geladen wurden.

method sqlalchemy.orm.Query.with_hint(selectable: _FromClauseArgument, text: str, dialect_name: str = '*') → Self

geerbt von der HasHints.with_hint() Methode von HasHints

Fügt diesem Select oder einem anderen wählbaren Objekt einen Indexierungs- oder anderen Ausführungskontext-Hinweis für das gegebene wählbare Objekt hinzu.

Tipp

Die Methode Select.with_hint() fügt Hinweise hinzu, die **für eine einzelne Tabelle spezifisch** sind, an einer **dialektspezifischen** Position. Um generische Optimierungshinweise **vor** dem SELECT-Schlüsselwort einer Anweisung hinzuzufügen, wie z. B. für MySQL oder Oracle Database, verwenden Sie die Methode Select.prefix_with(). Um Optimierungshinweise **am Ende** einer Anweisung hinzuzufügen, wie z. B. für PostgreSQL, verwenden Sie die Methode Select.with_statement_hint().

Der Text des Hinweises wird an der entsprechenden Stelle für das verwendete Datenbank-Backend gerendert, relativ zu der als selectable-Argument übergebenen Table oder Alias. Die Dialektimplementierung verwendet typischerweise die Python-String-Substitutionssyntax mit dem Token %(name)s, um den Namen der Tabelle oder des Alias zu rendern. Z. B. bei Verwendung von Oracle Database, folgendes

select(mytable).with_hint(mytable, "index(%(name)s ix_mytable)")

Würde SQL rendern als

select /*+ index(mytable ix_mytable) */ ... from mytable

Die Option dialect_name beschränkt die Wiedergabe eines bestimmten Hinweises auf ein bestimmtes Backend. Zum Beispiel, um Hinweise für Oracle Database und MSSql gleichzeitig hinzuzufügen

select(mytable).with_hint(
    mytable, "index(%(name)s ix_mytable)", "oracle"
).with_hint(mytable, "WITH INDEX ix_mytable", "mssql")

Siehe auch

Select.with_statement_hint()

Select.prefix_with() - generisches SELECT-Präfixieren, das auch für einige datenbankspezifische HINT-Syntaxen wie MySQL- oder Oracle Database-Optimierungshinweise geeignet ist

method sqlalchemy.orm.Query.with_labels() → Self

Veraltet seit Version 2.0: Die Methoden Query.with_labels() und Query.apply_labels() gelten seit der 1.x-Reihe von SQLAlchemy als Legacy und werden in 2.0 zu Legacy-Konstrukten. Verwenden Sie stattdessen set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL).

method sqlalchemy.orm.Query.with_parent(instance: object, property: attributes.QueryableAttribute[Any] | None = None, from_entity: _ExternalEntityType[Any] | None = None) → Self

Fügt ein Filterkriterium hinzu, das die gegebene Instanz mit einem untergeordneten Objekt oder einer Sammlung in Beziehung setzt, wobei dessen Attributstatus sowie eine eingerichtete relationship()-Konfiguration verwendet wird.

Seit Version 2.0 veraltet: Die Methode Query.with_parent() wird ab der SQLAlchemy-Serie 1.x als veraltet betrachtet und wird in 2.0 zu einem veralteten Konstrukt. Verwenden Sie das eigenständige Konstrukt with_parent(). (Hintergrund zu SQLAlchemy 2.0 unter: SQLAlchemy 2.0 - Major Migration Guide)

Die Methode verwendet die Funktion with_parent(), um die Klausel zu generieren, deren Ergebnis an Query.filter() übergeben wird.

Die Parameter sind die gleichen wie bei with_parent(), mit der Ausnahme, dass die gegebene Eigenschaft None sein kann, in welchem Fall eine Suche gegen die Ziel-Mapper dieses Query-Objekts durchgeführt wird.

Parameter:

• instance – Eine Instanz, die eine relationship() aufweist.

• property – Eine klassengebundene Attribut, das angibt, welche Beziehung von der Instanz verwendet werden soll, um die Eltern-/Kind-Beziehung abzugleichen.

• from_entity – Entität, die als linke Seite betrachtet werden soll. Dies ist standardmäßig die „Null“-Entität des Query selbst.

methode sqlalchemy.orm.Query.with_session(session: Session) → Self

Gibt eine Query zurück, die die angegebene Session verwendet.

Obwohl das Query-Objekt normalerweise über die Methode Session.query() instanziiert wird, ist es zulässig, die Query direkt zu erstellen, ohne unbedingt eine Session zu verwenden. Eine solche Query-Objekt oder eine bereits mit einer anderen Session verknüpfte Query kann über diese Methode ein neues Query-Objekt erstellen, das mit einer Ziel-Session verknüpft ist.

from sqlalchemy.orm import Query

query = Query([MyClass]).filter(MyClass.id == 5)

result = query.with_session(my_session).one()

methode sqlalchemy.orm.Query.with_statement_hint(text: str, dialect_name: str = '*') → Self

geerbt von der HasHints.with_statement_hint() Methode von HasHints

Fügt diesem Select oder einem anderen wählbaren Objekt einen Anweisungshinweis hinzu.

Tipp

Select.with_statement_hint() fügt normalerweise Hinweise **am Ende** einer SELECT-Anweisung hinzu. Um dialektspezifische Hinweise wie Optimierungshinweise **vor** dem SELECT-Schlüsselwort einer SELECT-Anweisung zu platzieren, verwenden Sie die Methode Select.prefix_with() für einen offenen Platz oder für tabellenspezifische Hinweise kann Select.with_hint() verwendet werden, die Hinweise an einer dialektspezifischen Stelle platziert.

Diese Methode ähnelt Select.with_hint(), außer dass sie keine einzelne Tabelle erfordert und stattdessen für die gesamte Anweisung gilt.

Hinweise hier sind spezifisch für die Backend-Datenbank und können Direktiven wie Isolationslevel, Datei-Direktiven, Abruf-Direktiven usw. enthalten.

Siehe auch

Select.with_hint()

Select.prefix_with() - generisches SELECT-Präfixieren, das auch für einige datenbankspezifische HINT-Syntaxen wie MySQL- oder Oracle Database-Optimierungshinweise geeignet ist

methode sqlalchemy.orm.Query.with_transformation(fn: Callable[[Query], Query]) → Query

Gibt ein neues Query-Objekt zurück, das durch die gegebene Funktion transformiert wurde.

Z. B.

def filter_something(criterion):
    def transform(q):
        return q.filter(criterion)

    return transform


q = q.with_transformation(filter_something(x == 5))

Dies ermöglicht die Erstellung von Ad-hoc-Rezepten für Query-Objekte.

methode sqlalchemy.orm.Query.yield_per(count: int) → Self

Gibt nur count Zeilen gleichzeitig zurück.

Der Zweck dieser Methode ist es, bei der Abfrage sehr großer Ergebnismengen (> 10.000 Zeilen) Ergebnisse in Unterkollektionen zu stapeln und sie teilweise zurückzugeben, sodass der Python-Interpreter keine sehr großen Speicherbereiche deklarieren muss, was sowohl zeitaufwendig ist als auch zu übermäßigem Speicherverbrauch führt. Die Leistung beim Abrufen von Hunderttausenden von Zeilen kann sich oft verdoppeln, wenn eine geeignete yield-per-Einstellung (z. B. ungefähr 1000) verwendet wird, selbst mit DBAPIs, die Zeilen puffern (was die meisten tun).

Ab SQLAlchemy 1.4 ist die Methode Query.yield_per() gleichbedeutend mit der Verwendung der Ausführungsoption yield_per auf ORM-Ebene. Siehe den Abschnitt Abrufen großer Ergebnismengen mit Yield Per für weitere Hintergrundinformationen zu dieser Option.

Siehe auch

Abrufen großer Ergebnissets mit Yield Per

ORM-spezifische Query-Konstrukte

Dieser Abschnitt wurde nach Zusätzliche ORM API-Konstrukte verschoben.