KnowForge/Apache Polaris 1.7.0 简体中文

命令行接口

师成师成· 更新于 2026-09-29· 阅读 88 分钟· 0 次阅读
登录后可跨设备保存划线和私人笔记登录

命令行接口

为了帮助管理员快速搭建和管理 Polaris 服务器，Polaris 提供了一个用于执行常见任务的简单命令行接口（CLI）。

安装

从 PyPI 安装最新版本：

pip install apache-polaris

进行开发时，运行 make client-setup-env 来设置 Python 客户端环境。

Polaris CLI 的基本语法概述如下：

usage: polaris [-h] [options] COMMAND ...

options:
  -h, --help                     show this help message and exit

Global Options:
  --host HOST                    Polaris server hostname
  --port PORT                    Polaris server port
  --scheme {http,https}          URL scheme for host/port (default: http)
  --base-url BASE_URL            Complete base URL (overrides host/port)
  --catalog-url CATALOG_URL      Base URL for the Iceberg REST Catalog (IRC) API. Use when a proxy or deployment maps a custom path directly to the catalog root (no /api/catalog appended).
  --client-id CLIENT_ID          OAuth client ID
  --client-secret CLIENT_SECRET  OAuth client secret
  --access-token ACCESS_TOKEN    OAuth access token
  --realm REALM                  Polaris realm (default: from server)
  --header HEADER                Context header name (default: Polaris-Realm)
  --profile PROFILE              Polaris profile name
  --proxy PROXY                  Proxy URL
  --debug                        Enable debug mode

COMMAND 必须是以下之一：

  1. catalogs
  2. principals
  3. principal-roles
  4. catalog-roles
  5. namespaces
  6. privileges
  7. profiles
  8. policies
  9. repair
  10. setup
  11. find
  12. tables
  13. repl

每个命令（command）支持若干子命令（subcommand），其中一些子命令后面还会有依次跟在其后的动作（action）。最后是参数（argument），由此构成一次完整的调用。在一次调用末尾的一组具名参数中，顺序通常并不重要。许多调用还需要一个位置参数，其类型即为该命令所对应的类型。同样，这个位置参数相对于具名参数的顺序也不重要。

以下是几个完整的调用示例：

polaris principals list
polaris catalogs delete some_catalog_name
polaris catalogs update --set-property foo=bar some_other_catalog
polaris catalogs update another_catalog --set-property k=v
polaris privileges namespace grant --namespace some.schema --catalog fourth_catalog --catalog-role some_catalog_role TABLE_READ_DATA
polaris profiles list
polaris policies list --catalog some_catalog --namespace some.schema
polaris repair
polaris setup apply setup-config.yaml
polaris find some_table
polaris tables list --catalog my_catalog --namespace ns1
polaris repl

身份验证

如上所述，Polaris CLI 可以使用 --client-id 和 --client-secret 选项传入凭据。例如：

polaris --client-id 4b5ed1ca908c3cc2 --client-secret 07ea8e4edefb9a9e57c247e8d1a4f51c principals ...

如果未提供 --client-id 和 --client-secret，Polaris CLI 将尝试分别从名为 CLIENT_ID 和 CLIENT_SECRET 的环境变量中读取客户端 ID 和客户端密钥。如果既未提供这些参数，也未设置相应的环境变量，CLI 将失败。

也可以使用 --access-token 选项替代 --client-id 和 --client-secret，但两种认证方式不能同时使用。

此外，还可以使用 --profile 选项指定已保存的配置文件，而不必直接提供认证信息。如果未提供 --profile，CLI 将检查 CLIENT_PROFILE 环境变量。配置文件存储认证信息和连接设置，便于重复使用 CLI。

如果未提供 --host 和 --port 选项，CLI 默认与 localhost:8181 通信。

也可以使用 --base-url 选项替代 --host 和 --port，但这两个选项不能同时使用。这样可以指定任意的 Polaris URL，包括 HTTPS URL，即在 /api/*/v1 子路径之前带有额外基础前缀的 URL。

如果你的 Polaris 服务器配置为使用非默认的 realm，可以使用 --realm 选项指定 realm。如果未提供 --realm，CLI 将检查 REALM 环境变量。如果两者都未提供，CLI 将不会发送 realm 上下文标头。另外，如果你的 Polaris 服务器使用自定义的 realm 标头名称，可以使用 --header 选项指定它。如果未提供 --header，CLI 将检查 HEADER 环境变量。如果两者都未提供，CLI 将使用默认标头名称 Polaris-Realm。

此处了解有关配置 Polaris 服务器以支持多 realm 的更多信息。

命令

catalogs、principals、principal-roles、catalog-roles 和 privileges 这些命令分别用于管理 Polaris 中不同类型的实体。

除此之外，还可以使用 profiles 命令管理已保存的认证配置文件，以便配置可重复使用的登录凭证。这为每次命令都传入认证信息提供了替代方案。默认情况下，配置文件存储在 ~/.polaris 目录下的 .polaris.json 文件中。可以通过设置 POLARIS_HOME 环境变量来覆盖该目录的位置。

要即时查找某个特定命令或子命令可以提供的选项详情，你可以使用 --help 标志。例如：

polaris catalogs --help
polaris principals create --help
polaris profiles --help
polaris setup --help
polaris find --help
polaris tables --help

Catalogs

catalogs 命令用于在 Polaris 中创建、发现以及以其他方式管理 catalog。

catalogs 支持以下子命令：

  1. create
  2. delete
  3. get
  4. list
  5. update
  6. summarize

⚠️ 警告

通过 --property 或 --set-property 配置的 catalog 属性是客户端可见的默认值。Polaris 会通过 Iceberg REST /config 响应将它们返回给已认证的 catalog 客户端。catalog 属性仅应用于非敏感的客户端配置，不要在 catalog 属性中存储密码、令牌、访问密钥或其他机密信息。

create

create 子命令用于创建一个 catalog。

usage: polaris catalogs create [-h] [options] CATALOG_NAME

positional arguments:
  CATALOG_NAME                                                         catalog

options:
  -h, --help                                                           show this help message and exit

Command Options:
  --type {internal,external}                                           The type of catalog [INTERNAL, EXTERNAL]
  --storage-type {s3,azure,gcs,file}                                   (Required) The storage type [S3, AZURE, GCS, FILE]
  --default-base-location DEFAULT_BASE_LOCATION                        (Required) Default base location for the catalog
  --allowed-location ALLOWED_LOCATION                                  An allowed location for files tracked by the catalog
  --property PROPERTY                                                  A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once. Do not put passwords, tokens, access keys, or other secrets into the client-visible catalog properties.

AWS S3 Storage Options:
  --endpoint ENDPOINT                                                  The S3 endpoint to use when connecting to S3
  --endpoint-internal ENDPOINT_INTERNAL                                The S3 endpoint used by Polaris to use when connecting to S3, if different from the one that clients use
  --sts-endpoint STS_ENDPOINT                                          The STS endpoint to use when connecting to STS
  --no-sts                                                             Indicates that Polaris should not use STS (e.g. if STS is not available)
  --no-kms                                                             Indicates that Polaris should not use KMS (e.g. if KMS is not available)
  --path-style-access                                                  Whether to use path-style-access for S3
  --current-kms-key CURRENT_KMS_KEY                                    The AWS KMS key ARN to be used for encrypting new S3 data
  --allowed-kms-key ALLOWED_KMS_KEY                                    AWS KMS key ARN(s) that this catalog and its clients are allowed to use for reading S3 data (zero or more)
  --role-arn ROLE_ARN                                                  A role ARN to use when connecting to S3
  --region REGION                                                      The region to use when connecting to S3
  --external-id EXTERNAL_ID                                            The external ID to use when connecting to S3

Azure Storage Options:
  --tenant-id TENANT_ID                                                (Required) A tenant ID to use when connecting to Azure Storage
  --multi-tenant-app-name MULTI_TENANT_APP_NAME                        The app name to use when connecting to Azure Storage
  --hierarchical                                                       Indicates whether the referenced Azure storage location(s) support hierarchical namespaces
  --consent-url CONSENT_URL                                            A consent URL granting permissions for the Azure Storage location

GCP Storage Options:
  --service-account SERVICE_ACCOUNT                                    The service account to use when connecting to GCS

External Catalog Federation: General Options:
  --catalog-connection-type {hadoop,iceberg-rest,hive}                 External catalog type [ICEBERG-REST, HADOOP, HIVE]
  --iceberg-remote-catalog-name ICEBERG_REMOTE_CATALOG_NAME            The remote catalog name when federating to an Iceberg REST catalog
  --hadoop-warehouse HADOOP_WAREHOUSE                                  The warehouse to use when federating to a HADOOP catalog
  --hive-warehouse HIVE_WAREHOUSE                                      The warehouse to use when federating to a HIVE catalog
  --catalog-authentication-type {oauth,bearer,sigv4,implicit}          Authentication type [OAUTH, BEARER, SIGV4, IMPLICIT]
  --catalog-service-identity-type {aws_iam}                            Service identity type [AWS_IAM]
  --catalog-uri CATALOG_URI                                            The URI of the external catalog

External Catalog Federation: AWS IAM Identity Options:
  --catalog-service-identity-iam-arn CATALOG_SERVICE_IDENTITY_IAM_ARN  The ARN of the IAM user or IAM role Polaris uses to assume roles and then access external resources.

External Catalog Federation: OAuth Options:
  --catalog-token-uri CATALOG_TOKEN_URI                                Token server URI
  --catalog-client-id CATALOG_CLIENT_ID                                OAuth client ID
  --catalog-client-secret CATALOG_CLIENT_SECRET                        OAuth client secret (input-only)
  --catalog-client-scope CATALOG_CLIENT_SCOPE                          OAuth scopes to specify when exchanging for a short-lived access token. Multiple can be provided by specifying this option more than once

External Catalog Federation: Bearer Token Options:
  --catalog-bearer-token CATALOG_BEARER_TOKEN                          Bearer token (input-only)

External Catalog Federation: AWS SigV4 Options:
  --catalog-role-arn CATALOG_ROLE_ARN                                  The AWS IAM role ARN assumed by Polaris when signing requests
  --catalog-role-session-name CATALOG_ROLE_SESSION_NAME                The role session name to be used by the SigV4 protocol for signing requests
  --catalog-external-id CATALOG_EXTERNAL_ID                            An optional external ID used to establish an AWS trust relationship
  --catalog-signing-region CATALOG_SIGNING_REGION                      Region to be used by the SigV4 protocol for signing requests
  --catalog-signing-name CATALOG_SIGNING_NAME                          The service name to be used by the SigV4 protocol for signing requests
示例
polaris catalogs create \
  --storage-type s3 \
  --default-base-location s3://example-bucket/my_data \
  --role-arn ${ROLE_ARN} \
  my_catalog

polaris catalogs create \
  --storage-type s3 \
  --default-base-location s3://example-bucket/my_other_data \
  --allowed-location s3://example-bucket/second_location \
  --allowed-location s3://other-bucket/third_location \
  --role-arn ${ROLE_ARN} \
  my_other_catalog

polaris catalogs create \
  --storage-type file \
  --default-base-location file:///example/tmp \
  quickstart_catalog

delete

delete 子命令用于删除目录（catalog）。

usage: polaris catalogs delete [-h] [options] CATALOG_NAME

positional arguments:
  CATALOG_NAME  catalog

options:
  -h, --help    show this help message and exit
示例
polaris catalogs delete some_catalog

get

get 子命令用于检索某个 catalog 的详细信息。

usage: polaris catalogs get [-h] [options] CATALOG_NAME

positional arguments:
  CATALOG_NAME  catalog

options:
  -h, --help    show this help message and exit
示例
polaris catalogs get some_catalog

polaris catalogs get another_catalog

list

list 子命令用于显示所有目录的详细信息，或显示某个主体角色（principal role）有权访问的目录的详细信息。执行此操作所使用的主体必须拥有 CATALOG_LIST 权限。

usage: polaris catalogs list [-h] [options]

options:
  -h, --help                       show this help message and exit

Command Options:
  --principal-role PRINCIPAL_ROLE  List only catalogs reachable by this principal role
示例
polaris catalogs list

polaris catalogs list --principal-role some_user

summarize

summarize 子命令用于显示目录（catalog）的摘要信息。

usage: polaris catalogs summarize [-h] [options] CATALOG_NAME

positional arguments:
  CATALOG_NAME  catalog

options:
  -h, --help    show this help message and exit
示例
polaris catalogs summarize some_catalog

update

update 子命令用于更新目录（catalog）。目前，该命令支持修改目录的属性或更新其存储配置。

usage: polaris catalogs update [-h] [options] CATALOG_NAME

positional arguments:
  CATALOG_NAME                                   catalog

options:
  -h, --help                                     show this help message and exit

Command Options:
  --default-base-location DEFAULT_BASE_LOCATION  A new default base location for the catalog
  --allowed-location ALLOWED_LOCATION            An additional allowed location for files
  --set-property SET_PROPERTY                    A key/value pair such as: tag=value. Merges the specified key/value into an existing properties map by updating the value if the key already exists or creating a new entry if not. Multiple can be provided by specifying this option more than once. Do not put passwords, tokens, access keys, or other secrets into the client-visible catalog properties.
  --remove-property REMOVE_PROPERTY              A key to remove from a properties map. If the key already does not exist then no action is taken for the specified key. Multiple can be provided by specifying this option more than once

AWS S3 Storage Options:
  --region REGION                                The region to use when connecting to S3
示例
polaris catalogs update --set-property tag=new_value my_catalog

polaris catalogs update --default-base-location s3://new-bucket/my_data my_catalog

主体（Principals）

principals 命令用于管理 Polaris 中的主体。

principals 支持以下子命令：

  1. create
  2. delete
  3. get
  4. list
  5. rotate-credentials
  6. update
  7. access
  8. reset

create

create 子命令用于创建一个新的主体。

usage: polaris principals create [-h] [options] PRINCIPAL_NAME

positional arguments:
  PRINCIPAL_NAME       principal

options:
  -h, --help           show this help message and exit

Command Options:
  --type {service}     The type of principal [SERVICE]
  --property PROPERTY  A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once
示例
polaris principals create some_user

polaris principals create --client-id ${CLIENT_ID} --property admin=true some_admin_user

delete

delete 子命令用于删除主体。

usage: polaris principals delete [-h] [options] PRINCIPAL_NAME

positional arguments:
  PRINCIPAL_NAME  principal

options:
  -h, --help      show this help message and exit
示例
polaris principals delete some_user

polaris principals delete some_admin_user

get

get 子命令用于检索主体的详细信息。

usage: polaris principals get [-h] [options] PRINCIPAL_NAME

positional arguments:
  PRINCIPAL_NAME  principal

options:
  -h, --help      show this help message and exit
示例
polaris principals get some_user

polaris principals get some_admin_user

list

list 子命令显示所有主体（principal）的详细信息。

示例
polaris principals list

rotate-credentials

rotate-credentials 子命令用于更新主体（principal）所使用的凭据。该命令成功执行后，新的凭据将输出到标准输出。

usage: polaris principals rotate-credentials [-h] [options] PRINCIPAL_NAME

positional arguments:
  PRINCIPAL_NAME  principal

options:
  -h, --help      show this help message and exit
示例
polaris principals rotate-credentials some_user

polaris principals rotate-credentials some_admin_user

update

update 子命令用于更新主体（principal）。目前，该子命令支持重写与主体关联的属性。

usage: polaris principals update [-h] [options] PRINCIPAL_NAME

positional arguments:
  PRINCIPAL_NAME                     principal

options:
  -h, --help                         show this help message and exit

Command Options:
  --set-property SET_PROPERTY        A key/value pair such as: tag=value. Merges the specified key/value into an existing properties map by updating the value if the key already exists or creating a new entry if not. Multiple can be provided by specifying this option more than once
  --remove-property REMOVE_PROPERTY  A key to remove from a properties map. If the key already does not exist then no action is taken for the specified key. Multiple can be provided by specifying this option more than once
示例
polaris principals update --property key=value --property other_key=other_value some_user

polaris principals update --property are_other_keys_removed=yes some_user

access

access 子命令用于检索与主体（principal）相关的实体关系。

usage: polaris principals access [-h] [options] PRINCIPAL_NAME

positional arguments:
  PRINCIPAL_NAME  principal

options:
  -h, --help      show this help message and exit
示例
polaris principals access quickstart_user

reset

reset 子命令用于重置主体（principal）凭据。

usage: polaris principals reset [-h] [options] PRINCIPAL_NAME

positional arguments:
  PRINCIPAL_NAME                         principal

options:
  -h, --help                             show this help message and exit

Command Options:
  --new-client-id NEW_CLIENT_ID          The new client ID for the principal
  --new-client-secret NEW_CLIENT_SECRET  The new client secret for the principal
示例
polaris principals create some_user

polaris principals reset some_user
polaris principals reset --new-client-id ${NEW_CLIENT_ID} some_user
polaris principals reset --new-client-secret ${NEW_CLIENT_SECRET} some_user
polaris principals reset --new-client-id ${NEW_CLIENT_ID} --new-client-secret ${NEW_CLIENT_SECRET} some_user

summarize

summarize 子命令用于显示主体（principal）的摘要信息。

usage: polaris principals summarize [-h] [options] PRINCIPAL_NAME

positional arguments:
  PRINCIPAL_NAME  principal

options:
  -h, --help      show this help message and exit
示例
polaris principals summarize some_user

主体角色

principal-roles 命令用于在 Polaris 中创建、发现和管理主体角色。此外，该命令可以识别与某个主体角色相关联的主体或目录角色，并可用于将主体角色授予某个主体。

principal-roles 支持以下子命令：

  1. create
  2. delete
  3. get
  4. list
  5. update
  6. grant
  7. revoke
  8. summarize

create

create 子命令用于创建一个新的主体角色。

usage: polaris principal-roles create [-h] [options] PRINCIPAL_ROLE_NAME

positional arguments:
  PRINCIPAL_ROLE_NAME  principal role

options:
  -h, --help           show this help message and exit

Command Options:
  --property PROPERTY  A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once
示例
polaris principal-roles create data_engineer

polaris principal-roles create --property key=value data_analyst

delete

delete 子命令用于删除主体角色。

usage: polaris principal-roles delete [-h] [options] PRINCIPAL_ROLE_NAME

positional arguments:
  PRINCIPAL_ROLE_NAME  principal role

options:
  -h, --help           show this help message and exit
示例
polaris principal-roles delete data_engineer

polaris principal-roles delete data_analyst

get

get 子命令用于检索主体角色的详细信息。

usage: polaris principal-roles get [-h] [options] PRINCIPAL_ROLE_NAME

positional arguments:
  PRINCIPAL_ROLE_NAME  principal role

options:
  -h, --help           show this help message and exit
示例
polaris principal-roles get data_engineer

polaris principal-roles get data_analyst

list

list 子命令用于打印出所有主体角色，或者列出与给定主体或给定目录角色相关联的所有主体角色。

usage: polaris principal-roles list [-h] [options]

options:
  -h, --help                   show this help message and exit

Command Options:
  --catalog-role CATALOG_ROLE  Show only principal roles assigned to this catalog role
  --principal PRINCIPAL        Show only principal roles assigned to this principal
示例
polaris principal-roles list

polaris principal-roles --principal d.knuth

polaris principal-roles --catalog-role super_secret_data

update

update 子命令用于更新主体角色。目前，该命令支持更新与主体角色关联的属性。

usage: polaris principal-roles update [-h] [options] PRINCIPAL_ROLE_NAME

positional arguments:
  PRINCIPAL_ROLE_NAME                principal role

options:
  -h, --help                         show this help message and exit

Command Options:
  --set-property SET_PROPERTY        A key/value pair such as: tag=value. Merges the specified key/value into an existing properties map by updating the value if the key already exists or creating a new entry if not. Multiple can be provided by specifying this option more than once
  --remove-property REMOVE_PROPERTY  A key to remove from a properties map. If the key already does not exist then no action is taken for the specified key. Multiple can be provided by specifying this option more than once
示例
polaris principal-roles update --property key=value2 data_engineer

polaris principal-roles update data_analyst --property key=value3

grant

grant 子命令用于将主体角色授予主体。

usage: polaris principal-roles grant [-h] [options] PRINCIPAL_ROLE_NAME

positional arguments:
  PRINCIPAL_ROLE_NAME    principal role

options:
  -h, --help             show this help message and exit

Command Options:
  --principal PRINCIPAL  The name of a principal
示例
polaris principal-roles grant --principal d.knuth data_engineer

polaris principal-roles grant data_scientist --principal a.ng

revoke

revoke 子命令用于从某个主体（principal）撤销主体角色（principal role）。

usage: polaris principal-roles revoke [-h] [options] PRINCIPAL_ROLE_NAME

positional arguments:
  PRINCIPAL_ROLE_NAME    principal role

options:
  -h, --help             show this help message and exit

Command Options:
  --principal PRINCIPAL  The name of a principal
示例
polaris principal-roles revoke --principal former.employee data_engineer

polaris principal-roles revoke data_scientist --principal changed.role

summarize

summarize 子命令用于显示主体角色（principal role）的摘要信息。

usage: polaris principal-roles summarize [-h] [options] PRINCIPAL_ROLE_NAME

positional arguments:
  PRINCIPAL_ROLE_NAME  principal role

options:
  -h, --help           show this help message and exit
示例
polaris principal-roles summarize data_engineer

目录角色

catalog-roles 命令用于在 Polaris 中创建、发现和管理目录角色。此外，该命令还可用于将目录角色授予主体角色。

catalog-roles 支持以下子命令：

  1. create
  2. delete
  3. get
  4. list
  5. update
  6. grant
  7. revoke
  8. summarize

create

create 子命令用于创建新的目录角色。

usage: polaris catalog-roles create [-h] [options] CATALOG_ROLE_NAME

positional arguments:
  CATALOG_ROLE_NAME    catalog role

options:
  -h, --help           show this help message and exit

Command Options:
  --catalog CATALOG    The name of a catalog
  --property PROPERTY  A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once
示例
polaris catalog-roles create --property key=value --catalog some_catalog sales_data

polaris catalog-roles create --catalog other_catalog sales_data

delete

delete 子命令用于删除目录角色（catalog role）。

usage: polaris catalog-roles delete [-h] [options] CATALOG_ROLE_NAME

positional arguments:
  CATALOG_ROLE_NAME  catalog role

options:
  -h, --help         show this help message and exit

Command Options:
  --catalog CATALOG  The name of a catalog
示例
polaris catalog-roles delete --catalog some_catalog sales_data

polaris catalog-roles delete --catalog other_catalog sales_data

get

get 子命令用于检索目录角色的详细信息。

usage: polaris catalog-roles get [-h] [options] CATALOG_ROLE_NAME

positional arguments:
  CATALOG_ROLE_NAME  catalog role

options:
  -h, --help         show this help message and exit

Command Options:
  --catalog CATALOG  The name of a catalog
示例
polaris catalog-roles get --catalog some_catalog inventory_data

polaris catalog-roles get --catalog other_catalog inventory_data

list

list 子命令用于打印所有目录角色。此外，如果提供了主体角色（principal role），则只会显示与该主体相关联的目录角色。

usage: polaris catalog-roles list [-h] [options] CATALOG_NAME

positional arguments:
  CATALOG_NAME                     catalog

options:
  -h, --help                       show this help message and exit

Command Options:
  --principal-role PRINCIPAL_ROLE  The name of a principal role
示例
polaris catalog-roles list

polaris catalog-roles list --principal-role data_engineer

update

update 子命令用于更新目录角色。目前仅支持更新与该目录角色关联的属性。

usage: polaris catalog-roles update [-h] [options] CATALOG_ROLE_NAME

positional arguments:
  CATALOG_ROLE_NAME                  catalog role

options:
  -h, --help                         show this help message and exit

Command Options:
  --catalog CATALOG                  The name of a catalog
  --set-property SET_PROPERTY        A key/value pair such as: tag=value. Merges the specified key/value into an existing properties map by updating the value if the key already exists or creating a new entry if not. Multiple can be provided by specifying this option more than once
  --remove-property REMOVE_PROPERTY  A key to remove from a properties map. If the key already does not exist then no action is taken for the specified key. Multiple can be provided by specifying this option more than once
示例
polaris catalog-roles update --property contains_pii=true --catalog some_catalog sales_data

polaris catalog-roles update sales_data --catalog some_catalog --property key=value

grant

grant 子命令用于向主体角色授予目录角色。

usage: polaris catalog-roles grant [-h] [options] CATALOG_ROLE_NAME

positional arguments:
  CATALOG_ROLE_NAME                catalog role

options:
  -h, --help                       show this help message and exit

Command Options:
  --catalog CATALOG                The name of a catalog
  --principal-role PRINCIPAL_ROLE  The name of a principal role
示例
polaris catalog-roles grant sensitive_data --catalog some_catalog --principal-role power_user

polaris catalog-roles grant --catalog sales_data contains_cc_info_catalog_role --principal-role financial_analyst_role

revoke

revoke 子命令用于从主体角色（principal role）中撤销目录角色（catalog role）。

usage: polaris catalog-roles revoke [-h] [options] CATALOG_ROLE_NAME

positional arguments:
  CATALOG_ROLE_NAME                catalog role

options:
  -h, --help                       show this help message and exit

Command Options:
  --catalog CATALOG                The name of a catalog
  --principal-role PRINCIPAL_ROLE  The name of a principal role
示例
polaris catalog-roles revoke sensitive_data --catalog some_catalog --principal-role power_user

polaris catalog-roles revoke --catalog sales_data contains_cc_info_catalog_role --principal-role financial_analyst_role

summarize

summarize 子命令用于显示目录角色的摘要信息。

usage: polaris catalog-roles summarize [-h] [options] CATALOG_ROLE_NAME

positional arguments:
  CATALOG_ROLE_NAME  catalog role

options:
  -h, --help         show this help message and exit

Command Options:
  --catalog CATALOG  The name of a catalog
示例
polaris catalog-roles summarize --catalog some_catalog some_catalog_role

命名空间

namespaces 命令用于管理 Polaris 中的命名空间。

namespaces 支持以下子命令：

  1. create
  2. delete
  3. get
  4. list
  5. summarize

create

create 子命令用于创建新的命名空间。

在创建指定了显式位置的命名空间时，该位置必须位于父目录或父命名空间之内。

usage: polaris namespaces create [-h] [options] NAMESPACE

positional arguments:
  NAMESPACE            namespace

options:
  -h, --help           show this help message and exit

Command Options:
  --catalog CATALOG    The name of a catalog
  --location LOCATION  The storage location for the namespace
  --property PROPERTY  A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once
示例
polaris namespaces create --catalog my_catalog outer

polaris namespaces create --catalog my_catalog --location 's3://bucket/outer/inner_SUFFIX' outer.inner

delete

delete 子命令用于删除命名空间。

usage: polaris namespaces delete [-h] [options] NAMESPACE

positional arguments:
  NAMESPACE          namespace

options:
  -h, --help         show this help message and exit

Command Options:
  --catalog CATALOG  The name of a catalog
示例
polaris namespaces delete  outer_namespace.inner_namespace --catalog my_catalog

polaris namespaces delete --catalog my_catalog outer_namespace

get

get 子命令用于检索命名空间的详细信息。

usage: polaris namespaces get [-h] [options] NAMESPACE

positional arguments:
  NAMESPACE          namespace

options:
  -h, --help         show this help message and exit

Command Options:
  --catalog CATALOG  The name of a catalog
示例
polaris namespaces get --catalog some_catalog a.b

polaris namespaces get a.b.c --catalog some_catalog

list

list 子命令显示目录中所有直接位于其下的命名空间的详细信息，或者可选地，显示该目录中某个父前缀下所有命名空间的详细信息。

usage: polaris namespaces list [-h] [options]

options:
  -h, --help         show this help message and exit

Command Options:
  --catalog CATALOG  The name of a catalog
  --parent PARENT    The parent namespace to list sub-namespaces from
示例
polaris namespaces list --catalog my_catalog

polaris namespaces list --catalog my_catalog --parent a

polaris namespaces list --catalog my_catalog --parent a.b

summarize

summarize 子命令用于显示某个命名空间的摘要信息。

usage: polaris namespaces summarize [-h] [options] NAMESPACE

positional arguments:
  NAMESPACE          namespace

options:
  -h, --help         show this help message and exit

Command Options:
  --catalog CATALOG  The name of a catalog
示例
polaris namespaces summarize --catalog my_catalog a.b

权限

privileges 命令用于向目录角色（catalog role）授予各种权限，或撤销这些权限。权限可以作用于目录（catalog）、命名空间（namespace）、表（table）或视图（view）级别。有关权限的更多信息，请参阅文档。

请注意，使用 privileges 命令时，用户需先指定相关的目录和目录角色，然后再选择子命令。

privileges 支持以下子命令：

  1. list
  2. catalog
  3. namespace
  4. table
  5. view

除 list 之外，上述每个子命令都支持 grant 和 revoke 操作，并且必须指定一个操作。

请注意，每个子命令的 revoke 操作始终接受与其对应的 grant 操作相同的选项，此外还增加了 cascade 选项。cascade 用于撤销依赖于指定权限的所有其他权限。

list

list 子命令显示目录角色的所有权限的详细信息。

usage: polaris privileges list [-h] [options]

options:
  -h, --help                   show this help message and exit

Command Options:
  --catalog CATALOG            The name of a catalog
  --catalog-role CATALOG_ROLE  The name of a catalog role
示例
polaris privileges  list --catalog my_catalog --catalog-role my_role

polaris privileges my_role list --catalog-role my_other_role --catalog my_catalog

catalog

catalog 子命令用于在目录（catalog）级别管理权限。grant 用于向指定的目录角色授予目录权限，revoke 用于撤销这些权限。

usage: polaris privileges catalog [-h] [options] SUBCOMMAND ...

options:
  -h, --help  show this help message and exit

Subcommands:
  SUBCOMMAND
    grant     Grant a catalog-level privilege
    revoke    Revoke a catalog-level privilege
示例
polaris privileges \
  catalog \
  grant \
  --catalog my_catalog \
  --catalog-role catalog_role \
  TABLE_CREATE

polaris privileges \
  catalog \
  revoke \
  --catalog my_catalog \
  --catalog-role catalog_role \
  --cascade \
  TABLE_CREATE

namespace

namespace 子命令用于在命名空间级别管理权限。

usage: polaris privileges namespace [-h] [options] SUBCOMMAND ...

options:
  -h, --help  show this help message and exit

Subcommands:
  SUBCOMMAND
    grant     Grant a namespace-level privilege
    revoke    Revoke a namespace-level privilege
示例
polaris privileges \
  namespace \
  grant \
  --catalog my_catalog \
  --catalog-role catalog_role \
  --namespace a.b \
  TABLE_LIST

polaris privileges \
  namespace \
  revoke \
  --catalog my_catalog \
  --catalog-role catalog_role \
  --namespace a.b \
  TABLE_LIST

table

table 子命令用于管理表级别的权限。

usage: polaris privileges table [-h] [options] SUBCOMMAND ...

options:
  -h, --help  show this help message and exit

Subcommands:
  SUBCOMMAND
    grant     Grant a table-level privilege
    revoke    Revoke a table-level privilege
示例
polaris privileges \
  table \
  grant \
  --catalog my_catalog \
  --catalog-role catalog_role \
  --namespace a.b \
  --table t \
  TABLE_DROP

polaris privileges \
  table \
  grant \
  --catalog my_catalog \
  --catalog-role catalog_role \
  --namespace a.b \
  --table t \
  --cascade \
  TABLE_DROP

view

view 子命令用于在视图级别管理权限。

usage: polaris privileges view [-h] [options] SUBCOMMAND ...

options:
  -h, --help  show this help message and exit

Subcommands:
  SUBCOMMAND
    grant     Grant a view-level privilege
    revoke    Revoke a view-level privilege
示例
polaris privileges \
  view \
  grant \
  --catalog my_catalog \
  --catalog-role catalog_role \
  --namespace a.b.c \
  --view v \
  VIEW_FULL_METADATA

polaris privileges \
  view \
  grant \
  --catalog my_catalog \
  --catalog-role catalog_role \
  --namespace a.b.c \
  --view v \
  --cascade \
  VIEW_FULL_METADATA

配置文件（Profiles）

profiles 命令用于管理 Polaris 中存储的身份验证配置文件。配置文件可以保存并复用身份验证凭据，从而无需在每次执行命令时都传递凭据。

profiles 支持以下子命令：

  1. create
  2. delete
  3. get
  4. list
  5. update

create

create 子命令用于创建新的身份验证配置文件。

usage: polaris profiles create [-h] [options] PROFILE_NAME

positional arguments:
  PROFILE_NAME  profile

options:
  -h, --help    show this help message and exit
示例
polaris profiles create dev

delete

delete 子命令用于删除已保存的配置文件。

usage: polaris profiles delete [-h] [options] PROFILE_NAME

positional arguments:
  PROFILE_NAME  profile

options:
  -h, --help    show this help message and exit
示例
polaris profiles delete dev

get

get 子命令会删除一个已存储的配置文件。

usage: polaris profiles get [-h] [options] PROFILE_NAME

positional arguments:
  PROFILE_NAME  profile

options:
  -h, --help    show this help message and exit
示例
polaris profiles get dev

list

list 子命令显示所有已存储的配置文件。

usage: polaris profiles list [-h] [options]

options:
  -h, --help  show this help message and exit
示例
polaris profiles list

update

update 子命令用于修改现有的配置文件。

usage: polaris profiles update [-h] [options] PROFILE_NAME

positional arguments:
  PROFILE_NAME  profile

options:
  -h, --help    show this help message and exit
示例
polaris profiles update dev

策略

policies 命令用于管理 Polaris 中的策略。

policies 支持以下子命令：

  1. attach
  2. create
  3. delete
  4. detach
  5. get
  6. list
  7. update

attach

attach 子命令用于在策略与资源实体之间创建映射关系。

usage: polaris policies attach [-h] [options] POLICY_NAME

positional arguments:
  POLICY_NAME                        policy

options:
  -h, --help                         show this help message and exit

Command Options:
  --catalog CATALOG                  The name of a catalog
  --namespace NAMESPACE              A period-delimited namespace
  --attachment-type ATTACHMENT_TYPE  The type of entity to attach to ('catalog', 'namespace', 'table-like')
  --attachment-path ATTACHMENT_PATH  The path of the target entity (e.g., 'ns1.tb1')
  --parameters PARAMETERS            Key-value pairs for the attachment (e.g., key=value)
示例
polaris policies attach --catalog some_catalog --namespace some.schema --attachment-type namespace --attachment-path some.schema some_policy

polaris policies attach --catalog some_catalog --namespace some.schema --attachment-type table-like --attachment-path some.schema.t some_table_policy

create

create 子命令用于创建策略。

usage: polaris policies create [-h] [options] POLICY_NAME

positional arguments:
  POLICY_NAME                              policy

options:
  -h, --help                               show this help message and exit

Command Options:
  --catalog CATALOG                        The name of a catalog
  --namespace NAMESPACE                    A period-delimited namespace
  --policy-file POLICY_FILE                Path to the JSON file containing the policy definition
  --policy-type POLICY_TYPE                The type of the policy (e.g., 'system.data-compaction')
  --policy-description POLICY_DESCRIPTION  An optional description for the policy
示例
polaris policies create --catalog some_catalog --namespace some.schema --policy-file some_policy.json --policy-type system.data-compaction some_policy

polaris policies create --catalog some_catalog --namespace some.schema --policy-file some_snapshot_expiry_policy.json --policy-type system.snapshot-expiry some_snapshot_expiry_policy

delete

delete 子命令用于删除一条策略。

usage: polaris policies delete [-h] [options] POLICY_NAME

positional arguments:
  POLICY_NAME            policy

options:
  -h, --help             show this help message and exit

Command Options:
  --catalog CATALOG      The name of a catalog
  --namespace NAMESPACE  A period-delimited namespace
  --detach-all           Delete the policy and all its attached mappings
示例
polaris policies delete --catalog some_catalog --namespace some.schema some_policy

polaris policies delete --catalog some_catalog --namespace some.schema --detach-all some_policy

detach

detach 子命令用于移除策略与目标实体之间的映射关系。

usage: polaris policies detach [-h] [options] POLICY_NAME

positional arguments:
  POLICY_NAME                        policy

options:
  -h, --help                         show this help message and exit

Command Options:
  --catalog CATALOG                  The name of a catalog
  --namespace NAMESPACE              A period-delimited namespace
  --attachment-type ATTACHMENT_TYPE  The type of entity to attach to ('catalog', 'namespace', 'table-like')
  --attachment-path ATTACHMENT_PATH  The path of the target entity (e.g., 'ns1.tb1')
  --parameters PARAMETERS            Key-value pairs for the attachment (e.g., key=value)
示例
polaris policies detach --catalog some_catalog --namespace some.schema --attachment-type namespace --attachment-path some.schema some_policy

polaris policies detach --catalog some_catalog --namespace some.schema --attachment-type catalog --attachment-path some_catalog some_policy

get

get 子命令用于从目录中加载策略。

usage: polaris policies get [-h] [options] POLICY_NAME

positional arguments:
  POLICY_NAME            policy

options:
  -h, --help             show this help message and exit

Command Options:
  --catalog CATALOG      The name of a catalog
  --namespace NAMESPACE  A period-delimited namespace
示例
polaris policies get --catalog some_catalog --namespace some.schema some_policy

list

list 子命令用于获取此命名空间下的所有策略标识符，以及指定实体所适用的所有策略。

usage: polaris policies list [-h] [options]

options:
  -h, --help                 show this help message and exit

Command Options:
  --catalog CATALOG          The name of a catalog
  --namespace NAMESPACE      A period-delimited namespace
  --target-name TARGET_NAME  The name of the target entity
  --applicable               List policies applicable to the target (considering inheritance)
  --policy-type POLICY_TYPE  The type of the policy (e.g., 'system.data-compaction')
示例
polaris policies list --catalog some_catalog

polaris policies list --catalog some_catalog --applicable

update

update 子命令用于更新一条策略。

usage: polaris policies update [-h] [options] POLICY_NAME

positional arguments:
  POLICY_NAME                              policy

options:
  -h, --help                               show this help message and exit

Command Options:
  --catalog CATALOG                        The name of a catalog
  --namespace NAMESPACE                    A period-delimited namespace
  --policy-file POLICY_FILE                Path to the JSON file containing the policy definition
  --policy-description POLICY_DESCRIPTION  An optional description for the policy
示例
polaris policies update --catalog some_catalog --namespace some.schema --policy-file my_updated_policy.json my_policy

polaris policies update --catalog some_catalog --namespace some.schema --policy-file my_updated_policy.json --policy-description "Updated policy description" my_policy

修复（Repair）

repair 命令是一个 bash 脚本包装器，用于重新生成 Python 客户端代码并更新必要的依赖，以确保 Polaris 客户端保持最新且可用。请注意，此命令不支持任何选项，且无法通过 --help 标志查看其用法信息。

设置（Setup）

setup 命令用于根据配置文件，在 Polaris 中自动创建各类实体，例如主体（principals）、角色（roles）、目录（catalogs）、命名空间（namespaces）、权限（privileges）和策略（policies）。这简化了搭建 Polaris 环境的流程。

setup 支持以下子命令：

  1. apply
  2. export

apply

apply 子命令会读取配置文件，并在 Polaris 中创建其中指定的实体。配置文件必须为 YAML 格式，并定义需要创建的实体。

usage: polaris setup apply [-h] [options] SETUP_CONFIG_FILE

positional arguments:
  SETUP_CONFIG_FILE  setup config

options:
  -h, --help         show this help message and exit

Command Options:
  --dry-run          Run without executing
示例
polaris setup apply setup-config.yaml

export

export 子命令会获取当前的 Polaris 配置，并以 YAML 格式输出。该输出与 apply 子命令兼容，可方便地用于备份、迁移或重新创建 Polaris 环境。

usage: polaris setup export [-h] [options]

options:
  -h, --help  show this help message and exit
示例
polaris setup export

Find

find 命令用于通过模糊匹配在全局实体（主体、角色、catalog）和 catalog 实体（命名空间、表、视图）中搜索标识符。

示例
polaris find my_table
polaris find ns1.ns2
polaris find --catalog my_catalog my_table
polaris find my_table --type table

表格

tables 命令用于管理 Polaris Catalog 中的 Iceberg 表。

tables 支持以下子命令：

  1. list
  2. get
  3. summarize
  4. delete

list

list 子命令用于列出指定 catalog 中某个命名空间下的表。

usage: polaris tables list [-h] [options]

options:
  -h, --help             show this help message and exit

Command Options:
  --catalog CATALOG      The name of a catalog
  --namespace NAMESPACE  A period-delimited namespace
示例
polaris tables list

get

get 子命令用于检索指定表的表元数据。

usage: polaris tables get [-h] [options] TABLE_NAME

positional arguments:
  TABLE_NAME             table

options:
  -h, --help             show this help message and exit

Command Options:
  --catalog CATALOG      The name of a catalog
  --namespace NAMESPACE  A period-delimited namespace
示例
polaris tables get my_table --catalog my_catalog --namespace ns1

summarize

summarize 子命令提供表格的详细概览。

usage: polaris tables summarize [-h] [options] TABLE_NAME

positional arguments:
  TABLE_NAME             table

options:
  -h, --help             show this help message and exit

Command Options:
  --catalog CATALOG      The name of a catalog
  --namespace NAMESPACE  A period-delimited namespace
示例
polaris tables summarize my_table --catalog my_catalog --namespace ns1

delete

delete 子命令从 catalog 中注销一张表（仅删除元数据）。

usage: polaris tables delete [-h] [options] TABLE_NAME

positional arguments:
  TABLE_NAME             table

options:
  -h, --help             show this help message and exit

Command Options:
  --catalog CATALOG      The name of a catalog
  --namespace NAMESPACE  A period-delimited namespace
示例
polaris tables delete my_table --catalog my_catalog --namespace ns1

REPL

REPL 命令会为 Polaris CLI 启动一个交互式 REPL 会话，使你能够在无需重新认证的情况下执行多条命令。

全局的认证与连接选项在会话启动时绑定。启动 REPL 时，可以使用 --catalog 标志指定默认目录（catalog）。在会话中，所有需要目录的命令都会自动使用该目录，除非被显式覆盖。

命令历史会自动保存到 ~/.polaris/.polaris_repl_history，历史条目数量可通过 POLARIS_REPL_HISTORY_LENGTH 环境变量进行配置。

在 REPL 中，使用 help 列出命令，使用 exit 或 Ctrl-D 退出，使用 Ctrl-C 清除当前行。

示例
polaris repl --catalog my_catalog

示例

本节列出了一些常见操作以及部分较为复杂操作的示例代码。

对于特别复杂的操作，你可能更希望直接使用 Python API。

创建主体与目录

polaris principals create my_user

polaris catalogs create \
  --type internal \
  --storage-type s3 \
  --default-base-location s3://iceberg-bucket/polaris-base \
  --role-arn arn:aws:iam::111122223333:role/ExampleCorpRole \
  --allowed-location s3://iceberg-bucket/polaris-alt-location-1 \
  --allowed-location s3://iceberg-bucket/polaris-alt-location-2 \
  my_catalog

授予主体管理目录内容的权限

polaris principal-roles create power_user
polaris principal-roles grant --principal my_user power_user

polaris catalog-roles create --catalog my_catalog my_catalog_role
polaris catalog-roles grant \
  --catalog my_catalog \
  --principal-role power_user \
  my_catalog_role

polaris privileges \
  catalog \
  grant \
  --catalog my_catalog \
  --catalog-role my_catalog_role \
  CATALOG_MANAGE_CONTENT

识别已获显式读取权限的表

请注意，某些其他权限（例如 CATALOG_MANAGE_CONTENT）包含 TABLE_READ_DATA，因此不会在此处被发现。

principal_roles=$(polaris principal-roles list --principal readonly_user | jq -r .name)
for principal_role in ${principal_roles}; do
  catalog_roles=$(polaris catalog-roles list quickstart_catalog --principal-role ${principal_role} | jq -r .name)
  for catalog_role in ${catalog_roles}; do
    grants=$(polaris privileges list  --catalog-role ${catalog_role} --catalog quickstart_catalog)
    for grant in $(echo ${grants} | jq -c 'select(.privilege == "TABLE_READ_DATA")'); do
      echo "${grant}"
    done
  done
done

评论

登录后参与评论

正在加载评论…