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)
  }
}
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 was never enabled for the catalog. For federated catalogs, the service account will be always provisioned and will be used to access the remote Iceberg REST Catalog using access to Secret Manager secret or identity federation.
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.
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.

CredentialMode

The credential mode used for the catalog.

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

Use credential vending. The authenticating user must have access to the catalog resources and the system will provide the caller with downscoped credentials to access the Google Cloud Storage files. All table operations in this mode would require X-Iceberg-Access-Delegation header with vended-credentials value included. System will generate a service account and the catalog administrator must grant the service account appropriate permissions.

See: https://github.com/apache/iceberg/blob/931865ecaf40a827f9081dddb675bf1c95c05461/open-api/rest-catalog-open-api.yaml#L1854 for more details.

CatalogType

Determines the catalog type.

Enums
CATALOG_TYPE_UNSPECIFIED Default 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 The replica state is unknown.
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, all accessible locations are allowed. If restrictedLocations is not empty, only defaultLocation and locations in this list are allowed.

FederatedCatalogOptions

Configuration options for a federated catalog.

JSON representation 
{
  "secret-name": string,
  "service-directory-name": string,
  "refresh-options": {
    object (RefreshOptions)
  },
  "refresh-status": {
    object (RefreshStatus)
  },

  // Union field remote_catalog_info can be only one of the following:
  "unity-catalog-info": {
    object (UnityCatalogInfo)
  },
  "glue-catalog-info": {
    object (GlueCatalogInfo)
  }
  // End of list of possible types for union field remote_catalog_info.
}
Fields
secret-name

string

Required. 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 location must match the catalog's location. If the version is not specified, the latest version will be used.
service-directory-name

string

Optional. The service directory resource name for routing traffic over a private network connection through Cross-Cloud Interconnect, in the format projects/{projectId}/locations/{locationId}/namespaces/{namespace_id}/services/{serviceId}.
refresh-options

object (RefreshOptions)

Optional. Refresh configuration.
refresh-status

object (RefreshStatus)

Output only. The status of the background refresh operations.
Union field remote_catalog_info. Info specific to a remote Iceberg REST catalog. remote_catalog_info can be only one of the following:
unity-catalog-info

object (UnityCatalogInfo)

Optional. Info specific to a Unity Catalog by Databricks.
glue-catalog-info

object (GlueCatalogInfo)

Optional. Info specific to an AWS Glue Catalog.

UnityCatalogInfo

Unity Catalog info.

JSON representation 
{
  "instance-name": string,
  "catalog-name": string
}
Fields
instance-name

string

Required. The instance name is the first part of the URL when logging into the Databricks deployment. For example, for a Databricks on GCP workspace URL https://1.1.gcp.databricks.com, the instance name is 1.1.gcp.databricks.com.
catalog-name

string

Required. Name of the catalog in Unity Catalog.

GlueCatalogInfo

AWS Glue Catalog info. We support regional AWS Glue default account catalog and S3 Table Buckets.

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

string

Required. Immutable. The warehouse to connect to a regional AWS Glue Iceberg REST Catalog. For top level access, use the AWS account ID (e.g. 111222333444). For an S3 table bucket, the warehouse is of the form: 111222333444:s3tablescatalog/. The URL to access catalog will be https://glue.{awsRegion}.amazonaws.com/iceberg/v1?warehouse={warehouse}. Must be non-empty and is immutable.
aws-region

string

Required. Immutable. The AWS region of the Glue catalog to connect to. The region should be in the same geographical region and jurisdiction as the federated catalog. Must be non-empty and is immutable.
aws-role-arn

string

Required. The AWS role ARN of the Glue catalog that the federated catalog will assume to access the catalog. Must be non-empty. Can be updated.

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 refresh will be disabled. If this field is updated for an existing federated catalog, the previous background 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'. The maximum number of namespace filters allowed is 32.

RefreshStatus

Remote catalog background 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 refresh operation, unset for in-progress refreshes.

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.