策略

Polaris 策略框架使组织能够集中定义、管理和强制执行涵盖目录中所有数据资源的细粒度治理、生命周期和运维规则。

通过策略 API，你可以：

创建和管理策略
将策略附加到特定资源（catalog、namespace、table 或 view）
检查任意给定资源所适用的策略

什么是策略？

Apache Polaris 中的策略是一种结构化实体，用于在预定义条件下，规定对指定资源执行操作的规则。每个策略包含：

名称（Name）：命名空间内的唯一标识符
类型（Type）：决定策略内容的语义和预期格式
描述（Description）：说明策略的用途
内容（Content）：包含定义策略行为的实际规则
版本（Version）：自动跟踪的修订号
可继承（Inheritable）：该策略是否可被子资源继承，由其类型决定

策略类型

Polaris 支持多种预定义的系统策略类型（以 system. 为前缀）：

策略类型	用途	JSON Schema	适用范围
`system.data-compaction`	定义数据文件压缩操作的规则	`data-compaction/2025-02-03.json`	Iceberg table、namespace、catalog
`system.metadata-compaction`	定义元数据文件压缩操作的规则	`metadata-compaction/2025-02-03.json`	Iceberg table、namespace、catalog
`system.orphan-file-removal`	定义移除孤立文件的规则	`orphan-file-removal/2025-02-03.json`	Iceberg table、namespace、catalog
`system.snapshot-expiry`	定义快照过期的规则	`snapshot-expiry/2025-02-03.json`	Iceberg table、namespace、catalog

更多预定义系统策略类型的支持以及自定义策略类型的定义正在开发中。详情请参阅路线图。

策略继承

Polaris 中的实体层级结构如下：

            Catalog
               |
           Namespace
               |
   +-----------+----------+
   |           |          |
Iceberg     Iceberg     Generic
 Table       View        Table

策略可以附加在任意层级，继承关系从目录向下依次传递到命名空间，再到表和视图。

策略可分为可继承与不可继承两类：

可继承策略：适用于目标资源及其所有适用的子资源
不可继承策略：仅适用于指定的目标资源

继承遵循覆盖机制：

❗重要提示

由于覆盖会完全替换更高层级上的同类型策略，因此某一给定类型的策略只能附加到（进而影响）一个资源上。

使用策略

创建策略

创建策略时，需要提供名称、类型，还可以选择性地提供描述和内容：

POST /polaris/v1/{prefix}/namespaces/{namespace}/policies
{
  "name": "compaction-policy",
  "type": "system.data-compaction",
  "description": "Policy for optimizing table storage",
  "content": "{\"version\": \"2025-02-03\", \"enable\": true, \"config\": {\"target_file_size_bytes\": 134217728}}"
}

策略内容会根据其类型所对应的 schema 进行校验。以下是几个策略内容的示例：

数据压缩策略（Data Compaction Policy）

{
  "version": "2025-02-03",
  "enable": true,
  "config": {
    "target_file_size_bytes": 134217728,
    "compaction_strategy": "bin-pack",
    "max-concurrent-file-group-rewrites": 5
  }
}

孤儿文件清理策略

{
  "version": "2025-02-03",
  "enable": true,
  "max_orphan_file_age_in_days": 30,
  "locations": ["s3://my-bucket/my-table-location"],
  "config": {
    "prefix_mismatch_mode": "ignore"
  }
}

将策略附加到资源

策略可以附加到不同的资源层级：

目录层级：适用于整个目录
命名空间层级：适用于特定的命名空间
表类层级：适用于单个表或视图

将策略附加到表的示例：

PUT /polaris/v1/{prefix}/namespaces/{namespace}/policies/{policy-name}/mappings
{
  "target": {
    "type": "table-like",
    "path": ["NS1", "NS2", "test_table_1"]
  }
}

对于可继承的策略，一个给定类型的策略只能附加到一个资源上。对于不可继承的策略，同一类型的多个策略都可以附加到资源上。

获取适用策略

只要用户对某个资源（例如表、命名空间或目录）具有读取权限，就可以查看该资源上适用的策略。

以下是查找适用于特定资源的所有策略（包括继承的策略）的示例：

GET /polaris/v1/catalog/applicable-policies?namespace=finance%1Fquarterly&target-name=transactions

示例响应：

{
  "policies": [
    {
      "name": "snapshot-expiry-policy",
      "type": "system.snapshot-expiry",
      "appliedAt": "namespace",
      "content": {
        "version": "2025-02-03",
        "enable": true,
        "config": {
          "min_snapshot_to_keep": 1,
          "max_snapshot_age_days": 2,
          "max_ref_age_days": 3
        }
      }
    },
    {
      "name": "compaction-policy",
      "type": "system.data-compaction",
      "appliedAt": "catalog",
      "content": {
        "version": "2025-02-03",
        "enable": true,
        "config": {
          "target_file_size_bytes": 134217728
        }
      }
    }
  ]
}

API 参考

如需完整且最新的 API 规范，请参阅 policy-api.yaml。

策略

策略