REST Resource: iceberg.v1.restcatalog.extensions.projects.catalogs

Resource: IcebergCatalog

The Iceberg REST Catalog information.

JSON representation 
{
  "name": string,
  "credential-mode": enum (CredentialMode),
  "biglake-service-account": string,
  "biglake-service-account-id": string,
  "catalog-type": enum (CatalogType),
  "default-location": string,
  "storage-regions": [
    string
  ],
  "create-time": string,
  "update-time": string,
  "replicas": [
    {
      object (Replica)
    }
  ],
  "description": string,
  "restricted-locations-config": {
    object (RestrictedLocationsConfig)
  },
  "federated-catalog-options": {
    object (FederatedCatalogOptions)
  },
  "cross-cloud-cache-options": {
    object (CrossCloudCacheOptions)
  },
  "encryption-config": {
    object (EncryptionConfig)
  }
}
Fields
name

string

Identifier. The catalog name, projects/my-project/catalogs/my-catalog. This field is immutable. This field is ignored for catalogs.create.
credential-mode

enum (CredentialMode)

Optional. The credential mode for the catalog.
biglake-service-account

string

Output only. The service account used for credential vending, output only. Might be empty if credential vending is never enabled for the catalog.

For federated catalogs, the service account will be always provisioned and is used to access the remote catalog for background metadata refresh. If google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.IdentityMode is set to IDENTITY_MODE_SERVICE_IDENTITY, it will be used for queries as well.
biglake-service-account-id

string

Output only. The unique ID of the service account. This is used for federation scenarios.
catalog-type

enum (CatalogType)

Required. The catalog type. Required for catalogs.create. Catalog type is immutable, except for the case of conversion from CATALOG_TYPE_GCS_BUCKET to CATALOG_TYPE_BIGLAKE.
default-location

string

Optional. The default storage location for the catalog, e.g., gs://my-bucket. For Google Cloud Storage bucket catalogs, this is output only.

For BigLake catalogs, this field must be provided and point to a Google Cloud Storage bucket or a path within that bucket. This path serves as the base directory for constructing the full path to a table's data and metadata directories when a location is not specified at the namespace or table level. The full path is formed by appending the namespace and table identifiers to the default location.
storage-regions[]

string

Output only. The GCP region(s) of the default location's bucket, e.g. us-central1, nam4 or us. This will contain one value for all locations, except for the catalogs that are configured to use custom dual region buckets, in which case it will contain the two regions of the bucket. The region(s) of this field should be in the jurisdiction of or nearby the primary location of the catalog.
create-time

string (Timestamp format)

Output only. When the catalog was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
update-time

string (Timestamp format)

Output only. When the catalog was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
replicas[]

object (Replica)

Output only. The replicas for the catalog metadata.
description

string

Optional. A user-provided description of the catalog. The description must be a UTF-8 string with a maximum length of 1024 characters.
restricted-locations-config

object (RestrictedLocationsConfig)

Optional. Restricted locations configuration. This field is currently only used for BigLake catalogs.

If this field is unset, or if restrictedLocationsConfig.restricted_locations is empty, all accessible locations are allowed. If restrictedLocationsConfig.restricted_locations is not empty, only locations in defaultLocation and restrictedLocationsConfig.restricted_locations are allowed.
federated-catalog-options

object (FederatedCatalogOptions)

Optional. Configuration options for federated catalogs.
cross-cloud-cache-options

object (CrossCloudCacheOptions)

Optional. Configuration options for cross-cloud caching of data and metadata files.
encryption-config

object (EncryptionConfig)

Optional. Custom encryption configuration (e.g., Cloud KMS keys).

CredentialMode

The credential mode used for the catalog.

Enums
CREDENTIAL_MODE_UNSPECIFIED Default/unset value. This value is unused.
CREDENTIAL_MODE_END_USER End user credentials mode, default. The authenticating user must have access to the catalog resources and the underlying Google Cloud Storage objects.
CREDENTIAL_MODE_VENDED_CREDENTIALS

Credential vending mode. The authenticating user only needs access to the catalog resources and the system will provide the caller with downscoped credentials to access the Google Cloud Storage objects. All table operations in this mode require the X-Iceberg-Access-Delegation header to be set as vended-credentials. The system will generate a service account in google.cloud.biglake.v1main.IcebergCatalog.biglake_service_account, which the catalog administrator must grant Google Cloud Storage object access to.

See https://docs.cloud.google.com/lakehouse/docs/credential-vending for more details.

CatalogType

Determines the catalog type.

Enums
CATALOG_TYPE_UNSPECIFIED Default/unset value. This value is unused.
CATALOG_TYPE_GCS_BUCKET Google Cloud Storage bucket catalog type.
CATALOG_TYPE_BIGLAKE BigLake catalog type.
CATALOG_TYPE_FEDERATED Federated catalog type.

Replica

The replica of the Catalog.

JSON representation 
{
  "region": string,
  "state": enum (State)
}
Fields
region

string

Output only. The region of the replica. For example "us-east1"
state

enum (State)

Output only. The current state of the replica.

State

If the catalog is replicated to multiple regions, this enum describes the current state of the replica.

Enums
STATE_UNKNOWN Default/unset value. This value is unused.
STATE_PRIMARY The replica is the writable primary.
STATE_PRIMARY_IN_PROGRESS The replica has been recently assigned as the primary, but not all namespaces are writeable yet.
STATE_SECONDARY The replica is a read-only secondary replica.

RestrictedLocationsConfig

Configuration of location restrictions.

JSON representation 
{
  "restricted-locations": [
    string
  ]
}
Fields
restricted-locations[]

string

Optional. Additional Google Cloud Storage buckets and locations (e.g., gs://my-other-bucket/...) that are permitted for use by resources within a catalog. This field is currently only used for BigLake catalogs.

If restrictedLocations is empty and unrestricted catalog creation is enabled, all accessible locations are allowed. Otherwise, only defaultLocation and locations in this list are allowed.

EncryptionConfig

Custom encryption configuration (e.g., Cloud KMS keys).

JSON representation 
{
  "kms-key-name": string
}
Fields
kms-key-name

string

Optional. Cloud KMS key name used to encrypt cached data fetched from the catalog. Format: projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}

FederatedCatalogOptions

Configuration options for a federated catalog.

JSON representation 
{
  "refresh-options": {
    object (RefreshOptions)
  },
  "refresh-status": {
    object (RefreshStatus)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "unity-catalog-info": {
    object (UnityCatalogInfo)
  },
  "glue-catalog-info": {
    object (GlueCatalogInfo)
  },
  "snowflake-catalog-info": {
    object (SnowflakeCatalogInfo)
  },
  "workday-catalog-info": {
    object (WorkdayCatalogInfo)
  }
  // End of mutually exclusive fields.
  "secret-name": string,
  "service-directory-name": string
}
Fields
refresh-options

object (RefreshOptions)

Optional. Refresh configuration.
refresh-status

object (RefreshStatus)

Output only. The status of the background metadata refresh operations.
Information specific to the remote Iceberg REST catalog. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
unity-catalog-info

object (UnityCatalogInfo)

Optional. Information specific to Databricks Unity Catalog.
glue-catalog-info

object (GlueCatalogInfo)

Optional. Information specific to AWS Glue Data Catalog.
snowflake-catalog-info

object (SnowflakeCatalogInfo)

Optional. Information specific to Snowflake Horizon Catalog.
workday-catalog-info

object (WorkdayCatalogInfo)

Optional. Information specific to Workday Data Lake.
End of mutually exclusive fields.
secret-name

string

Optional. The secret resource name in Secret Manager, in the format projects/{projectId}/locations/{location}/secrets/{secret_id} or projects/{projectId}/locations/{location}/secrets/{secret_id}/versions/{version_id}.

The project ID must match the catalog's project and the location must match the catalog's location. If the version is not specified, the latest version is used.

This field is not used when google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.UnityCatalogInfo.service_principal_application_id or google.cloud.biglake.v1main.IcebergCatalog.FederatedCatalogOptions.SnowflakeCatalogInfo.snowflake_role is set.
service-directory-name

string

Optional. The Service Directory resource name used to route transport layer traffic with the remote catalog (e.g. data file access in storage buckets) over a private network connection.

Format: projects/{projectId}/locations/{locationId}/namespaces/{namespace_id}/services/{serviceId}

This is used by BigQuery queries to resolve private endpoints for fetching data files (e.g., Iceberg data in S3 or Azure Data Lake Storage) via a private network connection such as Cross-Cloud Interconnect.

UnityCatalogInfo

Information specific to Databricks Unity Catalog. The Iceberg REST Catalog endpoint is of the form: https://<instanceName>/api/2.1/unity-catalog/iceberg-rest/v1/config?warehouse=<catalogName>.

JSON representation 
{
  "instance-name": string,
  "catalog-name": string,
  "service-principal-application-id": string
}
Fields
instance-name

string

Required. Immutable. The instance name of the Databricks workspace. For example, for the Databricks workspace URL https://1.1.gcp.databricks.com, the instance name is 1.1.gcp.databricks.com.
catalog-name

string

Required. Immutable. The name of the catalog in Databricks Unity Catalog.
service-principal-application-id

string

Optional. The application ID of the Databricks service principal used to access Databricks Unity Catalog in the OIDC authentication flow.

GlueCatalogInfo

Information specific to AWS Glue Data Catalog. The Iceberg REST Catalog endpoint is of the form: https://glue.<awsRegion>.amazonaws.com/iceberg/v1/config?warehouse=<warehouse>.

JSON representation 
{
  "warehouse": string,
  "aws-region": string,
  "aws-role-arn": string
}
Fields
warehouse

string

Required. Immutable. The warehouse location in AWS Glue Data Catalog.

For the default account catalog, use the 12-digit AWS account ID (for example, 111222333444). For an Amazon S3 table bucket, use the format <account_id>:s3tablescatalog/<table_bucket_name> (for example, 111222333444:s3tablescatalog/my-table-bucket).
aws-region

string

Required. Immutable. The AWS region of the AWS Glue Data Catalog (for example, us-east-1). The federated catalog's region should be in the same geographical location and jurisdiction as the AWS region for the best performance.
aws-role-arn

string

Required. The Amazon Resource Name (ARN) of the AWS IAM role that the federated catalog assumes to access the AWS Glue Data Catalog.

SnowflakeCatalogInfo

Information specific to Snowflake Horizon Catalog. The Iceberg REST Catalog endpoint is of the form: https://<accountIdentifier>.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<warehouse>.

JSON representation 
{
  "account-identifier": string,
  "warehouse": string,
  "snowflake-role": string
}
Fields
account-identifier

string

Required. Immutable. The account identifier in Snowflake. For example, for the Snowflake deployment URL https://myorg-myaccount.snowflakecomputing.com, the account identifier is myorg-myaccount.
warehouse

string

Required. Immutable. The database name in Snowflake Horizon Catalog.
snowflake-role

string

Optional. The Snowflake role name used to access Snowflake Horizon Catalog in the Workload Identity Federation (OIDC) authentication flow.

WorkdayCatalogInfo

Information specific to Workday Data Lake. The Iceberg REST Catalog endpoint is of the form: https://<baseUrl>/datalake/api/catalog/v1/config?warehouse=workday.

JSON representation 
{
  "base-url": string,
  "tenant": string
}
Fields
base-url

string

Required. Immutable. The base URL of the Workday instance. For example, impl-services1.wd12.myworkday.com or wd501.myworkday.com.
tenant

string

Required. Immutable. The Workday tenant name.

RefreshOptions

Refresh configuration.

JSON representation 
{
  "refresh-schedule": {
    object (RefreshSchedule)
  },
  "refresh-scope": {
    object (RefreshScope)
  }
}
Fields
refresh-schedule

object (RefreshSchedule)

Optional. Schedule defines if and when metadata refresh should be scheduled.
refresh-scope

object (RefreshScope)

Optional. Refresh scope configurations.

RefreshSchedule

Schedule defines if and when metadata refresh should be scheduled.

JSON representation 
{
  "refresh-interval": string
}
Fields
refresh-interval

string (Duration format)

Optional. The interval for refreshing metadata from the remote catalog. If unset or if the value is <= 0, the background metadata refresh will be disabled. If this field is updated for an existing federated catalog, the previous background metadata refresh must complete before the new refresh interval will take effect.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

RefreshScope

The scope defines a subset of namespaces to be refreshed.

JSON representation 
{
  "namespace-filters": [
    string
  ]
}
Fields
namespace-filters[]

string

Optional. Filters to determine which namespaces are included in the refresh process. - empty list means include all namespaces. - "[namespaces]" means include the specified namespaces. ['ns1', 'ns2'] : Discover only namespaces 'ns1' and 'ns2'.

RefreshStatus

Remote catalog background metadata refresh status.

JSON representation 
{
  "start-time": string,
  "end-time": string,
  "status": {
    object (Status)
  }
}
Fields
start-time

string (Timestamp format)

Output only. When the catalog refresh has started, including in-progress refreshes.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
end-time

string (Timestamp format)

Output only. When the catalog refresh has ended, unset for in-progress refreshes.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
status

object (Status)

Output only. The status of the last background metadata refresh operation, unset for in-progress refreshes.

CrossCloudCacheOptions

Configuration options for cross-cloud caching of data and metadata files.

JSON representation 
{
  "enabled": boolean
}
Fields
enabled

boolean

Optional. Specifies whether cross-cloud caching of data and metadata files is enabled. This only affects queries through BigQuery.

If this value is true, read data and metadata are stored in a cache, which can increase performance and decrease network egress costs for cross-cloud queries.

If this value is false, cross-cloud caching is disabled.

Methods

create

 Creates the Iceberg REST Catalog.

delete

 Deletes the Iceberg REST Catalog.

failover

 Failover the catalog to a new primary replica region.

get

 Returns the Iceberg REST Catalog configuration options.

list

 Lists the Iceberg REST Catalogs.

patch

 Update the Iceberg REST Catalog configuration options.