跳到主要内容
版本: 最新版本-3.5

Hive Catalog

Hive catalog 是一种外部 Catalog，StarRocks 自 v2.4 版本起支持。在 Hive catalog 中，您可以

  • 直接查询存储在 Hive 中的数据，无需手动创建表。
  • 使用 INSERT INTO 或者异步物化视图（自 v2.5 版本起支持）来处理存储在 Hive 中的数据，并将数据加载到 StarRocks 中。
  • 在 StarRocks 中执行操作来创建或删除 Hive 数据库和表，或者使用 INSERT INTO 将 StarRocks 表中的数据sink到 Parquet 格式（自 v3.2 版本起支持）、ORC 或 Textfile 格式（自 v3.3 版本起支持）的 Hive 表中。

为了确保在 Hive 集群上成功执行 SQL 工作负载，您的 StarRocks 集群必须能够访问 Hive 集群的存储系统和 Metastore。StarRocks 支持以下存储系统和 Metastore

  • 分布式文件系统（HDFS）或对象存储，如 AWS S3、Microsoft Azure Storage、Google GCS 或其他 S3 兼容的存储系统（例如，MinIO）

  • Metastore，如 Hive Metastore 或 AWS Glue

    注意

    如果您选择 AWS S3 作为存储，则可以使用 HMS 或 AWS Glue 作为 Metastore。如果您选择任何其他存储系统，则只能使用 HMS 作为 Metastore。

使用说明​

  • StarRocks 支持查询 Parquet、ORC、Textfile、Avro、RCFile 和 SequenceFile 文件格式的 Hive 表

    • Parquet 文件支持以下压缩格式：SNAPPY、LZ4、ZSTD、GZIP 和 NO_COMPRESSION。从 v3.1.5 版本开始，Parquet 文件还支持 LZO 压缩格式。
    • ORC 文件支持以下压缩格式：ZLIB、SNAPPY、LZO、LZ4、ZSTD 和 NO_COMPRESSION。
    • Textfile 文件从 v3.1.5 版本开始支持 LZO 压缩格式。

  • StarRocks 不支持的 Hive 数据类型包括 INTERVAL、BINARY 和 UNION。此外，StarRocks 不支持 Textfile 格式 Hive 表的 MAP 和 STRUCT 数据类型。

  • StarRocks 支持将数据 sink 到 Parquet 格式（自 v3.2 版本起支持）以及 ORC 或 Textfile 格式（自 v3.3 版本起支持）的 Hive 表中

    • Parquet 和 ORC 文件支持以下压缩格式：NO_COMPRESSION、SNAPPY、LZ4、ZSTD 和 GZIP。
    • Textfile 文件支持 NO_COMPRESSION 压缩格式。

    您可以使用会话变量 connector_sink_compression_codec 来指定用于将数据 sink 到 Hive 表的压缩算法。

集成准备​

在创建 Hive Catalog 之前，请确保您的 StarRocks 集群可以与 Hive 集群的存储系统和 Metastore 集成。

AWS IAM​

如果您的 Hive 集群使用 AWS S3 作为存储或 AWS Glue 作为 Metastore，请选择您合适的身份验证方法并进行必要的准备，以确保您的 StarRocks 集群可以访问相关的 AWS 云资源。

建议使用以下身份验证方法

  • 实例配置文件
  • Assume Role
  • IAM 用户

在上述三种身份验证方法中，实例配置文件使用最广泛。

有关更多信息，请参见 AWS IAM 中身份验证的准备工作。

HDFS​

如果您选择 HDFS 作为存储，请按如下方式配置您的 StarRocks 集群

  • （可选）设置用于访问您的 HDFS 集群和 Hive Metastore 的用户名。默认情况下，StarRocks 使用 FE 和 BE 或 CN 进程的用户名来访问您的 HDFS 集群和 Hive Metastore。您还可以通过在每个 FE 的 fe/conf/hadoop_env.sh 文件开头和每个 BE 的 be/conf/hadoop_env.sh 文件开头或每个 CN 的 cn/conf/hadoop_env.sh 文件开头添加 export HADOOP_USER_NAME="<user_name>" 来设置用户名。在这些文件中设置用户名后，重新启动每个 FE 和每个 BE 或 CN 以使参数设置生效。每个 StarRocks 集群只能设置一个用户名。

  • 当您查询 Hive 数据时，您的 StarRocks 集群的 FE 和 BE 或 CN 使用 HDFS 客户端访问您的 HDFS 集群。在大多数情况下，您不需要配置 StarRocks 集群来实现该目的，并且 StarRocks 使用默认配置启动 HDFS 客户端。仅在以下情况下，您需要配置 StarRocks 集群

    • 您的 HDFS 集群启用了高可用性（HA）：将您的 HDFS 集群的 hdfs-site.xml 文件添加到每个 FE 的 $FE_HOME/conf 路径和每个 BE 的 $BE_HOME/conf 路径或每个 CN 的 $CN_HOME/conf 路径。
    • 您的 HDFS 集群启用了 View File System (ViewFs)：将您的 HDFS 集群的 core-site.xml 文件添加到每个 FE 的 $FE_HOME/conf 路径和每个 BE 的 $BE_HOME/conf 路径或每个 CN 的 $CN_HOME/conf 路径。
注意

如果在发送查询时返回指示未知主机的错误，则必须将您的 HDFS 集群节点的 hostname 和 IP 地址之间的映射添加到 /etc/hosts 路径。

Kerberos 身份验证​

如果您的 HDFS 集群或 Hive Metastore 启用了 Kerberos 身份验证，请按如下方式配置您的 StarRocks 集群

  • 在每个 FE 和每个 BE 或 CN 上运行 kinit -kt keytab_path principal 命令，以从 Key Distribution Center (KDC) 获取 Ticket Granting Ticket (TGT)。要运行此命令，您必须具有访问您的 HDFS 集群和 Hive Metastore 的权限。请注意，使用此命令访问 KDC 对时间敏感。因此，您需要使用 cron 定期运行此命令。
  • 将 JAVA_OPTS="-Djava.security.krb5.conf=/etc/krb5.conf" 添加到每个 FE 的 $FE_HOME/conf/fe.conf 文件和每个 BE 的 $BE_HOME/conf/be.conf 文件或每个 CN 的 $CN_HOME/conf/cn.conf 文件。在此示例中，/etc/krb5.conf 是 krb5.conf 文件的保存路径。您可以根据需要修改路径。

创建 Hive Catalog​

语法​

CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES
(
    "type" = "hive",
    GeneralParams,
    MetastoreParams,
    StorageCredentialParams,
    MetadataUpdateParams
)

参数​

catalog_name​

Hive Catalog 的名称。命名约定如下

  • 该名称可以包含字母、数字 (0-9) 和下划线 (_)。它必须以字母开头。
  • 该名称区分大小写，长度不能超过 1023 个字符。

comment​

Hive Catalog 的描述。此参数是可选的。

type​

您的数据源的类型。将值设置为 hive。

GeneralParams​

一组常规参数。

下表描述了您可以在 GeneralParams 中配置的参数。

参数必需描述
enable_recursive_listing否指定 StarRocks 是否从表及其分区以及表及其分区的物理位置内的子目录中读取数据。有效值：true 和 false。默认值：true。值 true 指定递归列出子目录，值 false 指定忽略子目录。

MetastoreParams​

一组关于 StarRocks 如何与数据源的 Metastore 集成的参数。

Hive Metastore​

如果您选择 Hive Metastore 作为数据源的 Metastore，请按如下方式配置 MetastoreParams

"hive.metastore.type" = "hive",
"hive.metastore.uris" = "<hive_metastore_uri>"
注意

在查询 Hive 数据之前，您必须将 Hive Metastore 节点的 hostname 和 IP 地址之间的映射添加到 /etc/hosts 路径。否则，当您启动查询时，StarRocks 可能无法访问您的 Hive Metastore。

下表描述了您需要在 MetastoreParams 中配置的参数。

参数必需描述
hive.metastore.type是您用于 Hive 集群的 Metastore 的类型。将值设置为 hive。
hive.metastore.uris是您的 Hive Metastore 的 URI。格式：thrift://<metastore_IP_address>:<metastore_port>。
如果您的 Hive Metastore 启用了高可用性（HA），您可以指定多个 Metastore URI，并用逗号 (,) 分隔它们，例如，"thrift://<metastore_IP_address_1>:<metastore_port_1>,thrift://<metastore_IP_address_2>:<metastore_port_2>,thrift://<metastore_IP_address_3>:<metastore_port_3>"。
AWS Glue​

如果您选择 AWS Glue 作为数据源的 Metastore，这仅在您选择 AWS S3 作为存储时才支持，请执行以下操作之一

  • 要选择基于实例配置文件的身份验证方法，请按如下方式配置 MetastoreParams

    "hive.metastore.type" = "glue",
    "aws.glue.use_instance_profile" = "true",
    "aws.glue.region" = "<aws_glue_region>"

  • 要选择基于 Assume Role 的身份验证方法，请按如下方式配置 MetastoreParams

    "hive.metastore.type" = "glue",
    "aws.glue.use_instance_profile" = "true",
    "aws.glue.iam_role_arn" = "<iam_role_arn>",
    "aws.glue.region" = "<aws_glue_region>"

  • 要选择基于 IAM 用户的身份验证方法，请按如下方式配置 MetastoreParams

    "hive.metastore.type" = "glue",
    "aws.glue.use_instance_profile" = "false",
    "aws.glue.access_key" = "<iam_user_access_key>",
    "aws.glue.secret_key" = "<iam_user_secret_key>",
    "aws.glue.region" = "<aws_s3_region>"

下表描述了您需要在 MetastoreParams 中配置的参数。

参数必需描述
hive.metastore.type是您用于 Hive 集群的 Metastore 的类型。将值设置为 glue。
aws.glue.use_instance_profile是指定是否启用基于实例配置文件的身份验证方法和基于 Assume Role 的身份验证。有效值：true 和 false。默认值：false。
aws.glue.iam_role_arn否具有对您的 AWS Glue Data Catalog 权限的 IAM 角色的 ARN。如果您使用基于 Assume Role 的身份验证方法访问 AWS Glue，则必须指定此参数。
aws.glue.region是您的 AWS Glue Data Catalog 所在的区域。示例：us-west-1。
aws.glue.access_key否您的 AWS IAM 用户的访问密钥。如果您使用基于 IAM 用户的身份验证方法访问 AWS Glue，则必须指定此参数。
aws.glue.secret_key否您的 AWS IAM 用户的密钥。如果您使用基于 IAM 用户的身份验证方法访问 AWS Glue，则必须指定此参数。

有关如何选择访问 AWS Glue 的身份验证方法以及如何在 AWS IAM Console 中配置访问控制策略的信息，请参见 访问 AWS Glue 的身份验证参数。

StorageCredentialParams​

一组关于 StarRocks 如何与您的存储系统集成的参数。此参数集是可选的。

如果您使用 HDFS 作为存储，则无需配置 StorageCredentialParams。

如果您使用 AWS S3、其他 S3 兼容的存储系统、Microsoft Azure Storage 或 Google GCS 作为存储，则必须配置 StorageCredentialParams。

AWS S3​

如果您选择 AWS S3 作为您的 Hive 集群的存储，请执行以下操作之一

  • 要选择基于实例配置文件的身份验证方法，请按如下方式配置 StorageCredentialParams

    "aws.s3.use_instance_profile" = "true",
    "aws.s3.region" = "<aws_s3_region>"

  • 要选择基于假设角色的身份验证方法，请按如下方式配置 StorageCredentialParams

    "aws.s3.use_instance_profile" = "true",
    "aws.s3.iam_role_arn" = "<iam_role_arn>",
    "aws.s3.region" = "<aws_s3_region>"

  • 要选择基于 IAM 用户的身份验证方法，请按如下方式配置 StorageCredentialParams

    "aws.s3.use_instance_profile" = "false",
    "aws.s3.access_key" = "<iam_user_access_key>",
    "aws.s3.secret_key" = "<iam_user_secret_key>",
    "aws.s3.region" = "<aws_s3_region>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数必需描述
aws.s3.use_instance_profile是指定是否启用基于实例配置文件的身份验证方法和基于 Assume Role 的身份验证方法。有效值：true 和 false。默认值：false。
aws.s3.iam_role_arn否具有对您的 AWS S3 存储桶权限的 IAM 角色的 ARN。如果您使用基于 Assume Role 的身份验证方法访问 AWS S3，则必须指定此参数。
aws.s3.region是您的 AWS S3 bucket 所在的区域。示例：us-west-1。
aws.s3.access_key否您的 IAM 用户的访问密钥。如果您使用基于 IAM 用户的身份验证方法访问 AWS S3，则必须指定此参数。
aws.s3.secret_key否您的 IAM 用户的密钥。如果您使用基于 IAM 用户的身份验证方法访问 AWS S3，则必须指定此参数。

有关如何选择访问 AWS S3 的身份验证方法以及如何在 AWS IAM Console 中配置访问控制策略的信息，请参见 访问 AWS S3 的身份验证参数。

S3 兼容的存储系统​

Hive Catalog 自 v2.5 版本起支持 S3 兼容的存储系统。

如果您选择 S3 兼容的存储系统（例如，MinIO）作为您的 Hive 集群的存储，请按如下方式配置 StorageCredentialParams 以确保成功集成

"aws.s3.enable_ssl" = "false",
"aws.s3.enable_path_style_access" = "true",
"aws.s3.endpoint" = "<s3_endpoint>",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>"

下表描述了需要在 StorageCredentialParams 中配置的参数。

参数必需描述
aws.s3.enable_ssl是指定是否启用 SSL 连接。
有效值：true 和 false。默认值：true。
aws.s3.enable_path_style_access是指定是否启用 path-style 访问。
有效值：true 和 false。默认值：false。对于 MinIO，您必须将值设置为 true。
Path-style URL 使用以下格式：https://s3.<region_code>.amazonaws.com/<bucket_name>/<key_name>。例如，如果您在美国西部（俄勒冈）区域中创建了一个名为 DOC-EXAMPLE-BUCKET1 的存储桶，并且您想访问该存储桶中的 alice.jpg 对象，则可以使用以下 path-style URL：https://s3.us-west-2.amazonaws.com/DOC-EXAMPLE-BUCKET1/alice.jpg。
aws.s3.endpoint是用于连接到您的 S3 兼容存储系统而不是 AWS S3 的端点。
aws.s3.access_key是您的 IAM 用户的访问密钥。
aws.s3.secret_key是您的 IAM 用户的密钥。
Microsoft Azure Storage​

Hive Catalog 自 v3.0 版本起支持 Microsoft Azure Storage。

Azure Blob Storage​

如果您选择 Blob Storage 作为您的 Hive 集群的存储，请执行以下操作之一

  • 要选择共享密钥身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.blob.storage_account" = "<storage_account_name>",
    "azure.blob.shared_key" = "<storage_account_shared_key>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.blob.storage_account是您的 Blob Storage 帐户的用户名。
    azure.blob.shared_key是您的 Blob Storage 帐户的共享密钥。

  • 要选择 SAS 令牌身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.blob.storage_account" = "<storage_account_name>",
    "azure.blob.container" = "<container_name>",
    "azure.blob.sas_token" = "<storage_account_SAS_token>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.blob.storage_account是您的 Blob Storage 帐户的用户名。
    azure.blob.container是存储数据的 Blob 容器的名称。
    azure.blob.sas_token是用于访问 Blob 存储帐户的 SAS 令牌。
Azure Data Lake Storage Gen2​

如果您选择 Data Lake Storage Gen2 作为您的 Hive 集群的存储，请执行以下操作之一

  • 要选择托管标识身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls2.oauth2_use_managed_identity" = "true",
    "azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
    "azure.adls2.oauth2_client_id" = "<service_client_id>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls2.oauth2_use_managed_identity是指定是否启用托管标识身份验证方法。将值设置为 true。
    azure.adls2.oauth2_tenant_id是您要访问其数据的租户的 ID。
    azure.adls2.oauth2_client_id是托管标识的客户端（应用程序）ID。

  • 要选择共享密钥身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls2.storage_account" = "<storage_account_name>",
    "azure.adls2.shared_key" = "<storage_account_shared_key>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls2.storage_account是您的 Data Lake Storage Gen2 存储帐户的用户名。
    azure.adls2.shared_key是您的 Data Lake Storage Gen2 存储帐户的共享密钥。

  • 要选择服务主体身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls2.oauth2_client_id" = "<service_client_id>",
    "azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
    "azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"

    下表描述了您需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls2.oauth2_client_id是服务主体的客户端（应用程序）ID。
    azure.adls2.oauth2_client_secret是创建的新客户端（应用程序）密钥的值。
    azure.adls2.oauth2_client_endpoint是服务主体或应用程序的 OAuth 2.0 令牌端点 (v1)。
Azure Data Lake Storage Gen1​

如果您选择 Data Lake Storage Gen1 作为您的 Hive 集群的存储，请执行以下操作之一

  • 要选择托管服务标识身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls1.use_managed_service_identity" = "true"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls1.use_managed_service_identity是指定是否启用托管服务标识身份验证方法。将值设置为 true。

  • 要选择服务主体身份验证方法，请按如下方式配置 StorageCredentialParams

    "azure.adls1.oauth2_client_id" = "<application_client_id>",
    "azure.adls1.oauth2_credential" = "<application_client_credential>",
    "azure.adls1.oauth2_endpoint" = "<OAuth_2.0_authorization_endpoint_v2>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数必需描述
    azure.adls1.oauth2_client_id是服务主体的客户端（应用程序）ID。
    azure.adls1.oauth2_credential是创建的新客户端（应用程序）密钥的值。
    azure.adls1.oauth2_endpoint是服务主体或应用程序的 OAuth 2.0 令牌端点 (v1)。
Google GCS​

Hive Catalog 自 v3.0 版本起支持 Google GCS。

如果您选择 Google GCS 作为您的 Hive 集群的存储，请执行以下操作之一

  • 要选择基于 VM 的身份验证方法，请按如下方式配置 StorageCredentialParams

    "gcp.gcs.use_compute_engine_service_account" = "true"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数默认值值 示例描述
    gcp.gcs.use_compute_engine_service_accountfalsetrue指定是否直接使用绑定到您的 Compute Engine 的服务帐户。

  • 要选择基于服务帐户的身份验证方法，请按如下方式配置 StorageCredentialParams

    "gcp.gcs.service_account_email" = "<google_service_account_email>",
    "gcp.gcs.service_account_private_key_id" = "<google_service_private_key_id>",
    "gcp.gcs.service_account_private_key" = "<google_service_private_key>"

    下表描述了需要在 StorageCredentialParams 中配置的参数。

    参数默认值值 示例描述
    gcp.gcs.service_account_email"""user@hello.iam.gserviceaccount.com"在创建服务帐户时生成的 JSON 文件中的电子邮件地址。
    gcp.gcs.service_account_private_key_id"""61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"在创建服务帐户时生成的 JSON 文件中的私钥 ID。
    gcp.gcs.service_account_private_key"""-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"在创建服务帐户时生成的 JSON 文件中的私钥。

  • 要选择基于模拟的身份验证方法，请按如下方式配置 StorageCredentialParams

    • 使 VM 实例模拟服务帐户

      "gcp.gcs.use_compute_engine_service_account" = "true",
      "gcp.gcs.impersonation_service_account" = "<assumed_google_service_account_email>"

      下表描述了需要在 StorageCredentialParams 中配置的参数。

      参数默认值值 示例描述
      gcp.gcs.use_compute_engine_service_accountfalsetrue指定是否直接使用绑定到您的 Compute Engine 的服务帐户。
      gcp.gcs.impersonation_service_account"""hello"您要模拟的服务帐户。

    • 使服务帐户（暂时命名为 meta service account）模拟另一个服务帐户（暂时命名为 data service account）

      "gcp.gcs.service_account_email" = "<google_service_account_email>",
      "gcp.gcs.service_account_private_key_id" = "<meta_google_service_account_email>",
      "gcp.gcs.service_account_private_key" = "<meta_google_service_account_email>",
      "gcp.gcs.impersonation_service_account" = "<data_google_service_account_email>"

      下表描述了需要在 StorageCredentialParams 中配置的参数。

      参数默认值值 示例描述
      gcp.gcs.service_account_email"""user@hello.iam.gserviceaccount.com"在创建元服务帐户时生成的 JSON 文件中的电子邮件地址。
      gcp.gcs.service_account_private_key_id"""61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"在创建元服务帐户时生成的 JSON 文件中的私钥 ID。
      gcp.gcs.service_account_private_key"""-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"在创建元服务帐户时生成的 JSON 文件中的私钥。
      gcp.gcs.impersonation_service_account"""hello"您要模拟的数据服务帐户。

MetadataUpdateParams​

一组关于 StarRocks 如何更新 Hive 缓存元数据的参数。此参数集是可选的。

StarRocks 默认实现 自动异步更新策略。

在大多数情况下，您可以忽略 MetadataUpdateParams，并且无需调整其中的策略参数，因为这些参数的默认值已经为您提供了开箱即用的性能。

但是，如果 Hive 中的数据更新频率很高，您可以调整这些参数以进一步优化自动异步更新的性能。

注意

在大多数情况下，如果您的 Hive 数据以 1 小时或更短的粒度进行更新，则数据更新频率被认为是高的。

参数必需描述
enable_metastore_cache否指定 StarRocks 是否缓存 Hive 表的元数据。有效值：true 和 false。默认值：true。值 true 启用缓存，值 false 禁用缓存。
enable_remote_file_cache否指定 StarRocks 是否缓存 Hive 表或分区的底层数据文件的元数据。有效值：true 和 false。默认值：true。值 true 启用缓存，值 false 禁用缓存。
metastore_cache_refresh_interval_sec否StarRocks 异步更新自身缓存的 Hive 表或分区元数据的时间间隔。单位：秒。默认值：60，即一分钟。自 v3.3.0 起，此属性的默认值已从 7200 更改为 60。
remote_file_cache_refresh_interval_sec否StarRocks 异步更新自身缓存的 Hive 表或分区的底层数据文件元数据的时间间隔。单位：秒。默认值：60。
metastore_cache_ttl_sec否StarRocks 自动丢弃自身缓存的 Hive 表或分区元数据的时间间隔。单位：秒。默认值：86400，即 24 小时。
remote_file_cache_ttl_sec否StarRocks 自动丢弃自身缓存的 Hive 表或分区的底层数据文件元数据的时间间隔。单位：秒。默认值：129600，即 36 小时。
enable_cache_list_names否指定 StarRocks 是否缓存 Hive 分区名称。有效值：true 和 false。默认值：true。值 true 启用缓存，值 false 禁用缓存。

示例​

以下示例根据您使用的 Metastore 类型，创建名为 hive_catalog_hms 或 hive_catalog_glue 的 Hive Catalog，以从您的 Hive 集群中查询数据。

HDFS​

如果您使用 HDFS 作为存储，请运行如下命令

CREATE EXTERNAL CATALOG hive_catalog_hms
PROPERTIES
(
    "type" = "hive",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083"
);

AWS S3​

基于实例配置文件的身份验证​

  • 如果您在 Hive 集群中使用 Hive Metastore，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "aws.s3.use_instance_profile" = "true",
        "aws.s3.region" = "us-west-2"
    );

  • 如果您在 Amazon EMR Hive 集群中使用 AWS Glue，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_glue
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "glue",
        "aws.glue.use_instance_profile" = "true",
        "aws.glue.region" = "us-west-2",
        "aws.s3.use_instance_profile" = "true",
        "aws.s3.region" = "us-west-2"
    );
基于 Assume Role 的身份验证​

  • 如果您在 Hive 集群中使用 Hive Metastore，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "aws.s3.use_instance_profile" = "true",
        "aws.s3.iam_role_arn" = "arn:aws:iam::081976408565:role/test_s3_role",
        "aws.s3.region" = "us-west-2"
    );

  • 如果您在 Amazon EMR Hive 集群中使用 AWS Glue，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_glue
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "glue",
        "aws.glue.use_instance_profile" = "true",
        "aws.glue.iam_role_arn" = "arn:aws:iam::081976408565:role/test_glue_role",
        "aws.glue.region" = "us-west-2",
        "aws.s3.use_instance_profile" = "true",
        "aws.s3.iam_role_arn" = "arn:aws:iam::081976408565:role/test_s3_role",
        "aws.s3.region" = "us-west-2"
    );
基于 IAM 用户的身份验证​

  • 如果您在 Hive 集群中使用 Hive Metastore，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "aws.s3.use_instance_profile" = "false",
        "aws.s3.access_key" = "<iam_user_access_key>",
        "aws.s3.secret_key" = "<iam_user_access_key>",
        "aws.s3.region" = "us-west-2"
    );

  • 如果您在 Amazon EMR Hive 集群中使用 AWS Glue，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_glue
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "glue",
        "aws.glue.use_instance_profile" = "false",
        "aws.glue.access_key" = "<iam_user_access_key>",
        "aws.glue.secret_key" = "<iam_user_secret_key>",
        "aws.glue.region" = "us-west-2",
        "aws.s3.use_instance_profile" = "false",
        "aws.s3.access_key" = "<iam_user_access_key>",
        "aws.s3.secret_key" = "<iam_user_secret_key>",
        "aws.s3.region" = "us-west-2"
    );

S3 兼容的存储系统​

以 MinIO 为例。运行如下命令

CREATE EXTERNAL CATALOG hive_catalog_hms
PROPERTIES
(
    "type" = "hive",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "aws.s3.enable_ssl" = "true",
    "aws.s3.enable_path_style_access" = "true",
    "aws.s3.endpoint" = "<s3_endpoint>",
    "aws.s3.access_key" = "<iam_user_access_key>",
    "aws.s3.secret_key" = "<iam_user_secret_key>"
);

Microsoft Azure Storage​

Azure Blob Storage​

  • 如果您选择 Shared Key 身份验证方法，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "azure.blob.storage_account" = "<blob_storage_account_name>",
        "azure.blob.shared_key" = "<blob_storage_account_shared_key>"
    );

  • 如果您选择 SAS Token 身份验证方法，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "azure.blob.storage_account" = "<blob_storage_account_name>",
        "azure.blob.container" = "<blob_container_name>",
        "azure.blob.sas_token" = "<blob_storage_account_SAS_token>"
    );
Azure Data Lake Storage Gen1​

  • 如果您选择 Managed Service Identity 身份验证方法，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "azure.adls1.use_managed_service_identity" = "true"    
    );

  • 如果您选择 Service Principal 身份验证方法，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "azure.adls1.oauth2_client_id" = "<application_client_id>",
        "azure.adls1.oauth2_credential" = "<application_client_credential>",
        "azure.adls1.oauth2_endpoint" = "<OAuth_2.0_authorization_endpoint_v2>"
    );
Azure Data Lake Storage Gen2​

  • 如果您选择 Managed Identity 身份验证方法，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "azure.adls2.oauth2_use_managed_identity" = "true",
        "azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
        "azure.adls2.oauth2_client_id" = "<service_client_id>"
    );

  • 如果您选择 Shared Key 身份验证方法，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "azure.adls2.storage_account" = "<storage_account_name>",
        "azure.adls2.shared_key" = "<shared_key>"     
    );

  • 如果您选择 Service Principal 身份验证方法，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "azure.adls2.oauth2_client_id" = "<service_client_id>",
        "azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
        "azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"
    );

Google GCS​

  • 如果您选择基于 VM 的身份验证方法，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "gcp.gcs.use_compute_engine_service_account" = "true"    
    );

  • 如果您选择基于服务帐户的身份验证方法，请运行如下命令

    CREATE EXTERNAL CATALOG hive_catalog_hms
    PROPERTIES
    (
        "type" = "hive",
        "hive.metastore.type" = "hive",
        "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
        "gcp.gcs.service_account_email" = "<google_service_account_email>",
        "gcp.gcs.service_account_private_key_id" = "<google_service_private_key_id>",
        "gcp.gcs.service_account_private_key" = "<google_service_private_key>"    
    );

  • 如果您选择基于 Impersonation 的身份验证方法

    • 如果您使 VM 实例模拟服务帐户，请运行如下命令

      CREATE EXTERNAL CATALOG hive_catalog_hms
      PROPERTIES
      (
          "type" = "hive",
          "hive.metastore.type" = "hive",
          "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
          "gcp.gcs.use_compute_engine_service_account" = "true",
          "gcp.gcs.impersonation_service_account" = "<assumed_google_service_account_email>"    
      );

    • 如果您使服务帐户模拟另一个服务帐户，请运行如下命令

      CREATE EXTERNAL CATALOG hive_catalog_hms
      PROPERTIES
      (
          "type" = "hive",
          "hive.metastore.type" = "hive",
          "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
          "gcp.gcs.service_account_email" = "<google_service_account_email>",
          "gcp.gcs.service_account_private_key_id" = "<meta_google_service_account_email>",
          "gcp.gcs.service_account_private_key" = "<meta_google_service_account_email>",
          "gcp.gcs.impersonation_service_account" = "<data_google_service_account_email>"    
      );

查看 Hive Catalog​

您可以使用 SHOW CATALOGS 查询当前 StarRocks 集群中的所有 Catalog

SHOW CATALOGS;

您还可以使用 SHOW CREATE CATALOG 查询外部 Catalog 的创建语句。以下示例查询名为 hive_catalog_glue 的 Hive Catalog 的创建语句

SHOW CREATE CATALOG hive_catalog_glue;

切换到 Hive Catalog 及其中的数据库​

您可以使用以下方法之一来切换到 Hive Catalog 及其中的数据库

  • 使用 SET CATALOG 在当前会话中指定 Hive Catalog，然后使用 USE 指定活动数据库

    -- Switch to a specified catalog in the current session:
    SET CATALOG <catalog_name>
    -- Specify the active database in the current session:
    USE <db_name>

  • 直接使用 USE 切换到 Hive Catalog 及其中的数据库

    USE <catalog_name>.<db_name>

删除 Hive Catalog​

您可以使用 DROP CATALOG 删除外部 Catalog。

以下示例删除名为 hive_catalog_glue 的 Hive Catalog

DROP Catalog hive_catalog_glue;

查看 Hive 表的 Schema​

您可以使用以下语法之一来查看 Hive 表的 Schema

  • 查看 Schema

    DESC[RIBE] <catalog_name>.<database_name>.<table_name>

  • 从 CREATE 语句中查看 Schema 和 Location

    SHOW CREATE TABLE <catalog_name>.<database_name>.<table_name>

查询 Hive 表​

  1. 使用 SHOW DATABASES 查看您的 Hive 集群中的数据库

    SHOW DATABASES FROM <catalog_name>

  2. 切换到 Hive Catalog 及其中的数据库.

  3. 使用 SELECT 查询指定数据库中的目标表

    SELECT count(*) FROM <table_name> LIMIT 10

从 Hive 加载数据​

假设您有一个名为 olap_tbl 的 OLAP 表，您可以转换和加载数据，如下所示

INSERT INTO default_catalog.olap_db.olap_tbl SELECT * FROM hive_table

授予 Hive 表和视图的权限​

您可以使用 GRANT 语句将 Hive Catalog 中所有表和视图的权限授予特定角色。命令语法如下

GRANT SELECT ON ALL TABLES IN ALL DATABASES TO ROLE <role_name>

例如，使用以下命令创建一个名为 hive_role_table 的角色，切换到 Hive Catalog hive_catalog，然后授予角色 hive_role_table 查询 Hive Catalog hive_catalog 中所有表和视图的权限

-- Create a role named hive_role_table.
CREATE ROLE hive_role_table;

-- Switch to the Hive catalog hive_catalog.
SET CATALOG hive_catalog;

-- Grant the role hive_role_table the privilege to query all tables and views within the Hive catalog hive_catalog.
GRANT SELECT ON ALL TABLES IN ALL DATABASES TO ROLE hive_role_table;

创建 Hive 数据库​

与 StarRocks 的内部 Catalog 类似，如果您对 Hive Catalog 具有 CREATE DATABASE 权限，则可以使用 CREATE DATABASE 语句在该 Hive Catalog 中创建数据库。此功能自 v3.2 版本起支持。

注意

您可以使用 GRANT 和 REVOKE 授予和撤销权限。

注意

切换到 Hive Catalog，然后使用以下语句在该 Catalog 中创建 Hive 数据库

CREATE DATABASE <database_name>
[PROPERTIES ("location" = "<prefix>://<path_to_database>/<database_name.db>")]

location 参数指定您要在其中创建数据库的文件路径，该路径可以是 HDFS 或云存储。

  • 当您使用 Hive Metastore 作为 Hive 集群的 Metastore 时，如果您在数据库创建时未指定该参数，则 location 参数默认为 <warehouse_location>/<database_name.db>，Hive Metastore 支持此默认值。
  • 当您使用 AWS Glue 作为 Hive 集群的 Metastore 时，location 参数没有默认值，因此您必须在数据库创建时指定该参数。

prefix 的变化取决于您使用的存储系统

存储系统Prefix 值
HDFShdfs
Google GCSgs
Azure Blob Storage
  • 如果您的存储帐户允许通过 HTTP 访问，则 prefix 为 wasb。
  • 如果您的存储帐户允许通过 HTTPS 访问，则 prefix 为 wasbs。
Azure Data Lake Storage Gen1adl
Azure Data Lake Storage Gen2
  • 如果您的存储帐户允许通过 HTTP 访问，则 prefix 为 abfs。
  • 如果您的存储帐户允许通过 HTTPS 访问，则 prefix 为 abfss。
AWS S3 或其他 S3 兼容的存储（例如，MinIO）s3

删除 Hive 数据库​

与 StarRocks 的内部数据库类似，如果您对 Hive 数据库具有 DROP 权限，则可以使用 DROP DATABASE 语句删除该 Hive 数据库。此功能自 v3.2 版本起支持。您只能删除空数据库。

注意

您可以使用 GRANT 和 REVOKE 授予和撤销权限。

当您删除 Hive 数据库时，数据库在 HDFS 集群或云存储上的文件路径不会随数据库一起删除。

切换到 Hive Catalog，然后使用以下语句删除该 Catalog 中的 Hive 数据库

DROP DATABASE <database_name>

创建 Hive 表​

与 StarRocks 的内部数据库类似，如果您对 Hive 数据库具有 CREATE TABLE 权限，则可以使用 CREATE TABLE、[CREATE TABLE AS SELECT ../../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_AS_SELECT.mdELECT.md) 或 [CREATE TABL../../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_LIKE.md_LIKE.md) 语句在该 Hive 数据库中创建托管表。

此功能自 v3.2 版本起支持，其中 StarRocks 仅支持创建 Parquet 格式的 Hive 表。从 v3.3 开始，StarRocks 还支持创建 ORC 和 Textfile 格式的 Hive 表。

注意
  • 您可以使用 GRANT 和 REVOKE 授予和撤销权限。
  • Hive Catalog 自 v3.2.4 版本起支持 CREATE TABLE LIKE。

切换到 Hive Catalog 及其中的数据库，然后使用以下语法在该数据库中创建 Hive 托管表。

语法​

CREATE TABLE [IF NOT EXISTS] [database.]table_name
(column_definition1[, column_definition2, ...
partition_column_definition1,partition_column_definition2...])
[partition_desc]
[PROPERTIES ("key" = "value", ...)]
[AS SELECT query]
[LIKE [database.]<source_table_name>]

参数​

column_definition​

column_definition 的语法如下

col_name col_type [COMMENT 'comment']

下表描述了参数。

参数描述
col_name列的名称。
col_type列的数据类型。支持以下数据类型：TINYINT、SMALLINT、INT、BIGINT、FLOAT、DOUBLE、DECIMAL、DATE、DATETIME、CHAR、VARCHAR[(length)]、ARRAY、MAP 和 STRUCT。不支持 LARGEINT、HLL 和 BITMAP 数据类型。

注意

所有非分区列必须使用 NULL 作为默认值。这意味着您必须为表创建语句中的每个非分区列指定 DEFAULT "NULL"。此外，分区列必须定义在非分区列之后，并且不能使用 NULL 作为默认值。

partition_desc​

partition_desc 的语法如下

PARTITION BY (par_col1[, par_col2...])

目前，StarRocks 仅支持 identity transforms，这意味着 StarRocks 为每个唯一的分区值创建一个分区。

注意

分区列必须定义在非分区列之后。分区列支持除 FLOAT、DOUBLE、DECIMAL 和 DATETIME 之外的所有数据类型，并且不能使用 NULL 作为默认值。此外，在 partition_desc 中声明的分区列的顺序必须与 column_definition 中定义的列的顺序一致。

PROPERTIES​

您可以在 properties 中以 "key" = "value" 格式指定表属性。

下表描述了一些关键属性。

属性描述
location您要在其中创建托管表的文件路径。 当您使用 HMS 作为 Metastore 时，您无需指定 location 参数，因为 StarRocks 将在当前 Hive Catalog 的默认文件路径中创建表。当您使用 AWS Glue 作为元数据服务时
  • 如果您已为您要在其中创建表的数据库指定了 location 参数，则无需为表指定 location 参数。 这样，表默认使用其所属数据库的文件路径。
  • 如果您尚未为您要在其中创建表的数据库指定 location，则必须为表指定 location 参数。
file_format托管表的文件格式。 支持的文件格式为 Parquet、ORC 和 Textfile。 从 v3.3 开始支持 ORC 和 Textfile 格式。 有效值：parquet、orc 和 textfile。 默认值：parquet。
compression_codec用于托管表的压缩算法。 此属性在 v3.2.3 中已弃用，自该版本起，用于将数据 Sink 到 Hive 表的压缩算法统一由会话变量 connector_sink_compression_codec 控制。

示例​

以下 DDL 使用默认文件格式 Parquet 作为示例。

  1. 创建一个名为 unpartition_tbl 的非分区表。 该表由两列组成，分别为 id 和 score，如下所示

    CREATE TABLE unpartition_tbl
    (
        id int,
        score double
    );

  2. 创建一个名为 partition_tbl_1 的分区表。 该表由三列组成，分别为 action、id 和 dt，其中 id 和 dt 被定义为分区列，如下所示

    CREATE TABLE partition_tbl_1
    (
        action varchar(20),
        id int,
        dt date
    )
    PARTITION BY (id,dt);

  3. 查询一个名为 partition_tbl_1 的现有表，并根据 partition_tbl_1 的查询结果创建一个名为 partition_tbl_2 的分区表。 对于 partition_tbl_2，id 和 dt 被定义为分区列，如下所示

    CREATE TABLE partition_tbl_2
    PARTITION BY (k1, k2)
    AS SELECT * from partition_tbl_1;

将数据 Sink 到 Hive 表​

与 StarRocks 的内部表类似，如果您拥有 Hive 表（可以是托管表或外部表）的 INSERT 权限，则可以使用 INSERT 语句将 StarRocks 表的数据 Sink 到该 Hive 表。

此功能自 v3.2 起支持，在该版本中，数据只能 Sink 到 Parquet 格式的 Hive 表。 从 v3.3 开始，StarRocks 还支持将数据 Sink 到 ORC 和 Textfile 格式的 Hive 表。

请注意，默认情况下禁用将数据 Sink 到外部表。 要将数据 Sink 到外部表，您必须将 系统变量 ENABLE_WRITE_HIVE_EXTERNAL_TABLE 设置为 true。

注意

切换到 Hive Catalog 及其中的数据库，然后使用以下语法将 StarRocks 表的数据 Sink 到该数据库中的 Parquet 格式的 Hive 表。

语法​

INSERT {INTO | OVERWRITE} <table_name>
[ (column_name [, ...]) ]
{ VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }

-- If you want to sink data to specified partitions, use the following syntax:
INSERT {INTO | OVERWRITE} <table_name>
PARTITION (par_col1=<value> [, par_col2=<value>...])
{ VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }

注意

分区列不允许 NULL 值。 因此，您必须确保没有空值加载到 Hive 表的分区列中。

参数​

参数描述
INTO将 StarRocks 表的数据追加到 Hive 表。
OVERWRITE使用 StarRocks 表的数据覆盖 Hive 表的现有数据。
column_name您要加载数据的目标列的名称。 您可以指定一列或多列。 如果您指定多列，请用逗号 (,) 分隔它们。 您只能指定实际存在于 Hive 表中的列，并且您指定的目标列必须包括 Hive 表的分区列。 您指定的目标列按顺序一一映射到 StarRocks 表的列，而不管目标列名称是什么。 如果未指定目标列，则数据将加载到 Hive 表的所有列中。 如果 StarRocks 表的非分区列无法映射到 Hive 表的任何列，StarRocks 会将默认值 NULL 写入 Hive 表列。 如果 INSERT 语句包含查询语句，其返回的列类型与目标列的数据类型不同，StarRocks 会对不匹配的列执行隐式转换。 如果转换失败，将返回语法解析错误。
expression将值分配给目标列的表达式。
DEFAULT为目标列分配一个默认值。
query其结果将被加载到 Hive 表中的查询语句。 它可以是 StarRocks 支持的任何 SQL 语句。
PARTITION您要加载数据的分区。 您必须在此属性中指定 Hive 表的所有分区列。 您在此属性中指定的分区列的顺序可以与您在表创建语句中定义的分区列的顺序不同。 如果您指定此属性，则无法指定 column_name 属性。

示例​

以下 DML 使用默认文件格式 Parquet 作为示例。

  1. 将三行数据插入到 partition_tbl_1 表中

    INSERT INTO partition_tbl_1
    VALUES
        ("buy", 1, "2023-09-01"),
        ("sell", 2, "2023-09-02"),
        ("buy", 3, "2023-09-03");

  2. 将包含简单计算的 SELECT 查询的结果插入到 partition_tbl_1 表中

    INSERT INTO partition_tbl_1 (id, action, dt) SELECT 1+1, 'buy', '2023-09-03';

  3. 将从 partition_tbl_1 表读取数据的 SELECT 查询的结果插入到同一表中

    INSERT INTO partition_tbl_1 SELECT 'buy', 1, date_add(dt, INTERVAL 2 DAY)
    FROM partition_tbl_1
    WHERE id=1;

  4. 将 SELECT 查询的结果插入到满足两个条件 dt='2023-09-01' 和 id=1 的 partition_tbl_2 表的分区中

    INSERT INTO partition_tbl_2 SELECT 'order', 1, '2023-09-01';

    或

    INSERT INTO partition_tbl_2 partition(dt='2023-09-01',id=1) SELECT 'order';

  5. 将 partition_tbl_1 表中满足两个条件 dt='2023-09-01' 和 id=1 的分区中的所有 action 列值覆盖为 close

    INSERT OVERWRITE partition_tbl_1 SELECT 'close', 1, '2023-09-01';

    或

    INSERT OVERWRITE partition_tbl_1 partition(dt='2023-09-01',id=1) SELECT 'close';

删除 Hive 表​

与 StarRocks 的内部表类似，如果您拥有 Hive 表的 DROP 权限，则可以使用 DROP TABLE 语句删除该 Hive 表。 此功能自 v3.1 起支持。 请注意，目前 StarRocks 仅支持删除 Hive 的托管表。

注意

您可以使用 GRANT 和 REVOKE 授予和撤销权限。

删除 Hive 表时，必须在 DROP TABLE 语句中指定 FORCE 关键字。 操作完成后，表的文​​件路径将被保留，但 HDFS 集群或云存储上的表数据将随表一起全部删除。 执行此操作以删除 Hive 表时请务必小心。

切换到 Hive Catalog 及其中的数据库，然后使用以下语句删除该数据库中的 Hive 表。

DROP TABLE <table_name> FORCE

手动或自动更新元数据缓存​

手动更新​

默认情况下，StarRocks 会缓存 Hive 的元数据，并以异步模式自动更新元数据以提供更好的性能。 此外，在对 Hive 表进行一些架构更改或表更新后，您还可以使用 REFRESH EXTERNAL TABLE 手动更新其元数据，从而确保 StarRocks 可以在最早的时间获得最新的元数据并生成合适的执行计划

REFRESH EXTERNAL TABLE <table_name> [PARTITION ('partition_name', ...)]

在以下情况下，您需要手动更新元数据

  • 现有分区中的数据文件已更改，例如，通过运行 INSERT OVERWRITE ... PARTITION ... 命令。

  • 对 Hive 表进行架构更改。

  • 通过使用 DROP 语句删除现有 Hive 表，并创建一个与已删除的 Hive 表同名的新 Hive 表。

  • 您已在创建 Hive Catalog 时在 PROPERTIES 中指定 "enable_cache_list_names" = "true"，并且您想查询您刚刚在 Hive 集群上创建的新分区。

    注意

    从 v2.5.5 开始，StarRocks 提供了定期 Hive 元数据缓存刷新功能。 有关更多信息，请参见本主题的以下“定期刷新元数据缓存”部分。 启用此功能后，StarRocks 默认每 10 分钟刷新一次 Hive 元数据缓存。 因此，在大多数情况下，不需要手动更新。 只有当您想在 Hive 集群上创建新分区后立即查询新分区时，才需要执行手动更新。

请注意，REFRESH EXTERNAL TABLE 仅刷新 FE 中缓存的表和分区。

定期刷新元数据缓存​

从 v2.5.5 开始，StarRocks 可以定期刷新频繁访问的 Hive Catalog 的缓存元数据，以感知数据更改。 您可以通过以下 FE 参数配置 Hive 元数据缓存刷新

配置项默认描述
enable_background_refresh_connector_metadatav3.0 中为 true
v2.5 中为 false		是否启用定期 Hive 元数据缓存刷新。 启用后，StarRocks 会轮询 Hive 集群的 Metastore（Hive Metastore 或 AWS Glue），并刷新频繁访问的 Hive Catalog 的缓存元数据以感知数据更改。 true 表示启用 Hive 元数据缓存刷新，false 表示禁用它。 此项是 FE 动态参数。 您可以使用 ADMIN SET FRONTEND CONFIG 命令修改它。
background_refresh_metadata_interval_millis600000（10 分钟）两次连续 Hive 元数据缓存刷新之间的间隔。 单位：毫秒。 此项是 FE 动态参数。 您可以使用 ADMIN SET FRONTEND CONFIG 命令修改它。
background_refresh_metadata_time_secs_since_last_access_secs86400（24 小时）Hive 元数据缓存刷新任务的过期时间。 对于已访问的 Hive Catalog，如果超过指定时间未被访问，StarRocks 会停止刷新其缓存的元数据。 对于未访问的 Hive Catalog，StarRocks 不会刷新其缓存的元数据。 单位：秒。 此项是 FE 动态参数。 您可以使用 ADMIN SET FRONTEND CONFIG 命令修改它。

一起使用定期 Hive 元数据缓存刷新功能和元数据自动异步更新策略可以显着加快数据访问速度，减少来自外部数据源的读取负载并提高查询性能。

附录：了解元数据自动异步更新​

自动异步更新是 StarRocks 用于更新 Hive Catalog 中元数据的默认策略。

默认情况下（即，当 enable_metastore_cache 和 enable_remote_file_cache 参数都设置为 true 时），如果查询命中 Hive 表的分区，StarRocks 会自动缓存该分区的元数据以及该分区底层数据文件的元数据。 缓存的元数据通过使用惰性更新策略进行更新。

例如，有一个名为 table2 的 Hive 表，它有四个分区：p1、p2、p3 和 p4。 查询命中 p1，StarRocks 会缓存 p1 的元数据以及 p1 底层数据文件的元数据。 假设更新和丢弃缓存的元数据的默认时间间隔如下

  • 异步更新 p1 的缓存元数据的时间间隔（由 metastore_cache_refresh_interval_sec 参数指定）为 60 秒。
  • 异步更新 p1 的底层数据文件的缓存元数据的时间间隔（由 remote_file_cache_refresh_interval_sec 参数指定）为 60 秒。
  • 自动丢弃 p1 的缓存元数据的时间间隔（由 metastore_cache_ttl_sec 参数指定）为 24 小时。
  • 自动丢弃 p1 的底层数据文件的缓存元数据的时间间隔（由 remote_file_cache_ttl_sec 参数指定）为 36 小时。

下图显示了时间线上的时间间隔，以便于理解。

Timeline for updating and discarding cached metadata

然后，StarRocks 会按照以下规则更新或丢弃元数据

  • 如果另一个查询再次命中 p1，并且自上次更新以来的当前时间少于 60 秒，则 StarRocks 不会更新 p1 的缓存元数据或 p1 的底层数据文件的缓存元数据。
  • 如果另一个查询再次命中 p1，并且自上次更新以来的当前时间超过 60 秒，则 StarRocks 会更新 p1 的缓存元数据以及 p1 的底层数据文件的缓存元数据。
  • 如果在 24 小时内访问过该表，则相关缓存将每 10 分钟在后台刷新一次。
  • 如果自上次更新以来 24 小时内未访问 p1，则 StarRocks 会丢弃 p1 的缓存元数据。 元数据将在下次查询时被缓存。
  • 如果自上次更新以来 36 小时内未访问 p1，则 StarRocks 会丢弃 p1 的底层数据文件的缓存元数据。 元数据将在下次查询时被缓存。