Datentypabbildungen für mssql-python

Der mssql-python-Treiber bildet beim Senden von Parametern automatisch Python-Datentypen auf SQL Server-Typen ab und wandelt SQL Server-Typen in Python-Typen um, wenn Ergebnisse abgerufen werden.

Python-zu-SQL Server-Zuordnungen

Wenn du Python-Werte als Parameter an execute() oder executemany()gibst, wählt der Treiber automatisch den entsprechenden SQL Server-Typ. Für die meisten Anwendungen ist die automatische Zuordnung korrekt. Verwenden setinputsizes() Sie (später in diesem Artikel beschrieben) nur, wenn Sie den Standard überschreiben müssen, zum Beispiel um varchar statt nvarchar zu erzwingen oder um Parametermetadaten für String- und Ganzzahleingaben zu steuern.

Ganzzahlige Typauswahl

Der Treiber wählt automatisch den kleinsten ganzzahligen Typ, der den Wert halten kann:

Große Wert-Typen

Für Strings und Binärdaten, die Standardlimits überschreiten, verwendet der Treiber automatisch MAX-Typen:

Der Treiber streamt große Werte an den Server, um den Speicherverbrauch zu minimieren.

SQL Server-zu-Python-Mappings

Wenn der Treiber Daten aus dem SQL Server abruft, wandelt er Werte in Python-Typen um:

SQL-Typkonstanten

Der Treiber exportiert Konstanten, die den ODBC SQL-Typ-Identifikatoren entsprechen. Du verwendest diese Konstanten typischerweise mit setinputsizes() , um die Standardtyp-Inferenz des Fahrers zu überschreiben, wenn die automatische Zuordnung nicht mit deinem Schema übereinstimmt.

Zeichentypen

Numerische Typen

Datums- und Uhrzeittypen

Binäre Typen

Andere Typen

Verwenden Sie setinputsizes()

Ruf vorher auf setinputsizes() , executemany() um explizit Parametertypen zu deklarieren, wenn die automatische Typinferenz des Fahrers unerwartetes Verhalten verursacht, zum Beispiel wenn eine Spalte ist varchar(100) , aber der Treiber sendet nvarchar:

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

# Declare types: (sql_type, precision, scale)
cursor.setinputsizes([
    (mssql_python.SQL_WVARCHAR, 100, 0),  # nvarchar(100)
    (mssql_python.SQL_INTEGER, 0, 0),     # int
])

cursor.executemany(
    "SELECT ProductID, Name FROM Production.Product WHERE Name LIKE ? AND ProductSubcategoryID = ?",
    [
        ("Road%", 2),
        ("Mountain%", 1),
    ]
)

Dezimaltrennzeichen

Der Fahrer verwendet lokalisierte Dezimaltrenner. Zum Anpassen:

import mssql_python

# Get current separator
sep = mssql_python.getDecimalSeparator()
print(f"Current separator: {sep}")  # Usually "."

# Set custom separator (for locales using comma)
mssql_python.setDecimalSeparator(",")

Individuelle Wandler

Registrieren Sie benutzerdefinierte Konverter für bestimmte SQL-Typen:

import mssql_python
from decimal import Decimal

def money_to_float(value):
    """Convert money values to float instead of Decimal."""
    if value is None:
        return None
    return float(value)

conn.add_output_converter(Decimal, money_to_float)

Weitere Informationen finden Sie unter Custom type Converters.

Handle spezielle Typen

UUID-Handhabung

Der Treiber wird automatisch zugeordnet uuid.UUIDuniqueidentifier . Du kannst UUIDs ohne manuelle String-Umwandlung einfügen und abrufen:

import uuid

cursor.execute("CREATE TABLE #Users (UserId UNIQUEIDENTIFIER PRIMARY KEY, Name NVARCHAR(100))")

# Insert a generated UUID
user_id = uuid.uuid4()
cursor.execute("INSERT INTO #Users (UserId, Name) VALUES (%(user_id)s, %(name)s)", {"user_id": user_id, "name": "Alice"})
conn.commit()

# Retrieve as uuid.UUID object (default behavior)
cursor.execute("SELECT UserId, Name FROM #Users WHERE Name = %(name)s", {"name": "Alice"})
row = cursor.fetchone()
print(f"Type: {type(row.UserId)}")  # <class 'uuid.UUID'>
print(f"UUID: {row.UserId}")        # e.g., 3b4c8f2a-...

# Use the returned UUID directly in subsequent queries
cursor.execute("SELECT Name FROM #Users WHERE UserId = %(user_id)s", {"user_id": row.UserId})

Standardmäßig gibt der Treiber Spalten als UNIQUEIDENTIFIER Objekte zurückuuid.UUID. Um stattdessen pyodbc-kompatible Großbuchstaben-Zeichenketten zurückzugeben, setze native_uuid=False:

import uuid

# Per-connection: return UUIDs as strings
conn2 = mssql_python.connect(connection_string, native_uuid=False)
cursor2 = conn2.cursor()
cursor2.execute("CREATE TABLE #UuidDemo (Id UNIQUEIDENTIFIER DEFAULT NEWID(), Label NVARCHAR(50))")
cursor2.execute("INSERT INTO #UuidDemo (Label) VALUES (%(label)s)", {"label": "test"})
conn2.commit()

cursor2.execute("SELECT Id FROM #UuidDemo")
row = cursor2.fetchone()
print(type(row[0]))  # <class 'str'>
print(row[0])        # e.g., 3B4C8F2A-...
conn2.close()

Für die Konfiguration auf Modulebene siehe die native_uuidEinstellung in Modulkonfiguration.

Datumszeit mit Zeitzone

datetimeoffset Spalten geben zeitzonenbewusste datetime Objekte zurück. Für Hinweise zum Umgang mit offset-bewussten versus offset-naiven Werten siehe Datetime-Handling.

cursor.execute("SELECT SYSDATETIMEOFFSET()")
row = cursor.fetchone()
dt = row[0]

print(f"DateTime: {dt}")
print(f"Timezone: {dt.tzinfo}")

Räumliche Daten

Der Treiber gibt räumliche Typen (geography, geometry) als zurück bytes. Sie können Parameterstrings im WKT-Format verwenden:

# Insert using WKT
cursor.execute("CREATE TABLE #Locations (Name NVARCHAR(100), Geo GEOGRAPHY)")
cursor.execute(
    "INSERT INTO #Locations (Name, Geo) VALUES (%(name)s, geography::STGeomFromText(%(wkt)s, 4326))",
    {"name": "Seattle", "wkt": "POINT(-122.33 47.60)"}
)

# Retrieve as bytes
cursor.execute("SELECT Geo.STAsBinary() FROM #Locations")
row = cursor.fetchone()
geo_bytes = row[0]

Reihenversion/Zeitstempel

SQL Server rowversion (früher timestamp) ist ein binärer Typ, kein Datetime:

cursor.execute("""
    CREATE TABLE #RowVersionDemo (
        ID int PRIMARY KEY,
        Version rowversion
    )
""")
cursor.execute("INSERT INTO #RowVersionDemo (ID) VALUES (1)")
cursor.execute("SELECT Version FROM #RowVersionDemo WHERE ID = 1")
row = cursor.fetchone()
version = row[0]  # bytes, not datetime

Stream-Großwerttypen

Beim Einfügen oder Abrufen varchar(max)von , nvarchar(max), oder varbinary(max) Daten, verwendet der Treiber Data-at-Execution (DAE)-Streaming, um Daten in Chunks zu übertragen, anstatt den gesamten Wert auf einmal in den Speicher zu laden.

Das Streaming wird automatisch aktiviert, wenn die Eingabedaten die Größenschwellenwerte überschreiten:

Streaming funktioniert mit execute(), executemany(), und allen Fetch-APIs (fetchone(), fetchmany(), fetchall()). Der Treiber benötigt keine spezielle Konfiguration und übernimmt das Streaming automatisch für große Werte.

Nicht unterstützte SQL Server-Typen

Die folgenden SQL Server-Typen haben keine nativen Python-Typzuordnungen.

Die folgenden Typen geben Daten zurückbytes, haben aber keine nativen Python-Typ-Mappings:

Dezimal- versus Schwimmergenauigkeit

Verwenden decimal.Decimal Sie, wenn genaue Genauigkeit wichtig ist, wie bei finanziellen Berechnungen, Währung oder jedem Wert, bei dem Rundungsfehler nicht akzeptabel sind. Verwenden float Sie, wenn ungefähre Werte akzeptabel sind, wie wissenschaftliche Messungen oder Sensormessungen.

Der Treiber wird auf SQL Server decimal.Decimaldecimal/ abgebildet numeric und erhält eine Genauigkeit von bis zu 38 Ziffern. floatwird auf den SQL Server float (64-Bit-IEEE 754) abgebildet, der Rundungsartefakte einführen kann:

from decimal import Decimal

# Exact - use for currency and financial data
price = Decimal("19.99")
tax_rate = Decimal("0.0825")
total = price * (1 + tax_rate)  # Decimal("21.6391750")

cursor.execute("""
    CREATE TABLE #PrecisionDemo (
        Description NVARCHAR(100),
        DiscountPct DECIMAL(5,2),
        Rating FLOAT
    )
""")

cursor.execute(
    "INSERT INTO #PrecisionDemo (Description, DiscountPct, Rating) VALUES (%(desc)s, %(pct)s, %(rating)s)",
    {"desc": "Summer sale", "pct": Decimal("0.15"), "rating": 4.5}
)

cursor.execute("SELECT DiscountPct, Rating FROM #PrecisionDemo WHERE Description = %(desc)s", {"desc": "Summer sale"})
row = cursor.fetchone()
print(type(row.DiscountPct))  # <class 'decimal.Decimal'>
print(type(row.Rating))       # <class 'float'>

Beim Abrufen decimal/numericvon Spalten gibt der Treiber immer Objekte zurück.decimal.Decimal Beim Abrufen float/realvon Spalten gibt der Treiber Python floatzurück.

Numpy-Typbindung

Der Treiber mssql-python verwendet isinstance() Prüfungen, um SQL-Typen für Parameter zu bestimmen. Numpy-Ganzzahltypen (numpy.int64, numpy.int32, numpy.int8) passieren isinstance(x, int) in NumPy 2.x nicht, was zu Bindungsfehlern führt. Funktioniert nur numpy.float64 direkt, weil es eine Unterklasse von Python floatist.

Konvertiere Numpy-Werte in native Python-Typen, bevor du sie als Parameter übergibst:

import numpy as np

row_id = np.int64(42)
score = np.float32(3.14)

# This fails: numpy.int64 is not recognized as int
# cursor.execute("SELECT * FROM Products WHERE ID = ?", (row_id,))

# Convert to native Python types first
cursor.execute(
    "SELECT * FROM Production.Product WHERE ProductID = %(product_id)s",
    {"product_id": int(row_id)}
)

# For DataFrames, convert the whole column
import pandas as pd

df = pd.DataFrame({"ProductID": [1, 2, 3], "Quantity": [10, 20, 30]})

cursor.execute("CREATE TABLE #Orders (ProductID INT, Quantity INT)")

for _, row in df.iterrows():
    cursor.execute(
        "INSERT INTO #Orders (ProductID, Quantity) VALUES (%(product_id)s, %(quantity)s)",
        {"product_id": int(row["ProductID"]), "quantity": int(row["Quantity"])}
    )

Wenn du stark mit Pandas oder Numpy-Daten arbeitest, solltest du die Arrow-Integration oder pandas-Integrationspfade nutzen, die intern die Typkonvertierung übernehmen.

Verwandte Inhalte

• Abfragen mit mssql-python ausführen
• Daten mit mssql-python abrufen
• Benutzerdefinierte Typ-Konverter mit mssql-python