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,
  "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 the Google Cloud Storage Bucket catalog this is output only. For BigLake Iceberg 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.
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 Catalog type for Google Cloud Storage Buckets.
CATALOG_TYPE_FEDERATED BigLake federated catalog mirroring a remote Iceberg REST Catalog.

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.

FederatedCatalogOptions

Configuration options for Iceberg REST 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)
  }
  // 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 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.

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 you log into your 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.

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.

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.