KnowForgeDataFusion CLI
CLI 专用函数
师成· 更新于 2026-09-28· 阅读 26 分钟· 0 次阅读登录后可跨设备保存划线和私人笔记登录
CLI 专用函数
datafusion-cli 内置了一些默认未包含在 DataFusion SQL 引擎中的函数。这些函数如下：
parquet_metadata
parquet_metadata 表函数可用于查看 parquet 文件的详细元数据，例如统计信息、大小及其他信息。这有助于理解 parquet 文件的结构。
例如，要查看 hits.parquet 文件中 "WatchID" 列的相关信息，可以使用：
SELECT path_in_schema, row_group_id, row_group_num_rows, stats_min, stats_max, total_compressed_size
FROM parquet_metadata('hits.parquet')
WHERE path_in_schema = '"WatchID"'
LIMIT 3;
+----------------+--------------+--------------------+---------------------+---------------------+-----------------------+
| path_in_schema | row_group_id | row_group_num_rows | stats_min | stats_max | total_compressed_size |
+----------------+--------------+--------------------+---------------------+---------------------+-----------------------+
| "WatchID" | 0 | 450560 | 4611687214012840539 | 9223369186199968220 | 3883759 |
| "WatchID" | 1 | 612174 | 4611689135232456464 | 9223371478009085789 | 5176803 |
| "WatchID" | 2 | 344064 | 4611692774829951781 | 9223363791697310021 | 3031680 |
+----------------+--------------+--------------------+---------------------+---------------------+-----------------------+
3 rows in set. Query took 0.053 seconds.返回的表针对文件中的每个行组、每个列块包含以下各列。有关这些字段含义的更多信息，请参阅 Parquet 文档。
| column_name | data_type | 说明 |
|---|---|---|
| filename | Utf8 | 文件名 |
| row_group_id | Int64 | 该列块所属的行组索引 |
| row_group_num_rows | Int64 | 行组中存储的行数 |
| row_group_num_columns | Int64 | 行组中的列总数（所有行组均相同） |
| row_group_bytes | Int64 | 存储该行组所使用的字节数（不包含元数据） |
| column_id | Int64 | 列的 ID |
| file_offset | Int64 | 该列块数据在文件中的起始偏移量 |
| num_values | Int64 | 该列块中的值总数 |
| path_in_schema | Utf8 | 该列块在 schema 中的“路径”（列名） |
| type | Utf8 | 该列块的 Parquet 数据类型 |
| stats_min | Utf8 | 该列块的最小值（若统计信息中已存储），转换为字符串 |
| stats_max | Utf8 | 该列块的最大值（若统计信息中已存储），转换为字符串 |
| stats_null_count | Int64 | 该列块中空值的数量（若统计信息中已存储） |
| stats_distinct_count | Int64 | 该列块中不同值的数量（若统计信息中已存储） |
| stats_min_value | Utf8 | 与 stats_min 相同 |
| stats_max_value | Utf8 | 与 stats_max 相同 |
| compression | Utf8 | 该列块使用的块级压缩算法（例如 SNAPPY） |
| encodings | Utf8 | 该列块使用的所有块级编码（例如 [PLAIN_DICTIONARY, PLAIN, RLE]） |
| index_page_offset | Int64 | page index 在文件中的偏移量（如果有） |
| dictionary_page_offset | Int64 | 字典页在文件中的偏移量（如果有） |
| data_page_offset | Int64 | 第一个数据页在文件中的偏移量（如果有） |
| total_compressed_size | Int64 | 该列块数据经过编码和压缩后的字节数（即文件中实际存储的大小） |
| total_uncompressed_size | Int64 | 该列块数据经过编码后的字节数 |
metadata_cache
metadata_cache 函数用于显示 DataFusion 中 ListingTable 实现所使用的默认文件元数据缓存的相关信息。该缓存用于在扫描包含大量文件的目录时，加快从文件中读取元数据的速度。
例如，在使用 CREATE EXTERNAL TABLE 命令创建表之后：
> create external table hits
stored as parquet
location 's3://clickhouse-public-datasets/hits_compatible/athena_partitioned/';可以通过查询 metadata_cache 函数来检查元数据缓存：
> select * from metadata_cache();
+----------------------------------------------------+---------------------+-----------------+---------------------------------------+---------+---------------------+------+------------------+
| path | file_modified | file_size_bytes | e_tag | version | metadata_size_bytes | hits | extra |
+----------------------------------------------------+---------------------+-----------------+---------------------------------------+---------+---------------------+------+------------------+
| hits_compatible/athena_partitioned/hits_61.parquet | 2022-07-03T15:40:34 | 117270944 | "5db11cad1ca0d80d748fc92c914b010a-6" | NULL | 212949 | 0 | page_index=false |
| hits_compatible/athena_partitioned/hits_32.parquet | 2022-07-03T15:37:17 | 94506004 | "2f7db49a9fe242179590b615b94a39d2-5" | NULL | 278157 | 0 | page_index=false |
| hits_compatible/athena_partitioned/hits_40.parquet | 2022-07-03T15:38:07 | 142508647 | "9e5852b45a469d5a05bf270a286eab8a-8" | NULL | 212917 | 0 | page_index=false |
| hits_compatible/athena_partitioned/hits_93.parquet | 2022-07-03T15:44:07 | 127987774 | "751100bf0dac7d489b9836abf3108b99-7" | NULL | 278318 | 0 | page_index=false |
| . |
+----------------------------------------------------+---------------------+-----------------+---------------------------------------+---------+---------------------+------+------------------+由于 metadata_cache 是一个普通的表函数，你可以像使用表引用一样，在大多数场景中使用它。
例如，要获取缓存条目占用的总空间：
> select sum(metadata_size_bytes) from metadata_cache();
+-------------------------------------------+
| sum(metadata_cache().metadata_size_bytes) |
+-------------------------------------------+
| 22972345 |
+-------------------------------------------+返回表格的各列如下：
| 列名 | 数据类型 | 说明 |
|---|---|---|
| path | Utf8 | 相对于对象存储 / 文件系统根目录的文件路径 |
| file_modified | Timestamp | 文件的最后修改时间 |
| file_size_bytes | UInt64 | 文件大小（字节） |
| e_tag | Utf8 | 文件的实体标签（ETag）（如有） |
| version | Utf8 | 文件的版本信息（如有，适用于支持版本管理的对象存储） |
| metadata_size_bytes | UInt64 | 内存中缓存元数据的大小（非其 thrift 编码形式） |
| hits | UInt64 | 缓存元数据被访问的次数 |
| extra | Utf8 | 关于缓存元数据的额外信息（例如，是否包含页面索引信息） |
statistics_cache
与 metadata_cache 类似，statistics_cache 函数可用于查看 DataFusion 中 ListingTable 实现所使用的文件统计信息缓存的相关信息。要收集统计信息，必须启用配置项 datafusion.execution.collect_statistics。
你可以通过查询 statistics_cache 函数来检查统计信息缓存。例如：
> select * from statistics_cache();
+------------------+---------------------+-----------------+------------------------+---------+-----------------+-------------+--------------------+-----------------------+
| path | file_modified | file_size_bytes | e_tag | version | num_rows | num_columns | table_size_bytes | statistics_size_bytes |
+------------------+---------------------+-----------------+------------------------+---------+-----------------+-------------+--------------------+-----------------------+
| .../hits.parquet | 2022-06-25T22:22:22 | 14779976446 | 0-5e24d1ee16380-370f48 | NULL | Exact(99997497) | 105 | Exact(36445943240) | 0 |
+------------------+---------------------+-----------------+------------------------+---------+-----------------+-------------+--------------------+-----------------------+返回表格的各列如下：
| column_name | data_type | 说明 |
|---|---|---|
| path | Utf8 | 相对于对象存储 / 文件系统根目录的文件路径 |
| file_modified | Timestamp | 文件的最后修改时间 |
| file_size_bytes | UInt64 | 文件大小（字节） |
| e_tag | Utf8 | 文件的实体标签（ETag），如果可用 |
| version | Utf8 | 文件的版本，如果可用（针对支持版本管理的对象存储） |
| num_rows | Utf8 | 表中的行数 |
| num_columns | UInt64 | 表中的列数 |
| table_size_bytes | Utf8 | 表的大小（字节） |
| hits | UInt64 | 访问已缓存的文件统计信息的次数 |
| statistics_size_bytes | UInt64 | 内存中已缓存统计信息的大小 |
list_files_cache
list_files_cache 函数用于显示 DataFusion 中 ListingTable 实现所使用的 ListFilesCache 的相关信息。在创建 ListingTable 时，DataFusion 会列出表所在位置的文件，并将结果缓存到 ListFilesCache 中。随后对同一表的查询可以复用这些缓存信息，而无需重新列出文件。缓存条目按表划分作用域。
你可以通过查询 list_files_cache 函数来查看缓存。例如：
> set datafusion.runtime.list_files_cache_ttl = "30s";
> create external table overturemaps
stored as parquet
location 's3://overturemaps-us-west-2/release/2025-12-17.0/theme=base/type=infrastructure';
0 row(s) fetched.
> select table, path, metadata_size_bytes, expires_in, unnest(metadata_list)['file_size_bytes'] as file_size_bytes, unnest(metadata_list)['e_tag'] as e_tag from list_files_cache() limit 10;
+--------------+-----------------------------------------------------+---------------------+-----------------------------------+-----------------+---------------------------------------+
| table | path | metadata_size_bytes | expires_in | file_size_bytes | e_tag |
+--------------+-----------------------------------------------------+---------------------+-----------------------------------+-----------------+---------------------------------------+
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 999055952 | "35fc8fbe8400960b54c66fbb408c48e8-60" |
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 975592768 | "8a16e10b722681cdc00242564b502965-59" |
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 1082925747 | "24cd13ddb5e0e438952d2499f5dabe06-65" |
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 1008425557 | "37663e31c7c64d4ef355882bcd47e361-61" |
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 1065561905 | "4e7c50d2d1b3c5ed7b82b4898f5ac332-64" |
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 1045655427 | "8fff7e6a72d375eba668727c55d4f103-63" |
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 1086822683 | "b67167d8022d778936c330a52a5f1922-65" |
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 1016732378 | "6d70857a0473ed9ed3fc6e149814168b-61" |
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 991363784 | "c9cafb42fcbb413f851691c895dd7c2b-60" |
| overturemaps | release/2025-12-17.0/theme=base/type=infrastructure | 2750 | 0 days 0 hours 0 mins 25.264 secs | 1032469715 | "7540252d0d67158297a67038a3365e0f-62" |
+--------------+-----------------------------------------------------+---------------------+-----------------------------------+-----------------+---------------------------------------+返回表的列如下：
| column_name | data_type | 描述 |
|---|---|---|
| table | Utf8 | 表名 |
| path | Utf8 | 相对于对象存储 / 文件系统根目录的文件路径 |
| metadata_size_bytes | UInt64 | 内存中缓存元数据的大小（非其 thrift 编码形式） |
| expires_in | Duration(ms) | 文件的最后修改时间 |
| hits | UInt64 | 缓存元数据被访问的次数 |
| metadata_list | List(Struct) | 元数据列表，路径下每个文件对应一条记录 |
metadata_list 中的元数据结构体包含以下字段：
{
"file_path": "release/2025-12-17.0/theme=base/type=infrastructure/part-00000-d556e455-e0c5-4940-b367-daff3287a952-c000.zstd.parquet",
"file_modified": "2025-12-17T22:20:29",
"file_size_bytes": 999055952,
"e_tag": "35fc8fbe8400960b54c66fbb408c48e8-60",
"version": null
}评论
登录后参与评论
正在加载评论…