Hi wenwei, That would be great for some huge external tsfile datasets!
Best regards, -------------------- Yuan Tian On Fri, Jul 10, 2026 at 11:42 AM wenwei shu <[email protected]> wrote: > 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 > > >
