Hi all, I’d like to share a follow-up improvement to the `read_tsfile` table-valued function introduced previously:
https://github.com/apache/iotdb/pull/18146 This PR adds an optional `DEVICE_METADATA_INFO_SWAP_THRESHOLD` parameter to `read_tsfile`. It controls the upper size limit of flush run files used when swapping device metadata during external TsFile queries. The default value is `8 MiB`. Users can tune it for their workload when querying external TsFiles with large or numerous device metadata entries. Example usage: ```sql -- Use the default 8 MiB threshold SELECT * FROM read_tsfile( PATHS => '/path/to/file.tsfile' ); -- Use a custom 4 MiB threshold SELECT * FROM read_tsfile( PATHS => '/path/to/file.tsfile', DEVICE_METADATA_INFO_SWAP_THRESHOLD => 4194304 ); ``` The parameter accepts an `INT64` value in bytes. Non-positive values fall back to the default `8 MiB` threshold. This option provides more control over the device metadata swapping behavior for external TsFile queries, especially for workloads with different memory and file-size requirements. Feedback and suggestions are welcome. 大家好， 我想分享一下此前 `read_tsfile` 表值函数的一个后续改进： https://github.com/apache/iotdb/pull/18146 该 PR 为 `read_tsfile` 新增了一个可选参数 `DEVICE_METADATA_INFO_SWAP_THRESHOLD`，用于控制查询外部 TsFile 时，设备元数据换出过程中生成的 flush run 文件大小上限。 该参数默认值为 `8 MiB`。当查询包含大量设备元数据的大型外部 TsFile 时，用户可以根据实际工作负载进行调整。 使用示例： ```sql -- 使用默认的 8 MiB 阈值 SELECT * FROM read_tsfile( PATHS => '/path/to/file.tsfile' ); -- 使用自定义的 4 MiB 阈值 SELECT * FROM read_tsfile( PATHS => '/path/to/file.tsfile', DEVICE_METADATA_INFO_SWAP_THRESHOLD => 4194304 ); ``` 该参数接受以字节为单位的 `INT64` 值。非正数会自动回退为默认的 `8 MiB` 阈值。 该选项为外部 TsFile 查询中的设备元数据换出行为提供了更细粒度的控制，尤其适用于内存和文件大小需求不同的工作负载。 欢迎大家提出反馈和建议。 Best regards, Wenwei Shu wenwei shu <[email protected]> 于2026年7月2日周四 09:49写道： > Hi all, I’d like to share a new feature introduced by PR #17951: > https://github.com/apache/iotdb/pull/17951 > This PR adds a new table-valued function, read_tsfile, which allows IoTDB > to query external TsFiles that are not managed by IoTDB. With this feature, > users can directly analyze standalone TsFile data through IoTDB’s table SQL > engine, without importing the files into an IoTDB data region first. > Example usage: > SELECT > time > , tag1, tag2, s1, s2 > FROM > read_tsfile( > PATHS > => > '/path/to/a.tsfile,/path/to/b.tsfile' > , > TABLE_NAME > => > 'table1' > ) > WHERE > tag1 > = > 'tag1_1' > ORDER BY > time > ; > It also supports querying directories: > SELECT > * > FROM > read_tsfile( > PATHS > => > '/path/to/external_tsfiles' > , > TABLE_NAME > => > 'table1' > ); > Main capabilities include: - Query one or more external TsFiles via table > SQL. - Recursively scan .tsfile files under directory inputs. - Infer or > specify the target table name. - Merge compatible schemas across multiple > TsFiles. - Support normal SQL operations such as projection, filtering, > aggregation, grouping, and joins. This feature is useful for scenarios such > as offline TsFile analysis, migration verification, troubleshooting, backup > inspection, and ad-hoc exploration of TsFile data outside an IoTDB cluster. > Feedback, suggestions, and follow-up improvements are welcome. 大家好， 我想分享一个在 > PR #17951 中引入的新功能： https://github.com/apache/iotdb/pull/17951 该 PR > 新增了一个表值函数 read_tsfile，使 IoTDB 可以查询不受 IoTDB 管理的外部 TsFile。通过这个功能，用户可以直接使用 > IoTDB 的表模型 SQL 引擎分析独立的 TsFile 数据，而无需先将这些文件导入到 IoTDB 的数据区域中。 使用示例： > SELECT > time > , tag1, tag2, s1, s2 > FROM > read_tsfile( > PATHS > => > '/path/to/a.tsfile,/path/to/b.tsfile' > , > TABLE_NAME > => > 'table1' > ) > WHERE > tag1 > = > 'tag1_1' > ORDER BY > time > ; > 它也支持查询目录： > SELECT > * > FROM > read_tsfile( > PATHS > => > '/path/to/external_tsfiles' > , > TABLE_NAME > => > 'table1' > ); > 主要能力包括： - 通过表模型 SQL 查询一个或多个外部 TsFile。 - 对目录输入递归扫描其中的 .tsfile 文件。 - > 支持推断或显式指定目标表名。 - 支持合并多个 TsFile 中兼容的 schema。 - 支持常规 SQL 操作，例如投影、过滤、聚合、分组和 > Join。 该功能适用于离线 TsFile 分析、迁移验证、问题排查、备份检查，以及对 IoTDB 集群之外的 TsFile 数据进行临时探索等场景。 > 欢迎大家提出反馈、建议以及后续改进意见。 Best regards, Wenwei Shu >
