Die Typenhierarchie¶

SQLAlchemy bietet Abstraktionen für die meisten gängigen Datenbankdatentypen sowie mehrere Techniken zur Anpassung von Datentypen.

Datenbanktypen werden durch Python-Klassen dargestellt, die alle letztendlich von der Basis-Typklasse, bekannt als TypeEngine, erben. Es gibt zwei allgemeine Kategorien von Datentypen, die sich beide auf unterschiedliche Weise innerhalb der Typenhierarchie ausdrücken. Die von einer einzelnen Datentypklasse verwendete Kategorie kann anhand der Verwendung von zwei verschiedenen Namenskonventionen identifiziert werden, nämlich „CamelCase“ und „UPPERCASE“.

Siehe auch

Einrichten von MetaData mit Table-Objekten - im SQLAlchemy Unified Tutorial. Veranschaulicht die rudimentärste Verwendung von TypeEngine-Typobjekten zur Definition von Table-Metadaten und führt das Konzept von Typobjekten im Tutorial-Format ein.

Die „CamelCase“-Datentypen¶

Die rudimentären Typen haben „CamelCase“-Namen wie String, Numeric, Integer und DateTime. Alle direkten Unterklassen von TypeEngine sind „CamelCase“-Typen. Die „CamelCase“-Typen sind in größtmöglichem Umfang **datenbankagnostisch**, was bedeutet, dass sie alle auf jedem Datenbank-Backend verwendet werden können, wo sie sich so verhalten, wie es für dieses Backend angemessen ist, um das gewünschte Verhalten zu erzielen.

Ein Beispiel für einen einfachen „CamelCase“-Datentyp ist String. Auf den meisten Backends entspricht die Verwendung dieses Datentyps in einer Tabellenspezifikation dem VARCHAR-Datenbanktyp, der auf dem Ziel-Backend verwendet wird, und liefert Zeichenkettenwerte von und zur Datenbank, wie im folgenden Beispiel gezeigt.

from sqlalchemy import MetaData
from sqlalchemy import Table, Column, Integer, String

metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("user_name", String, primary_key=True),
    Column("email_address", String(60)),
)

Wenn eine bestimmte TypeEngine-Klasse in einer Table-Definition oder in irgendeinem SQL-Ausdruck insgesamt verwendet wird und keine Argumente benötigt werden, kann sie als Klasse selbst übergeben werden, d. h. ohne sie mit () zu instanziieren. Wenn Argumente benötigt werden, wie z. B. das Längenargument von 60 in der Spalte `"email_address"` oben, kann der Typ instanziiert werden.

Ein weiterer „CamelCase“-Datentyp, der spezifischeres Backend-Verhalten ausdrückt, ist der Boolean-Datentyp. Im Gegensatz zu String, das einen Zeichenketten-Datentyp darstellt, den alle Datenbanken haben, hat nicht jedes Backend einen echten „boolean“-Datentyp; einige verwenden Ganzzahlen oder BIT-Werte 0 und 1, einige haben boolesche Literal-Konstanten true und false, während andere das nicht tun. Für diesen Datentyp kann Boolean BOOLEAN auf einem Backend wie PostgreSQL, BIT auf dem MySQL-Backend und SMALLINT auf Oracle Database rendern. Wenn Daten mit diesem Typ von und zur Datenbank gesendet und empfangen werden, kann er, basierend auf dem verwendeten Dialekt, Python-numerische oder boolesche Werte interpretieren.

Die typische SQLAlchemy-Anwendung wird im Allgemeinen hauptsächlich „CamelCase“-Typen verwenden wollen, da diese im Allgemeinen das beste grundlegende Verhalten bieten und automatisch auf alle Backends portierbar sind.

Die Referenz für die allgemeine Menge der „CamelCase“-Datentypen finden Sie unten unter Generische „CamelCase“-Typen.

Die „UPPERCASE“-Datentypen¶

Im Gegensatz zu den „CamelCase“-Typen stehen die „UPPERCASE“-Datentypen. Diese Datentypen werden immer von einem bestimmten „CamelCase“-Datentyp abgeleitet und stellen immer einen **exakten** Datentyp dar. Bei Verwendung eines „UPPERCASE“-Datentyps wird der Name des Typs immer genau so gerendert, wie er angegeben ist, unabhängig davon, ob das aktuelle Backend ihn unterstützt oder nicht. Daher impliziert die Verwendung von „UPPERCASE“-Typen in einer SQLAlchemy-Anwendung, dass spezifische Datentypen erforderlich sind, was wiederum impliziert, dass die Anwendung normalerweise, ohne zusätzliche Schritte, auf die Backends beschränkt wäre, die den Typ genau so verwenden, wie er angegeben ist. Beispiele für UPPERCASE-Typen sind VARCHAR, NUMERIC, INTEGER und TIMESTAMP, die direkt von den zuvor erwähnten „CamelCase“-Typen String, Numeric, Integer bzw. DateTime abgeleitet werden.

Die „UPPERCASE“-Datentypen, die Teil von sqlalchemy.types sind, sind gängige SQL-Typen, die typischerweise auf mindestens zwei, wenn nicht mehr Backends verfügbar sein sollen.

Die Referenz für die allgemeine Menge der „UPPERCASE“-Datentypen finden Sie unten unter SQL-Standard und mehrere Anbieter „UPPERCASE“-Typen.

Backend-spezifische „UPPERCASE“-Datentypen¶

Die meisten Datenbanken haben auch ihre eigenen Datentypen, die entweder vollständig datenbankspezifisch sind oder zusätzliche Argumente enthalten, die für diese Datenbanken spezifisch sind. Für diese Datentypen stellen spezifische SQLAlchemy-Dialekte **backend-spezifische** „UPPERCASE“-Datentypen bereit, für einen SQL-Typ, der keine Entsprechung auf anderen Backends hat. Beispiele für backend-spezifische Uppercase-Datentypen sind PostgreSQLs JSONB, SQL Servers IMAGE und MySQLs TINYTEXT.

Spezifische Backends können auch „UPPERCASE“-Datentypen enthalten, die die von demselben „UPPERCASE“-Datentyp im sqlalchemy.types-Modul verfügbaren Argumente erweitern. Ein Beispiel ist die Erstellung eines MySQL-Zeichenketten-Datentyps, bei dem man MySQL-spezifische Argumente wie charset oder national angeben möchte, die von der MySQL-Version von VARCHAR als nur für MySQL verfügbare Parameter VARCHAR.charset und VARCHAR.national verfügbar sind.

Die API-Dokumentation für backend-spezifische Typen finden Sie in der dialektspezifischen Dokumentation unter Dialekte.

Verwendung von „UPPERCASE“- und Backend-spezifischen Typen für mehrere Backends¶

Die Betrachtung der Präsenz von „UPPERCASE“- und „CamelCase“-Typen führt zu dem natürlichen Anwendungsfall, wie „UPPERCASE“-Datentypen für backend-spezifische Optionen genutzt werden können, aber nur dann, wenn dieses Backend verwendet wird. Um die datenbankagnostischen „CamelCase“- und backend-spezifischen „UPPERCASE“-Systeme miteinander zu verbinden, verwendet man die Methode TypeEngine.with_variant(), um Typen zu **komponieren**, die mit spezifischen Verhaltensweisen auf spezifischen Backends zusammenarbeiten.

Zum Beispiel, um den String-Datentyp zu verwenden, aber unter MySQL den Parameter VARCHAR.charset von VARCHAR zu nutzen, wenn die Tabelle auf MySQL oder MariaDB erstellt wird, kann TypeEngine.with_variant() wie unten gezeigt verwendet werden.

from sqlalchemy import MetaData
from sqlalchemy import Table, Column, Integer, String
from sqlalchemy.dialects.mysql import VARCHAR

metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("user_name", String(100), primary_key=True),
    Column(
        "bio",
        String(255).with_variant(VARCHAR(255, charset="utf8"), "mysql", "mariadb"),
    ),
)

In der obigen Tabellendefinition hat die Spalte `"bio"` auf allen Backends Zeichenketten-Verhalten. Auf den meisten Backends wird sie in DDL als VARCHAR gerendert. Auf MySQL und MariaDB (angezeigt durch Datenbank-URLs, die mit mysql oder mariadb beginnen) wird sie jedoch als VARCHAR(255) CHARACTER SET utf8 gerendert.

Siehe auch

TypeEngine.with_variant() - zusätzliche Anwendungsbeispiele und Hinweise

Generische „CamelCase“-Typen¶

Generische Typen spezifizieren eine Spalte, die einen bestimmten Typ von Python-Daten lesen, schreiben und speichern kann. SQLAlchemy wählt den besten verfügbaren Datenbankspaltentyp auf der Ziel-Datenbank aus, wenn eine Anweisung CREATE TABLE ausgegeben wird. Für die vollständige Kontrolle darüber, welcher Spaltentyp in CREATE TABLE ausgegeben wird, wie z. B. VARCHAR, siehe SQL-Standard und mehrere Anbieter „UPPERCASE“-Typen und die anderen Abschnitte dieses Kapitels.

Objektname	Beschreibung
BigInteger	Ein Typ für größere `int`-Ganzzahlen.
Boolean	Ein Bool-Datentyp.
Date	Ein Typ für `datetime.date()`-Objekte.
DateTime	Ein Typ für `datetime.datetime()`-Objekte.
Double	Ein Typ für doppelte `FLOAT`-Gleitkommatypen.
Enum	Generischer Enum-Typ.
Float	Typ, der Gleitkommatypen wie `FLOAT` oder `REAL` darstellt.
Integer	Ein Typ für `int`-Ganzzahlen.
Interval	Ein Typ für `datetime.timedelta()`-Objekte.
LargeBinary	Ein Typ für große binäre Bytes.
MatchType	Bezieht sich auf den Rückgabetyp des MATCH-Operators.
Numeric	Basis für nicht-ganzzahlige numerische Typen, wie `NUMERIC`, `FLOAT`, `DECIMAL` und andere Varianten.
PickleType	Speichert Python-Objekte, die mittels Pickle serialisiert werden.
SchemaType	Fügt einem Typ Fähigkeiten hinzu, die DDL auf Schema-Ebene mit einem Typ assoziieren können.
SmallInteger	Ein Typ für kleinere `int`-Ganzzahlen.
String	Die Basis für alle Zeichenketten- und Zeichentypen.
Text	Ein variabel großer Zeichenkettentyp.
Time	Ein Typ für `datetime.time()`-Objekte.
Unicode	Ein variable Länge Unicode-Zeichenkettentyp.
UnicodeText	Ein Unicode-Zeichenkettentyp mit unbegrenzter Länge.
Uuid	Stellt einen datenbankagnostischen UUID-Datentyp dar.

class sqlalchemy.types.BigInteger¶

Ein Typ für größere int-Ganzzahlen.

Generiert typischerweise eine BIGINT in DDL und verhält sich ansonsten wie ein normaler Integer auf der Python-Seite.

Klassensignatur

class sqlalchemy.types.BigInteger (sqlalchemy.types.Integer)

class sqlalchemy.types.Boolean¶

Ein Bool-Datentyp.

Boolean verwendet typischerweise BOOLEAN oder SMALLINT auf der DDL-Seite und auf der Python-Seite behandelt es True oder False.

Der Boolean-Datentyp hat derzeit zwei Stufen der Zusicherung, dass die persistent gespeicherten Werte einfache Wahr/Falsch-Werte sind. Für alle Backends werden nur die Python-Werte None, True, False, 1 oder 0 als Parameterwerte akzeptiert. Für Backends, die keinen „nativen booleschen“ Datentyp unterstützen, gibt es die Option, auf der Zielspalte eine CHECK-Beschränkung zu erstellen.

Geändert in Version 1.2: Der Boolean-Datentyp stellt nun sicher, dass eingehende Python-Werte bereits in rein boolescher Form vorliegen.

Mitglieder

__init__(), bind_processor(), literal_processor(), python_type, result_processor()

Klassensignatur

class sqlalchemy.types.Boolean (sqlalchemy.types.SchemaType, sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Boolean.__init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)¶

Konstruiert ein Boolean.

Parameter:

create_constraint¶ –
standardmäßig False. Wenn das Boolean als int/smallint generiert wird, wird auch eine CHECK-Beschränkung für die Tabelle erstellt, die 1 oder 0 als Wert sicherstellt.

Hinweis

Es wird dringend empfohlen, der CHECK-Beschränkung einen expliziten Namen zu geben, um Schema-Management-Anliegen zu unterstützen. Dies kann entweder durch Setzen des Parameters Boolean.name oder durch Einrichten einer geeigneten Namenskonvention erfolgen; siehe Konfiguration von Beschränkungsnamenskonventionen für Hintergrundinformationen.

Geändert in Version 1.4: - dieses Flag ist jetzt standardmäßig False, d.h. es wird keine CHECK-Beschränkung für einen nicht-nativen Aufzählungstyp generiert.
name¶ – Wenn eine CHECK-Beschränkung generiert wird, geben Sie den Namen der Beschränkung an.

method sqlalchemy.types.Boolean.bind_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Bindungswerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Bindungsparameterwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der an die DB-API gesendet werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.bind_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.bind_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_bind_param() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:: dialect¶ – Der verwendete Dialekt.

method sqlalchemy.types.Boolean.literal_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Literalwerten zurück, die direkt ohne Verwendung von Binds gerendert werden sollen.

Diese Funktion wird verwendet, wenn der Compiler das Flag „literal_binds“ verwendet, was typischerweise bei der DDL-Generierung sowie in bestimmten Szenarien, in denen Backends keine gebundenen Parameter akzeptieren, verwendet wird.

Gibt eine aufrufbare Funktion zurück, die einen literalen Python-Wert als einziges positionsbezogenes Argument erhält und eine Zeichenkettendarstellung zurückgibt, die in einer SQL-Anweisung gerendert wird.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.literal_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.literal_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_literal_param() bereit.

Siehe auch

Erweitern bestehender Typen

attribute sqlalchemy.types.Boolean.python_type¶

method sqlalchemy.types.Boolean.result_processor(dialect, coltype)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Ergebniszeilenwerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Ergebniszeilen-Spaltenwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der dem Benutzer zurückgegeben werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.result_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.result_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_result_value() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:

dialect¶ – Der verwendete Dialekt.
coltype¶ – DBAPI coltype-Argument, das in cursor.description empfangen wird.

class sqlalchemy.types.Date¶

Ein Typ für datetime.date()-Objekte.

Mitglieder

get_dbapi_type(), literal_processor(), python_type

Klassensignatur

class sqlalchemy.types.Date (sqlalchemy.types._RenderISO8601NoT, sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

Methode sqlalchemy.types.Date.get_dbapi_type(dbapi)¶

Gibt den entsprechenden Typobjekt aus der zugrunde liegenden DB-API zurück, falls vorhanden.

Dies kann beispielsweise nützlich sein, um setinputsizes() aufzurufen.

Methode sqlalchemy.types.Date.literal_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Literalwerten zurück, die direkt ohne Verwendung von Binds gerendert werden sollen.

Diese Funktion wird verwendet, wenn der Compiler das Flag „literal_binds“ verwendet, was typischerweise bei der DDL-Generierung sowie in bestimmten Szenarien, in denen Backends keine gebundenen Parameter akzeptieren, verwendet wird.

Gibt eine aufrufbare Funktion zurück, die einen literalen Python-Wert als einziges positionsbezogenes Argument erhält und eine Zeichenkettendarstellung zurückgibt, die in einer SQL-Anweisung gerendert wird.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.literal_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.literal_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_literal_param() bereit.

Siehe auch

Erweitern bestehender Typen

Attribut sqlalchemy.types.Date.python_type¶

Klasse sqlalchemy.types.DateTime¶

Ein Typ für datetime.datetime()-Objekte.

Datums- und Uhrzeittypen geben Objekte aus dem Python-Modul datetime zurück. Die meisten DBAPIs haben eine integrierte Unterstützung für das datetime-Modul, mit der bemerkenswerten Ausnahme von SQLite. Im Fall von SQLite werden Datums- und Uhrzeittypen als Strings gespeichert, die dann beim Zurückgeben von Zeilen wieder in datetime-Objekte konvertiert werden.

Für die Zeitdarstellung innerhalb des Datetime-Typs bieten einige Backends zusätzliche Optionen, wie z. B. Zeitzonenunterstützung und Unterstützung für Bruchteile von Sekunden. Für Bruchteile von Sekunden verwenden Sie den Dialekt-spezifischen Datentyp, wie z. B. TIME. Für die Zeitzonenunterstützung verwenden Sie mindestens den Datentyp TIMESTAMP, wenn nicht das Dialekt-spezifische Datentypobjekt.

Mitglieder

__init__(), get_dbapi_type(), literal_processor(), python_type

Klassensignatur

class sqlalchemy.types.DateTime (sqlalchemy.types._RenderISO8601NoT, sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

Methode sqlalchemy.types.DateTime.__init__(timezone: bool = False)¶

Konstruiert ein neues DateTime.

Parameter:: timezone¶ – Boolean. Gibt an, dass der Datetime-Typ die Zeitzonenunterstützung aktivieren soll, falls auf dem **nur dem zugrunde liegenden Datums-/Uhrzeit-Halte-Typ** verfügbar. Es wird empfohlen, direkt den Datentyp TIMESTAMP zu verwenden, wenn dieses Flag verwendet wird, da einige Datenbanken separate generische Datums-/Uhrzeit-Halte-Typen enthalten, die sich vom zeitzonenfähigen TIMESTAMP-Datentyp unterscheiden, wie z. B. die Oracle Database.

Methode sqlalchemy.types.DateTime.get_dbapi_type(dbapi)¶

Gibt den entsprechenden Typobjekt aus der zugrunde liegenden DB-API zurück, falls vorhanden.

Dies kann beispielsweise nützlich sein, um setinputsizes() aufzurufen.

Methode sqlalchemy.types.DateTime.literal_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Literalwerten zurück, die direkt ohne Verwendung von Binds gerendert werden sollen.

Diese Funktion wird verwendet, wenn der Compiler das Flag „literal_binds“ verwendet, was typischerweise bei der DDL-Generierung sowie in bestimmten Szenarien, in denen Backends keine gebundenen Parameter akzeptieren, verwendet wird.

Gibt eine aufrufbare Funktion zurück, die einen literalen Python-Wert als einziges positionsbezogenes Argument erhält und eine Zeichenkettendarstellung zurückgibt, die in einer SQL-Anweisung gerendert wird.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.literal_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.literal_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_literal_param() bereit.

Siehe auch

Erweitern bestehender Typen

Attribut sqlalchemy.types.DateTime.python_type¶

Klasse sqlalchemy.types.Enum¶

Generischer Enum-Typ.

Der Typ Enum bietet eine Menge möglicher String-Werte, auf die die Spalte beschränkt ist.

Der Typ Enum verwendet den nativen "ENUM"-Typ des Backends, falls einer verfügbar ist; andernfalls verwendet er einen VARCHAR-Datentyp. Es besteht auch die Option, automatisch eine CHECK-Beschränkung zu erstellen, wenn die VARCHAR-Variante (sogenannte "nicht-native") erzeugt wird. Siehe das Flag Enum.create_constraint.

Der Typ Enum bietet auch eine In-Python-Validierung von String-Werten sowohl während der Lese- als auch während der Schreibvorgänge. Beim Lesen eines Wertes aus der Datenbank in einem Ergebnis-Set wird der String-Wert immer gegen die Liste der möglichen Werte geprüft und ein LookupError ausgelöst, wenn keine Übereinstimmung gefunden wird. Beim Übergeben eines Wertes an die Datenbank als einfacher String innerhalb einer SQL-Anweisung, wenn der Parameter Enum.validate_strings auf True gesetzt ist, wird ein LookupError für jeden String-Wert ausgelöst, der nicht in der angegebenen Liste möglicher Werte gefunden wird; beachten Sie, dass dies die Verwendung von LIKE-Ausdrücken mit aufgezählten Werten beeinträchtigt (ein ungewöhnlicher Anwendungsfall).

Die Quelle der aufgezählten Werte kann eine Liste von String-Werten sein oder alternativ eine PEP-435-konforme Aufzählungsklasse. Für die Zwecke des Datentyps Enum muss diese Klasse nur eine __members__ Methode bereitstellen.

Bei Verwendung einer Aufzählungsklasse werden die Aufzählungsobjekte sowohl für die Eingabe als auch für die Ausgabe verwendet, anstelle von Strings, wie es bei einem einfachen String-Aufzählungstyp der Fall ist.

import enum
from sqlalchemy import Enum


class MyEnum(enum.Enum):
    one = 1
    two = 2
    three = 3


t = Table("data", MetaData(), Column("value", Enum(MyEnum)))

connection.execute(t.insert(), {"value": MyEnum.two})
assert connection.scalar(t.select()) is MyEnum.two

Oben werden die String-Namen jedes Elements, z. B. "one", "two", "three", in der Datenbank gespeichert; die Werte des Python Enum, hier als Ganzzahlen angegeben, werden **nicht** verwendet; der Wert jedes Enums kann daher jedes beliebige Python-Objekt sein, unabhängig davon, ob es speicherbar ist.

Um die Werte und nicht die Namen zu speichern, kann der Parameter Enum.values_callable verwendet werden. Der Wert dieses Parameters ist ein vom Benutzer bereitgestellter Callable, der dazu bestimmt ist, mit einer PEP-435-konformen Aufzählungsklasse verwendet zu werden und eine Liste von String-Werten zurückgibt, die gespeichert werden sollen. Für eine einfache Aufzählung, die String-Werte verwendet, ist ein Callable wie lambda x: [e.value for e in x] ausreichend.

Siehe auch

Verwendung von Python Enum oder pep-586 Literal-Typen in der Typzuordnung - Hintergrundinformationen zur Verwendung des Datentyps Enum mit der ORM-Funktion ORM Annotated Declarative.

ENUM - PostgreSQL-spezifischer Typ mit zusätzlicher Funktionalität.

ENUM - MySQL-spezifischer Typ

Mitglieder

__init__(), create(), drop()

Klassensignatur

class sqlalchemy.types.Enum (sqlalchemy.types.String, sqlalchemy.types.SchemaType, sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

Methode sqlalchemy.types.Enum.__init__(*enums: object, **kw: Any)¶

Konstruiert ein Enum.

Schlüsselwortargumente, die für ein bestimmtes Backend nicht gelten, werden von diesem Backend ignoriert.

Parameter:

*enums¶ – entweder genau ein PEP-435-konformer Aufzählungstyp oder ein oder mehrere String-Labels.
create_constraint¶ –
Standardmäßig False. Beim Erstellen eines nicht-nativen Aufzählungstyps wird zusätzlich eine CHECK-Beschränkung in der Datenbank gegen die gültigen Werte erstellt.

Hinweis

Es wird dringend empfohlen, dass die CHECK-Beschränkung einen expliziten Namen hat, um Schemaverwaltungsanliegen zu unterstützen. Dies kann entweder durch Setzen des Parameters Enum.name oder durch Einrichten einer entsprechenden Benennungskonvention erfolgen. Siehe Konfiguration von Benennungskonventionen für Beschränkungen für Hintergrundinformationen.

Geändert in Version 1.4: - dieses Flag ist jetzt standardmäßig False, d.h. es wird keine CHECK-Beschränkung für einen nicht-nativen Aufzählungstyp generiert.
metadata¶ –
Verknüpft diesen Typ direkt mit einem MetaData-Objekt. Für Typen, die auf der Ziel-Datenbank als unabhängige Schemakonstrukte existieren (PostgreSQL), wird dieser Typ innerhalb der Operationen create_all() und drop_all() erstellt und gelöscht. Wenn der Typ nicht mit einem MetaData-Objekt verknüpft ist, verknüpft er sich mit jeder Table, in der er verwendet wird, und wird erstellt, wenn eine dieser einzelnen Tabellen erstellt wird, nach einer Prüfung seiner Existenz. Der Typ wird jedoch nur gelöscht, wenn drop_all() für das Metadatenobjekt dieser Table aufgerufen wird.

Der Wert des Parameters MetaData.schema des MetaData-Objekts wird, falls gesetzt, als Standardwert für das Enum.schema auf diesem Objekt verwendet, wenn kein expliziter Wert anders angegeben wird.

Geändert in Version 1.4.12: Enum erbt den Parameter MetaData.schema des MetaData-Objekts, falls vorhanden, wenn er über den Parameter Enum.metadata übergeben wird.
name¶ – Der Name dieses Typs. Dies ist erforderlich für PostgreSQL und zukünftige unterstützte Datenbanken, die einen explizit benannten Typ oder eine explizit benannte Beschränkung benötigen, um den Typ und/oder eine Tabelle, die ihn verwendet, zu generieren. Wenn eine PEP-435 Aufzählungsklasse verwendet wurde, wird standardmäßig deren Name (in Kleinbuchstaben umgewandelt) verwendet.
native_enum¶ – Verwendet den nativen ENUM-Typ der Datenbank, wenn verfügbar. Standardmäßig True. Wenn False, wird VARCHAR + CHECK-Beschränkung für alle Backends verwendet. Wenn False, kann die VARCHAR-Länge mit Enum.length gesteuert werden; derzeit wird "length" ignoriert, wenn native_enum=True.
length¶ –
Ermöglicht die Angabe einer benutzerdefinierten Länge für VARCHAR, wenn ein nicht-nativer Aufzählungstyp verwendet wird. Standardmäßig wird die Länge des längsten Werts verwendet.

Geändert in Version 2.0.0: Der Parameter Enum.length wird bedingungslos für die VARCHAR-Darstellung verwendet, unabhängig vom Parameter Enum.native_enum, für diejenigen Backends, bei denen VARCHAR für Aufzählungstypen verwendet wird.
schema¶ –
Schema-Name dieses Typs. Für Typen, die auf der Ziel-Datenbank als unabhängiges Schemakonstrukt (PostgreSQL) existieren, gibt dieser Parameter das benannte Schema an, in dem sich der Typ befindet.

Wenn nicht vorhanden, wird der Schema-Name aus der MetaData-Sammlung übernommen, wenn diese als Enum.metadata übergeben wird, für ein MetaData, das den Parameter MetaData.schema enthält.

Geändert in Version 1.4.12: Enum erbt den Parameter MetaData.schema des MetaData-Objekts, falls vorhanden, wenn er über den Parameter Enum.metadata übergeben wird.

Andernfalls, wenn das Flag Enum.inherit_schema auf True gesetzt ist, wird das Schema vom zugehörigen Table-Objekt übernommen, falls vorhanden; wenn Enum.inherit_schema auf seinem Standardwert False steht, wird das Schema der besitzenden Tabelle **nicht** verwendet.
quote¶ – Legt explizite Anführungszeichenpräferenzen für den Namen des Typs fest.
inherit_schema¶ – Wenn True, wird das "Schema" der besitzenden Table in das "Schema"-Attribut dieses Enum kopiert, wodurch jeder Wert für das `schema`-Attribut ersetzt wird. Dies gilt auch für die Operation Table.to_metadata().
validate_strings¶ – Wenn True, werden String-Werte, die in einer SQL-Anweisung an die Datenbank übergeben werden, auf Gültigkeit gegen die Liste der aufgezählten Werte geprüft. Nicht erkannte Werte führen zur Auslösung eines LookupError.
values_callable¶ –
Ein Callable, dem der PEP-435-konforme Aufzählungstyp übergeben wird, der dann eine Liste von String-Werten zurückgeben sollte, die gespeichert werden sollen. Dies ermöglicht alternative Verwendungen, wie z. B. die Speicherung des String-Werts eines Enums in der Datenbank anstelle seines Namens. Das Callable muss die zu speichernden Werte in der gleichen Reihenfolge zurückgeben, wie sie beim Iterieren durch das __member__ Attribut des Enums erscheinen. Beispiel: lambda x: [i.value for i in x].

Neu in Version 1.2.3.
sort_key_function¶ –
ein Python Callable, das als "key"-Argument für die Python-eingebaute Funktion sorted() verwendet werden kann. Die SQLAlchemy ORM verlangt, dass Primärschlüsselspalten, die zugeordnet sind, auf irgendeine Weise sortierbar sind. Bei Verwendung eines unsortierbaren Aufzählungsobjekts, wie z. B. eines Python 3 Enum-Objekts, kann dieser Parameter verwendet werden, um eine Standard-Sortierschlüsselfunktion für die Objekte festzulegen. Standardmäßig wird der Datenbankwert der Aufzählung als Sortierfunktion verwendet.

Neu seit Version 1.3.8.
omit_aliases¶ –
Ein Boolean, der bei True Aliase aus pep 435 Enums entfernt. Standardmäßig True.

Geändert in Version 2.0: Dieser Parameter ist jetzt standardmäßig True.

Methode sqlalchemy.types.Enum.create(bind, checkfirst=False)¶: geerbt von der SchemaType.create() *Methode von* SchemaType

Erzeugt CREATE DDL für diesen Typ, falls zutreffend.

Methode sqlalchemy.types.Enum.drop(bind, checkfirst=False)¶: geerbt von der SchemaType.drop() *Methode von* SchemaType

Erzeugt DROP DDL für diesen Typ, falls zutreffend.

Klasse sqlalchemy.types.Double¶

Ein Typ für doppelte FLOAT-Gleitkommatypen.

Generiert typischerweise DOUBLE oder DOUBLE_PRECISION in DDL und verhält sich ansonsten wie ein normaler Float auf der Python-Seite.

Neu in Version 2.0.

Klassensignatur

class sqlalchemy.types.Double (sqlalchemy.types.Float)

Klasse sqlalchemy.types.Float¶

Typ, der Gleitkommatypen wie FLOAT oder REAL darstellt.

Dieser Typ gibt standardmäßig Python-Objekte vom Typ float zurück, es sei denn, das Flag Float.asdecimal ist auf True gesetzt, in welchem Fall sie in decimal.Decimal-Objekte umgewandelt werden.

Wenn keine Float.precision in einem Float-Typ angegeben ist, können einige Backends diesen Typ als 8-Byte / 64-Bit-Gleitkommazahl-Datentyp kompilieren. Um einen 4-Byte / 32-Bit-Gleitkommazahl-Datentyp zu verwenden, kann normalerweise eine Präzision von <= 24 angegeben werden oder der Typ REAL verwendet werden. Dies ist bekannt für die PostgreSQL- und MSSQL-Dialekte, die den Typ als FLOAT rendern, was in beiden Fällen ein Alias für DOUBLE PRECISION ist. Andere Dialekte von Drittanbietern können ein ähnliches Verhalten aufweisen.

Mitglieder

__init__(), result_processor()

Klassensignatur

class sqlalchemy.types.Float (sqlalchemy.types.Numeric)

Methode sqlalchemy.types.Float.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

Konstruiert einen Float.

Parameter:

precision¶ –
die numerische Präzision für die Verwendung in DDL CREATE TABLE. Backends **sollten** versuchen, diese Präzision anzugeben, um die Anzahl der Ziffern für den generischen Datentyp Float anzugeben.
Hinweis

Für das Oracle Database-Backend wird der Parameter Float.precision bei der Rendern von DDL nicht akzeptiert, da die Oracle Database keine Gleitkommapräzision unterstützt, die als Anzahl von Dezimalstellen angegeben wird. Verwenden Sie stattdessen den Oracle Database-spezifischen Datentyp FLOAT und geben Sie den Parameter FLOAT.binary_precision an. Dies ist neu in Version 2.0 von SQLAlchemy.

Um ein datenbankagnostisches Float zu erstellen, das die binäre Präzision für Oracle Database separat angibt, verwenden Sie TypeEngine.with_variant() wie folgt
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – das gleiche Flag wie bei Numeric, aber standardmäßig auf False gesetzt. Beachten Sie, dass das Setzen dieses Flags auf True zu einer Gleitkommakonvertierung führt.
decimal_return_scale¶ – Standard-Skalierung, die bei der Konvertierung von Gleitkommazahlen in Python-Dezimalzahlen verwendet wird. Gleitkommawerte werden aufgrund der Dezimalungenauigkeit typischerweise viel länger sein, und die meisten Gleitkommadatenbanktypen haben keine Vorstellung von „Skalierung“, sodass der Gleitkommatyp standardmäßig die ersten zehn Dezimalstellen bei der Konvertierung berücksichtigt. Die Angabe dieses Werts überschreibt diese Länge. Beachten Sie, dass die MySQL-Gleitkommatypen, die „Skalierung“ beinhalten, „Skalierung“ als Standard für decimal_return_scale verwenden, wenn nicht anders angegeben.

method sqlalchemy.types.Float.result_processor(dialect, coltype)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Ergebniszeilenwerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Ergebniszeilen-Spaltenwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der dem Benutzer zurückgegeben werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.result_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.result_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_result_value() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:

dialect¶ – Instanz des verwendeten Dialekts.
coltype¶ – DBAPI coltype-Argument, das in cursor.description empfangen wurde.

class sqlalchemy.types.Integer¶

Ein Typ für int-Ganzzahlen.

Mitglieder

get_dbapi_type(), literal_processor(), python_type

Klassensignatur

class sqlalchemy.types.Integer (sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Integer.get_dbapi_type(dbapi)¶

Gibt den entsprechenden Typobjekt aus der zugrunde liegenden DB-API zurück, falls vorhanden.

Dies kann beispielsweise nützlich sein, um setinputsizes() aufzurufen.

method sqlalchemy.types.Integer.literal_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Literalwerten zurück, die direkt ohne Verwendung von Binds gerendert werden sollen.

Diese Funktion wird verwendet, wenn der Compiler das Flag „literal_binds“ verwendet, was typischerweise bei der DDL-Generierung sowie in bestimmten Szenarien, in denen Backends keine gebundenen Parameter akzeptieren, verwendet wird.

Gibt eine aufrufbare Funktion zurück, die einen literalen Python-Wert als einziges positionsbezogenes Argument erhält und eine Zeichenkettendarstellung zurückgibt, die in einer SQL-Anweisung gerendert wird.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.literal_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.literal_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_literal_param() bereit.

Siehe auch

Erweitern bestehender Typen

attribute sqlalchemy.types.Integer.python_type¶

class sqlalchemy.types.Interval¶

Ein Typ für datetime.timedelta()-Objekte.

Der `Interval`-Typ befasst sich mit `datetime.timedelta`-Objekten. In PostgreSQL und Oracle Database wird der native `INTERVAL`-Typ verwendet; für andere wird der Wert als Datum gespeichert, das relativ zum „Epoche“ (1. Januar 1970) ist.

Beachten Sie, dass der `Interval`-Typ derzeit keine Datumsarithmetik auf Plattformen anbietet, die keine Intervalltypen nativ unterstützen. Solche Operationen erfordern normalerweise eine Transformation beider Seiten des Ausdrucks (z. B. die Konvertierung beider Seiten in ganzzahlige Epochenwerte zuerst), was derzeit ein manuelles Verfahren ist (z. B. über expression.func).

Mitglieder

__init__(), adapt_to_emulated(), bind_processor(), cache_ok, coerce_compared_value(), comparator_factory, impl, python_type, result_processor()

Klassensignatur

class sqlalchemy.types.Interval (sqlalchemy.types.Emulated, sqlalchemy.types._AbstractInterval, sqlalchemy.types.TypeDecorator)

class Comparator¶: Klassensignatur

class sqlalchemy.types.Interval.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)

method sqlalchemy.types.Interval.__init__(native: bool = True, second_precision: int | None = None, day_precision: int | None = None)¶

Konstruiert ein `Interval`-Objekt.

Parameter:

native¶ – Wenn True, wird der vom Datenbank unterstützte native INTERVAL-Typ verwendet, falls vorhanden (derzeit PostgreSQL, Oracle Database). Andernfalls wird der Intervallwert unabhängig davon als Epochenwert dargestellt.
second_precision¶ – Für native Intervalltypen, die einen Parameter für die „Bruchteilsekundenpräzision“ unterstützen, d. h. Oracle Database und PostgreSQL.
day_precision¶ – Für native Intervalltypen, die einen Parameter für die „Tagpräzision“ unterstützen, d. h. Oracle Database.

method sqlalchemy.types.Interval.adapt_to_emulated(impltype, **kw)¶

Angesichts einer impl-Klasse wird dieser Typ an die impl angepasst, unter der Annahme von „emulated“.

Die impl sollte ebenfalls eine „emulated“ Version dieses Typs sein, höchstwahrscheinlich dieselbe Klasse wie dieser Typ selbst.

z. B.: sqltypes.Enum wird an die Enum-Klasse angepasst.

method sqlalchemy.types.Interval.bind_processor(dialect: Dialect) → _BindProcessorType[dt.timedelta]¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Bindungswerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Bindungsparameterwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der an die DB-API gesendet werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.bind_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.bind_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_bind_param() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:: dialect¶ – Instanz des verwendeten Dialekts.

attribute sqlalchemy.types.Interval.cache_ok: bool | None = True¶

Zeigt an, ob Anweisungen, die diesen ExternalType verwenden, „cachebar“ sind.

Der Standardwert None gibt eine Warnung aus und erlaubt dann nicht das Caching einer Anweisung, die diesen Typ enthält. Setzen Sie ihn auf False, um das Caching von Anweisungen, die diesen Typ verwenden, ohne Warnung vollständig zu deaktivieren. Wenn auf True gesetzt, werden die Klasse des Objekts und ausgewählte Elemente aus seinem Zustand als Teil des Cache-Schlüssels verwendet. Zum Beispiel die Verwendung eines TypeDecorator

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

Der Cache-Schlüssel für den obigen Typ wäre äquivalent zu

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

Das Caching-Schema extrahiert Attribute aus dem Typ, die den Namen der Parameter in der Methode __init__() entsprechen. Oben wird das Attribut "choices" Teil des Cache-Schlüssels, "internal_only" jedoch nicht, da es keinen Parameter namens "internal_only" gibt.

Die Anforderungen an cachebare Elemente sind, dass sie hashbar sind und auch, dass sie für gegebene Cache-Werte bei jeder Ausführung dieselbe SQL-Darstellung für Ausdrücke anzeigen, die diesen Typ verwenden.

Um Datentypen zu unterstützen, die sich auf nicht hashbare Strukturen wie Wörterbücher, Mengen und Listen beziehen, können diese Objekte "cachebar" gemacht werden, indem hashbare Strukturen den Attributen zugewiesen werden, deren Namen mit den Namen der Argumente übereinstimmen. Zum Beispiel kann ein Datentyp, der ein Wörterbuch mit Nachschlage-Werten akzeptiert, dieses als sortierte Reihe von Tupeln veröffentlichen. Angenommen, ein zuvor nicht cachebarer Typ als

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

wobei "lookup" ein Wörterbuch ist. Der Typ kann keinen Cache-Schlüssel generieren

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

Wenn wir einen solchen Cache-Schlüssel **einrichten** würden, wäre er nicht verwendbar. Wir würden eine Tupelstruktur erhalten, die ein Wörterbuch enthält, das selbst nicht als Schlüssel in einem "Cache-Wörterbuch" wie dem Statement-Cache von SQLAlchemy verwendet werden kann, da Python-Wörterbücher nicht hashbar sind.

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

Der Typ kann cachebar gemacht werden, indem ein sortiertes Tupel von Tupeln dem Attribut ".lookup" zugewiesen wird

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

wobei der Cache-Schlüssel für LookupType({"a": 10, "b": 20}) ist

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

Neu in Version 1.4.14: - das Flag cache_ok hinzugefügt, um eine gewisse Konfigurierbarkeit des Cachings für TypeDecorator-Klassen zu ermöglichen.

Neu in Version 1.4.28: - die Mixin ExternalType hinzugefügt, die das Flag cache_ok sowohl auf die TypeDecorator- als auch auf die UserDefinedType-Klassen verallgemeinert.

Siehe auch

SQL-Kompilierungs-Caching

method sqlalchemy.types.Interval.coerce_compared_value(op, value)¶

Schlagen Sie einen Typ für einen „koerzierten“ Python-Wert in einem Ausdruck vor.

Gibt dem Typ die Möglichkeit, einen Typ zurückzugeben, in den der Wert koerziert werden soll, gegeben einen Operator und einen Wert.

Das Standardverhalten ist konservativ; wenn die rechte Seite bereits basierend auf ihrem Python-Typ in einen SQL-Typ koerziert wurde, wird sie normalerweise unverändert gelassen.

Erweiterungen für Endbenutzerfunktionalitäten sollten hier generell über TypeDecorator erfolgen, welches ein freizügigeres Verhalten bietet, da es standardmäßig die andere Seite des Ausdrucks in diesen Typ koerziert und damit spezielle Python-Konvertierungen über die für den DBAPI benötigten hinaus auf beide Seiten anwendet. Es bietet auch die öffentliche Methode TypeDecorator.coerce_compared_value(), die für die Anpassung dieses Verhaltens durch Endbenutzer gedacht ist.

attribute sqlalchemy.types.Interval.comparator_factory¶: Alias für Comparator

attribute sqlalchemy.types.Interval.impl¶: Alias für DateTime

attribute sqlalchemy.types.Interval.python_type¶

method sqlalchemy.types.Interval.result_processor(dialect: Dialect, coltype: Any) → _ResultProcessorType[dt.timedelta]¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Ergebniszeilenwerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Ergebniszeilen-Spaltenwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der dem Benutzer zurückgegeben werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.result_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.result_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_result_value() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:

dialect¶ – Instanz des verwendeten Dialekts.
coltype¶ – DBAPI coltype-Argument, das in cursor.description empfangen wurde.

class sqlalchemy.types.LargeBinary¶

Ein Typ für große binäre Bytes.

Der Typ LargeBinary entspricht einem großen und/oder nicht befristeten Binärtyp für die Zielplattform, wie BLOB unter MySQL und BYTEA für PostgreSQL. Er kümmert sich auch um die notwendigen Konvertierungen für den DBAPI.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.LargeBinary (sqlalchemy.types._Binary)

method sqlalchemy.types.LargeBinary.__init__(length: int | None = None)¶

Konstruiert einen LargeBinary-Typ.

Parameter:: length¶ – optional, eine Länge für die Spalte zur Verwendung in DDL-Anweisungen, für die Binärtypen, die eine Länge akzeptieren, wie z. B. der MySQL BLOB-Typ.

class sqlalchemy.types.MatchType¶

Bezieht sich auf den Rückgabetyp des MATCH-Operators.

Da der Operator ColumnOperators.match() wahrscheinlich der offenste Operator in generischem SQLAlchemy Core ist, können wir den Rückgabetyp zur Auswertungszeit der SQL-Abfrage nicht annehmen, da MySQL einen Gleitkommawert und keinen booleschen Wert zurückgibt und andere Backends möglicherweise etwas anderes tun. Daher dient dieser Typ als Platzhalter, der derzeit von Boolean abgeleitet wird. Der Typ erlaubt es Dialekten, bei Bedarf Funktionalität zur Verarbeitung von Ergebnissen einzufügen, und gibt unter MySQL Gleitkommawerte zurück.

Klassensignatur

class sqlalchemy.types.MatchType (sqlalchemy.types.Boolean)

class sqlalchemy.types.Numeric¶

Basis für nicht-ganzzahlige numerische Typen, wie NUMERIC, FLOAT, DECIMAL und andere Varianten.

Der Datentyp Numeric wird bei direkter Verwendung DDL rendern, die Präzisionsnumeriken entspricht, falls verfügbar, wie z. B. NUMERIC(precision, scale). Die Unterklasse Float versucht, einen Gleitkommadatentyp wie FLOAT(precision) zu rendern.

Numeric gibt standardmäßig Python-decimal.Decimal-Objekte zurück, basierend auf dem Standardwert True für den Parameter Numeric.asdecimal. Wenn dieser Parameter auf False gesetzt ist, werden zurückgegebene Werte in Python-float-Objekte koerziert.

Die Unterklasse Float, die spezifischer für Gleitkommazahlen ist, setzt das Flag Float.asdecimal standardmäßig auf False, sodass der Standard-Python-Datentyp float ist.

Hinweis

Bei Verwendung eines Numeric-Datentyps gegen einen Datenbanktyp, der Python-Gleitkommazahlen an den Treiber zurückgibt, kann die Genauigkeit der durch Numeric.asdecimal angegebenen Dezimalkonvertierung begrenzt sein. Das Verhalten spezifischer numerischer/Gleitkomma-Datentypen ist ein Produkt des verwendeten SQL-Datentyps, des verwendeten Python DBAPI sowie von Strategien, die im verwendeten SQLAlchemy-Dialekt vorhanden sein können. Benutzer, die eine spezifische Präzision/Skalierung benötigen, werden ermutigt, mit den verfügbaren Datentypen zu experimentieren, um die besten Ergebnisse zu erzielen.

Mitglieder

__init__(), bind_processor(), get_dbapi_type(), literal_processor(), python_type, result_processor()

Klassensignatur

class sqlalchemy.types.Numeric (sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Numeric.__init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)¶

Konstruiert einen `Numeric`.

Parameter:

precision¶ – die numerische Präzision zur Verwendung in DDL CREATE TABLE.
scale¶ – die numerische Skalierung zur Verwendung in DDL CREATE TABLE.
asdecimal¶ – standardmäßig True. Gibt an, ob Werte als Python Decimal-Objekte oder als Floats gesendet werden sollen. Unterschiedliche DBAPIs senden das eine oder das andere basierend auf den Datentypen – der Numeric-Typ stellt sicher, dass die Rückgabewerte über DBAPIs hinweg konsistent das eine oder das andere sind.
decimal_return_scale¶ – Standard-Skalierung, die bei der Konvertierung von Gleitkommazahlen in Python-Dezimalzahlen verwendet wird. Gleitkommawerte werden aufgrund der Dezimalungenauigkeit typischerweise viel länger sein, und die meisten Gleitkommadatenbanktypen haben keine Vorstellung von „Skalierung“, sodass der Gleitkommatyp standardmäßig die ersten zehn Dezimalstellen bei der Konvertierung berücksichtigt. Die Angabe dieses Werts überschreibt diese Länge. Typen, die einen expliziten `.scale`-Wert enthalten, wie der Basis- Numeric sowie die MySQL-Gleitkommatypen, verwenden den Wert von `.scale` als Standard für decimal_return_scale, wenn nicht anders angegeben.

Bei Verwendung des Numeric-Datentyps ist Vorsicht geboten, um sicherzustellen, dass die `asdecimal`-Einstellung für den verwendeten DBAPI geeignet ist. Wenn Numeric eine Konvertierung von Decimal->float oder float->Decimal anwendet, verursacht diese Konvertierung zusätzliche Leistungskosten für alle empfangenen Ergebnisspalten.

DBAPIs, die Decimal nativ zurückgeben (z. B. psycopg2), haben eine bessere Genauigkeit und höhere Leistung bei True, da die native Übersetzung zu Decimal die Anzahl der Gleitkommaprobleme reduziert und der Numeric-Typ selbst keine weiteren Konvertierungen anwenden muss. Ein anderer DBAPI, der Floats nativ zurückgibt, *verursacht* jedoch zusätzliche Konvertierungskosten und unterliegt weiterhin Gleitkommadatenverlust – in diesem Fall entfernt asdecimal=False zumindest die zusätzlichen Konvertierungskosten.

method sqlalchemy.types.Numeric.bind_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Bindungswerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Bindungsparameterwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der an die DB-API gesendet werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.bind_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.bind_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_bind_param() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:: dialect¶ – Instanz des verwendeten Dialekts.

method sqlalchemy.types.Numeric.get_dbapi_type(dbapi)¶

Gibt den entsprechenden Typobjekt aus der zugrunde liegenden DB-API zurück, falls vorhanden.

Dies kann beispielsweise nützlich sein, um setinputsizes() aufzurufen.

method sqlalchemy.types.Numeric.literal_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Literalwerten zurück, die direkt ohne Verwendung von Binds gerendert werden sollen.

Diese Funktion wird verwendet, wenn der Compiler das Flag „literal_binds“ verwendet, was typischerweise bei der DDL-Generierung sowie in bestimmten Szenarien, in denen Backends keine gebundenen Parameter akzeptieren, verwendet wird.

Gibt eine aufrufbare Funktion zurück, die einen literalen Python-Wert als einziges positionsbezogenes Argument erhält und eine Zeichenkettendarstellung zurückgibt, die in einer SQL-Anweisung gerendert wird.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.literal_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.literal_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_literal_param() bereit.

Siehe auch

Erweitern bestehender Typen

attribute sqlalchemy.types.Numeric.python_type¶

method sqlalchemy.types.Numeric.result_processor(dialect, coltype)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Ergebniszeilenwerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Ergebniszeilen-Spaltenwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der dem Benutzer zurückgegeben werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.result_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.result_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_result_value() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:

dialect¶ – Instanz des verwendeten Dialekts.
coltype¶ – DBAPI coltype-Argument, das in cursor.description empfangen wurde.

class sqlalchemy.types.PickleType¶

Speichert Python-Objekte, die mittels Pickle serialisiert werden.

PickleType baut auf dem Binary-Typ auf, um Python's pickle.dumps() auf eingehende Objekte anzuwenden und pickle.loads() auf dem Weg nach draußen, wodurch jedes pickle-fähige Python-Objekt als serialisiertes Binärfeld gespeichert werden kann.

Um ORM-Änderungsereignisse für Elemente, die mit PickleType verknüpft sind, weiterzugeben, siehe Mutationsverfolgung.

Mitglieder

__init__(), bind_processor(), cache_ok, compare_values(), impl, result_processor()

Klassensignatur

class sqlalchemy.types.PickleType (sqlalchemy.types.TypeDecorator)

methode sqlalchemy.types.PickleType.__init__(protocol: int = 5, pickler: Any = None, comparator: Callable[[Any, Any], bool] | None = None, impl: _TypeEngineArgument[Any] | None = None)¶

Konstruiert einen PickleType.

Parameter:

protocol¶ – Standardwert ist pickle.HIGHEST_PROTOCOL.
pickler¶ – Standardwert ist pickle. Kann jedes Objekt mit Pickle-kompatiblen dumps und loads Methoden sein.
comparator¶ – Ein 2-Argument-Callable-Prädikat zum Vergleichen von Werten dieses Typs. Wenn es auf None gesetzt ist, wird der Python-Operator „equals“ zum Vergleichen von Werten verwendet.
impl¶ –
Eine binärspeichernde TypeEngine-Klasse oder -Instanz, die anstelle des Standardwerts LargeBinary verwendet wird. Zum Beispiel kann die Klasse :class: _mysql.LONGBLOB bei der Verwendung von MySQL effektiver sein.

Neu in Version 1.4.20.

methode sqlalchemy.types.PickleType.bind_processor(dialect)¶

Stellt eine Funktion zur Verarbeitung von gebundenen Werten für die gegebene Dialect bereit.

Dies ist die Methode, die den TypeEngine-Vertrag für die Konvertierung von gebundenen Werten erfüllt, die normalerweise über die Methode TypeEngine.bind_processor() erfolgt.

Hinweis

Benutzerdefinierte Unterklassen von TypeDecorator sollten diese Methode **nicht** implementieren, sondern stattdessen TypeDecorator.process_bind_param() implementieren, damit die interne Verarbeitung, die vom implementierenden Typ bereitgestellt wird, erhalten bleibt.

Parameter:: dialect¶ – Die verwendete Dialektinstanz.

attribut sqlalchemy.types.PickleType.cache_ok: bool | None = True¶

Zeigt an, ob Anweisungen, die diesen ExternalType verwenden, „cachebar“ sind.

Der Standardwert None gibt eine Warnung aus und erlaubt dann nicht das Caching einer Anweisung, die diesen Typ enthält. Setzen Sie ihn auf False, um das Caching von Anweisungen, die diesen Typ verwenden, ohne Warnung vollständig zu deaktivieren. Wenn auf True gesetzt, werden die Klasse des Objekts und ausgewählte Elemente aus seinem Zustand als Teil des Cache-Schlüssels verwendet. Zum Beispiel die Verwendung eines TypeDecorator

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

Der Cache-Schlüssel für den obigen Typ wäre äquivalent zu

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

Das Caching-Schema extrahiert Attribute aus dem Typ, die den Namen der Parameter in der Methode __init__() entsprechen. Oben wird das Attribut "choices" Teil des Cache-Schlüssels, "internal_only" jedoch nicht, da es keinen Parameter namens "internal_only" gibt.

Die Anforderungen an cachebare Elemente sind, dass sie hashbar sind und auch, dass sie für gegebene Cache-Werte bei jeder Ausführung dieselbe SQL-Darstellung für Ausdrücke anzeigen, die diesen Typ verwenden.

Um Datentypen zu unterstützen, die sich auf nicht hashbare Strukturen wie Wörterbücher, Mengen und Listen beziehen, können diese Objekte "cachebar" gemacht werden, indem hashbare Strukturen den Attributen zugewiesen werden, deren Namen mit den Namen der Argumente übereinstimmen. Zum Beispiel kann ein Datentyp, der ein Wörterbuch mit Nachschlage-Werten akzeptiert, dieses als sortierte Reihe von Tupeln veröffentlichen. Angenommen, ein zuvor nicht cachebarer Typ als

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

wobei "lookup" ein Wörterbuch ist. Der Typ kann keinen Cache-Schlüssel generieren

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

Wenn wir einen solchen Cache-Schlüssel **einrichten** würden, wäre er nicht verwendbar. Wir würden eine Tupelstruktur erhalten, die ein Wörterbuch enthält, das selbst nicht als Schlüssel in einem "Cache-Wörterbuch" wie dem Statement-Cache von SQLAlchemy verwendet werden kann, da Python-Wörterbücher nicht hashbar sind.

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

Der Typ kann cachebar gemacht werden, indem ein sortiertes Tupel von Tupeln dem Attribut ".lookup" zugewiesen wird

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

wobei der Cache-Schlüssel für LookupType({"a": 10, "b": 20}) ist

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

Neu in Version 1.4.14: - das Flag cache_ok hinzugefügt, um eine gewisse Konfigurierbarkeit des Cachings für TypeDecorator-Klassen zu ermöglichen.

Neu in Version 1.4.28: - die Mixin ExternalType hinzugefügt, die das Flag cache_ok sowohl auf die TypeDecorator- als auch auf die UserDefinedType-Klassen verallgemeinert.

Siehe auch

SQL-Kompilierungs-Caching

methode sqlalchemy.types.PickleType.compare_values(x, y)¶

Vergleicht zwei Werte auf Gleichheit.

Standardmäßig ruft dies die Methode TypeEngine.compare_values() des zugrunde liegenden „impl“ auf, welche wiederum normalerweise den Python-Gleichheitsoperator == verwendet.

Diese Funktion wird vom ORM verwendet, um einen ursprünglich geladenen Wert mit einem abgefangenen „geänderten“ Wert zu vergleichen, um festzustellen, ob eine Nettänderung eingetreten ist.

attribut sqlalchemy.types.PickleType.impl¶: Alias für LargeBinary

methode sqlalchemy.types.PickleType.result_processor(dialect, coltype)¶

Stellt eine Funktion zur Verarbeitung von Ergebniswerten für die gegebene Dialect bereit.

Dies ist die Methode, die den TypeEngine-Vertrag für die Konvertierung von gebundenen Werten erfüllt, die normalerweise über die Methode TypeEngine.result_processor() erfolgt.

Hinweis

Benutzerdefinierte Unterklassen von TypeDecorator sollten diese Methode **nicht** implementieren, sondern stattdessen TypeDecorator.process_result_value() implementieren, damit die interne Verarbeitung, die vom implementierenden Typ bereitgestellt wird, erhalten bleibt.

Parameter:

dialect¶ – Die verwendete Dialektinstanz.
coltype¶ – Ein SQLAlchemy-Datentyp

klasse sqlalchemy.types.SchemaType¶

Fügt einem Typ Fähigkeiten hinzu, die DDL auf Schema-Ebene mit einem Typ assoziieren können.

Unterstützt Typen, die explizit erstellt/gelöscht werden müssen (z.B. PG ENUM Typ) sowie Typen, die durch Tabellen- oder Schemabeschränkungen, Trigger und andere Regeln ergänzt werden.

SchemaType-Klassen können auch Ziele für die Events DDLEvents.before_parent_attach() und DDLEvents.after_parent_attach() sein, wobei die Events rund um die Zuordnung des Typs zu einer übergeordneten Column ausgelöst werden.

Siehe auch

Enum

Boolean

Mitglieder

adapt(), copy(), create(), drop(), name

Klassensignatur

class sqlalchemy.types.SchemaType (sqlalchemy.sql.expression.SchemaEventTarget, sqlalchemy.types.TypeEngineMixin)

methode sqlalchemy.types.SchemaType.adapt(cls: Type[TypeEngine | TypeEngineMixin], **kw: Any) → TypeEngine¶

methode sqlalchemy.types.SchemaType.copy(**kw)¶

methode sqlalchemy.types.SchemaType.create(bind, checkfirst=False)¶: Erzeugt CREATE DDL für diesen Typ, falls zutreffend.

methode sqlalchemy.types.SchemaType.drop(bind, checkfirst=False)¶: Erzeugt DROP DDL für diesen Typ, falls zutreffend.

attribut sqlalchemy.types.SchemaType.name: str | None¶

klasse sqlalchemy.types.SmallInteger¶

Ein Typ für kleinere int-Ganzzahlen.

Erzeugt normalerweise ein SMALLINT in DDL und verhält sich ansonsten wie ein normaler Integer auf Python-Seite.

Klassensignatur

class sqlalchemy.types.SmallInteger (sqlalchemy.types.Integer)

klasse sqlalchemy.types.String¶

Die Basis für alle Zeichenketten- und Zeichentypen.

In SQL entspricht dies VARCHAR.

Das Feld length ist normalerweise erforderlich, wenn der String-Typ in einer CREATE TABLE-Anweisung verwendet wird, da VARCHAR bei den meisten Datenbanken eine Länge benötigt.

Mitglieder

__init__(), bind_processor(), get_dbapi_type(), literal_processor(), python_type, result_processor()

Klassensignatur

class sqlalchemy.types.String (sqlalchemy.types.Concatenable, sqlalchemy.types.TypeEngine)

methode sqlalchemy.types.String.__init__(length: int | None = None, collation: str | None = None)¶

Erstellt einen String-speichernden Typ.

Parameter:

length¶ – optional, eine Länge für die Spalte zur Verwendung in DDL und CAST-Ausdrücken. Kann sicher weggelassen werden, wenn keine CREATE TABLE ausgegeben wird. Bestimmte Datenbanken benötigen möglicherweise eine length für die Verwendung in DDL und lösen eine Ausnahme aus, wenn die DDL-Anweisung CREATE TABLE ausgegeben wird, wenn ein VARCHAR ohne Länge enthalten ist. Ob der Wert als Bytes oder Zeichen interpretiert wird, ist datenbankspezifisch.
collation¶ –
Optional, eine Spalten-Kollation zur Verwendung in DDL- und CAST-Ausdrücken. Wird mit dem COLLATE-Schlüsselwort gerendert, das von SQLite, MySQL und PostgreSQL unterstützt wird. Z.B.
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
Hinweis

In den meisten Fällen sollten die Datentypen Unicode oder UnicodeText für eine Column verwendet werden, die nicht-ASCII-Daten speichern soll. Diese Datentypen stellen sicher, dass die korrekten Typen auf der Datenbank verwendet werden.

methode sqlalchemy.types.String.bind_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Bindungswerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Bindungsparameterwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der an die DB-API gesendet werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.bind_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.bind_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_bind_param() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:: dialect¶ – Die verwendete Dialektinstanz.

methode sqlalchemy.types.String.get_dbapi_type(dbapi)¶

Gibt den entsprechenden Typobjekt aus der zugrunde liegenden DB-API zurück, falls vorhanden.

Dies kann beispielsweise nützlich sein, um setinputsizes() aufzurufen.

methode sqlalchemy.types.String.literal_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Literalwerten zurück, die direkt ohne Verwendung von Binds gerendert werden sollen.

Diese Funktion wird verwendet, wenn der Compiler das Flag „literal_binds“ verwendet, was typischerweise bei der DDL-Generierung sowie in bestimmten Szenarien, in denen Backends keine gebundenen Parameter akzeptieren, verwendet wird.

Gibt eine aufrufbare Funktion zurück, die einen literalen Python-Wert als einziges positionsbezogenes Argument erhält und eine Zeichenkettendarstellung zurückgibt, die in einer SQL-Anweisung gerendert wird.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.literal_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.literal_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_literal_param() bereit.

Siehe auch

Erweitern bestehender Typen

attribut sqlalchemy.types.String.python_type¶

methode sqlalchemy.types.String.result_processor(dialect, coltype)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Ergebniszeilenwerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Ergebniszeilen-Spaltenwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der dem Benutzer zurückgegeben werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.result_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.result_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_result_value() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:

dialect¶ – Die verwendete Dialektinstanz.
coltype¶ – DBAPI coltype-Argument aus cursor.description.

klasse sqlalchemy.types.Text¶

Ein variabel großer Zeichenkettentyp.

In SQL entspricht dies normalerweise CLOB oder TEXT. Im Allgemeinen haben TEXT-Objekte keine Länge; obwohl einige Datenbanken ein Längenargument hier akzeptieren, wird es von anderen abgelehnt.

Klassensignatur

class sqlalchemy.types.Text (sqlalchemy.types.String)

klasse sqlalchemy.types.Time¶

Ein Typ für datetime.time()-Objekte.

Mitglieder

get_dbapi_type(), literal_processor(), python_type

Klassensignatur

class sqlalchemy.types.Time (sqlalchemy.types._RenderISO8601NoT, sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

methode sqlalchemy.types.Time.get_dbapi_type(dbapi)¶

Gibt den entsprechenden Typobjekt aus der zugrunde liegenden DB-API zurück, falls vorhanden.

Dies kann beispielsweise nützlich sein, um setinputsizes() aufzurufen.

methode sqlalchemy.types.Time.literal_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Literalwerten zurück, die direkt ohne Verwendung von Binds gerendert werden sollen.

Diese Funktion wird verwendet, wenn der Compiler das Flag „literal_binds“ verwendet, was typischerweise bei der DDL-Generierung sowie in bestimmten Szenarien, in denen Backends keine gebundenen Parameter akzeptieren, verwendet wird.

Gibt eine aufrufbare Funktion zurück, die einen literalen Python-Wert als einziges positionsbezogenes Argument erhält und eine Zeichenkettendarstellung zurückgibt, die in einer SQL-Anweisung gerendert wird.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.literal_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.literal_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_literal_param() bereit.

Siehe auch

Erweitern bestehender Typen

attribut sqlalchemy.types.Time.python_type¶

klasse sqlalchemy.types.Unicode¶

Ein variable Länge Unicode-Zeichenkettentyp.

Der Typ Unicode ist eine Unterklasse von String, die davon ausgeht, dass Ein- und Ausgabestrings Nicht-ASCII-Zeichen enthalten können. Für einige Backends impliziert dies einen zugrunde liegenden Spaltentyp, der explizit Nicht-ASCII-Daten unterstützt, wie z.B. NVARCHAR in Oracle Database und SQL Server. Dies beeinflusst die Ausgabe von CREATE TABLE-Anweisungen und CAST-Funktionen auf Dialektebene.

Die vom Unicode-Typ verwendete Zeichenkodierung für die Übertragung und den Empfang von Daten zur Datenbank wird normalerweise vom DBAPI selbst bestimmt. Alle modernen DBAPIs unterstützen Nicht-ASCII-Strings, können aber unterschiedliche Methoden zur Verwaltung von Datenbankkodierungen haben. Falls erforderlich, sollte diese Kodierung wie in den Hinweisen für den Ziel-DBAPI im Abschnitt Dialekte beschrieben konfiguriert werden.

In modernem SQLAlchemy impliziert die Verwendung des Unicode-Datentyps keine Kodierungs-/Dekodierungsverhalten innerhalb von SQLAlchemy selbst. In Python 3 sind alle String-Objekte von Natur aus Unicode-fähig, und SQLAlchemy erzeugt keine Bytestring-Objekte und unterstützt auch keine DBAPIs, die für String-Werte keine Python-Unicode-Objekte in Ergebnislisten zurückgeben.

Warnung

Einige Datenbank-Backends, insbesondere SQL Server mit pyodbc, sind bekannt dafür, unerwünschte Verhaltensweisen in Bezug auf Daten zu zeigen, die als NVARCHAR-Typ und nicht als VARCHAR gekennzeichnet sind, einschließlich Datentyp-Mismatch-Fehlern und Nichtverwendung von Indizes. Siehe den Abschnitt über DialectEvents.do_setinputsizes() für Hintergrundinformationen zur Umgehung von Unicode-Zeichenproblemen für Backends wie SQL Server mit pyodbc sowie cx_Oracle.

Siehe auch

UnicodeText - das textuelle Gegenstück ohne Längenbeschränkung zu Unicode.

DialectEvents.do_setinputsizes()

Klassensignatur

class sqlalchemy.types.Unicode (sqlalchemy.types.String)

klasse sqlalchemy.types.UnicodeText¶

Ein Unicode-Zeichenkettentyp mit unbegrenzter Länge.

Siehe Unicode für Details zum Unicode-Verhalten dieses Objekts.

Wie Unicode impliziert die Verwendung des Typs UnicodeText einen Unicode-fähigen Typ auf dem Backend, wie z.B. NCLOB, NTEXT.

Klassensignatur

class sqlalchemy.types.UnicodeText (sqlalchemy.types.Text)

class sqlalchemy.types.Uuid¶

Stellt einen datenbankagnostischen UUID-Datentyp dar.

Für Backends, die keinen "nativen" UUID-Datentyp haben, wird der Wert CHAR(32) verwenden und die UUID als 32-stelligen alphanumerischen Hex-String speichern.

Für Backends, von denen bekannt ist, dass sie UUID direkt oder einen ähnlichen UUID-speichernden Datentyp wie SQL Server's UNIQUEIDENTIFIER unterstützen, ermöglicht ein standardmäßig aktivierter "nativer" Modus, dass diese Typen auf diesen Backends verwendet werden.

Im Standardmodus erwartet der Uuid Datentyp **Python uuid-Objekte** aus dem Python uuid Modul.

import uuid

from sqlalchemy import Uuid
from sqlalchemy import Table, Column, MetaData, String


metadata_obj = MetaData()

t = Table(
    "t",
    metadata_obj,
    Column("uuid_data", Uuid, primary_key=True),
    Column("other_data", String),
)

with engine.begin() as conn:
    conn.execute(
        t.insert(), {"uuid_data": uuid.uuid4(), "other_data": "some data"}
    )

Damit der Uuid Datentyp mit String-basierten UUIDs (z.B. 32-stellige Hexadezimalstrings) funktioniert, übergeben Sie den Parameter Uuid.as_uuid mit dem Wert False.

Neu in Version 2.0.

Siehe auch

UUID - repräsentiert exakt den UUID Datentyp ohne Backend-agnostische Verhaltensweisen.

Mitglieder

__init__(), bind_processor(), coerce_compared_value(), literal_processor(), python_type, result_processor()

Klassensignatur

class sqlalchemy.types.Uuid (sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Uuid.__init__(as_uuid: bool = True, native_uuid: bool = True)¶

Erstellt einen Uuid Typ.

Parameter:

as_uuid=True¶ –
wenn True, werden Werte als Python-UUID-Objekte interpretiert und über DBAPI in Zeichenketten konvertiert.
native_uuid=True¶ – wenn True, werden von den Backends, die entweder den UUID Datentyp direkt oder einen UUID-speichernden Wert (wie z.B. SQL Server's UNIQUEIDENTIFIER) unterstützen, diese verwendet. Wenn False, wird für alle Backends, unabhängig von nativer Unterstützung, ein CHAR(32) Datentyp verwendet.

method sqlalchemy.types.Uuid.bind_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Bindungswerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Bindungsparameterwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der an die DB-API gesendet werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.bind_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.bind_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_bind_param() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:: dialect¶ – Instanz des verwendeten Dialekts.

method sqlalchemy.types.Uuid.coerce_compared_value(op, value)¶: Siehe TypeEngine.coerce_compared_value() für eine Beschreibung.

method sqlalchemy.types.Uuid.literal_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Literalwerten zurück, die direkt ohne Verwendung von Binds gerendert werden sollen.

Diese Funktion wird verwendet, wenn der Compiler das Flag „literal_binds“ verwendet, was typischerweise bei der DDL-Generierung sowie in bestimmten Szenarien, in denen Backends keine gebundenen Parameter akzeptieren, verwendet wird.

Gibt eine aufrufbare Funktion zurück, die einen literalen Python-Wert als einziges positionsbezogenes Argument erhält und eine Zeichenkettendarstellung zurückgibt, die in einer SQL-Anweisung gerendert wird.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.literal_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.literal_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_literal_param() bereit.

Siehe auch

Erweitern bestehender Typen

attribute sqlalchemy.types.Uuid.python_type¶

method sqlalchemy.types.Uuid.result_processor(dialect, coltype)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Ergebniszeilenwerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Ergebniszeilen-Spaltenwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der dem Benutzer zurückgegeben werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.result_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.result_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_result_value() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:

dialect¶ – Instanz des verwendeten Dialekts.
coltype¶ – DBAPI coltype Argument, das in cursor.description empfangen wurde.

SQL-Standard und "UPPERCASE"-Typen für mehrere Anbieter¶

Diese Kategorie von Typen bezieht sich auf Typen, die entweder Teil des SQL-Standards sind oder potenziell innerhalb einer Teilmenge von Datenbank-Backends vorkommen. Im Gegensatz zu den "generischen" Typen gibt es für die SQL-Standard-/Multi-Vendor-Typen **keine** Garantie, dass sie auf allen Backends funktionieren, und sie funktionieren nur auf den Backends, die sie explizit namentlich unterstützen. Das heißt, der Typ gibt seinen genauen Namen in DDL aus, wenn CREATE TABLE ausgegeben wird.

Objektname	Beschreibung
ARRAY	Repräsentiert einen SQL-Array-Typ.
BIGINT	Der SQL-Datentyp BIGINT.
BINARY	Der SQL-Datentyp BINARY.
BLOB	Der SQL-Datentyp BLOB.
BOOLEAN	Der SQL-Datentyp BOOLEAN.
CHAR	Der SQL-Datentyp CHAR.
CLOB	Der CLOB-Datentyp.
DATE	Der SQL-Datentyp DATE.
DATETIME	Der SQL-Datentyp DATETIME.
DECIMAL	Der SQL-Datentyp DECIMAL.
DOUBLE	Der SQL-Datentyp DOUBLE.
DOUBLE_PRECISION	Der SQL-Datentyp DOUBLE PRECISION.
FLOAT	Der SQL-Datentyp FLOAT.
INT	Alias für `INTEGER`
INTEGER	Der SQL-Datentyp INT oder INTEGER.
JSON	Repräsentiert einen SQL-JSON-Typ.
NCHAR	Der SQL-Datentyp NCHAR.
NUMERIC	Der SQL-Datentyp NUMERIC.
NVARCHAR	Der SQL-Datentyp NVARCHAR.
REAL	Der SQL-Datentyp REAL.
SMALLINT	Der SQL-Datentyp SMALLINT.
TEXT	Der SQL-Datentyp TEXT.
TIME	Der SQL-Datentyp TIME.
TIMESTAMP	Der SQL-Datentyp TIMESTAMP.
UUID	Repräsentiert den SQL-Datentyp UUID.
VARBINARY	Der SQL-Datentyp VARBINARY.
VARCHAR	Der SQL-Datentyp VARCHAR.

class sqlalchemy.types.ARRAY¶

Repräsentiert einen SQL-Array-Typ.

Hinweis

Dieser Typ dient als Grundlage für alle ARRAY-Operationen. Derzeit **unterstützt nur der PostgreSQL-Backend SQL-Arrays in SQLAlchemy**. Es wird empfohlen, direkt den PostgreSQL-spezifischen sqlalchemy.dialects.postgresql.ARRAY Typ zu verwenden, wenn ARRAY-Typen mit PostgreSQL verwendet werden, da dieser zusätzliche, backend-spezifische Operatoren bietet.

ARRAY ist Teil von Core zur Unterstützung verschiedener SQL-Standardfunktionen wie array_agg, die explizit Arrays beinhalten; jedoch haben mit Ausnahme des PostgreSQL-Backends und möglicherweise einiger Drittanbieter-Dialekte keine anderen SQLAlchemy-eingebauten Dialekte Unterstützung für diesen Typ.

Ein ARRAY Typ wird anhand des "Typs" des Elements konstruiert.

mytable = Table("mytable", metadata, Column("data", ARRAY(Integer)))

Der obige Typ repräsentiert ein N-dimensionales Array, was bedeutet, dass ein unterstützendes Backend wie PostgreSQL Werte mit beliebiger Anzahl von Dimensionen automatisch interpretiert. Um eine INSERT-Anweisung zu erstellen, die ein 1-dimensionales Array von Ganzzahlen übergibt.

connection.execute(mytable.insert(), {"data": [1, 2, 3]})

Der ARRAY Typ kann mit einer festen Anzahl von Dimensionen konstruiert werden.

mytable = Table(
    "mytable", metadata, Column("data", ARRAY(Integer, dimensions=2))
)

Die Angabe der Anzahl der Dimensionen ist optional, aber empfohlen, wenn der Datentyp Arrays mit mehr als einer Dimension repräsentieren soll. Diese Zahl wird verwendet.

Beim Ausgeben der Typdeklaration selbst an die Datenbank, z.B. INTEGER[][].
Beim Übersetzen von Python-Werten in Datenbankwerte und umgekehrt, z.B. verwendet ein ARRAY von Unicode-Objekten diese Zahl, um effizient auf die String-Werte innerhalb von Array-Strukturen zuzugreifen, ohne auf die Typinspektion pro Zeile zurückgreifen zu müssen.
Bei Verwendung mit dem Python getitem Akzessor dient die Anzahl der Dimensionen dazu, die Art des Typs zu definieren, den der [] Operator zurückgeben soll, z.B. für ein ARRAY von INTEGER mit zwei Dimensionen.
```
>>> expr = table.c.column[5]  # returns ARRAY(Integer, dimensions=1)
>>> expr = expr[6]  # returns Integer
```

Für 1-dimensionale Arrays geht eine ARRAY Instanz ohne Dimensionsparameter generell von eindimensionalen Verhaltensweisen aus.

SQL-Ausdrücke vom Typ ARRAY unterstützen "Index"- und "Slice"-Verhalten. Der [] Operator erzeugt Ausdruckskonstrukte, die die entsprechende SQL-Anweisung generieren, sowohl für SELECT-Anweisungen.

select(mytable.c.data[5], mytable.c.data[2:7])

als auch für UPDATE-Anweisungen, wenn die Methode Update.values() verwendet wird.

mytable.update().values(
    {mytable.c.data[5]: 7, mytable.c.data[2:7]: [1, 2, 3]}
)

Der indizierte Zugriff ist standardmäßig einsbasiert; für die nullbasierte Indexkonvertierung setzen Sie ARRAY.zero_indexes.

Der ARRAY Typ bietet auch die Operatoren Comparator.any() und Comparator.all(). Die PostgreSQL-spezifische Version von ARRAY bietet zusätzliche Operatoren.

Erkennung von Änderungen in ARRAY-Spalten bei Verwendung des ORM

Der ARRAY Typ erkennt bei Verwendung mit dem SQLAlchemy ORM keine In-Place-Mutationen des Arrays. Um diese zu erkennen, muss die Erweiterung sqlalchemy.ext.mutable mit der Klasse MutableList verwendet werden.

from sqlalchemy import ARRAY
from sqlalchemy.ext.mutable import MutableList


class SomeOrmClass(Base):
    # ...

    data = Column(MutableList.as_mutable(ARRAY(Integer)))

Diese Erweiterung ermöglicht es, "In-Place"-Änderungen am Array, wie z.B. .append(), auszulösen, die vom Unit of Work erkannt werden. Beachten Sie, dass Änderungen an Elementen **innerhalb** des Arrays, einschließlich von Unter-Arrays, die in-Place mutiert werden, **nicht** erkannt werden.

Alternativ wird durch die Zuweisung eines neuen Array-Werts zu einem ORM-Element, das den alten ersetzt, immer ein Änderungsereignis ausgelöst.

Siehe auch

sqlalchemy.dialects.postgresql.ARRAY

Mitglieder

__init__(), contains(), any(), all()

Klassensignatur

class sqlalchemy.types.ARRAY (sqlalchemy.sql.expression.SchemaEventTarget, sqlalchemy.types.Indexable, sqlalchemy.types.Concatenable, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.ARRAY.__init__(item_type: _TypeEngineArgument[Any], as_tuple: bool = False, dimensions: int | None = None, zero_indexes: bool = False)¶

Konstruiert ein ARRAY.

Z. B.

Column("myarray", ARRAY(Integer))

Argumente sind

Parameter:

item_type¶ – Der Datentyp der Elemente dieses Arrays. Beachten Sie, dass die Dimensionalität hier irrelevant ist, so dass mehrdimensionale Arrays wie INTEGER[][] als ARRAY(Integer) und nicht als ARRAY(ARRAY(Integer)) oder ähnliches konstruiert werden.
as_tuple=False¶ – Gibt an, ob Ergebniswerte von Listen in Tupel konvertiert werden sollen. Dieser Parameter ist im Allgemeinen nicht notwendig, da eine Python-Liste gut mit einem SQL-Array korrespondiert.
dimensions¶ – wenn ungleich None, nimmt das ARRAY eine feste Anzahl von Dimensionen an. Dies beeinflusst, wie das Array in der Datenbank deklariert wird, wie es Python- und Ergebniswerte interpretiert und wie das Ausdrucksverhalten in Verbindung mit dem "getitem"-Operator funktioniert. Siehe die Beschreibung bei ARRAY für weitere Details.
zero_indexes=False¶ – wenn True, werden Indexwerte zwischen Python-Nullbasierung und SQL-Einsbasierung konvertiert, z.B. wird ein Wert von eins zu allen Indexwerten addiert, bevor sie an die Datenbank übergeben werden.

class Comparator¶

Definiert Vergleichsoperationen für ARRAY.

Weitere Operatoren sind in der dialektspezifischen Form dieses Typs verfügbar. Siehe Comparator.

Klassensignatur

class sqlalchemy.types.ARRAY.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)

method sqlalchemy.types.ARRAY.Comparator.contains(*arg, **kw)¶: ARRAY.contains() ist für den Basis-ARRAY-Typ nicht implementiert. Verwenden Sie den dialektspezifischen ARRAY-Typ.

Siehe auch

ARRAY - PostgreSQL-spezifische Version.

method sqlalchemy.types.ARRAY.Comparator.any(other, operator=None)¶

Gibt eine other operator ANY (array) Klausel zurück.

Legacy-Funktion

Diese Methode ist eine ARRAY-spezifische Konstruktion, die nun von der Funktion any_() abgelöst wurde, welche einen anderen Aufrufstil aufweist. Die Funktion any_() wird auch auf Methodenebene über die Methode ColumnOperators.any_() gespiegelt.

Verwendung des array-spezifischen Comparator.any() erfolgt wie folgt:

from sqlalchemy.sql import operators

conn.execute(
    select(table.c.data).where(table.c.data.any(7, operator=operators.lt))
)

Parameter:

other¶ – Ausdruck, der verglichen werden soll.
operator¶ – ein Operatorobjekt aus dem Paket sqlalchemy.sql.operators, standardmäßig eq().

Siehe auch

any_()

Comparator.all()

method sqlalchemy.types.ARRAY.Comparator.all(other, operator=None)¶

Gibt eine other operator ALL (array) Klausel zurück.

Legacy-Funktion

Diese Methode ist eine ARRAY-spezifische Konstruktion, die nun von der Funktion all_() abgelöst wurde, welche einen anderen Aufrufstil aufweist. Die Funktion all_() wird auch auf Methodenebene über die Methode ColumnOperators.all_() gespiegelt.

Verwendung des array-spezifischen Comparator.all() erfolgt wie folgt:

from sqlalchemy.sql import operators

conn.execute(
    select(table.c.data).where(table.c.data.all(7, operator=operators.lt))
)

Parameter:

other¶ – Ausdruck, der verglichen werden soll.
operator¶ – ein Operatorobjekt aus dem Paket sqlalchemy.sql.operators, standardmäßig eq().

Siehe auch

all_()

Comparator.any()

class sqlalchemy.types.BIGINT¶: Der SQL-Datentyp BIGINT.

Siehe auch

BigInteger - Dokumentation für den Basistyp.

Klassensignatur

class sqlalchemy.types.BIGINT (sqlalchemy.types.BigInteger)

class sqlalchemy.types.BINARY¶: Der SQL-Datentyp BINARY.

Klassensignatur

class sqlalchemy.types.BINARY (sqlalchemy.types._Binary)

class sqlalchemy.types.BLOB¶

Der SQL-Datentyp BLOB.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.BLOB (sqlalchemy.types.LargeBinary)

method sqlalchemy.types.BLOB.__init__(length: int | None = None)¶

geerbt von der sqlalchemy.types.LargeBinary.__init__ Methode von LargeBinary

Konstruiert einen LargeBinary-Typ.

Parameter:: length¶ – optional, eine Länge für die Spalte zur Verwendung in DDL-Anweisungen, für Binärtypen, die eine Länge akzeptieren, wie z. B. der MySQL BLOB-Typ.

class sqlalchemy.types.BOOLEAN¶

Der SQL-Datentyp BOOLEAN.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.BOOLEAN (sqlalchemy.types.Boolean)

method sqlalchemy.types.BOOLEAN.__init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)¶

geerbt von der sqlalchemy.types.Boolean.__init__ Methode von Boolean

Konstruiert ein Boolean.

Parameter:

create_constraint¶ –
standardmäßig False. Wenn das Boolean als int/smallint generiert wird, wird auch eine CHECK-Beschränkung für die Tabelle erstellt, die 1 oder 0 als Wert sicherstellt.

Hinweis

Es wird dringend empfohlen, der CHECK-Beschränkung einen expliziten Namen zu geben, um Schema-Management-Anliegen zu unterstützen. Dies kann entweder durch Setzen des Parameters Boolean.name oder durch Einrichten einer geeigneten Namenskonvention erfolgen; siehe Konfiguration von Beschränkungsnamenskonventionen für Hintergrundinformationen.

Geändert in Version 1.4: - dieses Flag ist jetzt standardmäßig False, d.h. es wird keine CHECK-Beschränkung für einen nicht-nativen Aufzählungstyp generiert.
name¶ – wenn eine CHECK-Einschränkung generiert wird, geben Sie den Namen der Einschränkung an.

class sqlalchemy.types.CHAR¶

Der SQL-Datentyp CHAR.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.CHAR (sqlalchemy.types.String)

method sqlalchemy.types.CHAR.__init__(length: int | None = None, collation: str | None = None)¶

geerbt von der sqlalchemy.types.String.__init__ Methode von String

Erstellt einen String-speichernden Typ.

Parameter:

length¶ – optional, eine Länge für die Spalte zur Verwendung in DDL- und CAST-Ausdrücken. Kann sicher weggelassen werden, wenn keine CREATE TABLE ausgegeben wird. Bestimmte Datenbanken benötigen möglicherweise eine length für die Verwendung in DDL und lösen eine Ausnahme aus, wenn die CREATE TABLE DDL für ein VARCHAR ohne Länge ausgegeben wird. Ob der Wert als Bytes oder Zeichen interpretiert wird, ist datenbankspezifisch.
collation¶ –
Optional, eine Spalten-Kollation zur Verwendung in DDL- und CAST-Ausdrücken. Wird mit dem COLLATE-Schlüsselwort gerendert, das von SQLite, MySQL und PostgreSQL unterstützt wird. Z.B.
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
Hinweis

In den meisten Fällen sollten die Datentypen Unicode oder UnicodeText für eine Column verwendet werden, die nicht-ASCII-Daten speichern soll. Diese Datentypen stellen sicher, dass die korrekten Typen auf der Datenbank verwendet werden.

class sqlalchemy.types.CLOB¶

Der CLOB-Datentyp.

Dieser Typ ist in Oracle Database und Informix zu finden.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.CLOB (sqlalchemy.types.Text)

method sqlalchemy.types.CLOB.__init__(length: int | None = None, collation: str | None = None)¶

geerbt von der sqlalchemy.types.String.__init__ Methode von String

Erstellt einen String-speichernden Typ.

Parameter:

length¶ – optional, eine Länge für die Spalte zur Verwendung in DDL- und CAST-Ausdrücken. Kann sicher weggelassen werden, wenn keine CREATE TABLE ausgegeben wird. Bestimmte Datenbanken benötigen möglicherweise eine length für die Verwendung in DDL und lösen eine Ausnahme aus, wenn die CREATE TABLE DDL für ein VARCHAR ohne Länge ausgegeben wird. Ob der Wert als Bytes oder Zeichen interpretiert wird, ist datenbankspezifisch.
collation¶ –
Optional, eine Spalten-Kollation zur Verwendung in DDL- und CAST-Ausdrücken. Wird mit dem COLLATE-Schlüsselwort gerendert, das von SQLite, MySQL und PostgreSQL unterstützt wird. Z.B.
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
Hinweis

In den meisten Fällen sollten die Datentypen Unicode oder UnicodeText für eine Column verwendet werden, die nicht-ASCII-Daten speichern soll. Diese Datentypen stellen sicher, dass die korrekten Typen auf der Datenbank verwendet werden.

class sqlalchemy.types.DATE¶: Der SQL-Datentyp DATE.

Klassensignatur

class sqlalchemy.types.DATE (sqlalchemy.types.Date)

class sqlalchemy.types.DATETIME¶

Der SQL-Datentyp DATETIME.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.DATETIME (sqlalchemy.types.DateTime)

method sqlalchemy.types.DATETIME.__init__(timezone: bool = False)¶

geerbt von der sqlalchemy.types.DateTime.__init__ Methode von DateTime

Konstruiert ein neues DateTime.

Parameter:: timezone¶ – boolesch. Gibt an, dass der Datetime-Typ die Zeitzonenunterstützung aktivieren soll, falls auf dem **grundlegenden datums-/zeitspeichernden Typ** verfügbar. Es wird empfohlen, den TIMESTAMP-Datentyp direkt zu verwenden, wenn dieses Flag verwendet wird, da einige Datenbanken separate generische datums-/zeitspeichernde Typen aufweisen, die sich vom zeitzonenfähigen TIMESTAMP-Datentyp unterscheiden, wie z. B. Oracle Database.

class sqlalchemy.types.DECIMAL¶

Der SQL-Datentyp DECIMAL.

Siehe auch

Numeric - Dokumentation für den Basistyp.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.DECIMAL (sqlalchemy.types.Numeric)

method sqlalchemy.types.DECIMAL.__init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)¶

geerbt von der sqlalchemy.types.Numeric.__init__ Methode von Numeric

Konstruiert einen `Numeric`.

Parameter:

precision¶ – die numerische Präzision für die Verwendung in DDL CREATE TABLE.
scale¶ – die numerische Skalierung für die Verwendung in DDL CREATE TABLE.
asdecimal¶ – Standardmäßig True. Gibt an, ob Werte als Python Decimal-Objekte oder als Gleitkommazahlen zurückgegeben werden sollen. Verschiedene DBAPIs geben eines von beiden zurück, je nach Datentyp – der Numeric-Typ stellt sicher, dass die Rückgabewerte über DBAPIs hinweg konsistent sind.
decimal_return_scale¶ – Standard-Skalierung, die beim Konvertieren von Gleitkommazahlen in Python-Dezimalzahlen verwendet wird. Gleitkommazahlen sind aufgrund von Dezimalungenauigkeiten typischerweise viel länger, und die meisten Gleitkomma-Datenbanktypen haben keine Vorstellung von "Skalierung", so dass der Float-Typ standardmäßig die ersten zehn Dezimalstellen bei der Konvertierung sucht. Die Angabe dieses Wertes überschreibt diese Länge. Typen, die einen expliziten ".scale"-Wert enthalten, wie der Basistyp Numeric sowie die MySQL-Float-Typen, verwenden den Wert von ".scale" als Standard für decimal_return_scale, falls nicht anders angegeben.

Bei Verwendung des Numeric-Datentyps ist Vorsicht geboten, um sicherzustellen, dass die `asdecimal`-Einstellung für den verwendeten DBAPI geeignet ist. Wenn Numeric eine Konvertierung von Decimal->float oder float->Decimal anwendet, verursacht diese Konvertierung zusätzliche Leistungskosten für alle empfangenen Ergebnisspalten.

DBAPIs, die Decimal nativ zurückgeben (z. B. psycopg2), haben eine bessere Genauigkeit und höhere Leistung bei True, da die native Übersetzung zu Decimal die Anzahl der Gleitkommaprobleme reduziert und der Numeric-Typ selbst keine weiteren Konvertierungen anwenden muss. Ein anderer DBAPI, der Floats nativ zurückgibt, *verursacht* jedoch zusätzliche Konvertierungskosten und unterliegt weiterhin Gleitkommadatenverlust – in diesem Fall entfernt asdecimal=False zumindest die zusätzlichen Konvertierungskosten.

class sqlalchemy.types.DOUBLE¶

Der SQL-Datentyp DOUBLE.

Neu in Version 2.0.

Siehe auch

Double - Dokumentation für den Basistyp.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.DOUBLE (sqlalchemy.types.Double)

method sqlalchemy.types.DOUBLE.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

geerbt von der sqlalchemy.types.Float.__init__ Methode von Float

Konstruiert einen Float.

Parameter:

precision¶ –
die numerische Präzision für die Verwendung in DDL CREATE TABLE. Backends **sollten** versuchen, diese Präzision anzugeben, um die Anzahl der Ziffern für den generischen Datentyp Float anzugeben.
Hinweis

Für das Oracle Database-Backend wird der Parameter Float.precision bei der Rendern von DDL nicht akzeptiert, da die Oracle Database keine Gleitkommapräzision unterstützt, die als Anzahl von Dezimalstellen angegeben wird. Verwenden Sie stattdessen den Oracle Database-spezifischen Datentyp FLOAT und geben Sie den Parameter FLOAT.binary_precision an. Dies ist neu in Version 2.0 von SQLAlchemy.

Um ein datenbankagnostisches Float zu erstellen, das die binäre Präzision für Oracle Database separat angibt, verwenden Sie TypeEngine.with_variant() wie folgt
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – dasselbe Flag wie bei Numeric, aber standardmäßig auf False gesetzt. Beachten Sie, dass das Setzen dieses Flags auf True zu einer Gleitkommakonvertierung führt.
decimal_return_scale¶ – Standard-Skalierung, die beim Konvertieren von Gleitkommazahlen in Python-Dezimalzahlen verwendet wird. Gleitkommazahlen sind aufgrund von Dezimalungenauigkeiten typischerweise viel länger, und die meisten Gleitkomma-Datenbanktypen haben keine Vorstellung von "Skalierung", so dass der Float-Typ standardmäßig die ersten zehn Dezimalstellen bei der Konvertierung sucht. Die Angabe dieses Wertes überschreibt diese Länge. Beachten Sie, dass die MySQL-Float-Typen, die eine "Skalierung" enthalten, "Skalierung" als Standard für decimal_return_scale verwenden, falls nicht anders angegeben.

class sqlalchemy.types.DOUBLE_PRECISION¶

Der SQL-Datentyp DOUBLE PRECISION.

Neu in Version 2.0.

Siehe auch

Double - Dokumentation für den Basistyp.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.DOUBLE_PRECISION (sqlalchemy.types.Double)

method sqlalchemy.types.DOUBLE_PRECISION.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

geerbt von der sqlalchemy.types.Float.__init__ Methode von Float

Konstruiert einen Float.

Parameter:

precision¶ –
die numerische Präzision für die Verwendung in DDL CREATE TABLE. Backends **sollten** versuchen, diese Präzision anzugeben, um die Anzahl der Ziffern für den generischen Datentyp Float anzugeben.
Hinweis

Für das Oracle Database-Backend wird der Parameter Float.precision bei der Rendern von DDL nicht akzeptiert, da die Oracle Database keine Gleitkommapräzision unterstützt, die als Anzahl von Dezimalstellen angegeben wird. Verwenden Sie stattdessen den Oracle Database-spezifischen Datentyp FLOAT und geben Sie den Parameter FLOAT.binary_precision an. Dies ist neu in Version 2.0 von SQLAlchemy.

Um ein datenbankagnostisches Float zu erstellen, das die binäre Präzision für Oracle Database separat angibt, verwenden Sie TypeEngine.with_variant() wie folgt
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – dasselbe Flag wie bei Numeric, aber standardmäßig auf False gesetzt. Beachten Sie, dass das Setzen dieses Flags auf True zu einer Gleitkommakonvertierung führt.
decimal_return_scale¶ – Standard-Skalierung, die beim Konvertieren von Gleitkommazahlen in Python-Dezimalzahlen verwendet wird. Gleitkommazahlen sind aufgrund von Dezimalungenauigkeiten typischerweise viel länger, und die meisten Gleitkomma-Datenbanktypen haben keine Vorstellung von "Skalierung", so dass der Float-Typ standardmäßig die ersten zehn Dezimalstellen bei der Konvertierung sucht. Die Angabe dieses Wertes überschreibt diese Länge. Beachten Sie, dass die MySQL-Float-Typen, die eine "Skalierung" enthalten, "Skalierung" als Standard für decimal_return_scale verwenden, falls nicht anders angegeben.

class sqlalchemy.types.FLOAT¶

Der SQL-Datentyp FLOAT.

Siehe auch

Float - Dokumentation für den Basistyp.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.FLOAT (sqlalchemy.types.Float)

method sqlalchemy.types.FLOAT.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

geerbt von der sqlalchemy.types.Float.__init__ Methode von Float

Konstruiert einen Float.

Parameter:

precision¶ –
die numerische Präzision für die Verwendung in DDL CREATE TABLE. Backends **sollten** versuchen, diese Präzision anzugeben, um die Anzahl der Ziffern für den generischen Datentyp Float anzugeben.
Hinweis

Für das Oracle Database-Backend wird der Parameter Float.precision bei der Rendern von DDL nicht akzeptiert, da die Oracle Database keine Gleitkommapräzision unterstützt, die als Anzahl von Dezimalstellen angegeben wird. Verwenden Sie stattdessen den Oracle Database-spezifischen Datentyp FLOAT und geben Sie den Parameter FLOAT.binary_precision an. Dies ist neu in Version 2.0 von SQLAlchemy.

Um ein datenbankagnostisches Float zu erstellen, das die binäre Präzision für Oracle Database separat angibt, verwenden Sie TypeEngine.with_variant() wie folgt
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – dasselbe Flag wie bei Numeric, aber standardmäßig auf False gesetzt. Beachten Sie, dass das Setzen dieses Flags auf True zu einer Gleitkommakonvertierung führt.
decimal_return_scale¶ – Standard-Skalierung, die beim Konvertieren von Gleitkommazahlen in Python-Dezimalzahlen verwendet wird. Gleitkommazahlen sind aufgrund von Dezimalungenauigkeiten typischerweise viel länger, und die meisten Gleitkomma-Datenbanktypen haben keine Vorstellung von "Skalierung", so dass der Float-Typ standardmäßig die ersten zehn Dezimalstellen bei der Konvertierung sucht. Die Angabe dieses Wertes überschreibt diese Länge. Beachten Sie, dass die MySQL-Float-Typen, die eine "Skalierung" enthalten, "Skalierung" als Standard für decimal_return_scale verwenden, falls nicht anders angegeben.

attribute sqlalchemy.types..sqlalchemy.types.INT¶: Alias für INTEGER

class sqlalchemy.types.JSON¶

Repräsentiert einen SQL-JSON-Typ.

Hinweis

JSON wird als Fassade für herstellerspezifische JSON-Typen bereitgestellt. Da er JSON-SQL-Operationen unterstützt, funktioniert er nur auf Backends, die einen tatsächlichen JSON-Typ haben, derzeit

PostgreSQL - siehe sqlalchemy.dialects.postgresql.JSON und sqlalchemy.dialects.postgresql.JSONB für backend-spezifische Hinweise
MySQL - siehe sqlalchemy.dialects.mysql.JSON für backend-spezifische Hinweise
SQLite ab Version 3.9 - siehe sqlalchemy.dialects.sqlite.JSON für backend-spezifische Hinweise
Microsoft SQL Server 2016 und höher - siehe sqlalchemy.dialects.mssql.JSON für backend-spezifische Hinweise

JSON ist Teil des Core zur Unterstützung der wachsenden Popularität nativer JSON-Datentypen.

Der JSON-Datentyp speichert beliebige JSON-Formatdaten, z. B.

data_table = Table(
    "data_table",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("data", JSON),
)

with engine.connect() as conn:
    conn.execute(
        data_table.insert(), {"data": {"key1": "value1", "key2": "value2"}}
    )

JSON-spezifische Ausdrucksoperatoren

Der JSON-Datentyp bietet diese zusätzlichen SQL-Operationen

Schlüsselbasierte Indexoperationen
```
data_table.c.data["some key"]
```
Ganzzahlbasierte Indexoperationen
```
data_table.c.data[3]
```

Pfadbasierte Indexoperationen

data_table.c.data[("key_1", "key_2", 5, ..., "key_n")]

Datenkonverter für bestimmte JSON-Elementtypen, nach Aufruf einer Index- oder Pfadoperation
```
data_table.c.data["some key"].as_integer()
```
Neu ab Version 1.3.11.

Zusätzliche Operationen können von den dialektspezifischen Versionen von JSON verfügbar sein, wie z. B. sqlalchemy.dialects.postgresql.JSON und sqlalchemy.dialects.postgresql.JSONB, die beide zusätzliche PostgreSQL-spezifische Operationen bieten.

Konvertierung von JSON-Elementen in andere Typen

Indexoperationen, d.h. solche, die durch Aufruf des Ausdrucks mit dem Python-Klammeroperator wie in some_column['some key'] aufgerufen werden, geben ein Ausdrucksobjekt zurück, dessen Typ standardmäßig JSON ist, so dass weitere JSON-orientierte Anweisungen auf den Ergebnistyp angewendet werden können. Wahrscheinlicher ist jedoch, dass eine Indexoperation ein bestimmtes Skalar-Element wie eine Zeichenkette oder eine Ganzzahl zurückgeben soll. Um auf diese Elemente backend-unabhängig zugreifen zu können, wird eine Reihe von Datenkonvertern bereitgestellt

Comparator.as_string() - gibt das Element als Zeichenkette zurück
Comparator.as_boolean() - gibt das Element als booleschen Wert zurück
Comparator.as_float() - gibt das Element als Gleitkommazahl zurück
Comparator.as_integer() - gibt das Element als Ganzzahl zurück

Diese Datentypen werden von unterstützenden Dialekten implementiert, um sicherzustellen, dass Vergleiche mit den obigen Typen wie erwartet funktionieren, z. B.:

# integer comparison
data_table.c.data["some_integer_key"].as_integer() == 5

# boolean comparison
data_table.c.data["some_boolean"].as_boolean() == True

Neu in Version 1.3.11: Typenspezifische Konverter für die grundlegenden JSON-Datenelementtypen hinzugefügt.

Hinweis

Die Datenkonverterfunktionen sind neu in Version 1.3.11 und ersetzen die zuvor dokumentierten Ansätze zur Verwendung von CAST; als Referenz sah dies wie folgt aus:

from sqlalchemy import cast, type_coerce
from sqlalchemy import String, JSON

cast(data_table.c.data["some_key"], String) == type_coerce(55, JSON)

Der obige Fall funktioniert jetzt direkt wie

data_table.c.data["some_key"].as_integer() == 5

Details zum vorherigen Vergleichsansatz in der Serie 1.3.x finden Sie in der Dokumentation für SQLAlchemy 1.2 oder in den enthaltenen HTML-Dateien im Verzeichnis doc/ der jeweiligen Version.

Änderungen in JSON-Spalten bei Verwendung des ORM erkennen

Der Typ JSON erkennt bei Verwendung mit dem SQLAlchemy ORM keine In-Place-Mutationen der Struktur. Um diese zu erkennen, muss die Erweiterung sqlalchemy.ext.mutable verwendet werden, am häufigsten mit der Klasse MutableDict. Diese Erweiterung ermöglicht es "In-Place"-Änderungen an der Datenstruktur, Ereignisse zu erzeugen, die von der Unit of Work erkannt werden. Siehe das Beispiel unter HSTORE für ein einfaches Beispiel mit einem Wörterbuch.

Alternativ löst die Zuweisung einer JSON-Struktur an ein ORM-Element, das das alte ersetzt, immer ein Änderungsereignis aus.

Unterstützung für JSON-Null vs. SQL-NULL

Bei der Arbeit mit NULL-Werten empfiehlt der Typ JSON die Verwendung von zwei spezifischen Konstanten, um zwischen einer Spalte, die zu SQL NULL ausgewertet wird (d. h. kein Wert), und dem JSON-kodierten String "null" zu unterscheiden. Um einen Wert einzufügen oder abzufragen, der SQL NULL ist, verwenden Sie die Konstante null(). Dieses Symbol kann als Parameterwert übergeben werden, insbesondere bei Verwendung des Datentyps JSON, der spezielle Logik enthält, die dieses Symbol interpretiert als bedeutet, dass der Spaltenwert SQL NULL und nicht JSON "null" sein soll.

from sqlalchemy import null

conn.execute(table.insert(), {"json_value": null()})

Um einen Wert einzufügen oder abzufragen, der JSON "null" ist, verwenden Sie die Konstante JSON.NULL.

conn.execute(table.insert(), {"json_value": JSON.NULL})

Der Typ JSON unterstützt ein Flag JSON.none_as_null, das, wenn es auf True gesetzt ist, dazu führt, dass die Python-Konstante None als SQL NULL ausgewertet wird, und wenn es auf False gesetzt ist, dazu führt, dass die Python-Konstante None als JSON "null" ausgewertet wird. Der Python-Wert None kann in Verbindung mit JSON.NULL und null() verwendet werden, um NULL-Werte anzuzeigen. Dabei ist jedoch auf den Wert von JSON.none_as_null zu achten.

Anpassen des JSON-Serialisierers

Der von JSON verwendete JSON-Serialisierer und -Deserialisierer sind standardmäßig die Funktionen json.dumps und json.loads von Python; im Fall des psycopg2-Dialekts kann psycopg2 seine eigene benutzerdefinierte Ladefunktion verwenden.

Um den Serialisierer/Deserialisierer zu beeinflussen, können diese derzeit auf der Ebene von create_engine() über die Parameter create_engine.json_serializer und create_engine.json_deserializer konfiguriert werden. Zum Beispiel, um ensure_ascii zu deaktivieren.

engine = create_engine(
    "sqlite://",
    json_serializer=lambda obj: json.dumps(obj, ensure_ascii=False),
)

Geändert in Version 1.3.7: Die Parameter json_serializer und json_deserializer des SQLite-Dialekts wurden von _json_serializer und _json_deserializer umbenannt.

Siehe auch

sqlalchemy.dialects.postgresql.JSON

sqlalchemy.dialects.postgresql.JSONB

sqlalchemy.dialects.mysql.JSON

sqlalchemy.dialects.sqlite.JSON

Mitglieder

as_boolean(), as_float(), as_integer(), as_json(), as_numeric(), as_string(), bind_processor(), literal_processor(), NULL, __init__(), bind_processor(), comparator_factory, hashable, python_type, result_processor(), should_evaluate_none

Klassensignatur

class sqlalchemy.types.JSON (sqlalchemy.types.Indexable, sqlalchemy.types.TypeEngine)

class Comparator¶

Definiert Vergleichsoperationen für JSON.

Klassensignatur

class sqlalchemy.types.JSON.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)

method sqlalchemy.types.JSON.Comparator.as_boolean()¶

Betrachtet einen indizierten Wert als booleschen Wert.

Dies ist ähnlich wie die Verwendung von type_coerce und wird normalerweise kein CAST() anwenden.

z. B.

stmt = select(mytable.c.json_column["some_data"].as_boolean()).where(
    mytable.c.json_column["some_data"].as_boolean() == True
)

Neu ab Version 1.3.11.

method sqlalchemy.types.JSON.Comparator.as_float()¶

Betrachtet einen indizierten Wert als Float.

Dies ist ähnlich wie die Verwendung von type_coerce und wird normalerweise kein CAST() anwenden.

z. B.

stmt = select(mytable.c.json_column["some_data"].as_float()).where(
    mytable.c.json_column["some_data"].as_float() == 29.75
)

Neu ab Version 1.3.11.

method sqlalchemy.types.JSON.Comparator.as_integer()¶

Betrachtet einen indizierten Wert als Integer.

Dies ist ähnlich wie die Verwendung von type_coerce und wird normalerweise kein CAST() anwenden.

z. B.

stmt = select(mytable.c.json_column["some_data"].as_integer()).where(
    mytable.c.json_column["some_data"].as_integer() == 5
)

Neu ab Version 1.3.11.

method sqlalchemy.types.JSON.Comparator.as_json()¶

Betrachtet einen indizierten Wert als JSON.

Dies ist ähnlich wie die Verwendung von type_coerce und wird normalerweise kein CAST() anwenden.

z. B.

stmt = select(mytable.c.json_column["some_data"].as_json())

Dies ist in der Regel das Standardverhalten für indizierte Elemente.

Beachten Sie, dass der Vergleich vollständiger JSON-Strukturen möglicherweise nicht von allen Backends unterstützt wird.

Neu ab Version 1.3.11.

method sqlalchemy.types.JSON.Comparator.as_numeric(precision, scale, asdecimal=True)¶

Betrachtet einen indizierten Wert als numerischen/Dezimalwert.

Dies ist ähnlich wie die Verwendung von type_coerce und wird normalerweise kein CAST() anwenden.

z. B.

stmt = select(mytable.c.json_column["some_data"].as_numeric(10, 6)).where(
    mytable.c.json_column["some_data"].as_numeric(10, 6) == 29.75
)

Neu ab Version 1.4.0b2.

method sqlalchemy.types.JSON.Comparator.as_string()¶

Betrachtet einen indizierten Wert als String.

Dies ist ähnlich wie die Verwendung von type_coerce und wird normalerweise kein CAST() anwenden.

z. B.

stmt = select(mytable.c.json_column["some_data"].as_string()).where(
    mytable.c.json_column["some_data"].as_string() == "some string"
)

Neu ab Version 1.3.11.

class JSONElementType¶

Gemeinsame Funktion für Index- / Pfadelemente in einem JSON-Ausdruck.

Klassensignatur

class sqlalchemy.types.JSON.JSONElementType (sqlalchemy.types.TypeEngine)

method sqlalchemy.types.JSON.JSONElementType.bind_processor(dialect: Dialect) → _BindProcessorType[Any]¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Bindungswerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Bindungsparameterwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der an die DB-API gesendet werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.bind_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.bind_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_bind_param() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:: dialect¶ – Instanz des verwendeten Dialekts.

method sqlalchemy.types.JSON.JSONElementType.literal_processor(dialect: Dialect) → _LiteralProcessorType[Any]¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Literalwerten zurück, die direkt ohne Verwendung von Binds gerendert werden sollen.

Diese Funktion wird verwendet, wenn der Compiler das Flag „literal_binds“ verwendet, was typischerweise bei der DDL-Generierung sowie in bestimmten Szenarien, in denen Backends keine gebundenen Parameter akzeptieren, verwendet wird.

Gibt eine aufrufbare Funktion zurück, die einen literalen Python-Wert als einziges positionsbezogenes Argument erhält und eine Zeichenkettendarstellung zurückgibt, die in einer SQL-Anweisung gerendert wird.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.literal_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.literal_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_literal_param() bereit.

Siehe auch

Erweitern bestehender Typen

class JSONIndexType¶

Platzhalter für den Datentyp eines JSON-Indexwerts.

Dies ermöglicht die Laufzeitverarbeitung von JSON-Indexwerten für spezielle Syntaxen.

Klassensignatur

class sqlalchemy.types.JSON.JSONIndexType (sqlalchemy.types.JSONElementType)

class JSONIntIndexType¶

Platzhalter für den Datentyp eines JSON-Indexwerts.

Dies ermöglicht die Laufzeitverarbeitung von JSON-Indexwerten für spezielle Syntaxen.

Klassensignatur

class sqlalchemy.types.JSON.JSONIntIndexType (sqlalchemy.types.JSONIndexType)

class JSONPathType¶

Platzhaltertyp für JSON-Pfadoperationen.

Dies ermöglicht die Laufzeitverarbeitung eines pfadbasierten Indexwerts in eine spezifische SQL-Syntax.

Klassensignatur

class sqlalchemy.types.JSON.JSONPathType (sqlalchemy.types.JSONElementType)

class JSONStrIndexType¶

Platzhalter für den Datentyp eines JSON-Indexwerts.

Dies ermöglicht die Laufzeitverarbeitung von JSON-Indexwerten für spezielle Syntaxen.

Klassensignatur

class sqlalchemy.types.JSON.JSONStrIndexType (sqlalchemy.types.JSONIndexType)

attribute sqlalchemy.types.JSON.NULL = symbol('JSON_NULL')¶

Beschreibt den JSON-Wert von NULL.

Dieser Wert wird verwendet, um zu erzwingen, dass der JSON-Wert "null" als Wert verwendet wird. Ein Wert von Python None wird entweder als SQL NULL oder als JSON "null" erkannt, basierend auf der Einstellung des Flags JSON.none_as_null; die Konstante JSON.NULL kann verwendet werden, um unabhängig von dieser Einstellung immer zu JSON "null" aufzulösen. Dies steht im Gegensatz zu dem Konstrukt null(), das immer zu SQL NULL aufgelöst wird. Z.B.

from sqlalchemy import null
from sqlalchemy.dialects.postgresql import JSON

# will *always* insert SQL NULL
obj1 = MyObject(json_value=null())

# will *always* insert JSON string "null"
obj2 = MyObject(json_value=JSON.NULL)

session.add_all([obj1, obj2])
session.commit()

Um JSON NULL als Standardwert für eine Spalte festzulegen, ist die transparenteste Methode die Verwendung von text()

Table(
    "my_table", metadata, Column("json_data", JSON, default=text("'null'"))
)

Obwohl es möglich ist, JSON.NULL in diesem Kontext zu verwenden, wird der Wert JSON.NULL als Wert der Spalte zurückgegeben, was im Kontext des ORM oder anderer Wiederverwendungen des Standardwerts möglicherweise nicht wünschenswert ist. Die Verwendung eines SQL-Ausdrucks bedeutet, dass der Wert aus der Datenbank im Kontext des Abrufens generierter Standardwerte neu abgefragt wird.

method sqlalchemy.types.JSON.__init__(none_as_null: bool = False)¶

Konstruiert einen JSON-Typ.

Parameter:

none_as_null=False¶ –

wenn True, persistiert den Wert None als SQL NULL, nicht als JSON-Kodierung von null. Beachten Sie, dass, wenn dieses Flag False ist, das Konstrukt null() immer noch verwendet werden kann, um einen NULL-Wert zu persistieren, der direkt als Parameterwert übergeben werden kann, der vom Typ JSON speziell als SQL NULL interpretiert wird.

from sqlalchemy import null

conn.execute(table.insert(), {"data": null()})

Hinweis

JSON.none_as_null gilt **nicht** für die Werte, die an Column.default und Column.server_default übergeben werden; ein Wert von None, der für diese Parameter übergeben wird, bedeutet "kein Standard vorhanden".

Zusätzlich gilt bei Verwendung in SQL-Vergleichsausdrücken der Python-Wert None weiterhin für SQL null und nicht für JSON null. Das Flag JSON.none_as_null bezieht sich explizit auf die **Persistenz** des Werts in einer INSERT- oder UPDATE-Anweisung. Der Wert JSON.NULL sollte für SQL-Ausdrücke verwendet werden, die mit JSON null verglichen werden sollen.

Siehe auch

JSON.NULL

method sqlalchemy.types.JSON.bind_processor(dialect)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Bindungswerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Bindungsparameterwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der an die DB-API gesendet werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.bind_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.bind_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_bind_param() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:: dialect¶ – Instanz des verwendeten Dialekts.

attribute sqlalchemy.types.JSON.comparator_factory¶: alias von Comparator

attribute sqlalchemy.types.JSON.hashable = False¶

Flag, wenn False, bedeutet, dass Werte dieses Typs nicht hashbar sind.

Wird vom ORM beim Eindeutigen machen von Ergebnislisten verwendet.

attribute sqlalchemy.types.JSON.python_type¶

method sqlalchemy.types.JSON.result_processor(dialect, coltype)¶

Gibt eine Konvertierungsfunktion zur Verarbeitung von Ergebniszeilenwerten zurück.

Gibt eine aufrufbare Funktion zurück, die einen Ergebniszeilen-Spaltenwert als einziges Positionsargument empfängt und einen Wert zurückgibt, der dem Benutzer zurückgegeben werden soll.

Wenn keine Verarbeitung erforderlich ist, sollte die Methode None zurückgeben.

Hinweis

Diese Methode wird nur in Bezug auf ein **dialektspezifisches Typobjekt** aufgerufen, das oft **privat für den verwendeten Dialekt** ist und nicht dasselbe Typobjekt wie das öffentlich sichtbare ist. Daher ist es nicht möglich, eine TypeEngine-Klasse zu unterklassen, um eine alternative TypeEngine.result_processor()-Methode bereitzustellen, es sei denn, Sie unterklassen explizit die UserDefinedType-Klasse.

Um ein alternatives Verhalten für TypeEngine.result_processor() bereitzustellen, implementieren Sie eine TypeDecorator-Klasse und stellen Sie eine Implementierung von TypeDecorator.process_result_value() bereit.

Siehe auch

Erweitern bestehender Typen

Parameter:

dialect¶ – Instanz des verwendeten Dialekts.
coltype¶ – DBAPI-coltype-Argument, das in cursor.description empfangen wurde.

attribute sqlalchemy.types.JSON.should_evaluate_none: bool¶

Wenn True, wird die Python-Konstante None explizit von diesem Typ behandelt.

Das ORM verwendet dieses Flag, um anzuzeigen, dass ein positiver Wert von None in einer INSERT-Anweisung an die Spalte übergeben wird, anstatt die Spalte aus der INSERT-Anweisung wegzulassen, was die Ausführung spaltenspezifischer Standardwerte zur Folge hat. Es ermöglicht auch Typen mit speziellem Verhalten für Python None, wie z. B. ein JSON-Typ, anzuzeigen, dass sie den None-Wert explizit behandeln möchten.

Um dieses Flag für einen vorhandenen Typ festzulegen, verwenden Sie die Methode TypeEngine.evaluates_none().

Siehe auch

TypeEngine.evaluates_none()

class sqlalchemy.types.INTEGER¶: Der SQL-Datentyp INT oder INTEGER.

Siehe auch

Integer - Dokumentation für den Basistyp.

Klassensignatur

class sqlalchemy.types.INTEGER (sqlalchemy.types.Integer)

class sqlalchemy.types.NCHAR¶

Der SQL-Datentyp NCHAR.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.NCHAR (sqlalchemy.types.Unicode)

method sqlalchemy.types.NCHAR.__init__(length: int | None = None, collation: str | None = None)¶

geerbt von der sqlalchemy.types.String.__init__ Methode von String

Erstellt einen String-speichernden Typ.

Parameter:

length¶ – optional, eine Länge für die Spalte zur Verwendung in DDL- und CAST-Ausdrücken. Kann sicher weggelassen werden, wenn keine CREATE TABLE-Anweisung ausgegeben wird. Bestimmte Datenbanken erfordern möglicherweise eine length für die Verwendung in DDL und lösen eine Ausnahme aus, wenn die CREATE TABLE-DDL ausgegeben wird, wenn ein VARCHAR ohne Länge enthalten ist. Ob der Wert als Bytes oder Zeichen interpretiert wird, ist datenbankspezifisch.
collation¶ –
Optional, eine Spalten-Kollation zur Verwendung in DDL- und CAST-Ausdrücken. Wird mit dem COLLATE-Schlüsselwort gerendert, das von SQLite, MySQL und PostgreSQL unterstützt wird. Z.B.
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
Hinweis

In den meisten Fällen sollten die Datentypen Unicode oder UnicodeText für eine Column verwendet werden, die nicht-ASCII-Daten speichern soll. Diese Datentypen stellen sicher, dass die korrekten Typen auf der Datenbank verwendet werden.

class sqlalchemy.types.NVARCHAR¶

Der SQL-Datentyp NVARCHAR.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.NVARCHAR (sqlalchemy.types.Unicode)

method sqlalchemy.types.NVARCHAR.__init__(length: int | None = None, collation: str | None = None)¶

geerbt von der sqlalchemy.types.String.__init__ Methode von String

Erstellt einen String-speichernden Typ.

Parameter:

length¶ – optional, eine Länge für die Spalte zur Verwendung in DDL- und CAST-Ausdrücken. Kann sicher weggelassen werden, wenn keine CREATE TABLE Anweisung ausgegeben wird. Bestimmte Datenbanken können eine length für die Verwendung in DDL benötigen und lösen eine Ausnahme aus, wenn die CREATE TABLE DDL-Anweisung ausgegeben wird, wenn ein VARCHAR ohne Länge enthalten ist. Ob der Wert als Bytes oder Zeichen interpretiert wird, ist datenbankspezifisch.
collation¶ –
Optional, eine Spalten-Kollation zur Verwendung in DDL- und CAST-Ausdrücken. Wird mit dem COLLATE-Schlüsselwort gerendert, das von SQLite, MySQL und PostgreSQL unterstützt wird. Z.B.
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
Hinweis

In den meisten Fällen sollten die Datentypen Unicode oder UnicodeText für eine Column verwendet werden, die nicht-ASCII-Daten speichern soll. Diese Datentypen stellen sicher, dass die korrekten Typen auf der Datenbank verwendet werden.

class sqlalchemy.types.NUMERIC¶

Der SQL-Datentyp NUMERIC.

Siehe auch

Numeric - Dokumentation für den Basistyp.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.NUMERIC (sqlalchemy.types.Numeric)

method sqlalchemy.types.NUMERIC.__init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)¶

geerbt von der sqlalchemy.types.Numeric.__init__ Methode von Numeric

Konstruiert einen `Numeric`.

Parameter:

precision¶ – die numerische Präzision zur Verwendung in DDL CREATE TABLE.
scale¶ – der numerische Scale zur Verwendung in DDL CREATE TABLE.
asdecimal¶ – Standardmäßig True. Gibt zurück, ob Werte als Python Decimal-Objekte oder als Floats gesendet werden sollen. Verschiedene DBAPIs senden eines von beiden basierend auf Datentypen – der Numeric-Typ stellt sicher, dass Rückgabewerte über DBAPIs hinweg konsistent eines von beiden sind.
decimal_return_scale¶ – Standard-Scale bei der Konvertierung von Floats in Python-Dezimalzahlen. Gleitkommazahlen sind typischerweise aufgrund von Dezimalungenauigkeiten sehr lang, und die meisten Gleitkomma-Datenbanktypen haben keinen Begriff von "Scale". Daher sucht der Float-Typ standardmäßig nach den ersten zehn Dezimalstellen bei der Konvertierung. Die Angabe dieses Werts überschreibt diese Länge. Typen, die einen expliziten ".scale"-Wert enthalten, wie z. B. der Basis-Typ Numeric sowie die MySQL-Float-Typen, verwenden den Wert von ".scale" als Standard für decimal_return_scale, sofern nicht anders angegeben.

Bei Verwendung des Numeric-Datentyps ist Vorsicht geboten, um sicherzustellen, dass die `asdecimal`-Einstellung für den verwendeten DBAPI geeignet ist. Wenn Numeric eine Konvertierung von Decimal->float oder float->Decimal anwendet, verursacht diese Konvertierung zusätzliche Leistungskosten für alle empfangenen Ergebnisspalten.

DBAPIs, die Decimal nativ zurückgeben (z. B. psycopg2), haben eine bessere Genauigkeit und höhere Leistung bei True, da die native Übersetzung zu Decimal die Anzahl der Gleitkommaprobleme reduziert und der Numeric-Typ selbst keine weiteren Konvertierungen anwenden muss. Ein anderer DBAPI, der Floats nativ zurückgibt, *verursacht* jedoch zusätzliche Konvertierungskosten und unterliegt weiterhin Gleitkommadatenverlust – in diesem Fall entfernt asdecimal=False zumindest die zusätzlichen Konvertierungskosten.

class sqlalchemy.types.REAL¶

Der SQL-Datentyp REAL.

Siehe auch

Float - Dokumentation für den Basistyp.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.REAL (sqlalchemy.types.Float)

method sqlalchemy.types.REAL.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

geerbt von der sqlalchemy.types.Float.__init__ Methode von Float

Konstruiert einen Float.

Parameter:

precision¶ –
die numerische Präzision für die Verwendung in DDL CREATE TABLE. Backends **sollten** versuchen, diese Präzision anzugeben, um die Anzahl der Ziffern für den generischen Datentyp Float anzugeben.
Hinweis

Für das Oracle Database-Backend wird der Parameter Float.precision bei der Rendern von DDL nicht akzeptiert, da die Oracle Database keine Gleitkommapräzision unterstützt, die als Anzahl von Dezimalstellen angegeben wird. Verwenden Sie stattdessen den Oracle Database-spezifischen Datentyp FLOAT und geben Sie den Parameter FLOAT.binary_precision an. Dies ist neu in Version 2.0 von SQLAlchemy.

Um ein datenbankagnostisches Float zu erstellen, das die binäre Präzision für Oracle Database separat angibt, verwenden Sie TypeEngine.with_variant() wie folgt
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – das gleiche Flag wie bei Numeric, aber standardmäßig auf False gesetzt. Beachten Sie, dass das Setzen dieses Flags auf True zu einer Gleitkomma-Konvertierung führt.
decimal_return_scale¶ – Standard-Scale bei der Konvertierung von Floats in Python-Dezimalzahlen. Gleitkommazahlen sind typischerweise aufgrund von Dezimalungenauigkeiten sehr lang, und die meisten Gleitkomma-Datenbanktypen haben keinen Begriff von "Scale". Daher sucht der Float-Typ standardmäßig nach den ersten zehn Dezimalstellen bei der Konvertierung. Die Angabe dieses Werts überschreibt diese Länge. Beachten Sie, dass die MySQL-Float-Typen, die "Scale" enthalten, "Scale" als Standard für decimal_return_scale verwenden, sofern nicht anders angegeben.

class sqlalchemy.types.SMALLINT¶: Der SQL-Datentyp SMALLINT.

Siehe auch

SmallInteger - Dokumentation für den Basistyp.

Klassensignatur

class sqlalchemy.types.SMALLINT (sqlalchemy.types.SmallInteger)

class sqlalchemy.types.TEXT¶

Der SQL-Datentyp TEXT.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.TEXT (sqlalchemy.types.Text)

method sqlalchemy.types.TEXT.__init__(length: int | None = None, collation: str | None = None)¶

geerbt von der sqlalchemy.types.String.__init__ Methode von String

Erstellt einen String-speichernden Typ.

Parameter:

length¶ – optional, eine Länge für die Spalte zur Verwendung in DDL- und CAST-Ausdrücken. Kann sicher weggelassen werden, wenn keine CREATE TABLE Anweisung ausgegeben wird. Bestimmte Datenbanken können eine length für die Verwendung in DDL benötigen und lösen eine Ausnahme aus, wenn die CREATE TABLE DDL-Anweisung ausgegeben wird, wenn ein VARCHAR ohne Länge enthalten ist. Ob der Wert als Bytes oder Zeichen interpretiert wird, ist datenbankspezifisch.
collation¶ –
Optional, eine Spalten-Kollation zur Verwendung in DDL- und CAST-Ausdrücken. Wird mit dem COLLATE-Schlüsselwort gerendert, das von SQLite, MySQL und PostgreSQL unterstützt wird. Z.B.
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
Hinweis

In den meisten Fällen sollten die Datentypen Unicode oder UnicodeText für eine Column verwendet werden, die nicht-ASCII-Daten speichern soll. Diese Datentypen stellen sicher, dass die korrekten Typen auf der Datenbank verwendet werden.

class sqlalchemy.types.TIME¶: Der SQL-Datentyp TIME.

Klassensignatur

class sqlalchemy.types.TIME (sqlalchemy.types.Time)

class sqlalchemy.types.TIMESTAMP¶

Der SQL-Datentyp TIMESTAMP.

TIMESTAMP-Datentypen unterstützen die Zeitzonenspeicherung auf einigen Backends, wie z. B. PostgreSQL und Oracle Database. Verwenden Sie das Argument TIMESTAMP.timezone, um "TIMESTAMP WITH TIMEZONE" für diese Backends zu aktivieren.

Mitglieder

__init__(), get_dbapi_type()

Klassensignatur

class sqlalchemy.types.TIMESTAMP (sqlalchemy.types.DateTime)

method sqlalchemy.types.TIMESTAMP.__init__(timezone: bool = False)¶

Erstellt einen neuen TIMESTAMP.

Parameter:: timezone¶ – boolesch. Gibt an, dass der TIMESTAMP-Typ die Zeitzonenunterstützung aktivieren soll, falls auf der Ziel-Datenbank verfügbar. Auf Dialekt-Basis ist dies ähnlich wie "TIMESTAMP WITH TIMEZONE". Wenn die Ziel-Datenbank keine Zeitzonen unterstützt, wird dieses Flag ignoriert.

method sqlalchemy.types.TIMESTAMP.get_dbapi_type(dbapi)¶

Gibt den entsprechenden Typobjekt aus der zugrunde liegenden DB-API zurück, falls vorhanden.

Dies kann beispielsweise nützlich sein, um setinputsizes() aufzurufen.

class sqlalchemy.types.UUID¶

Repräsentiert den SQL-Datentyp UUID.

Dies ist die SQL-native Form des datenbankagnostischen Datentyps Uuid und ist abwärtskompatibel mit der früheren PostgreSQL-spezifischen Version von UUID.

Der Datentyp UUID funktioniert nur auf Datenbanken, die einen SQL-Datentyp namens UUID haben. Er funktioniert nicht für Backends, die diesen exakten Typnamen nicht haben, einschließlich SQL Server. Für backend-agnostische UUID-Werte mit nativer Unterstützung, einschließlich SQL Servers UNIQUEIDENTIFIER Datentyp, verwenden Sie den Datentyp Uuid.

Neu in Version 2.0.

Siehe auch

Uuid

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.UUID (sqlalchemy.types.Uuid, sqlalchemy.types.NativeForEmulated)

method sqlalchemy.types.UUID.__init__(as_uuid: bool = True)¶

Konstruiert einen UUID-Typ.

Parameter:

as_uuid=True¶ –

wenn True, werden Werte als Python-UUID-Objekte interpretiert und über DBAPI in Zeichenketten konvertiert.

class sqlalchemy.types.VARBINARY¶: Der SQL-Datentyp VARBINARY.

Klassensignatur

class sqlalchemy.types.VARBINARY (sqlalchemy.types._Binary)

class sqlalchemy.types.VARCHAR¶

Der SQL-Datentyp VARCHAR.

Mitglieder

__init__()

Klassensignatur

class sqlalchemy.types.VARCHAR (sqlalchemy.types.String)

method sqlalchemy.types.VARCHAR.__init__(length: int | None = None, collation: str | None = None)¶

geerbt von der sqlalchemy.types.String.__init__ Methode von String

Erstellt einen String-speichernden Typ.

Parameter:

length¶ – optional, eine Länge für die Spalte zur Verwendung in DDL- und CAST-Ausdrücken. Kann sicher weggelassen werden, wenn keine CREATE TABLE Anweisung ausgegeben wird. Bestimmte Datenbanken können eine length für die Verwendung in DDL benötigen und lösen eine Ausnahme aus, wenn die CREATE TABLE DDL-Anweisung ausgegeben wird, wenn ein VARCHAR ohne Länge enthalten ist. Ob der Wert als Bytes oder Zeichen interpretiert wird, ist datenbankspezifisch.
collation¶ –
Optional, eine Spalten-Kollation zur Verwendung in DDL- und CAST-Ausdrücken. Wird mit dem COLLATE-Schlüsselwort gerendert, das von SQLite, MySQL und PostgreSQL unterstützt wird. Z.B.
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
Hinweis

In den meisten Fällen sollten die Datentypen Unicode oder UnicodeText für eine Column verwendet werden, die nicht-ASCII-Daten speichern soll. Diese Datentypen stellen sicher, dass die korrekten Typen auf der Datenbank verwendet werden.

SQLAlchemy 2.0 Dokumentation

SQLAlchemy 2.0 Dokumentation

SQLAlchemy Core

Projektversionen

Die Typenhierarchie¶

Die „CamelCase“-Datentypen¶

Die „UPPERCASE“-Datentypen¶

Backend-spezifische „UPPERCASE“-Datentypen¶

Verwendung von „UPPERCASE“- und Backend-spezifischen Typen für mehrere Backends¶

Generische „CamelCase“-Typen¶

SQL-Standard und "UPPERCASE"-Typen für mehrere Anbieter¶