mssql-python 的資料型別映射

mssql-python 驅動程式在傳送參數時會自動將 Python 資料型態對應到 SQL Server 型別，並在取得結果時將 SQL Server 型別轉換成 Python 型別。

Python 到 SQL Server 映射

當你將 Python 值作為參數傳入 execute() 或 executemany()時，驅動程式會自動選擇適當的 SQL Server 類型。 對大多數應用來說，自動映射是正確的。 只有在需要覆寫預設值時才使用 setinputsizes() （稍後會說明），例如強制用 varchar 取代 nvarchar ，或控制字串和整數輸入的參數元資料。

這些映射描述了參數化的執行。 使用元組批量複製，ISO 格式字串可保留 datetime2（7） 的七個分秒數字。 對於 datetimeoffset（7） 字串，保留分數精度，但偏移量則正規化至 UTC。 時間字串（7）會透過 Python datetime.time 解析，並去除第七位小數。 Python datetime 和time物件只攜帶六個分秒的數字。 欲了解更多資訊，請參閱日期處理。

整數型選擇

驅動程式會自動選擇能儲存該值的最小整數類型：

大值類型

對於超出標準限制的字串與二進位資料，驅動程式會自動使用 MAX 類型：

驅動程式會將大量值串流給伺服器，以減少記憶體使用。

SQL Server 到 Python 映射

當驅動程式從 SQL Server 取得資料時，會將值轉換成 Python 類型：

SQL 型別常數

驅動程式匯出對應 ODBC SQL 類型識別碼的常數。 當自動映射與你的結構不符時，通常會用這些常數 setinputsizes() 來覆寫驅動程式預設的類型推論。

字元類型

數值類型

日期和時間類型

二元類型

其他類型

使用 setinputsize（）

當驅動程式的自動型別推論導致意外行為時，例如setinputsizes()executemany()欄位為 但varchar(100)驅動程式傳送 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),
    ]
)

小數分隔符號

驅動程式使用區域感知的十進位分隔符。 自訂方式：

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

客製化類型轉換器

針對特定 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)

欲了解更多資訊，請參閱 自訂類型轉換器。

特殊握把類型

UUID 處理

驅動程式自動映射 uuid.UUID 到 uniqueidentifier 。 你可以在不手動字串轉換的情況下插入和取回 UUID：

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

預設情況下，驅動程式會將欄位以UNIQUEIDENTIFIER物件形式回傳uuid.UUID。 若要返回與 pyodbc 相容的大寫字串，請設定 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()

關於模組層級的配置，請參見native_uuid模組配置中的設定。

日期時間與時區

datetimeoffset 欄位會回傳時區感知 datetime 的物件。 關於如何處理偏移感知值與不移量純淨值的指引，請參見 日期時間處理。

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

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

空間資料

驅動程式回傳空間類型（，geographygeometry ），為 bytes。 你可以使用參數字串的 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]

行版本/時間戳記

SQL Server rowversion （以前稱為 timestamp）是二進位型態，而非 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

串流大值類型

在插入或取回varchar(max)資料nvarchar(max)varbinary(max)時，驅動程式會使用執行時資料串流（DAE）將資料分段傳送，而非一次將整個值載入記憶體。

當輸入資料超過大小門檻時，串流會自動啟動：

串流支援 execute()、 executemany()，以及所有取用 API（fetchone()， fetchmany()， fetchall()）。 驅動程式不需要特殊設定，且能自動處理大數值的串流。

不支援的 SQL Server 類型

以下 SQL Server 類型沒有原生的 Python 類型映射。

以下類型會回傳資料，bytes但沒有原生的 Python 型態映射：

十進位與浮點數精確度

當精確度很重要時，例如 decimal.Decimal 財務計算、貨幣，或任何無法四捨五入誤差的數值。 當近似值可接受時使用 float ，例如科學測量或感測器讀數。

驅動程式對應decimal.Decimal至 SQL Serverdecimal/numeric，並保留最高 38 位數的精確度。 float映射到 SQL Server float （64 位元 IEEE 754），這可能會引入捨入的產物：

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

在擷取 decimal/numeric 欄位時，驅動程式總是回傳 decimal.Decimal 物件。 當擷取float/real欄位時，驅動程式會回傳 Python 。 float

numpy 型裝訂

驅動程式 mssql-python 會用 isinstance() 檢查來決定參數的 SQL 類型。 numpy 整數類型（，numpy.int64numpy.int32 ， numpy.int8）在 NumPy 2.x 中無法通過isinstance(x, int)，導致綁定失敗。 之所以numpy.float64能直接運作，是因為它是 Python float的子類別。

在將 numpy 值作為參數傳遞前，先將 numpy 值轉換成原生 Python 類型：

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

如果你經常使用 pandas 或 numpy 資料，可以考慮使用 Arrow 整合 或 PANDAS 整合 路徑，這些路徑內部處理型別轉換。

相關內容

• 使用 mssql-python 執行查詢
• 使用 mssql-python 擷取資料
• 使用 mssql-python 的自訂型別轉換器