Llama-Index查询SQL Server时如何指定自定义非dbo的schema？

问题场景 #

使用Llama-Index查询SQL Server 2014数据库时，SQLAlchemy默认使用dbo schema，抛出如下错误：

raise exc.NoSuchTableError(f"{owner}.{tablename}")
sqlalchemy.exc.NoSuchTableError: dbo.ll_computers

实际目标表位于dbo_v2 schema下，已尝试在SQLDatabase实例中指定schema='dbo_v2'但未生效。

解决方案 #

1. 连接引擎时指定默认Schema #

在创建SQLAlchemy引擎的连接字符串中，直接添加default_schema参数，让SQLAlchemy全局默认使用目标schema：

from sqlalchemy import create_engine

engine = create_engine(
    "mssql+pyodbc://user:password@server_name/db_name?driver=ODBC+Driver+17+for+SQL+Server&default_schema=dbo_v2"
)

2. 显式给SQLTableSchema指定Schema #

创建SQLTableSchema对象时，必须显式传入schema_name参数，确保Llama-Index生成查询时关联正确的schema：

table_node_mapping = SQLTableNodeMapping(sql_database)
table_names_filter = ["ll_computers"]
# 新增schema_name参数指定目标schema
table_schema_objs = [
    SQLTableSchema(table_name=table_name, schema_name='dbo_v2') 
    for table_name in metadata_obj.tables.keys() 
    if table_name in table_names_filter
]

obj_index = ObjectIndex.from_objects(
    table_schema_objs,
    table_node_mapping,
    VectorStoreIndex,
)

3. 验证SQLDatabase实例的Schema配置 #

打印SQLDatabase的属性，确认schema是否正确加载：

# 检查schema是否设置成功
print(sql_database.schema)
# 检查表是否带正确的schema前缀
print(sql_database.tables)

如果输出的表名未包含dbo_v2.前缀，需要重新检查metadata.reflect的参数，确保反射的是目标schema下的表：

metadata_obj = MetaData()
# 确保schema参数正确传入
metadata_obj.reflect(engine, schema='dbo_v2', only=["ll_computers"])

4. 强制SQL解析时绑定Schema（备选方案） #

通过SQLParserConfig强制指定表与schema的映射，确保生成的SQL语句带正确的schema前缀：

from llama_index.indices.struct_store.sql_query import SQLParserConfig

sql_parser_config = SQLParserConfig(
    table_schema_map={"ll_computers": "dbo_v2"}
)

query_engine = SQLTableRetrieverQueryEngine(
    sql_database,
    obj_index.as_retriever(similarity_top_k=1),
    service_context=service_context,
    sql_parser_config=sql_parser_config
)

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