# Iceberg表服务函数
#### iceberg_expire_snapshots
**描述**：Iceberg每个commit都会生成一个新快照，同时保留旧数据和元数据，以便进行快照隔离和time travel。expire snapshots可以用来清理不再需要的旧快照以及仅被不需要快照包含的数据文件，以提高查询、成本效率。
**注意** **事项**：
- 要明确旧快照的清理、保留策略。执行旧快照清理后，被删除的旧快照数据将无法再通过常规查询访问，如果有正在运行的查询依赖于即将过期的快照数据，可能会导致查询失败或结果不准确。
- 执行expire snapshots，retain_last、older_than、snapshot_ids可能会出现条件互相冲突的场景，iceberg不是严格按照传入条件处理的，会尽可能多地保留snapshots。
**语法**：
```
iceberg_expire_snapshots('schema.table','older_than')
iceberg_expire_snapshots('schema.table','older_than', retain_last, 'snapshot_ids')
```
**入参说明**：
| **名称**       | **类型**    | **默认值** | **是否必填** | **说明**                                                                                                                               |
|:---|:---|:---|:---|:---|
| table        | string    | 无       | 是        | 要操作的表                                                                                                                                |
| older_than   | timestamp | 5天前     | 是        | 超过该时限的快照将被删除 注意：需要输入确定具体时区，避免误解。可以在输入时指定，或者通过set timezone=xxx指定。 |
| retain_last  | int       | 1       | 否        | 保留多少个snapshots。                                                                                                                      |
| snapshot_ids | string    | 无       | 否        | 以分号（;）分隔, 可以传入多个snapshot_id。                                                                                                         |
   
**返回值**：
| 名称                                  | 说明                       |
|:---|:---|
| deleted_data_files_count            | 被删除的数据文件数量。              |
| deleted_position_delete_files_count | 被删除的position delete文件数量。 |
| deleted_equality_delete_files_count | 被删除的equality delete文件数量。 |
| deleted_manifest_files_count        | 被删除的清单文件数量。              |
| deleted_manifest_lists_count        | 被删除的快照文件数量。              |
| deleted_statistics_files_count      | 被删除的统计文件数量。              |
   
#### iceberg_rewrite_manifests
**描述**：Iceberg表跟踪每个数据文件，数据文件越多，存储在快照文件中的元数据就越多，rewrite manifests可以重写表的清单，优化扫描规划。
注意事项：该操作会生成新的清单文件，可能影响正在进行的查询和写入操作，导致元数据冲突，应避免与其他操作并发执行。
**语法**：
```
iceberg_rewrite_manifests(table)
iceberg_rewrite_manifests(table, options)
```
**入参说明**：
| **名称**  | **类型** | **默认值** | **是否必填** | **说明**                     |
|:---|:---|:---|:---|:---|
| table   | string | 无       | 是        | 要操作的表。                     |
| options | array  | 无       | 否        | 操作功能选项。格式样例： '{spec_id=2}' |
   
options支持如下选项：
| **名称**  | **类型** | **说明**                                                    |
|:---|:---|:---|
| spec_id | int32  | 仅重写指定spec_id的manifest文件。 有效值可查询iceberg_partition_specs获得。 |
   
**返回值**：
| 名称                        | 说明          |
|:---|:---|
| rewritten_manifests_count | 被重写的清单文件数量。 |
| added_manifests_count     | 新增的清单文件数量。  |
   
#### iceberg_remove_orphanfiles
**描述**：对于未被任何Iceberg元数据文件引用的文件，我们称之为孤立文件，这类文件可能由失败的事务、并发操作未能成功提交、旧快照清理失败、元数据清理失败等原因造成，通常可以删除。
**注意事项**：确保无并发写操作，删除过程中，如果有运行中的写入任务，可能会误删正在生成的文件（未提交的临时文件）。
**语法**：
```
iceberg_remove_orphanfiles('schema.table')
iceberg_remove_orphanfiles('schema.table', 'older_than', 'location')
```
**入参说明**：
| **名称**     | **类型**    | **默认值** | **是否必填** | **说明**                 |
|:---|:---|:---|:---|:---|
| table      | string    | 无       | 是        | 要操作的表                  |
| older_than | timestamp | 三天前     | 否        | 早于older_than的孤立文件将被删除。 |
| location   | string    | 表根目录    | 否        | location下的孤立文件将被删除。    |
   
**返回值**：
| 名称                   | 说明             |
|:---|:---|
| orphan_file_location | 被认定为孤立文件的文件路径。 |
   
#### iceberg_add_files
**描述：**将目标文件夹下的所有文件添加到iceberg表中。
该语法会递归扫描目标文件夹下的所有文件，并添加到iceberg表中。
所有文件必须满足：
- 必须为parquet文件格式。
- parquet文件中的列名、列类型、列个数（包括分区列）必须与目标表一致。
- 单个parquet文件中的所有数据必须隶属于同一个分区。
**语法**：
```
iceberg_add_files(table,foldername,iscopy)
```
**入参说明**：
- table：regclass类型，表名。
- foldername：text类型，文件夹路径列表，支持多个路径，以逗号分隔。
- iscopy：bool类型，是否拷贝。
**返回值：**bool，是否执行成功。
#### iceberg_show_snapshots
**描述：**查询指定Iceberg表的快照信息。
**语法**：
```
iceberg_show_snapshots(table)
```
**入参说明**：table：regclass类型，表名。
**返回值：**
- sequence_number：int64类型，快照序号。
- snapshot_id：int64类型，快照ID。
- create_time：timestamptz类型，快照创建时间。
- parent_id：int64类型，快照的父节点，如果为0，表示无父节点。
- operation：text类型，本次快照的操作类型。
- manifestlist：text类型，快照对应的manifest list路径。
- summary：text类型，快照统计信息。
 
#### iceberg_manifests
**描述：**查询指定Iceberg表的所有清单文件。
**语法**：
```
iceberg_manifests(table)
```
**入参说明**：
| **名称** | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table  | string | 无       | 是        | 要查询的表。 |
   
**返回值**：
| 名称                          | 说明                                                                                                                                         |
|:---|:---|
| content                     | int32类型，manifest中文件内容类型；0表示数据文件（DATA），1表示删除文件（DELETES）。                                                                                    |
| path                        | text类型，manifest文件在存储系统中的完整路径。                                                                                                              |
| length                      | int64类型，manifest文件的字节大小。                                                                                                                   |
| partition_spec_id           | int32类型，该manifest所使用的分区规范ID。                                                                                                               |
| added_snapshot_id           | int64类型，创建此manifest的快照ID。                                                                                                                  |
| added_data_files_count      | int32类型，此manifest中新增的数据文件数量。                                                                                                               |
| existing_data_files_count   | int32类型，此manifest中已存在的数据文件数量。                                                                                                              |
| deleted_data_files_count    | int32类型，此manifest中被标记为删除的数据文件数量。                                                                                                           |
| added_delete_files_count    | int32类型，此manifest中新增的删除文件数量。                                                                                                               |
| existing_delete_files_count | int32类型，此manifest中已存在的删除文件数量。                                                                                                              |
| deleted_delete_files_count  | int32类型，此manifest中被标记为删除的删除文件数量。                                                                                                           |
| partition_summaries         | text类型，以JSON数组形式存储的分区统计摘要，每个元素对应一个分区字段，包含contains_null（是否含null）、contains_nan（是否含NaN，仅浮点类型）、lower_bound和upper_bound（该分区字段在此manifest中的值域范围）。 |
   
#### iceberg_manifest_entries
**描述：**查询指定Iceberg表的所有manifest条目（entries）信息，每个条目反映一个数据文件在特定快照中的状态。
**语法**：
```
iceberg_manifest_entries(table)
```
**入参说明**：
| **名称** | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table  | string | 无       | 是        | 要查询的表。 |
   
**返回值**：
| 名称                   | 说明                                                              |
|:---|:---|
| status               | int32类型，文件状态；0表示已存在（EXISTING），1表示新增（ADDED），2表示已删除（DELETED）。     |
| snapshot_id          | int64类型，该条目所属的快照ID。                                             |
| sequence_number      | int64类型，文件序列号，用于确定写入顺序。                                         |
| file_sequence_number | int64类型，标识该文件在单个快照内的添加顺序。                                       |
| data_file            | text类型，包含该数据文件的完整元数据（如路径、格式、分区、大小、记录数及列级统计信息等）。                 |
| readable_metrics     | text类型，以可读形式呈现从data_file中提取的列级扩展统计信息（如最小值、最大值、空值计数等），便于人工检查和调试。 |
   
#### iceberg_partitions
**描述：**查询指定Iceberg表的分区统计信息，汇总每个分区中所有数据文件的聚合指标。
**语法**：
```
iceberg_partitions(table, small_file_threshold)
```
**入参说明**：
| **名称**               | **类型** | **默认值** | **是否必填** | **说明**  |
|:---|:---|:---|:---|:---|
| table                | string | 无       | 是        | 要查询的表。  |
| small_file_threshold | int32  | 128（MB） | 否        | 小文件的阈值。 |
   
**返回值**：
| 名称                            | 说明                                                     |
|:---|:---|
| partition                     | text类型，分区字段的具体值（结构与表的分区schema一致）。                      |
| spec_id                       | int32类型，该分区所使用的分区规范ID。                                 |
| record_count                  | int64类型，该分区内所有活跃数据文件包含的总记录数。                           |
| file_count                    | int32类型，该分区内活跃数据文件的总数。                                 |
| total_data_file_size_in_bytes | int64类型，该分区内所有活跃数据文件的总大小（字节）。                          |
| position_delete_record_count  | int64类型，该分区内由位置删除文件（positional delete files）标记的删除记录总数。 |
| position_delete_file_count    | int32类型，该分区内位置删除文件的数量。                                 |
| equality_delete_record_count  | int64类型，该分区内由等值删除文件（equality delete files）标记的删除记录总数。   |
| equality_delete_file_count    | int32类型，该分区内等值删除文件的数量。                                 |
| last_updated_at               | timestamptz类型，该分区最近一次被更新的时间（对应快照的创建时间）。                |
| updated_snapshot_id           | int64类型，最近一次更新该分区的快照ID。                                |
| small_file_count              | int64类型，小文件的数量。                                        |
   
#### iceberg_partition_specs
**描述：**查询指定Iceberg表的所有历史版本的分区键定义集合。
**语法**：
```
iceberg_partition_specs(table)
```
**入参说明**：
| **名称** | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table  | string | 无       | 是        | 要查询的表。 |
   
**返回值**：
| 名称        | 说明                                                       |
|:---|:---|
| spec_id   | int32类型，分区键定义的版本号ID。                                     |
| field_id  | int32类型，分区键的ID。                                          |
| name      | text类型，分区键的名字。                                           |
| transform | text类型，分区键的表达式的文本描述。                                     |
| source_id | int32类型，分区键的表达式所引用的表列ID。该值对应iceberg_schemas中的field_id字段。 |
   
#### iceberg_schemas
**描述：**查询指定Iceberg表的所有历史版本的表定义集合。
**语法**：
```
iceberg_schemas(table)
```
**入参说明**：
| **名称** | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table  | string | 无       | 是        | 要查询的表。 |
   
**返回值**：
| 名称        | 说明                 |
|:---|:---|
| schema_id | int32类型，表定义的版本号ID。 |
| field_id  | int32类型，列ID。       |
| name      | text类型，列的名字。       |
| type      | text类型，列的类型。       |
   
#### iceberg_history
**描述：**查询指定Iceberg表的历史版本信息。
**语法**：
```
iceberg_history(table)
```
**入参说明**：
| **名称** | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table  | string | 无       | 是        | 要查询的表。 |
   
**返回值**：
| 名称                  | 说明                                 |
|:---|:---|
| made_current_at     | timestamptz类型，快照创建时间。              |
| snapshot_id         | int64类型，快照ID。                      |
| parent_id           | int64类型，该快照的父快照id。                 |
| is_current_ancestor | bool类型，snapshot_id是否是当前表最新快照的祖先快照。 |
   
#### iceberg_metadata_log_entries
**描述：**查询指定Iceberg表的metadata文件信息。
**语法**：
```
iceberg_metadata_log_entries(table)
```
**入参说明**：
| **名称** | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table  | string | 无       | 是        | 要查询的表。 |
   
**返回值**：
| 名称                     | 说明                                              |
|:---|:---|
| timestamp              | timestamptz类型，metadata.json文件的生成时间。             |
| file                   | string类型，metadata.json文件的路径。                    |
| latest_snapshot_id     | int64类型，metadata.json文件创建时，对应的最新快照。             |
| latest_schema_id       | int64类型，metadata.json文件创建时，表的最新表结构（Schema）id。   |
| latest_sequence_number | int64类型，metadata.json文件创建时，表的最新sequence_number。 |
   
#### iceberg_files
**描述：**查询指定Iceberg表的所有数据文件和删除文件信息。
**语法**：
```
iceberg_files(table)
```
**入参说明**：
| **名称** | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table  | string | 无       | 是        | 要查询的表。 |
   
**返回值**：
| 名称                 | 说明                   |
|:---|:---|
| content            | int32类型，文件类型。        |
| file_path          | string类型，文件路径。       |
| file_format        | string类型，文件存储格式。     |
| spec_id            | int64类型，文件所属spec_id。 |
| record_count       | int64类型，文件内的数据行数。    |
| file_size_in_bytes | int64类型，文件大小。        |
| column_sizes       | string类型，各列的存储大小。    |
| value_counts       | string类型，各列的非空值数量。   |
| null_value_counts  | string类型，各列的空值数量。    |
| nan_value_counts   | string类型，各列的非数值数量。   |
| lower_bounds       | string类型，各列值的下界。     |
| upper_bounds       | string类型，各列值的上界。     |
   
#### iceberg_position_delete_files
**描述：**查询指定Iceberg表的位置删除文件信息。
**语法**：
```
iceberg_position_delete_files(table)
```
**入参说明**：
| **名称** | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table  | string | 无       | 是        | 要查询的表。 |
   
**返回值**：
| 名称               | 说明                       |
|:---|:---|
| file_path        | string类型，与删除文件关联的数据文件路径。 |
| pos              | int64类型，对应文件的行号。         |
| partition        | string类型，分区名。            |
| spec_id          | int64类型，分区spec_id。       |
| delete_file_path | string类型，删除文件的路径。        |
   
#### iceberg_refs
**描述：**查询指定Iceberg表的所有branch/tag。
**语法**：
```
iceberg_refs(table)
```
**入参说明**：
| **名称** | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table  | string | 无       | 是        | 要查询的表。 |
   
**返回值**：
| 名称                      | 说明                      |
|:---|:---|
| name                    | string类型，名称。            |
| type                    | string类型，branch或tag。    |
| snapshot_id             | int64类型，对应的snapshot id。 |
| max_reference_age_in_ms | int64类型，保留时间，单位ms。      |
| min_snapshots_to_keep   | int64类型，保留快照的最小数量。      |
| max_snapshot_age_in_ms  | int64类型，快照的最大保留时间，单位ms。 |
   
#### iceberg_register_table
**描述：** 将已存在的**metadata.json**文件注册到当前Catalog中。
**语法**：
```
select * from iceberg_register_table(table, file_path)
```
**入参说明**：
| **名称**    | **类型** | **默认值** | **是否必填** | **说明**                  |
|:---|:---|:---|:---|:---|
| table     | string | 无       | 是        | 注册后的表名。                 |
| file_path | string | 无       | 是        | **metadata.json**对应的路径。 |
   
**返回值**：
| 名称                     | 说明                        |
|:---|:---|
| snapshot_id            | int64类型，新注册表的Snapshot ID。 |
| record_count           | int64类型，新注册表的总行数。         |
| total_data_files_count | int64类型，新注册表的数据文件数量。      |
   
#### iceberg_rollback_to_snapshot
**描述：**回滚表主分支到指定快照。
**语法**：
```
select * from iceberg_rollback_to_snapshot(table, snapshot_id)
```
**入参说明**：
| **名称**      | **类型** | **默认值** | **是否必填** | **说明**       |
|:---|:---|:---|:---|:---|
| table       | string | 无       | 是        | 表名称。         |
| snapshot_id | int64  | 无       | 是        | 指定要回滚到的快照ID。 |
   
**返回值**：
| 名称                   | 说明                        |
|:---|:---|
| previous_snapshot_id | int64类型，回滚前表的Snapshot ID。 |
| current_snapshot_id  | int64类型，回滚后表的Snapshot ID。 |
   
#### iceberg_rollback_to_timestamp
**描述：**回滚表主分支到指定时间戳。
**语法**：
```
select * from iceberg_rollback_to_timestamp(table, timestamp)
```
**入参说明**：
| **名称**    | **类型**      | **默认值** | **是否必填** | **说明**      |
|:---|:---|:---|:---|:---|
| table     | string      | 无       | 是        | 表名称。        |
| timestamp | timestamptz | 无       | 是        | 指定要回滚到的时间戳。 |
   
**返回值**：
| 名称                   | 说明                        |
|:---|:---|
| previous_snapshot_id | int64类型，回滚前表的Snapshot ID。 |
| current_snapshot_id  | int64类型，回滚后表的Snapshot ID。 |
   
#### iceberg_set_current_snapshot
**描述：**设置主分支的当前快照。
**语法**：
```
select * from iceberg_set_current_snapshot(table, snapshot_id)
```
**入参说明**：
| **名称**      | **类型** | **默认值** | **是否必填** | **说明**  |
|:---|:---|:---|:---|:---|
| table       | string | 无       | 是        | 表名。     |
| snapshot_id | int64  | 无       | 是        | 目标快照ID。 |
   
**返回值**：
| 名称                   | 说明                          |
|:---|:---|
| previous_snapshot_id | int64类型，设置快照前表的Snapshot ID。 |
| current_snapshot_id  | int64类型，设置快照后表的Snapshot ID。 |
   
#### iceberg_cherrypick_snapshot
**描述：**提取快照到主分支并创建新快照，且提取的快照不能是主分支的祖先节点。
**语法**：
```
select * from iceberg_cherrypick_snapshot(table, snapshot_id)
```
**入参说明**：
| **名称**      | **类型** | **默认值** | **是否必填** | **说明**    |
|:---|:---|:---|:---|:---|
| table       | string | 无       | 是        | 表名称。      |
| snapshot_id | int64  | 无       | 是        | 要提取的快照ID。 |
   
**返回值**：
| 名称                   | 说明                          |
|:---|:---|
| previous_snapshot_id | int64类型，提取快照前表的Snapshot ID。 |
| current_snapshot_id  | int64类型，提取快照后表的Snapshot ID。 |
   
#### iceberg_fast_forward
**描述：**快进分支，即将一个分支的当前快照快进到另一个分支的最新快照。
**语法**：
```
select * from iceberg_fast_forward(table, from_branch, to_branch)
```
**入参说明**：
| **名称**      | **类型** | **默认值** | **是否必填** | **说明** |
|:---|:---|:---|:---|:---|
| table       | string | 无       | 是        | 表名称。   |
| from_branch | string | 无       | 是        | 当前分支。  |
| to_branch   | string | 无       | 是        | 目标分支。  |
   
**返回值**：
| 名称             | 说明                          |
|:---|:---|
| branch_updated | string类型，更新的分支名称。           |
| previous_ref   | int64类型，快照快进前表的Snapshot ID。 |
| updated_ref    | int64类型，快照快进后表的Snapshot ID。 |