Mapeamentos de tipos de dados para mssql-python

O driver mssql-python automaticamente mapeia 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 você passa valores de Python como parâmetros para execute() ou executemany(), o driver seleciona automaticamente o tipo apropriado de SQL Server. Para a maioria das aplicações, o mapeamento automático está correto. Use setinputsizes() (descrito mais adiante neste artigo) apenas quando precisar 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 excedem os limites padrão, o driver usa automaticamente os tipos MAX:

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

Mapeamentos de SQL Server para Python

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

Constantes de tipo SQL

O driver exporta constantes que correspondem aos identificadores de tipo SQL ODBC. Normalmente você usa essas constantes para setinputsizes() sobrescrever a inferência padrão do tipo do driver quando o mapeamento automático não corresponde ao seu esquema.

Tipos de caracteres

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 um comportamento inesperado, 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

Registre 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, veja Conversores de tipo personalizado.

Tipos especiais de alças

Tratamento com UUID

O driver mapeia uuid.UUID para uniqueidentifier automaticamente. Você pode inserir e recuperar UUIDs sem conversão manual de cordas:

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 padrão, o driver retorna UNIQUEIDENTIFIER as colunas como uuid.UUID objetos. Para retornar 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 em nível de módulo, veja a native_uuid configuração em Configuração do módulo.

Data-hora com fuso horário

datetimeoffset colunas retornam objetos conscientes datetime do fuso horário. Para orientações sobre como trabalhar com valores conscientes do offset versus valores ingênuais no deslocamento, veja Gerenciamento do Tempo de Data.

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

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

Dados espaciais

O driver retorna tipos espaciais (geography, geometry) como bytes. Você pode usar strings 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 o streaming Data-at-Execution (DAE) para transmitir dados em blocos, em vez de carregar o valor total na memória de uma vez.

O streaming é ativado automaticamente quando os dados de entrada ultrapassam os limites de tamanho:

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

Tipos de SQL Server não suportados

Os seguintes tipos de SQL Server não possuem mapeamentos nativos de tipos Python.

Os seguintes tipos retornam dados como bytes mapeamento nativo de Python:

Precisão decimal versus flutuante

Use decimal.Decimal quando a precisão exata importa, 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 o SQL Server decimal/numeric e preserva a precisão de até 38 dígitos. floatmapes para SQL Server float (IEEE 754 de 64 bits), que pode introduzir artefatos 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 sempre retorna decimal.Decimal objetos. Ao recuperar float/real colunas, o driver retorna Python . float

Encadernação tipo anestesia

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

Converta valores numpy para tipos nativos de Python antes de passá-los 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 você trabalha bastante com dados pandas ou numpy, considere usar os caminhos de integração Arrow ou pandas , que gerenciam a conversão de tipos internamente.

Conteúdo relacionado

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