modules.readers 模块帮助

本章节包含 modules.readers 包中常用「数据读取」模块的使用说明和示例，例如：

Excel / CSV / 文本 / 数据库等不同数据源的读取模块
针对 GDIM 或特定业务格式的专用读取模块（含数字模型结构读取、项目表数据读取等）

CsvReader

模块简介与适用场景

CsvReader 用于读取 .csv 文件，支持本地路径或 GDIM 文件描述（dict）。
可输出表格数据（OutputTable），也可从多行表头生成供 LLM 使用的列 schema 文本（OutputSchema）。
典型适用场景：
- 将外部导出的 CSV（如仪器数据、统计结果、第三方表格）作为 Pipeline 的数据源；
- 在 GDIM 前端选择 CSV 文件后直接读取；
- CSV 前几行含字段名、说明、单位等多行表头时，生成结构化 schema 供 PromptTemplate 等模块使用。

端口说明

输入端口 - （无）：该模块主要通过参数 file / sep / encoding 等提供输入配置；其中 file 可为本地路径，也可为 GDIM 文件服务文件描述 dict
输出端口 - OutputTable：读取到的表格（TableData）；output_mode 为 "table" 或 "both" 时写入 - OutputSchema：列 schema 的 ResultModel``（纯文本，**不是** ``TableData）；output_mode 为 "schema" 或 "both" 时写入。格式与用法见下文「schema 输出格式说明」

快速上手示例：读取 CSV 表格

from gdisdk.modules.readers import CsvReader

reader = CsvReader(mname="ReadCsv")
reader.file = "example.csv"
reader.sep = ","          # 分隔符，默认 ","
reader.encoding = "auto"  # 自动识别编码（推荐用于中文 CSV）
reader.output_mode = "table"

reader.execute()
table = reader.OutputTable.data
df = table.dataframe  # 如需 pandas DataFrame，可从 TableData 取出

快速上手示例：读取 CSV schema

from gdisdk.modules.readers import CsvReader

reader = CsvReader(mname="ReadCsvSchema")
reader.file = "example.csv"
reader.output_mode = "schema"
reader.name_row = 0           # 第 1 行是字段名
reader.description_row = 1    # 第 2 行是字段说明；如果没有说明行可设为 None
reader.unit_row = 2           # 第 3 行是物理单位；如果没有单位行可设为 None
reader.schema_field_name = "fields"

reader.execute()
schema = reader.OutputSchema.data
schema_text = schema.fields   # 纯文本，可直接用于提示词占位符 {fields}

# 输出示例：
# Table: example
# Fields:
# - 孔号: 钻孔编号
# - 深度: 钻孔深度 [m]
# - 孔压: 孔隙水压力 [kPa]

快速上手示例：读取 GDIM 文件服务上的 CSV

from gdisdk.modules.readers import CsvReader

# gdim_file 一般由 GDIM 前端文件选择器或上游模块直接提供
# 不建议手写这个 dict；应直接使用平台返回的完整文件描述
gdim_file = {
    "success": True,
    "fileId": "your-file-id",
    "fileUrl": "/minio/preview/your-file-id",
    "originalFilename": "监测数据.csv",
    "filename": "monitor.csv",
    "size": 1024,
    "contentType": "text/csv",
    "objectId": None,
    "objectType": None,
    "message": None,
    "thFileUrl": None,
    "thFilename": None,
    "thSize": None,
    "downloadUrl": "/minio/download/your-file-id",
    "host": "https://your-gdim-host/api/",
}

reader = CsvReader(mname="ReadCsvFromGdimFile")
reader.file = gdim_file
reader.encoding = "auto"
reader.output_mode = "table"

reader.execute()
table = reader.OutputTable.data

参数说明

CsvReader 参数一览
参数名	类型	默认值	说明
`file`	`str \| Path \| dict \| None`	`None`	CSV 文件来源。传本地路径时直接读取本机文件；传 `dict` 时会先按 `GdimMinIOFile` 校验，并根据 `downloadUrl` / `host` 从 GDIM 文件服务下载到工作目录后再读取；为 `None` 时不读取并输出 `None`。
`sep`	`str`	`,`	分隔符（如 `,`, `"\t"` 等）。
`encoding`	`str \| None`	`"auto"`	文件编码； `"auto"` 会自动尝试常见编码并选择可解码的编码。
`header`	`int \| list[int] \| str \| None`	`"infer"`	表头行配置： `"infer"` 自动推断； `0` 表示第一行为列名； `None` 表示无表头（列名为 0,1,2…）； `[0,1]` 支持多级表头。
`index_col`	`int \| str \| list[int] \| list[str] \| None`	`None`	指定作为索引的列。
`usecols`	`list[int] \| list[str] \| None`	`None`	只读取指定列（可用列序号或列名）。
`dtype`	`dict[str, str] \| str \| None`	`None`	指定数据类型（可为单一类型或按列指定类型字典），用于避免类型推断误差。
`skiprows`	`int \| list[int] \| None`	`None`	跳过行：可为跳过前 N 行的 `int`，或指定要跳过的行号列表（0-indexed）。
`nrows`	`int \| None`	`None`	读取行数上限（用于大文件抽样/加速）。
`na_values`	`str \| list[str] \| dict[str, str \| list[str]] \| None`	`None`	额外识别为缺失值的字符串（支持按列指定）。
`output_mode`	`Literal["table", "schema", "both"]`	`"table"`	控制输出模式： `"table"` 只输出 `OutputTable`； `"schema"` 只输出 `OutputSchema`，且不会加载整张表； `"both"` 同时输出表格和 schema。
`name_row`	`int`	`0`	读取 schema 时，字段名所在的原始 CSV 行号（从 0 开始计数）。仅在输出 `OutputSchema` 时使用。
`description_row`	`int \| None`	`1`	读取 schema 时，字段说明所在的原始 CSV 行号（从 0 开始计数）；若 CSV 没有说明行，设为 `None`。仅在输出 `OutputSchema` 时使用。
`unit_row`	`int \| None`	`2`	读取 schema 时，各列物理单位所在的原始 CSV 行号（从 0 开始计数），默认第三行；无单位行、或行号超出文件时可设为 None``（与 ``description_row 行为一致）。仅在输出 `OutputSchema` 时使用。
`check_units`	`bool`	`True`	是否校验单位字符串与 `gdi.dataclass.terminologies.Units` 的匹配。 True``（默认）：仅识别到的标准单位会写入 schema（如 ``[m]），未知单位会发出 `GDIDataQualityWarning` 且该列不带单位标注； `False`：不校验，非空单位单元格按原文放入方括号（如 `[my unit]`）。
`schema_field_name`	`str`	`"fields"`	`OutputSchema` 中承载 schema 纯文本的 ResultModel 字段名。默认可通过 `schema.fields` 访问；若下游 `PromptTemplate` 占位符为 `{columns}` 等，可改为对应名称（如 `"columns"`、`"schema"`）。

schema 输出格式说明

OutputSchema 输出的是一个 ResultModel 实例（内部为单字段 Pydantic BaseModel），不是 TableData，也不包含 CSV 数据行本身。
模型仅有一个字符串字段，字段名等于 schema_field_name``（默认 ``"fields"），值为可直接注入提示词的纯文本摘要。
典型用法：将 OutputSchema 连到 PromptTemplate.InputValues，使模板中的 {fields}``（或与 ``schema_field_name 同名的占位符）自动填入列说明。
文本格式大致如下：

Table: <文件名（不含扩展名）>
Fields:
- <字段名>: <字段说明> [<单位>]
- <字段名>: <字段说明>
- <字段名>

各部分的来源：
- Table: ...：取自 CSV 文件名（stem）；
- 字段名：来自 name_row 对应行的各列单元格；
- 字段说明：来自 description_row；若该行不存在或 description_row=None，则只输出 - 字段名；
- 单位：来自 unit_row，以方括号附在字段行末尾，如 [m]、[kPa]。
如果某列没有对应说明，则仅输出字段名（及可选的单位标注）。
当 description_row 超出文件行数或设为 None 时，模块仍会输出字段名列表，但不附带字段说明。
当配置了 unit_row 且该行存在有效单元格时，字段行会在 schema 中附带单位方括号，例如 - depth: 钻孔深度 [m]。 check_units=True``（默认）时只接受能匹配 ``Units 的单位，未知单位会发出 GDIDataQualityWarning 并省略该列单位； check_units=False 时不校验，非空单位按原字符串写入方括号（如 [my unit]）。

上传 GDIM 前检查

是否需要特别处理：当读取的 CSV 文件需要由 GDIM 前端上传、选择或在平台运行时提供时，是。
必须检查：
- 不要再依赖本机绝对路径或仅本地存在的相对路径；上传后的推荐方式是由前端传入 GDIM 文件描述，并直接赋给 file；
- 模板建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``dict``） 提供，这是上传后的推荐方式。
建议检查：
- encoding 优先设为 "auto"，减少中文 CSV 编码不一致导致的读取失败；
若遗漏，常见现象：
- 本地调试可正常读取固定路径文件，但上传 GDIM 后报“文件不存在”；
- 文件能下载，但因编码出现乱码。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import CsvReader

pipeline = PipeLine(app_name="ReadCsvDemo", app_title="读取CSV示例")

read_csv = CsvReader("ReadCsv")
read_csv.file = "example.csv"
read_csv.encoding = "auto"
read_csv.output_mode = "both"
read_csv.name_row = 0
read_csv.description_row = 1

pipeline.add_module(read_csv)
pipeline.run()

table = read_csv.OutputTable.data
schema = read_csv.OutputSchema.data
schema_text = schema.fields   # 纯文本列 schema，可传给 PromptTemplate

更多信息

ExcelReader

模块简介与适用场景

ExcelReader 用于读取 .xlsx 工作簿，支持本地路径或 GDIM 文件描述（dict）。
可输出单张 TableData``（``OutputTable）、多张工作表的 TableCollection``（``OutputTables），也可从表头行生成供 LLM 使用的列 schema 文本（OutputSchema）。
典型适用场景：
- 将 GDIM 导出的 Excel 模板或第三方 .xlsx 作为 Pipeline 数据源；
- 在 GDIM 前端选择 Excel 文件后直接读取指定工作表或全部工作表；
- 工作表前几行含字段名、说明、单位等多行表头时，生成结构化 schema 供 PromptTemplate 等模块使用；
- 多工作表工作簿中手动配置主表/子表关系，供下游按层级处理。
格式限制：仅支持 .xlsx，不支持旧版 .xls。
GDIM 导出布局（常见）：工作表前几行常为标题、字段名、单位等多行表头，按默认表头推断可能取错列名；header 与 schema 行号参数的配置见下文「参数说明」。
多工作表时的 ``OutputTable``：当 sheet_name 为列表或 None 时，OutputTable **始终**对应工作簿索引 0 的工作表，而非列表中的第一张；sheet_name 与 OutputTables 的对应关系见「参数说明」。

端口说明

输入端口 - （无）：该模块主要通过参数 file / sheet_name / header 等提供输入配置；其中 file 可为本地路径，也可为 GDIM 文件服务文件描述 dict
输出端口 - OutputTable：单张 TableData；output_mode 为 "table" 或 "both" 时写入，否则为 None。file 为 None 时也为 None。 - OutputTables：多表 TableCollection；output_mode 为 "table" 或 "both" 时写入，否则为 None。file 为 None 时也为 None。 - OutputSchema：列 schema 的 ResultModel``（纯文本，**不是** ``TableData）；output_mode 为 "schema" 或 "both" 时写入，否则为 None。file 为 None 时也为 None。格式与用法见下文「schema 输出格式说明」。

快速上手示例：读取单个工作表

from gdisdk.modules.readers import ExcelReader

reader = ExcelReader(mname="ReadExcel")
reader.file = "survey.xlsx"
reader.sheet_name = "钻孔一览表"   # 也可用工作表索引，如 0
reader.header = 1                # GDIM 导出：第 2 行为字段名
reader.output_mode = "table"

reader.execute()
table = reader.OutputTable.data
df = table.dataframe

快速上手示例：读取多个工作表

from gdisdk.modules.readers import ExcelReader

reader = ExcelReader(mname="ReadExcelSheets")
reader.file = "survey.xlsx"
reader.sheet_name = ["钻孔一览表", "地层表"]
reader.header = 1
reader.table_relationship_mode = "manual"
reader.main_table = "钻孔一览表"
reader.sub_tables = ["地层表"]
reader.primary_key = "bore_number"

reader.execute()
collection = reader.OutputTables.data
first_sheet = reader.OutputTable.data   # 始终是工作簿索引 0 的工作表

快速上手示例：读取 Excel schema

from gdisdk.modules.readers import ExcelReader

reader = ExcelReader(mname="ReadExcelSchema")
reader.file = "survey.xlsx"
reader.sheet_name = "钻孔一览表"
reader.output_mode = "schema"
reader.name_row = 1           # 第 2 行是字段名（GDIM 导出常见）
reader.description_row = 1    # 若无说明行可设为 None
reader.unit_row = 2           # 第 3 行是物理单位
reader.schema_field_name = "fields"

reader.execute()
schema = reader.OutputSchema.data
schema_text = schema.fields   # 纯文本，可直接用于提示词占位符 {fields}

# 输出示例：
# Table: 钻孔一览表
# Fields:
# - bore_number: bore_number
# - design_bore_depth: design_bore_depth [m]

快速上手示例：读取 GDIM 文件服务上的 Excel

from gdisdk.modules.readers import ExcelReader

# gdim_file 一般由 GDIM 前端文件选择器或上游模块直接提供
gdim_file = {
    "success": True,
    "fileId": "your-file-id",
    "originalFilename": "勘察数据.xlsx",
    "filename": "survey.xlsx",
    "downloadUrl": "/minio/download/your-file-id",
    "host": "https://your-gdim-host/api/",
}

reader = ExcelReader(mname="ReadExcelFromGdim")
reader.file = gdim_file
reader.sheet_name = 0
reader.header = 1
reader.output_mode = "table"

reader.execute()
table = reader.OutputTable.data

参数说明

ExcelReader 参数一览
参数名	类型	默认值	说明
`file`	`str \| Path \| dict \| None`	`None`	Excel 文件来源。传本地路径时直接读取本机文件；传 `dict` 时会先按 `GdimMinIOFile` 校验，并根据 `downloadUrl` / `host` 从 GDIM 文件服务下载到工作目录后再读取；为 `None` 时不读取并输出 `None`。
`sheet_name`	`str \| int \| list[str \| int] \| None`	`None`	要读取的工作表。`str` / `int`：读单表，`OutputTable` 为该表、`OutputTables` 为仅含该表的单表集合；`list`：读列表中的工作表到 `OutputTables`，`OutputTable` 为工作簿索引 `0`，且若索引 `0` 不在列表中也会自动加入 `OutputTables`；`None`：读全部工作表到 `OutputTables`，`OutputTable` 为索引 `0`。
`header`	`int \| list[int] \| str \| None`	`"infer"`	表头行配置：`"infer"` 自动推断；`0` 表示第一行为列名；`None` 表示无表头；`[0,1]` 支持多级表头。GDIM 导出 Excel 常见布局为第 1 行中文标题、第 2 行字段名、第 3 行单位、第 4 行起数据，通常应设为 ``1``（第二行为字段名）。
`index_col`	`int \| str \| list[int] \| list[str] \| None`	`None`	指定作为索引的列。
`usecols`	`list[int] \| list[str] \| None`	`None`	只读取指定列（可用列序号或列名）。
`dtype`	`dict[str, str] \| str \| None`	`None`	指定数据类型，约定与 `CsvReader` 相同（如 `{"bore_number": "str"}` 避免编号被读成整数）。
`skiprows`	`int \| list[int] \| None`	`None`	跳过行：可为跳过前 N 行的 `int`，或指定要跳过的行号列表（0-indexed）。
`nrows`	`int \| None`	`None`	读取行数上限；`0` 视为不限制。
`na_values`	`str \| list[str] \| dict[str, str \| list[str]] \| None`	`None`	额外识别为缺失值的字符串（支持按列指定）。
`output_mode`	`Literal["table", "schema", "both"]`	`"table"`	控制输出模式：`"table"` 只输出表数据端口；`"schema"` 只输出 `OutputSchema`，且不会加载整张表；`"both"` 同时输出表格和 schema。
`name_row`	`int`	`0`	读取 schema 时，字段名所在的原始工作表行号（从 0 开始）。仅在输出 `OutputSchema` 时使用。
`description_row`	`int \| None`	`1`	读取 schema 时，字段说明所在的原始行号；若无说明行设为 `None`。仅在输出 `OutputSchema` 时使用。
`unit_row`	`int \| None`	`2`	读取 schema 时，各列物理单位所在的原始行号；无单位行可设为 `None`。仅在输出 `OutputSchema` 时使用。
`check_units`	`bool`	`True`	是否校验单位与 `gdi.dataclass.terminologies.Units` 的匹配。True``（默认）：仅识别到的标准单位写入 schema；未知单位发出 ``GDIDataQualityWarning 并省略该列单位；`False`：不校验，非空单位按原文放入方括号。
`schema_field_name`	`str`	`"fields"`	`OutputSchema` 中承载 schema 纯文本的 ResultModel 字段名。
`table_relationship_mode`	`Literal["none", "manual"]`	`"none"`	多工作表时 `OutputTables` 的主子表关系：`"none"` 各表独立添加；`"manual"` 按 `main_table` / `sub_tables` / `primary_key` 配置层级。仅一张工作表时忽略。
`main_table`	`str \| list[str] \| None`	`None`	主表工作表名或标题；`table_relationship_mode="manual"` 时必填。多个主表时用 `list[str]`，并配合 `sub_tables` 字典。
`sub_tables`	`list[str] \| dict[str, list[str]] \| None`	`None`	子表工作表名或标题；`table_relationship_mode="manual"` 时必填。单主表时用 `list[str]`；多主表时用 `dict` 映射各主表到其子表列表。
`primary_key`	`str \| dict[str, str] \| None`	`None`	主表与子表的关联列名。`str`：单主表配置下的统一关联列；`dict[str, str]`：多主表时按主表分别指定；`None`：自动取主表与各子表的第一列公共列。

schema 输出格式说明

OutputSchema 输出的是一个 ResultModel 实例（内部为单字段 Pydantic BaseModel），不是 TableData，也不包含工作表数据行本身。
模型仅有一个字符串字段，字段名等于 schema_field_name``（默认 ``"fields"），值为可直接注入提示词的纯文本摘要。
典型用法：将 OutputSchema 连到 PromptTemplate.InputValues，使模板中的 {fields} 自动填入列说明。
文本格式大致如下：

Table: <工作表名>
Fields:
- <字段名>: <字段说明> [<单位>]
- <字段名>: <字段说明>
- <字段名>

各部分的来源：
- Table: ...：取自工作表名称（sheet_label）；
- 字段名：来自 name_row 对应行的各列单元格；
- 字段说明：来自 description_row；若该行不存在或 description_row=None，则只输出 - 字段名；
- 单位：来自 unit_row，以方括号附在字段行末尾。
读取多个工作表时，各工作表的 schema 块之间以空行分隔。
当 name_row 超出工作表行数时会抛出 ValueError。

主子表关系说明

仅当 sheet_name 读取到 两张及以上 工作表，且 table_relationship_mode="manual" 时生效。
main_table、sub_tables 可使用工作表名称或 **标题**（与 TableData.title 一致）；模块内部会解析为 TableData.name``（形如 ``excel_<工作表名>）。
primary_key 未指定时，取主表与每个子表之间的第一列公共列；若无公共列会抛出 ValueError，需显式设置 primary_key。
未纳入主/子关系配置的工作表仍会加入 OutputTables，但不带层级元数据。

上传 GDIM 前检查

是否需要特别处理：当 Excel 文件需要由 GDIM 前端上传、选择或在平台运行时提供时，是。
必须检查：
- 使用 pipeline.add_attribute 将 file 映射为 Pipeline 属性（param_name="file"），供 GDIM 前端上传或选择 Excel；平台运行时前端会传入 GDIM 文件描述 dict，模块据此下载后读取；
- 不要在 .pipe 里写死本机绝对路径或仅本地存在的相对路径。
建议检查：
- 确认文件扩展名为 .xlsx``（不支持 ``.xls）；
- 本地调试可用 pipeline.set_attributes(file=...) 预设测试文件，上传 GDIM 后以前端传入的值为准。
若遗漏，常见现象：
- 本地调试可正常读取固定路径文件，但上传 GDIM 后报”文件不存在”；
- 未将 file 注册为 Pipeline 属性，GDIM 前端无法提供文件，模块 file 始终为 None；

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import ExcelReader

pipeline = PipeLine(app_name="ReadExcelDemo", app_title="读取Excel示例")

read_excel = ExcelReader("ReadExcel")
read_excel.sheet_name = ["钻孔一览表", "地层表"]
read_excel.header = 1
read_excel.output_mode = "both"
read_excel.name_row = 1
read_excel.unit_row = 2
read_excel.table_relationship_mode = "manual"
read_excel.main_table = "钻孔一览表"
read_excel.sub_tables = ["地层表"]
read_excel.primary_key = "bore_number"

pipeline.add_module(read_excel)

pipeline.add_attribute(
    attr_name="file",
    module_name="ReadExcel",
    param_name="file",
    attr_title="Excel 文件",
)

# 本地调试时预设测试文件；上传 GDIM 后由前端赋值
pipeline.set_attributes(file="survey.xlsx")

pipeline.run()

table = read_excel.OutputTable.data
collection = read_excel.OutputTables.data
schema_text = read_excel.OutputSchema.data.fields

更多信息

MdbReader

模块简介与适用场景

MdbReader 读取 Microsoft Access .mdb 文件，可将表数据输出为 TableData / TableCollection，也可导出表结构 schema 文本供 PromptTemplate 等下游模块使用。
典型适用场景：
- 将第三方或历史 Access 数据库作为 Pipeline 数据源（如勘察、档案类 MDB）；
- 在 GDIM 前端上传 MDB 后读取指定表或全部表；
- 仅需表结构、主键及表间关系说明时，用 output_mode="schema" 生成 LLM 可读的字段摘要，无需加载全量数据。
平台差异（重要）：Windows 下通过 ODBC + Access COM 读取，可自动识别主子表关系并尽量补全字段/表描述；Linux 下通过 mdbtools 读取表数据，OutputTables **不会**附带主子表层级，Schema 也可能缺少字段说明、主键与关系信息（会发出 GDIDataQualityWarning）。需要完整元数据时建议在 Windows 环境运行。
加密库：带密码的 MDB 必须设置 password，否则无法打开。

端口说明

输入端口 - InputFile：MDB 文件路径或 GDIM 文件描述 dict。若端口有数据，会覆盖模块参数 file 的值。
输出端口 - OutputTable：单张 TableData；output_mode 为 "table" 或 "both" 时写入。table_names 仅含一张表时输出该表；否则输出 MDB 读取顺序中的第一张用户表。 - OutputTables：多表 TableCollection；output_mode 为 "table" 或 "both" 时写入。Windows 下会按 MDB 中的关系自动设置主表/子表。 - OutputSchema：表结构的 ResultModel``（纯文本，**不是** ``TableData）；output_mode 为 "schema" 或 "both" 时写入。格式见下文「schema 输出格式说明」。

快速上手示例：读取 MDB 全部表

from gdisdk.modules.readers import MdbReader

reader = MdbReader(mname="ReadMdb")
reader.InputFile = "sample.mdb"
reader.output_mode = "table"

reader.execute()
tables = reader.OutputTables.data
first_table = reader.OutputTable.data   # 读取顺序中的第一张用户表

快速上手示例：只读指定表与列

from gdisdk.modules.readers import MdbReader

reader = MdbReader(mname="ReadMdbPartial")
reader.InputFile = "sample.mdb"
reader.table_names = ["钻孔表", "地层表"]
reader.usecols = {
    "钻孔表": ["孔号", "孔口高程"],
    "地层表": ["层号", "岩土名称", "厚度"],
}
reader.nrows = 100      # 每个表最多读取 100 行
reader.skiprows = 0

reader.execute()
tables = reader.OutputTables.data
borehole = reader.OutputTable.data   # table_names 有多张表时，OutputTable 为第一张

快速上手示例：导出 Schema 供 PromptTemplate 使用

from gdisdk.modules.readers import MdbReader

reader = MdbReader(mname="ReadMdbSchema")
reader.InputFile = "sample.mdb"
reader.table_names = ["钻孔表"]
reader.output_mode = "schema"
reader.include_sample_values = 3   # 每个字段附带最多 3 个 distinct 示例值
reader.schema_field_name = "fields"

reader.execute()
schema = reader.OutputSchema.data
schema_text = schema.fields   # 纯文本，可传给 PromptTemplate 的 {fields}

快速上手示例：读取 GDIM 文件服务上的 MDB

from gdisdk.modules.readers import MdbReader

# gdim_file 一般由 GDIM 前端文件选择器或上游模块直接提供
gdim_file = {
    "success": True,
    "fileId": "your-file-id",
    "originalFilename": "勘察数据.mdb",
    "filename": "survey.mdb",
    "downloadUrl": "/minio/download/your-file-id",
    "host": "https://your-gdim-host/api/",
}

reader = MdbReader(mname="ReadMdbFromGdim")
reader.InputFile = gdim_file
reader.password = "your-mdb-password"   # 加密库必填
reader.output_mode = "both"

reader.execute()
tables = reader.OutputTables.data
schema_text = reader.OutputSchema.data.fields

参数说明

MdbReader 参数一览
参数名	类型	默认值	说明
`file`	`str \| Path \| dict \| None`	`None`	MDB 文件来源。传本地路径时直接读取本机文件；传 `dict` 时会先按 `GdimMinIOFile` 校验，并根据 `downloadUrl` / `host` 从 GDIM 文件服务下载到工作目录后再读取；为 `None` 时不读取并输出 `None`。若 `InputFile` 端口有数据，会覆盖本参数。
`table_names`	`list[str] \| None`	`None`	仅读取指定表；为 `None` 时读取 MDB 中全部用户表（自动跳过 `MSys*`、`~` 开头的系统表）。Schema 导出同样仅包含这些表。
`password`	`str \| None`	`None`	MDB 数据库访问密码。加密库必须提供正确密码才能读取。
`usecols`	`list[str] \| dict[str, list[str]] \| None`	`None`	仅读取部分列。`list[str]` 对所有表应用同一组列名；`dict[str, list[str]]` 按表名分别指定。Schema 导出同样仅包含这些列。列名不存在时会报错。
`nrows`	`int \| None`	`None`	每个表最多读取的数据行数；`0` 或留空表示不限制。
`skiprows`	`int \| None`	`None`	每个表跳过开头的数据行数（在 `nrows` 限制之前应用）。
`output_mode`	`Literal["table", "schema", "both"]`	`"table"`	控制输出模式：`"table"` 只输出表数据端口；`"schema"` 只输出 `OutputSchema`，且不会加载整张表；`"both"` 同时输出表数据与 Schema。
`schema_field_name`	`str`	`"fields"`	`OutputSchema` 中承载 schema 纯文本的 ResultModel 字段名。默认可通过 `schema.fields` 访问；若下游 `PromptTemplate` 占位符为 `{columns}` 等，可改为对应名称。
`include_sample_values`	`int`	`0`	Schema 导出时每个字段附带的 distinct 示例值个数。`0` 表示不包含；大于 `0` 时会扫描少量行以提取示例值。

schema 输出格式说明

OutputSchema 输出的是一个 ResultModel 实例（内部为单字段 Pydantic BaseModel），不是 TableData，也不包含 MDB 数据行本身。
典型用法：将 OutputSchema 连到 PromptTemplate.InputValues，使模板中的 {fields}``（或与 ``schema_field_name 同名的占位符）自动填入表结构说明。
单表示例格式大致如下：

Table: 钻孔表
Description: 钻孔基本信息
Primary key: 孔号
Fields:
- 孔号: 钻孔编号 [VARCHAR]
- 孔口高程: 孔口标高 [DOUBLE] (samples: 12.3, 15.0, 18.2)
- 孔深 [REAL, not null]
Relationships:
- child: 地层表 (join: 孔号 -> 孔号)

多表时，每个表块之间以空行分隔。
Windows 下字段说明、表描述、主键与关系信息较完整；Linux 下可能仅有字段名与类型，并可能缺少 Primary key / Relationships 段落（见上文平台差异说明）。

读取行为说明

系统表（MSys*、~ 开头）会被自动跳过，不会进入输出。
Windows 下通过 Microsoft Access Driver (*.mdb, *.accdb) ODBC 驱动连接；Linux 下依赖 mdbtools``（``mdb-export、mdb-schema 等），服务器需已安装相应工具。
Linux 下 nrows / skiprows 在 mdb-export 导出全表后于内存中切片实现；大表抽样时 Windows 侧通常更高效。
output_mode="schema" 时不会读取表数据，适合仅需结构说明的场景。

上传 GDIM 前检查

是否需要特别处理：当 MDB 文件需要由 GDIM 前端上传、选择或在平台运行时提供时，是。
必须检查：
- 使用 pipeline.add_attribute 将 file 映射为 Pipeline 属性（param_name="file"），供 GDIM 前端上传或选择 MDB；平台运行时前端会传入 GDIM 文件描述 dict，模块据此下载后读取；
- 不要在 .pipe 里写死本机绝对路径或仅本地存在的相对路径。
建议检查：
- 加密 MDB 须配置 password；也可通过 add_attribute 一并暴露，便于前端填写；
- 本地调试可用 pipeline.set_attributes(file=...) 预设测试文件，上传 GDIM 后以前端传入的值为准。
若遗漏，常见现象：
- 本地调试可正常读取固定路径文件，但上传 GDIM 后报“文件不存在”；
- 未将 file 注册为 Pipeline 属性，GDIM 前端无法提供文件，模块 file 始终为 None；
- 加密库未设密码导致 ODBC / mdbtools 连接失败。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import MdbReader

pipeline = PipeLine(app_name="ReadMdbDemo", app_title="读取MDB示例")

read_mdb = MdbReader("ReadMdb")
read_mdb.table_names = ["钻孔表"]
read_mdb.output_mode = "both"
read_mdb.include_sample_values = 2

pipeline.add_module(read_mdb)

pipeline.add_attribute(
    attr_name="file",
    module_name="ReadMdb",
    param_name="file",
    attr_title="MDB 文件",
)

# 本地调试时预设测试文件；上传 GDIM 后由前端赋值
pipeline.set_attributes(file="sample.mdb")

pipeline.run()

table = read_mdb.OutputTable.data
schema_text = read_mdb.OutputSchema.data.fields

更多信息

GdimTemplateReader

模块简介与适用场景

GdimTemplateReader 按数字模型 ID（tpl_id）或项目 ID 读取 GDIM **数字模型结构**（不含表内业务数据），输出 GdimTemplate。平台界面称「数字模型」；SDK / API 仍沿用 template 命名，见术语对照。
与 GdimTableReader 不同：本模块只返回表元数据、字段定义、主/子表关系等，用于对照内部 表名 / 字段名，或在代码中按数字模型动态生成读表、写表、校验逻辑。
典型适用场景：
- 本地开发时打印某项目数字模型的表名、字段名与主/子表树；
- 根据数字模型结构动态配置 GdimTableReader.table_fields 或 UI 下拉选项；
- 需要程序化遍历全部表结构时（若只查单表的 name/title，也可直接用 GDIM 开发模式，不必运行本模块）。

端口说明

输入端口 - InputToken：鉴权与项目定位信息 (token, proj_id, host)。若 Pipeline 已通过 pipeline.update_gdim_state(token=..., proj_id=..., host=...) 配置 gdim_state，模块会从 Pipeline 自动取 token（及项目、host 等），此时该端口可以不连接。若已设置 tpl_id，则不强制要求 proj_id。
输出端口 - OutputTemplate：数字模型结构（GdimTemplate）；鉴权失败时为 None

快速上手示例：按项目读取数字模型结构

from gdisdk.modules.readers import GdimTemplateReader

reader = GdimTemplateReader(mname="ReadTemplate")
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)

reader.execute()
tpl = reader.OutputTemplate.data

# 按表标题取元数据，再查看内部表名与字段
bore_meta = tpl.get_table_metadata("勘探孔参数表")
print(bore_meta.name)                            # 例如 bore_table
print(list(bore_meta.fields_metadata.keys()))    # 字段内部名列表

参数说明

GdimTemplateReader 参数一览
参数名	类型	默认值	说明
`tpl_id`	`str \| None`	`None`	数字模型 ID（API 参数名仍为 `tpl_id`）。若不为 `None`，则按该数字模型读取，并忽略 `proj_id`。
`get_app_info`	`bool`	`False`	是否同时获取数字模型下的应用信息（写入 `GdimTemplate.app_info`）。
`template_tree`	`bool`	`True`	是否获取带主/子表关系的树形结构（`sub_tables`）。为 `False` 时只拉取扁平表元数据。
`token` / `proj_id` / `host`	`str \| None`	`None`	构造参数形式的鉴权信息；文档示例推荐用 `InputToken` 或 `pipeline.update_gdim_state`，见上文端口说明。

读取行为说明

若当前模块已挂在 Pipeline 上，且 pipeline.gdim_template 已有缓存，则 优先复用 该缓存，不再请求远端。
template_tree=True``（默认）走树形结构接口，便于使用 ``get_children / root_tables 等关系查询；False 时仅扁平元数据。
输出数据结构与常用方法见 GdimTemplate。

在 pipeline 中的使用方式

from gdisdk.connectors import log_in
from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import GdimTemplateReader

pipeline = PipeLine(app_name="InspectTemplate", app_title="查看数字模型结构")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_tpl = GdimTemplateReader("ReadTemplate")
# 也可改为按数字模型 ID 读取：read_tpl.tpl_id = "你的数字模型ID"
pipeline.add_module(read_tpl)

pipeline.run()
tpl = read_tpl.OutputTemplate.data

更多信息

术语对照：数字模型与模板
:doc:`GDIM 开发模式 (Dev Mode) <gdim_dev_mode>`（页面上直接查看表名 / 字段名）
GdimTemplate 数据结构
API 参考 - modules 包
完整类定义与参数说明（readers）

GdimTableReader

模块简介与适用场景

GdimTableReader 从 GDIM 项目读取一个或多个数据表，输出 TableCollection，并可指定其中一张表为 TableData。
输出 TableCollection 时会基于 GDIM 数字模型自动识别主/子表关系；支持按表配置读取过滤（table_filters）、主表主键过滤（primary_key_value_filter）及行数上限（nrows）。过滤语法见下文「GDIM 读取过滤说明」。
典型适用场景：
- 在 Pipeline 起点拉取业务表（如剖面、钻孔、地层等）；
- 只读关键字段并在下游筛选、统计、绘图；
- 按主表主键或字段条件只拉取部分关联子表数据。

Hint

table_fields 等参数中的表、字段均可写 内部名（name） 或 显示标题（title）。跨数字模型复用时建议优先用内部名；可在 GDIM 页面开启开发模式（网址后加 ?dev）直接查看，或用上文 GdimTemplateReader 批量读取数字模型结构。

端口说明

输入端口 - InputToken：鉴权与项目定位信息 (token, proj_id, host)。若 Pipeline 已通过 pipeline.update_gdim_state(token=..., proj_id=..., host=...) 配置 gdim_state，模块会从 Pipeline 自动取 token（及项目、host 等），此时该端口可以不连接，否则由本端口传入。
输出端口 - OutputTables：读取到的多表集合（TableCollection） - OutputTable：从集合中选出的单表（TableData），由 output_table_name 指定

快速上手示例：读取指定表与字段

from gdisdk.modules.readers import GdimTableReader

# 最小可运行：通过 InputToken 提供鉴权信息（无需 Pipeline）
reader = GdimTableReader(mname="ReadTables")
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)

# 只读一张表的指定字段（key 可以写表名或表标题，value 可以写字段名或字段标题，系统会自动识别）
reader.table_fields = {
    "剖面数据表": ["剖面编号", "x_coordinate", "y_coordinate"],
}

# 指定 OutputTable 要输出哪张表（未指定时默认取读取到的第一张表）
reader.output_table_name = "剖面数据表"

reader.execute()
one_table = reader.OutputTable.data

参数说明

GdimTableReader 参数一览
参数名	类型	默认值	说明
`table_fields`	`dict[str, list[str]] \| list[str] \| str \| None`	`None`	需要读取的表/字段配置。为 `None` 时读取全部表的全部字段；为 `str/list` 时读取指定表全部字段；为 `dict` 时可指定表与字段（表与字段支持用「name」或「title」，系统会自动识别）。
`format_dict`	`dict[str, dict[str, str]] \| None`	`None`	字段格式化配置（按表维度指定字段格式），用于在读取后对数据类型/格式进行统一处理。
`table_filters`	`dict[str, GdimTableReadFilter \| dict] \| None`	`None`	按表配置高级读取过滤；键为表内部名或表标题。仅 `gdim=True` 时生效。完整结构与示例见下文「GDIM 读取过滤说明」。
`filter_template_variables`	`dict[str, TemplateVariableConfig \| UIAttributeSchema] \| None`	`None`	`table_filters` 中 `{tpl_*}` 占位符的 UI Schema 与默认值；详见「GDIM 读取过滤说明」。
`primary_key_value_filter`	`int \| float \| str \| list \| dict \| UIAttributeSchema \| TemplateVariableConfig \| None`	`None`	按主表主键值过滤关联子表的快捷参数；与 `table_filters` 合并规则见「GDIM 读取过滤说明」。
`nrows`	`int \| dict[str, int] \| None`	`None`	每张表最多读取前 N 行；仅 `gdim=True` 时生效。
`keep_gdim_id`	`bool`	`False`	是否保留输出表中的 `gdim_id` 列（仅 `gdim=True` 时生效）。该列主要用于后续更新 GDIM 中已有的数据。
`table_collection_name`	`str \| None`	`None`	输出 `TableCollection` 的 ``name``（集合元数据）。
`table_collection_title`	`str \| None`	`None`	输出 `TableCollection` 的 `title`。
`table_collection_description`	`str \| None`	`None`	输出 `TableCollection` 的 `description`。
`missing_error_type`	`Literal["error","warning","gdi_warning"]`	`"error"`	表/字段缺失时的处理策略：抛错、控制台警告、或在 GDIM 中以 `GDIWarning` 形式提示。
`empty_error_type`	`Literal["warning","gdi_warning","create_empty_table"]`	`"warning"`	读取到空表时的处理策略：`"warning"` / `"gdi_warning"` 会提示后跳过该表；`"create_empty_table"` 会按模板结构创建空的 `TableData` 并继续输出。若 `table_fields` 以 `dict` 指定了字段，生成的空表还会裁剪到本次请求的字段集合，保证空表 schema 与正常读取时一致。
`all_empty_output`	`Literal["empty_collection","none"]`	`"empty_collection"`	当最终没有任何表进入集合时的输出行为（例如所有表均因 `empty_error_type` 被跳过）。`"empty_collection"` 返回空的 TableCollection``（向后兼容默认）；”none”`` 时 `OutputTables`、`OutputTable` 及 `execute` 返回值均为 `None`。
`output_table_name`	`str \| None`	`None`	`OutputTable` 端口要输出的表名/表标题（与 `TableCollection.get_table` 的查找规则一致）；为 `None` 时默认取集合中第一张表；名称在集合中不存在时 `OutputTable` 为 `None`。
`gdim`	`bool`	`True`	若数据平台为原老版本系统 GBIM，则设置该值为 `False`。
`token / proj_id / host`	`str \| None` 等	`None`	构造函数中可直接传入鉴权信息：`token`、`proj_id`、host``（``host 为 `None` 时使用默认地址）。若未传入，则由 `pipeline.gdim_state` 或 `InputToken` 提供。注意：若在构造函数中设置了 proj_id``（赋给 ``self.proj_id），其优先级高于 `InputToken` 与 Pipeline 上的 `proj_id`；若希望通过 `InputToken` 切换项目，则不要在构造函数里写死 `proj_id`。

GDIM 读取过滤说明

table_filters、primary_key_value_filter 与 nrows 均仅 gdim=True 时生效。

``table_filters`` 结构（每张表一个过滤对象）

table_filters 的键为表内部名或表标题；值为 GdimTableReadFilter 或等价的 dict，支持以下三种条件（可组合）：

字段	类型	说明
`contains`	`list[dict]`	字段匹配（映射 API `filters`）。每项含 `field`、`value`；exact=False``（默认）为模糊匹配（LIKE），``exact=True 为精确匹配（`=`）。
`ranges`	`list[dict]`	范围比较（映射 API `rangeFilters`）。每项含 `field`、operator``（``gt / `gte` / `lt` / `lte`）、`value`。
`filter_group`	`dict`	嵌套逻辑组（映射 API `filterGroup`）。含 logic``（``and / `or`，默认 `and`）、ranges``（本层范围条件）、``children``（子组列表）。注意：``filter_group 各层仅支持 `ranges`，不支持 `contains`。

过滤条件中的 field 可写字段内部名或字段标题。

常见 ``contains`` / ``ranges`` 示例

reader.table_filters = {
    # 模糊匹配：钻孔编号包含 "ZK"
    "勘探点表": {
        "contains": [{"field": "钻孔编号", "value": "ZK"}],
    },
    # 精确匹配 + 范围
    "地层表": {
        "contains": [{"field": "层号", "value": "3", "exact": True}],
        "ranges": [{"field": "厚度", "operator": "gte", "value": "1.5"}],
    },
}

``filter_group`` 嵌套示例

reader.table_filters = {
    "地层表": {
        "filter_group": {
            "logic": "or",
            "ranges": [
                {"field": "厚度", "operator": "gte", "value": "5"},
            ],
            "children": [
                {
                    "logic": "and",
                    "ranges": [
                        {"field": "岩土名称", "operator": "gte", "value": "A"},
                        {"field": "层号", "operator": "lte", "value": "10"},
                    ],
                },
            ],
        },
    },
}

``filter_template_variables`` 与 ``{tpl_*}`` 占位符

在 table_filters 的条件值中可使用 {tpl_变量名} 占位符；变量 UI Schema 与默认值在 filter_template_variables 中统一定义（变量名必须以 ``tpl_`` 开头）。同一占位符可在多张表、多个条件中复用；运行前可通过 reader.tpl_xxx = ... 赋值。

from gdisdk.modules.readers import GdimTableReader
from gdisdk.pipeline.pipeData import StringAttributeSchema

reader = GdimTableReader(mname="ReadWithTplFilter")
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
reader.table_fields = ["勘探点表"]
reader.filter_template_variables = {
    "tpl_hole": StringAttributeSchema(title="钻孔编号", default="ZK1"),
}
reader.table_filters = {
    "勘探点表": {
        "contains": [{"field": "钻孔编号", "value": "{tpl_hole}"}],
    },
}
reader.tpl_hole = "ZK2"  # 运行前改值

reader.execute()

``primary_key_value_filter``（主表主键快捷过滤）

适用于「只读某一主表记录及其子表」的常见场景，比手写 table_filters 更简洁：

模块会自动在主表上生成主键字段的**精确匹配**（contains + exact=True），并与该表已有的 table_filters **合并**（条件追加，而非覆盖）。
同时会为读取集合中的关联子表设置父表主键传参，只拉取对应父记录下的子表数据。
**单值**（str / int / float）时，应用于读取集合内所有含子表的主表。
**列表**（list[str] / list[int] / list[float]）时，按多个主键做 IN 过滤（子表走 parentTablePrimaryKeyValues；若主表也在读取集合中，主表走 filters.values）。
**字典**时，键必须是**父表**（内部名或表标题），不能是正在读取的那张子表；值为对应主键取值（标量或列表）。只读子表、父表不在 table_fields 里时，仍按父表名/标题作为键。多层嵌套时，键是被读子表的**直接父表**（该父表在数字模型里可能本身也是上一级的子表）。
可直接传入 UIAttributeSchema / TemplateVariableConfig``（单值或 per-main-table 字典），在 GDIM UI 中生成控件，而不必使用 ``{tpl_*} 占位符。
空列表 [] 视为未设置主键过滤。
由 GDIM 前端通过 Pipeline 属性注入时（auto_bind="pk_field" / "poi_field"），绑定方式与取值形态见自动绑定属性（auto_bind）。

from gdisdk.modules.readers import GdimTableReader
from gdisdk.pipeline.pipeData import StringAttributeSchema

reader = GdimTableReader(mname="ReadByPk")
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
reader.table_fields = ["勘探点表", "地层表"]

# 方式 A：直接传值
reader.primary_key_value_filter = "ZK1"

# 方式 B：UI 控件（GDIM 前端可改）
# reader.primary_key_value_filter = StringAttributeSchema(
#     title="钻孔编号", default="ZK1", selections=["ZK1", "ZK2"]
# )

# 方式 C：与 table_filters 合并（主表上追加精确匹配，子表仍按主键关联）
# reader.table_filters = {"勘探点表": {"contains": [{"field": "备注", "value": "有效"}]}}
# reader.primary_key_value_filter = "ZK1"

# 方式 D：多个主键
# reader.primary_key_value_filter = ["ZK1", "ZK2"]

reader.execute()

过滤选用建议

父子表「按主键只读一条记录及其子表」→ 优先 primary_key_value_filter。
单表字段模糊/范围/复杂逻辑 → table_filters。
需要在 GDIM UI 中让用户改过滤值 → filter_template_variables + {tpl_*}，或 primary_key_value_filter 直接传 UIAttributeSchema。
需要 GDIM 前端自动注入（地图 POI 或子表主键）→ 见自动绑定属性（auto_bind）。

空表处理说明

当 empty_error_type="warning" 或 "gdi_warning" 时，空表会给出提示后被跳过，不会进入 OutputTables。
当 empty_error_type="create_empty_table" 时，模块会使用该表的模板元数据生成一个空的 TableData：
- 表名、标题、描述、字段元数据仍会保留；
- 若表中存在 id 列，后续仍会按 keep_gdim_id 的规则转换为 gdim_id 或删除；
- 若 table_fields 为 dict，则会仅保留本次请求的字段，避免空表比正常读取多出未请求列。
若所有表均被跳过且集合为空，all_empty_output 决定最终输出是空 TableCollection 还是 None。

快速上手示例：按主表主键读取关联子表

from gdisdk.modules.readers import GdimTableReader

reader = GdimTableReader(mname="ReadByPrimaryKey")
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
reader.table_fields = ["勘探点表", "地层表"]
reader.primary_key_value_filter = "ZK1"
reader.output_table_name = "地层表"

reader.execute()
layers = reader.OutputTable.data

快速上手示例：按字段条件过滤读取

from gdisdk.modules.readers import GdimTableReader

reader = GdimTableReader(mname="ReadWithFilter")
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
reader.table_fields = ["勘探点表"]
reader.table_filters = {
    "勘探点表": {
        "contains": [{"field": "钻孔编号", "value": "ZK"}],
    },
}
reader.nrows = 100

reader.execute()
tables = reader.OutputTables.data

快速上手示例：空表时按模板生成空表

from gdisdk.modules.readers import GdimTableReader

reader = GdimTableReader(mname="ReadMaybeEmptyTable")
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
reader.empty_error_type = "create_empty_table"
reader.output_table_name = "地层表"
reader.table_fields = {
    "地层表": ["层号", "岩土名称", "厚度"],
}

reader.execute()
table = reader.OutputTable.data

# 即使 GDIM 中这张表当前没有数据，仍会得到一个 0 行的 TableData，
# 并保留请求字段对应的 schema，便于后续模块继续运行。

在 pipeline 中的使用方式

from gdisdk.connectors import log_in
from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import GetGdimToken, GdimTableReader

pipeline = PipeLine(app_name="ReadGdimTables", app_title="读取GDIM表数据示例")

# 方式 A：在 Pipeline 上统一配置 GDIM 凭证（模块内部 get_token() 会优先使用 pipeline 的值）
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["剖面数据表", "钻孔表"]
read_tables.output_table_name = "剖面数据表"

pipeline.add_module(read_tables)

# 方式 B：用 GetGdimToken 输出到 InputToken（适合在 Pipeline 中统一鉴权/切换项目）
# get_token = GetGdimToken("GetToken", token="你的GDIM Token", proj_id="你的GDIM项目ID")
# links = get_token.OutputToken >> read_tables.InputToken
# pipe.add_links(links)

result = pipeline.run()
tables = read_tables.OutputTables.data
one_table = read_tables.OutputTable.data

更多信息

:doc:`GDIM 开发模式 (Dev Mode) <gdim_dev_mode>`（查看表名 / 字段名）
:ref:`GdimTemplateReader <modules_help_gdim_template_reader>`（批量读取模板结构）
API 参考 - modules 包
完整类定义与参数说明（readers）

ReadGtbFile

模块简介与适用场景

ReadGtbFile 读取 ExportGdimTables 导出的 .gtb / .xlsx，重建为 TableCollection，适用于「导出 → 本地/外部编辑 → 再读回 Pipeline」的流程。
读取时会恢复模板 ID、表元数据、主/子表关系及坐标系（可通过 OutputCoordinateSystem 输出）。
工作表结构约定：第 1 行字段标题、第 2 行内部名、第 3 行单位、第 4 行起为数据；若 exportFieldsDescription 为 True，第 4 行为字段描述，数据从第 5 行起。

端口说明

输入端口 - InputToken：鉴权与项目定位信息 (token, proj_id, host)；仅当需要从 GDIM 文件服务下载文件，或要执行模板 ID 校验时需要；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取
输出端口 - OutputTables：从 .gtb / .xlsx 文件重建得到的 TableCollection - OutputCoordinateSystem：从文件 metadata.coordinateSystem 解析得到的坐标系对象；若文件中未包含坐标系信息，则输出 None

快速上手示例：读取本地导出的 GTB 文件

from gdisdk.modules.readers import ReadGtbFile

reader = ReadGtbFile(mname="ReadExportedTables")
reader.file = "项目表格导出.gtb"
reader.validate_template_id = False  # 仅做本地读取时可关闭模板校验

reader.execute()
print(reader.OutputTables.data)

快速上手示例：读取 GDIM 文件服务中的导出文件

from gdisdk.modules.readers import ReadGtbFile

gdim_file = {
    "success": True,
    "fileId": "your-file-id",
    "filename": "gdim_tables.gtb",
    "originalFilename": "项目表格导出.gtb",
    "downloadUrl": "/minio/download/your-file-id",
    "host": "https://your-gdim-host/api/",
}

reader = ReadGtbFile(mname="ReadGtbFromGdim")
reader.file = gdim_file
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)

reader.execute()
tables = reader.OutputTables.data

快速上手示例：从 GTB 文件恢复坐标系统

from gdisdk.modules import ReadGtbFile, UpdateGdimAppProjectInfo
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="RestoreCoordinateSystem", app_title="恢复坐标系统示例")
pipeline.update_gdim_state(token="你的GDIM Token", proj_id="你的GDIM项目ID")

read_gtb = ReadGtbFile("ReadGtbFile")
read_gtb.file = "项目表格导出.gtb"
update_proj_info = UpdateGdimAppProjectInfo("UpdateProjectInfo")

pipeline.add_links(
    read_gtb.OutputCoordinateSystem >> update_proj_info.InputResultModel
)
pipeline.run()

参数说明

ReadGtbFile 参数一览
参数名	类型	默认值	说明
`file`	`str \| Path \| dict \| None`	`None`	要读取的 `.gtb` / `.xlsx` 文件。支持本地路径，也支持 GDIM 文件描述 dict``（例如 ``ExportGdimTables(save_to_gdim=True) 的输出）。
`validate_template_id`	`bool`	`True`	是否校验文件中的 `dataTemplateId` 与目标 GDIM 项目的模板 ID 一致。仅在能取得有效 `token + proj_id` 时执行；不一致时会给出 warning 并停止输出。
`token`	`str \| None`	`None`	用户 token；也可通过 `InputToken` 或 `pipeline.gdim_state` 提供。
`proj_id`	`int \| str \| None`	`None`	目标 GDIM 项目 ID，用于模板 ID 校验；若设置，会覆盖 `InputToken` 或 `pipeline.gdim_state` 中的项目 ID。
`host`	`str \| None`	`None`	GDIM 平台地址。若为 `None`，则使用 `pipeline.gdim_state.host` 或环境变量默认值。

读取行为说明

当 file 为本地路径时，模块直接读取该文件。
当 file 为 GDIM 文件描述 dict 时，模块会先根据 downloadUrl / host 下载到工作目录，再执行解析。
若文件扩展名不是 .gtb 或 .xlsx，或 metadata 缺失 / 格式错误，模块会给出 GDIDataQualityWarning 并输出 None。
输出的每张 TableData 会使用字段内部名作为列名，同时把字段标题写入 name_to_title，以便兼顾程序处理与展示。
若导出文件开启了 export_fields_description，模块会根据 metadata.headerFormat 自动跳过第 4 行描述行，从第 5 行开始读取数据。

上传 GDIM 前检查

是否需要特别处理：当该模块在 GDIM 平台运行，且读取对象来自前端上传文件或需要校验目标项目模板时，是。
必须检查：
- 不要依赖仅本地存在的路径；上传后的推荐方式是由前端传入 GDIM 文件描述，并直接赋给 file；
- 文件建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``dict``） 提供，这是上传后的推荐方式。
建议检查：
- 仅在“离线查看导出结果”场景下，可将 validate_template_id 设为 False，避免因没有项目上下文而中断读取；
- 若需同时恢复坐标系统，可将 OutputCoordinateSystem 连入 UpdateGdimAppProjectInfo.InputResultModel。
若遗漏，常见现象：
- 本地调试可读取固定路径文件，但上传 GDIM 后因文件路径不可见而失败；

更多信息

GdimAppDataReader

模块简介与适用场景

GdimAppDataReader 读取 GDIM 中其他 Pipeline 应用已落库的数据，反序列化为 ResultModel，从 OutputResultModel 输出。
上游应用须调用 save_data_to_db() 声明持久化内容；本模块按 app_title 定位应用并取回全部已存字段。键名规则与 save_data_to_db 一致："模块名@输出端口名"、"pipeline@属性名"、"模块名#参数名"``（``add_attribute() 映射的参数须用后者）。
典型适用场景：**拆分应用**（分析应用落库、报告应用读回）、**本地联调**已落库结果。

更详细的配置见运行机制 (Runtime) 中「跨 Pipeline 数据」；取单个字段可配合 filters）。

端口说明

输入端口 - InputToken：(token, proj_id, host)。若当前 Pipeline 已通过 pipeline.update_gdim_state(token=..., proj_id=..., host=...) 配置运行上下文，通常可不连接此端口，模块会从 Pipeline 自动获取 token。
输出端口 - OutputResultModel：反序列化后的 ResultModel；当无法解析 token、未设置 app_title、proj_id 缺失或与平台数据不匹配时可能为 None。

参数说明

GdimAppDataReader 参数一览
参数名	类型	默认值	说明
`app_title`	`str \| None`	`None`	目标应用在 GDIM 模板中的标题，须与保存数据的应用标题完全一致，且能唯一定位到一个应用（`appId`）。
`token` / `proj_id` / `host`	`str \| None` 等	`None`	鉴权与平台地址。可在构造函数传入并写入 `InputToken`；若未传，则依赖 `InputToken` 或 `pipeline.gdim_state`。`proj_id` 若在模块上显式设置，会覆盖 token 中的项目 ID。

快速上手示例：在 Pipeline 中读取另一应用保存的数据

from gdisdk.pipeline import PipeLine
from gdisdk.modules import GdimAppDataReader

pipe = PipeLine(app_name="ReportGenerate", app_title="报告生成")
pipe.update_gdim_state(token="...", proj_id="...")

reader = GdimAppDataReader(mname="ReadCorrosionApp")
reader.app_title = "水腐蚀性分析"  # 与上游应用在模板中的标题一致

pipe.add_module(reader)
pipe.run()

result_model = reader.OutputResultModel.data
if result_model is not None:
    # 键名取决于上游 save_data_to_db 的配置，例如：
    # table = result_model.get("CorrosionModule@OutputTable")

更多信息

运行机制 (Runtime)
modules.filters 模块帮助中的 GdimAppDataSelector。
API 参考 - modules 包
完整类定义与参数说明（readers）

GdimAppProjectInfoReader

模块简介与适用场景

GdimAppProjectInfoReader 读取 GDIM「项目信息」应用（Project Information APP）数据。
典型适用场景：报表/成果图生成前读取工程元数据；获取坐标系供坐标转换或统一基准。

端口说明

输入端口 - InputToken：鉴权与项目定位信息 (token, proj_id, host)；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取
输出端口 - OutputProjectInfo：项目信息（ResultModel，字段会根据 GDIM 项目信息动态生成） - OutputCoordinateSystem：项目坐标系（CoordinateSystem）

快速上手示例：读取项目信息与坐标系

from gdisdk.modules.readers import GdimAppProjectInfoReader

reader = GdimAppProjectInfoReader(mname="ReadProjectInfo")
reader.InputToken = ("你的GDIM Token", "12345", None)

reader.execute()
project_info = reader.OutputProjectInfo.data
coord = reader.OutputCoordinateSystem.data

参数说明

GdimAppProjectInfoReader 参数一览
参数名	类型	默认值	说明
`token / proj_id / host`	`str \| int \| None / int \| None / str \| None`	`None`	鉴权与项目定位信息。若未在模块中显式传入，模块会优先从 `pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host` 中获取；也可以通过 `InputToken` 端口传入 `(token, proj_id, host)`。
`gdim`	`bool`	`True`	若数据平台为原老版本系统 GBIM，则设置该值为 `False`。

在 pipeline 中的使用方式

from gdisdk.connectors import log_in
from gdisdk.pipeline import PipeLine
from gdisdk.modules.readers import GdimAppProjectInfoReader

pipe = PipeLine(app_name="ReadProjectInfo", app_title="读取项目信息示例")
pipe.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_info = GdimAppProjectInfoReader("ReadInfo")
pipe.add_module(read_info)

result = pipeline.run()
info = read_info.OutputProjectInfo.data
coord = read_info.OutputCoordinateSystem.data

更多信息

GdimTerrainDataReader

模块简介与适用场景

GdimTerrainDataReader 从 GDIM「地形数据管理」应用中读取地形点，输出含 x_coordinate、y_coordinate、z_coordinate 的 TableData。
支持按全部点、参考点附近、参考线附近、闭合区域内四种方式查询；查询模式与对应参数见后文「查询模式说明」。
典型场景：地形切片（SliceTerrain）、剖面出图前拉取剖面线附近地形点；与 CreatePolyLines 联用，由 InputPolyLines 提供参考线顶点。
前置条件：目标 GDIM 项目须已启用「地形数据管理」应用，且存在至少一个地形数据组；group_name 须与平台中组名一致。
空结果：查询无点时发出 GDIDataQualityWarning 并输出 None；token / group_name 缺失，或 nearest_line 模式下既无 line_points 也未连接 InputPolyLines 时，亦输出 None 而不抛错。

端口说明

输入端口 - InputToken：鉴权与项目定位信息 (token, proj_id, host)。若 Pipeline 已通过 pipeline.update_gdim_state(token=..., proj_id=..., host=...) 配置 gdim_state，模块会从 Pipeline 自动取 token，此时该端口可以不连接。 - InputPolyLines：可选，来自 CreatePolyLines 的多段线顶点表（TableData）。连接后，line_name 选中的那条线会覆盖参数 line_points，供 nearest_line 查询使用。
输出端口 - OutputTable：地形点表（TableData）。列名为 x_coordinate、y_coordinate、z_coordinate；keep_gdim_id=True 时额外保留 gdim_id 列。

快速上手示例：读取指定地形数据组的全部点

from gdisdk.modules.readers import GdimTerrainDataReader

reader = GdimTerrainDataReader(mname="ReadTerrainAll")
reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
reader.group_name = "默认地形组"
reader.query_mode = "all"

reader.execute()
table = reader.OutputTable.data

快速上手示例：沿剖面线查询附近地形点

from gdisdk.modules.gisOperators import CreatePolyLines
from gdisdk.modules.readers import GdimTerrainDataReader

create_lines = CreatePolyLines(mname="CreateSectionLine")
create_lines.define_poly_lines_by = "points"
create_lines.poly_lines = [
    {"name": "剖面1", "x_coordinate": 100.0, "y_coordinate": 50.0, "z_coordinate": 10.0},
    {"name": "剖面1", "x_coordinate": 200.0, "y_coordinate": 80.0, "z_coordinate": 12.0},
]
create_lines.execute()

terrain_reader = GdimTerrainDataReader(mname="TerrainNearLine")
terrain_reader.InputToken = ("你的GDIM Token", "你的GDIM项目ID", None)
terrain_reader.group_name = "默认地形组"
terrain_reader.query_mode = "nearest_line"
terrain_reader.line_name = "剖面1"   # 与 InputPolyLines 中的 name 列对应
terrain_reader.limit = 2000
terrain_reader.InputPolyLines = create_lines.OutputPolyLines.data

terrain_reader.execute()
terrain_table = terrain_reader.OutputTable.data

参数说明

GdimTerrainDataReader 参数一览
参数名	类型	默认值	说明
`group_name`	`str \| None`	`None`	地形数据组名称（与 GDIM 地形数据管理器中显示的组名一致）。模块会自动解析为组 ID；为 `None` 时不查询并输出 `None`。
`query_mode`	`Literal["all", "nearest_point", "nearest_line", "region"]`	`"all"`	查询策略，详见「查询模式说明」。
`ref_point`	`tuple[float, float, float] \| None`	`None`	`nearest_point` 模式的参考坐标 `(x, y, z)`；未设置时执行会抛出 `ValueError`。
`line_points`	`list[tuple[float, float, float]] \| None`	`None`	`nearest_line` 模式的参考线顶点列表 `[(x, y, z), ...]`。若 `InputPolyLines` 已连接，所选线的顶点会覆盖本参数。
`line_name`	`str \| int`	`0`	配合 `InputPolyLines` 选择参考线：`str` 按 `name` 列匹配；`int` 按去重后的线名列表索引选取（从 0 开始）。
`polygon`	`list[tuple[float, float, float]] \| None`	`None`	`region` 模式的闭合多边形顶点 `[(x, y, z), ...]`；API 会自动闭合首尾，边界上的点不计入结果。
`limit`	`int`	`10`	`nearest_point` / `nearest_line` 返回的最近点数量上限；`all` 与 `region` 模式忽略。
`keep_gdim_id`	`bool`	`False`	是否保留 GDIM 点 ID 为 `gdim_id` 列；`False` 时丢弃原始 `id` 列。
`token / proj_id / host`	`str \| None` 等	`None`	鉴权与平台地址。可在构造函数传入；若未传则由 `pipeline.gdim_state` 或 `InputToken` 提供。注意：若在构造函数中设置了 proj_id``（赋给 ``self.proj_id），其优先级高于 `InputToken` 与 Pipeline 上的 `proj_id`。

查询模式说明

query_mode 与必填参数
`query_mode`	含义	必填参数	`limit` 是否生效
`all`	读取组内全部地形点	`group_name`	否
`nearest_point`	距参考点最近的前 N 个点	`group_name`、`ref_point`	是
`nearest_line`	距参考线最近的前 N 个点	`group_name`，以及 `line_points` 或已连接的 `InputPolyLines`	是
`region`	闭合多边形区域内的点（不含边界）	`group_name`、`polygon`	否

Note

InputPolyLines 须含 name、x_coordinate、y_coordinate、z_coordinate 列（与 CreatePolyLines 输出一致）；表为空或 line_name 无法匹配时会抛出 ValueError。
group_name 在项目中不存在时会抛出 ValueError，错误信息会列出当前可用组名。
GDIM 界面上 query_mode 切换时，update_ui_schema 会联动显示/隐藏 ref_point、line_points、polygon、limit、line_name 等字段。

在 pipeline 中的使用方式

from gdisdk.connectors import log_in
from gdisdk.pipeline import PipeLine
from gdisdk.modules.gisOperators import CreatePolyLines
from gdisdk.modules.readers import GdimTerrainDataReader

pipe = PipeLine(app_name="TerrainSliceDemo", app_title="地形切片示例")
pipe.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

create_lines = CreatePolyLines("CreatePolyLines")
terrain_reader = GdimTerrainDataReader("TerrainReader")
terrain_reader.group_name = "默认地形组"
terrain_reader.query_mode = "nearest_line"
terrain_reader.limit = 2000

links = create_lines.OutputPolyLines >> terrain_reader.InputPolyLines
pipe.add_links(links)
pipe.add_module(create_lines)
pipe.add_module(terrain_reader)

result = pipe.run()
terrain_table = terrain_reader.OutputTable.data

更多信息

modules.gisOperators 模块帮助中的 CreatePolyLines``（``InputPolyLines 来源）。
modules.geoDataProcess 模块帮助中的 ``SliceTerrain``（地形切剖）。
API 参考 - modules 包
完整类定义与参数说明（readers）