Mappature dei tipi dati per mssql-python

Il driver mssql-python mappa automaticamente i tipi di dati Python ai tipi SQL Server quando invia i parametri e converte i tipi SQL Server in tipi Python quando recupera i risultati.

Mappaggi da Python a SQL Server

Quando passi valori Python come parametri a execute() o executemany(), il driver seleziona automaticamente il tipo SQL Server appropriato. Per la maggior parte delle applicazioni, la mappatura automatica è corretta. Usa setinputsizes() (descritto più avanti in questo articolo) solo quando devi sovrascrivere il predefinito, ad esempio per forzare varchar invece di nvarchar o per controllare i metadati dei parametri per stringhe e ingressi interi.

Selezione dei tipi interi

Il driver seleziona automaticamente il tipo intero più piccolo che può contenere il valore:

Tipi di grande valore

Per stringhe e dati binari che superano i limiti standard, il driver utilizza automaticamente i tipi MAX:

Il driver trasmette valori elevati al server per minimizzare l'uso di memoria.

Mappe da SQL Server a Python

Quando il driver recupera dati da SQL Server, converte i valori in tipi Python:

Costanti di tipo SQL

Il driver esporta costanti che corrispondono agli identificatori di tipo SQL ODBC. Di solito usi queste costanti per setinputsizes() sovrascrivere l'inferenza di tipo predefinita del driver quando la mappatura automatica non corrisponde al tuo schema.

Tipi di caratteri

Tipi numerici

Tipi di data e ora

Tipi binari

Altri tipi

Usa setinputsizes()

Chiama setinputsizes() prima executemany() per dichiarare esplicitamente i tipi di parametri quando l'inferenza automatica del tipo del driver causa comportamenti inaspettati, ad esempio quando una colonna è varchar(100) ma il driver invia 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),
    ]
)

Separatore decimale

Il driver utilizza separatori decimali consapevoli della zona. Per personalizzare:

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(",")

Convertitori di tipo personalizzato

Registra convertitori personalizzati per tipi SQL specifici:

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)

Per maggiori informazioni, vedi Convertitori di tipo personalizzati.

Tipi speciali di maniglia

Gestione UUID

Il driver si mappa uuid.UUID su uniqueidentifier automaticamente. Puoi inserire e recuperare UUID senza conversione manuale delle stringhe:

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})

Di default, il driver restituisce UNIQUEIDENTIFIER le colonne come uuid.UUID oggetti. Per restituire stringhe maiuscole compatibili con pyodbc, impostare 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()

Per la configurazione a livello di modulo, vedi l'impostazione native_uuid in Configurazione del modulo.

Data e ora con fuso orario

datetimeoffset le colonne restituiscono oggetti consapevoli datetime del fuso orario. Per indicazioni su come lavorare con valori offset-aware rispetto a offset-naiveive, vedi Gestione Datetime.

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

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

Dati spaziali

Il driver restituisce i tipi spaziali (geography, geometry) come bytes. Puoi usare stringhe di parametri in formato WKT:

# 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]

Rowversion/timestamp

SQL Server rowversion (precedentemente timestamp) è un tipo binario, non una data-ora:

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

Tipi di grande valore a flusso

Quando inserisce o recupera varchar(max), nvarchar(max), o varbinary(max) dati, il driver utilizza lo streaming Data-at-Execution (DAE) per trasmettere i dati a blocchi invece di caricare l'intero valore in memoria contemporaneamente.

Lo streaming si attiva automaticamente quando i dati di input superano le soglie di dimensione:

Lo streaming funziona con execute(), executemany(), e tutte le API di fetch (fetchone(), fetchmany(), fetchall()). Il driver non richiede una configurazione speciale e gestisce automaticamente lo streaming per valori elevati.

Tipi di SQL Server non supportati

I seguenti tipi di SQL Server non hanno mappe nativi di tipo Python.

I seguenti tipi restituiscono dati come bytes ma non hanno mappe nativi di tipo Python:

Precisione decimale contro float

Usalo decimal.Decimal quando la precisione esatta è importante, come calcoli finanziari, valuta o qualsiasi valore in cui gli errori di arrotondamento sono inaccettabili. Utilizzare float quando valori approssimati sono accettabili, come misurazioni scientifiche o letture dei sensori.

Il driver si mappa decimal.Decimal su SQL Server decimal/numeric e mantiene la precisione fino a 38 cifre. floatmappa a SQL Server float (IEEE 754 a 64 bit), che può introdurre artefatti di arrotondamento:

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'>

Quando si recuperano decimal/numeric colonne, il driver restituisce decimal.Decimal sempre oggetti. Quando si recuperano float/real le colonne, il driver restituisce Python float.

Rilegato tipo insensibile

Il mssql-python driver utilizza isinstance() controlli per determinare i tipi SQL per i parametri. I tipi di interi Numpy (numpy.int64, numpy.int32, numpy.int8) non passano isinstance(x, int) in NumPy 2.x, il che causa fallimenti di binding. Funziona direttamente solo numpy.float64 perché è una sottoclasse di Pythonfloat.

Converti i valori numpy in tipi nativi di Python prima di passarli come parametri:

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"])}
    )

Se lavori molto con pandas o dati numpy, considera di usare l'integrazione Arrow o i percorsi di integrazione pandas , che gestiscono internamente la conversione dei tipi.

Contenuti correlati

• Esegui query con mssql-python
• Recupera dati con mssql-python
• Convertitori di tipi personalizzati con mssql-python