pyodbc原生查询中能否传入表值参数(TVP)及传入类型报错排查

你当前的写法存在三个核心偏差，直接触发了全部报错：

• 原生SQL执行场景下，普通?占位符默认按标量参数解析，无法自动识别你传入的嵌套元组表结构数据，pyodbc会错误生成TVP相关的参数声明语法，最终触发类型解析失败。
• SQL Server 不支持在动态执行的SQL里临时声明表类型作为TVP使用，所有TVP必须对应预先在数据库中创建的用户定义表类型（UDTT），临时DECLARE的表变量不能作为TVP类型绑定。
• 向pyodbc传入TVP时，必须显式指定对应UDTT的名称，不能直接把裸的嵌套元组当参数传入。

1. 预先创建数据库级UDTT #

在目标数据库中执行一次创建语句（永久生效，无需每次运行代码重复执行）：

CREATE TYPE PersonTableType AS TABLE (
    PersonName VARCHAR(50) NOT NULL
);
GO

2. 调整Python端传参和SQL逻辑 #

去掉原代码里临时声明表变量的冗余逻辑，按照pyodbc的TVP传参规则构造参数值：

• TVP参数值必须是二元组结构：(行数据列表, 对应UDTT的全限定名称)
• 不需要额外嵌套临时表做中转，传入的TVP本身就是可直接查询的表对象

修正后的代码参考：

import pyodbc
from src.data.dbaccess import con

queryString = """
SET NOCOUNT ON;
-- 直接使用绑定的TVP查询即可
SELECT PersonName FROM ?;
"""

# 构造TVP参数：第一部分是待传入的行数据，第二部分是之前创建的UDTT名称
tvp_param = (
    [('Jim', ), ('Bob', )],
    'dbo.PersonTableType'
)

with pyodbc.connect(con.conString) as testCon:
    crsr = testCon.execute(queryString, tvp_param)
    for row in crsr:
        print(row)

你收到的一连串报错是连锁触发的结果：

• Cannot find data type READONLY：pyodbc未拿到明确的UDTT类型名时，生成的错误参数声明把READONLY关键字当成了数据类型名传给SQL Server，直接触发类型找不到的错误。
• Must declare the table variable "@P1"：因为第一个参数类型解析失败，整个参数声明链路中断，后续逻辑找不到对应的表变量。
• Parameter or variable '@P1' has an invalid data type：参数类型未匹配成功的最终反馈。

• 传入的行数据列顺序、数据类型必须和UDTT定义完全匹配，否则会触发类型兼容性报错。
• 如果只是小批量传测试数据、不需要TVP的批量传输性能优势，也可以直接把数据拼成VALUES子句嵌入SQL，或者通过JSON参数在SQL端解析使用，省去创建UDTT的步骤。

内容的提问来源于stack exchange，提问作者Robert Criqui