LlamaIndex DatabaseReader 数据库读取器完全指南四种连接模式、元数据映射与 RAG 实战【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index数据库是 RAG 应用中最高价值的数据源之一。LlamaIndex 官方提供了专门的数据库读取器DatabaseReader它能把任意 SQL 查询的结果逐行转换为Document对象直接喂给VectorStoreIndex等索引结构是构建查询数据库 → 向量检索 → LLM 问答链路的起点。本指南以 DatabaseReader 源码实现 与官方 DatabaseReader 演示 Notebook 为据带你掌握它的四种连接方式、metadata_cols/excluded_text_cols/document_id三个核心参数的精确语义以及如何与向量索引无缝集成。一、DatabaseReader 是什么DatabaseReader是 LlamaIndex 为从数据库加载数据而设计的轻量级读取器继承自llama_index.core.readers.base.BaseReader。它的定位非常聚焦接受一条 SQL 查询执行后将每一行结果封装成一个Document文本内容为整行各列的列名: 值拼接同时允许你指定哪些列进入Document.metadata、哪些列从正文中剔除甚至用行数据自定义 Document ID。在 base.py 的类文档中它明确说明了自己的能力边界读取数据、指定元数据列可重命名、排除正文列、从行数据生成自定义 Document ID。它内部依赖两层基础设施SQLDatabase封装类位于 llama-index-core/llama_index/core/utilities/sql_wrapper.py负责持有 SQLAlchemyEngine、反射表结构、提供表信息与 SQL 执行能力SQLAlchemy 引擎本身负责真正的数据库连接与查询执行。因此只要你的数据库能被 SQLAlchemy 方言驱动DatabaseReader就能工作——从项目 pyproject.toml 的关键词postgres、aws rds、snowflake、sql可以看出PostgreSQL、Snowflake、AWS RDS 等场景都是它的目标使用环境。二、安装与导入DatabaseReader位于独立的集成包llama-index-readers-database中需要单独安装pip install llama-index-readers-database同时你还需要一个可用的 SQLAlchemy 数据库驱动如psycopg2/psycopg之于 PostgreSQL以及核心包llama-index-core包依赖声明为llama-index-core0.13.0,0.15见 pyproject.toml。官方 演示 Notebook 中的导入方式如下from llama_index.readers.database import DatabaseReader from llama_index.core import VectorStoreIndex包入口 __init__.py 仅导出DatabaseReader一个公开符号。三、四种连接方式与 schema 语义DatabaseReader的构造函数见 base.py L91-L130接受四组互斥的连接参数按优先级依次为sql_database→engine→uri→scheme/host/port/user/password/dbname。其源码文档给出了清晰的对照表连接模式是否支持 schema说明sql_database✖传入预构建的SQLDatabase对象如需 schema 处理请用此方式schema 已内置于该对象engineschema✔传入 SQLAlchemyEngine可在本类中新建SQLDatabase时指定 schemaurischema✔传入连接 URI 字符串如postgresql://user:passhost:5432/dbscheme/host/…schema✔分别传入 scheme、host、port、user、password、dbname 六个凭据注意区分两个易混概念schema指数据库命名空间namespace而scheme指驱动/方言如postgresqlpsycopg。源码 docstring 在 base.py L87 中特意标注了这一点。3.1 方式一拆分连接参数这是官方演示 Notebook 采用的写法最直观db DatabaseReader( schemepostgresql, # 数据库 scheme方言 hostlocalhost, # 数据库主机 port5432, # 数据库端口 userpostgres, # 数据库用户 passwordFakeExamplePassword, # 数据库密码 dbnamepostgres, # 数据库名 )在 base.py L121-L124 中这一模式会内部拼装为f{scheme}://{user}:{password}{host}:{port}/{dbname}并调用SQLDatabase.from_uri因此本质上仍是走 URI 路径。注意只有当六个参数全部提供时该分支才会生效否则会抛出ValueError。3.2 方式二复用 SQLAlchemy Enginefrom sqlalchemy import create_engine engine create_engine(postgresql://postgres:FakeExamplePasswordlocalhost:5432/postgres) db_from_engine DatabaseReader(engineengine)该分支调用SQLDatabase(engine, *args, **db_kwargs)把用户传入的额外关键字参数含schema透传给SQLDatabase构造器。3.3 方式三直接给连接 URIuri postgresql://postgres:FakeExamplePasswordlocalhost:5432/postgres db_from_uri DatabaseReader(uriuri)该分支调用SQLDatabase.from_uri(uri, ...)。从 sql_wrapper.py L130-L136 可以看到from_uri实际上就是create_engine(database_uri, **_engine_args)后再构建SQLDatabase的类方法封装。3.4 方式四传入预构建的 SQLDatabasedb DatabaseReader(sql_databasedb.sql_database) # 复用已有 SQLDatabase这是演示 Notebook 中展示的复用写法适合你已经在其他地方如 SQL 查询引擎构建好SQLDatabase的场景。3.5 schema 参数的关键语义schema 参数有一个非常容易踩坑的细节源码在 base.py L108-L112 中明确处理当你传入engine/uri/ 拆分凭据且同时指定schema时schema 会被塞进db_kwargs并最终传给SQLDatabase此时 schema 生效当你传入sql_database时schema 参数会被忽略实际使用的是该SQLDatabase对象内部已有的 schema如果有。换言之sql_database模式不支持在DatabaseReader层再覆盖 schema。官方文档用schema database namespace; scheme driver/dialect一句话帮助记忆二者区别。四、核心方法lazy_load_data 与 load_dataDatabaseReader的核心方法在 base.py L132-L245 中实现名为lazy_load_data——它返回一个生成器逐行产出Document。你实际调用时更常用的是父类BaseReader提供的load_data在演示 Notebook 中即为db.load_data(queryquery)它会惰性消费该生成器并返回Document列表。方法的签名与参数如下def lazy_load_data( self, query: str, # 必填要执行的 SQL 查询 metadata_cols: Optional[Iterable[Union[str, Tuple[str, str]]]] None, # 元数据列 excluded_text_cols: Optional[Iterable[str]] None, # 从正文中排除的列 document_id: Optional[Callable[[Dict[str, Any]], str]] None, # 自定义 Document ID **load_kwargs, # 额外参数被忽略 ) - Generator[Document, Any, None]:4.1 query唯一的必填参数在 base.py L176-L179 中空查询会直接抛出ValueError(A query parameter is necessary.)。执行方式为connection.execute(text(query))即把查询原样作为 SQL 文本交给 SQLAlchemy 执行——这意味着查询语句的合法性、表名/列名是否正确都由你的数据库决定。官方 Notebook 中的示例查询会先把行数据拼装成一句话SELECT CONCAT(name, is , age, years old.) AS text FROM public.users WHERE age 184.2 正文文本的生成规则对查询结果的每一行base.py L217-L223 会构建文本内容text_parts [ f{col}: {val} for col, val in row_values.items() if col not in exclude_set ] text_resource MediaResource(text, .join(text_parts))即每一行变为列A: 值A, 列B: 值B, ...的拼接字符串存为Document的text_resource。行数据通过dict(zip(column_names, row))与查询返回的列名一一对应。4.3 metadata_cols元数据列支持重命名metadata_cols接受列名字符串或(数据库列名, 元数据键名) 二元组的迭代器两种形态在 base.py L187-L215 中分别处理my_col以列名本身作为 metadata 键(db_col_name, meta_key_name)把数据库列db_col_name的值以meta_key_name为键写入 metadata。源码文档给出了两个典型使用模式# 模式一仅把 my_col 放入元数据配合 excluded_text_cols 从正文剔除 documents db.load_data( queryquery, metadata_cols[my_col], excluded_text_cols[my_col], ) # 模式二重命名元数据键 documents db.load_data( queryquery, metadata_cols[(db_col_name, meta_key_name)], )值得注意的健壮性细节若metadata_cols中指定的列在查询结果中不存在代码会通过logger.warning提示Column ... not found in query result并跳过而不是报错base.py L211-L215若metadata_cols中出现非字符串、非二元组的非法项同样会告警跳过base.py L200-L207。此外如果有两个条目映射到同一个元数据键后者会静默覆盖前者——务必避免重复键。4.4 excluded_text_cols从正文中剔除列excluded_text_cols用于把仅作元数据的列从正文拼接中排除避免正文被 ID、时间戳等非语义列污染。它与metadata_cols配合即可实现某列只进 metadata、不进正文的效果即上面模式一展示的用法。实现上base.py L171 先把该参数转为集合exclude_set随后在构建text_parts时通过if col not in exclude_set过滤。4.5 document_id用行数据生成自定义 Document IDdocument_id接收一个接收行字典、返回字符串的函数返回的字符串会成为该行Document的id_取代已废弃的doc_id字段。源码在 base.py L229-L243 中的处理逻辑函数必须返回字符串否则告警并退化为自动生成的 UUID函数执行抛异常时会被捕获并告警document_id failed for row ...不影响整体流程。典型用法示例def make_id(row: dict) - str: return fuser-{row[id]} documents db.load_data(queryquery, document_idmake_id)这一能力对去重更新很有价值稳定的自定义 ID 意味着同一行数据反复加载时文档 ID 不变便于索引的增量更新与幂等处理。五、底层 SQLDatabase 工具速览DatabaseReader把连接与元数据能力委托给了SQLDatabasesql_wrapper.py演示 Notebook 也特意打印了db.sql_database暴露的方法与属性run_sql(command)执行 SQL 并返回结果Notebook 中用它验证查询输出get_single_table_info(table_name)返回单表的结构描述含列、类型、注释与外键见 sql_wrapper.py L153-L189get_table_columns(table_name)获取表列信息get_usable_table_names()按include_tables/ignore_tables过滤后返回可用表名sql_wrapper.py L143-L147dialect属性返回驱动方言名如postgresqlengine属性返回 SQLAlchemyEngine。SQLDatabase构造器还支持include_tables/ignore_tables二者不可同时指定否则抛ValueError、sample_rows_in_table_info、view_support把视图纳入表清单、max_string_length等参数——虽然DatabaseReader主要透传schema但理解这些能力有助于你后续在 SQL 查询引擎等其他组件中复用同一个SQLDatabase对象。六、完整实战从数据库到向量索引结合官方 DatabaseReaderDemo.ipynb 的完整流程一个端到端的 RAG 数据接入示例如下import logging, sys logging.basicConfig(streamsys.stdout, levellogging.INFO) from llama_index.readers.database import DatabaseReader from llama_index.core import VectorStoreIndex # 1. 建立连接四种方式任选其一 db DatabaseReader( schemepostgresql, hostlocalhost, port5432, userpostgres, passwordFakeExamplePassword, dbnamepostgres, ) # 2. 直接用 SQLDatabase 执行 SQL 做验证可选 texts db.sql_database.run_sql(commandquery) print(texts) # 3. 用 DatabaseReader 把查询结果加载为 Document 列表 documents db.load_data(queryquery) # 4. 构建向量索引进入检索问答链路 index VectorStoreIndex.from_documents(documents)在 Notebook 中db.load_data(queryquery)返回的是Document对象列表随后被VectorStoreIndex.from_documents(documents)消费——这意味着你可以把任意 SQL 查询的结果直接变成可检索的知识库。配合第 4 节的metadata_cols、excluded_text_cols、document_id你可以在加载阶段就完成哪些列进入正文、哪些列进元数据、文档如何唯一标识的完整数据工程。七、实践建议与注意事项综合源码与文档使用DatabaseReader时有几点值得注意查询即 SchemaDatabaseReader不做表结构推断最终Document的字段完全取决于你的 SQL 查询返回的列。建议在 SQL 中用CONCAT/AS预先拼装好适合语义检索的正文文本就像官方示例中把name、age拼成自然语句那样。元数据键不要重复多个metadata_cols条目映射到同一键会静默覆盖base.py L150。schema 只在类内建连时生效复用SQLDatabase对象时无法在DatabaseReader层覆盖 schemabase.py L35-L36。document_id必须返回字符串否则回退到 UUID并伴随 warning 日志异常会被捕获不会中断整个加载流程。指定缺失列不致命但需留意日志metadata_cols引用了查询结果中不存在的列时只打 warning若你的场景对元数据完整性要求高应检查这些告警。惰性加载适合大批量数据lazy_load_data是生成器逐行产出Document配合load_data使用时适合大数据集的流式处理。八、小结DatabaseReader用极简的接口一条 SQL 三个可选参数完成了数据库 → LlamaIndex Document的桥接四种连接方式覆盖了从零配置到深度复用的所有场景metadata_cols与excluded_text_cols让你在加载阶段就完成字段分流document_id则为数据更新的幂等性提供了保障。你可以进一步阅读 base.py 与 SQLDatabase 实现 深入底层细节或直接运行 演示 Notebook 验证全流程。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考