> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> PuffinMetadata 格式的文档

# PuffinMetadata

<div id="description">
  ## 描述
</div>

一种用于读取 [Apache Iceberg Puffin](https://iceberg.apache.org/puffin-spec/) 文件页脚元数据的特殊输入格式。
它会针对页脚 `BlobMetadata` 列表中的每个 blob 条目输出一行。

`deletion-vector-v1` 是唯一支持的 blob 类型：文件包含任何其他 blob 类型 (例如 `apache-datasketches-theta-v1`) 时将被拒绝。

固定输出列：

* `blob_type` (`String`) - blob 类型，例如 `deletion-vector-v1`
* `snapshot_id` (`Int64`) - blob 的快照 ID
* `sequence_number` (`Int64`) - blob 的序列号
* `fields` (`Array(Int32)`) - 此 blob 适用的字段 ID 列表
* `offset` (`Int64`) - blob 载荷在文件中的偏移量
* `length` (`Int64`) - blob 载荷的长度 (字节)
* `compression_codec` (`String`) - blob 载荷的压缩编解码器 (如有)
* `properties` (`Map(String, String)`) - blob 专有属性

页脚中可选的顶层 `FileMetadata.properties` (例如 `created-by`) 若存在，会进行类型检查，但不会作为列返回。若该键存在，其值必须是一个所有值均为字符串的 JSON 对象 (不接受 null) 。

支持 LZ4 压缩和未压缩的 Puffin 页脚。页脚载荷大小 (以及声明的 LZ4 内容大小) 在适用时受压缩率和绝对上限约束；超出限制的页脚会在内存分配前被拒绝。

<div id="example-usage">
  ## 使用示例
</div>

检查页脚 blob：

```sql theme={null}
SELECT blob_type, snapshot_id, sequence_number, offset, length, compression_codec,
       mapKeys(properties), mapValues(properties)
FROM file(deletes.puffin, PuffinMetadata);
```

与 `Puffin` 格式配合使用，以读取 `deletion-vector-v1` blob 载荷。