Mapeamentos de tipos de dados para mssql-python

O driver mssql-python mapeia automaticamente tipos de dados Python para tipos SQL Server ao enviar parâmetros e converte tipos SQL Server para tipos Python ao recuperar resultados.

Mapeamentos de Python para SQL Server

Quando passa valores Python como parâmetros para execute() ou executemany(), o driver seleciona automaticamente o tipo de SQL Server apropriado. Para a maioria das aplicações, o mapeamento automático está correto. Use setinputsizes() (descrito mais adiante neste artigo) apenas quando precisar de sobrescrever o padrão, por exemplo para forçar varchar em vez de nvarchar ou para controlar metadados de parâmetros para entradas de string e inteiros.

Seleção de tipos inteiros

O driver seleciona automaticamente o menor tipo inteiro que pode conter o valor:

Tipos de grande valor

Para strings e dados binários que excedam os limites padrão, o driver usa automaticamente os tipos MAX:

O driver transmite valores elevados para o servidor para minimizar o uso de memória.

Mapeamentos de SQL Server para Python

Quando o driver recupera dados do SQL Server, converte valores para tipos Python:

Constantes de tipo SQL

O driver exporta constantes que correspondem a identificadores de tipo SQL ODBC. Normalmente usas estas constantes para setinputsizes() sobrepor a inferência de tipo padrão do driver quando o mapeamento automático não corresponde ao teu esquema.

Tipos de personagens

Tipos numéricos

Tipos de data e hora

Tipos binários

Outros tipos

Use setinputsizes()

Chame setinputsizes() antes executemany() para declarar explicitamente os tipos de parâmetros quando a inferência automática de tipos do driver causa comportamentos inesperados, por exemplo, quando uma coluna é varchar(100) mas o driver envia 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),
    ]
)

Separador decimal

O driver utiliza separadores decimais conscientes da localidade. Para personalizar:

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

Conversores de tipo personalizado

Registe conversores personalizados para tipos específicos de SQL:

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)

Para mais informações, consulte Conversores de tipo personalizado.

Tipos especiais de alça

Tratamento de UUID

O condutor mapeia uuid.UUID para uniqueidentifier automaticamente. Pode inserir e recuperar UUIDs sem conversão manual de cadeias:

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

Por defeito, o driver devolve UNIQUEIDENTIFIER as colunas como uuid.UUID objetos. Para devolver cordas maiúsculas compatíveis com pyodbc, defina 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()

Para configuração ao nível do módulo, consulte a native_uuid definição em Configuração do módulo.

Data-hora com fuso horário

datetimeoffset as colunas devolvem objetos conscientes datetime do fuso horário. Para orientações sobre como trabalhar com valores conscientes do offset versus ingênuos do deslocamento, veja Gestão da data-hora.

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

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

Dados geográficos

O driver devolve tipos espaciais (geography, geometry) como bytes. Pode usar cadeias de parâmetros no 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

O SQL Server rowversion (anteriormentetimestamp) é um tipo binário, não uma data-hora:

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

Tipos de grande valor de fluxo

Ao inserir ou recuperar varchar(max), nvarchar(max), ou varbinary(max) dados, o driver utiliza streaming Data-at-Execution (DAE) para transmitir dados em blocos, em vez de carregar o valor total na memória de uma só vez.

O streaming ativa automaticamente quando os dados de entrada ultrapassam os limiares de tamanho:

O streaming funciona com execute(), executemany(), e todas as APIs de fetch (fetchone(), fetchmany(), fetchall()). O driver não requer configuração especial e gere o streaming automaticamente para valores elevados.

Tipos de SQL Server não suportados

Os seguintes tipos de SQL Server não têm mapeamentos nativos de tipos Python.

Os seguintes tipos devolvem dados como bytes mapeamentos nativos de Python mas não possuem:

Precisão decimal versus float

Use decimal.Decimal quando a precisão exata for importante, como cálculos financeiros, moeda ou qualquer valor onde erros de arredondamento sejam inaceitáveis. Use float quando valores aproximados são aceitáveis, como medições científicas ou leituras de sensores.

O driver mapeia decimal.Decimal para SQL Server decimal/numeric e preserva a precisão até 38 dígitos. floatmapeia para o SQL Server float (IEEE 754 de 64 bits), que pode introduzir artefactos de arredondamento:

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

Ao recuperar decimal/numeric colunas, o driver devolve decimal.Decimal sempre objetos. Ao recuperar float/real colunas, o driver devolve Python . float

Encadernação tipo entorpecido

O mssql-python driver utiliza isinstance() verificações para determinar os tipos SQL dos parâmetros. Os tipos de inteiros numpy (numpy.int64, numpy.int32, numpy.int8) não passam isinstance(x, int) no NumPy 2.x, o que causa falhas nas ligações. Só numpy.float64 funciona diretamente porque é uma subclasse de Pythonfloat.

Converter valores numpy para tipos nativos de Python antes de os passar como parâmetros:

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 trabalhas muito com pandas ou dados numpy, considera usar a integração Arrow ou os caminhos de integração pandas , que tratam internamente da conversão de tipos.

Conteúdo relacionado

• Executar consultas com mssql-python
• Recuperar dados com mssql-python
• Conversores de tipos personalizados com mssql-python