Manage your AlloyDB resources using Knowledge Catalog

Knowledge Catalog integration is enabled by default for all new AlloyDB clusters, allowing you to search for and manage your AlloyDB for PostgreSQL resources using Knowledge Catalog, a platform that lets you store, manage, and access metadata. This integration helps you discover and understand your AlloyDB metadata, supporting the following use cases:

• Analysis: Understand dependencies and assess suitability for various use cases.
• Change Management: Track and manage metadata changes effectively.
• Schema Evolution: Monitor and plan schema modifications.

Knowledge Catalog automatically retrieves the following metadata from AlloyDB clusters, instances, databases, tables, columns, and views:

• Name
• Location (Region)
• Labels (for clusters and instances)
• Dataplex Integration Enabled (for clusters)
• Database Version
• Machine CPU Count (for instances)
• Availability Type (for instances)
• Charset (for databases)
• Collation (for databases)
• Owner
• Description (for table, views, columns, and foreign keys)
• Type (for clusters, instances, and machines)
• Columns
  • Data Type
  • Mode
• Primary Key
• Foreign Keys
  • Referenced Table
  • Column Mappings
• Creation Time
• Last modification Time

For more information, see About metadata management in Knowledge Catalog.

Types of metadata discovery

Knowledge Catalog metadata discovery is an automated process that scans connected data sources—such as AlloyDB—to identify data assets like tables, views, and databases. Then, Knowledge Catalog extracts technical metadata from the assets like schemas, descriptions, and locations, into Knowledge Catalog.

This process syncs metadata in near real-time, which keeps the catalog synchronized with source systems. For AlloyDB, cluster and instance metadata is discovered by default. Database, schema, table, and view metadata discovery is enabled by default on new clusters. For clusters created before this default was implemented (February 26, 2026), manually enable the integration.

Keyword and natural language search

Knowledge Catalog supports keyword and natural language searches.

• Keyword search helps you find resources using specific keywords, filters, and a defined syntax. For example, to view all AlloyDB databases, enter system=AlloyDB AND type=Database.
• Natural language search uses AI to understand semantic queries. It helps you find resources using everyday language, eliminating the need for complex syntax. For example, enter a query such as List all AlloyDB tables related to sales.

For more information, see Search syntax for Knowledge Catalog.

Example: Discovering an AlloyDB database schema

To understand the metadata discovery process, consider the example of an AlloyDB cluster named user-data-cluster with Knowledge Catalog integration enabled. Inside this cluster's primary instance, a database named profiles exists, which contains a table customers (id, email, signup_date) and a view active_users (id, email).

Because AlloyDB syncs in near real-time to Knowledge Catalog, the following resources are available:

• Clusters
• Columns
• Databases
• Instances
• Tables
• Views

After discovery is complete, search for these assets—customers table and active_users—in the Knowledge Catalog page of the Google Cloud console or by using the API. Then, view their schemas and enrich them with additional business or operational metadata.

Enrich metadata using aspects

Aspect types are reusable resources that serve as templates for aspects. Aspect types help avoid duplicating work and creating incomplete aspects. Create the necessary aspect types using Knowledge Catalog.

After you create custom aspect types, attach aspects to your AlloyDB assets. Attaching aspects to AlloyDB assets lets you do the following:

• Add business metadata to the assets.
• Search for assets by business metadata and other custom metadata.

To learn more about creating aspect types and attaching aspects to AlloyDB, see Manage aspects and enrich metadata.

Metadata discovery workflow

By default, cluster and instance resources are ingested and discoverable. To ingest and discover database, schema, table and view resources, follow these steps:

1. Enable the Knowledge Catalog integration for your AlloyDB cluster using the AlloyDB API if it's not already enabled. This is required for clusters created before February 26, 2026.

2. Search for your AlloyDB assets using the Knowledge Catalog search page in the Google Cloud console. For more information, see Search for resources in Knowledge Catalog.

3. To add more context to your AlloyDB assets, attach aspects to your assets. Aspects are custom metadata entries that help with data governance and analysis. For example, use an aspect to label a column that contains personally identifiable information (PII). For more information, see Manage aspects and enrich metadata.

4. Navigate through your AlloyDB resources following this hierarchy: Cluster > Database > Schema > Table or View > Column. This hierarchy provides a detailed view of your data landscape. For more information, see Search for resources in Knowledge Catalog.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Enable the Dataplex API for the project.

   Enable the Dataplex API

2. Check permissions.

   You must have specific Identity and Access Management (IAM) roles and permissions to search for and attach entries to AlloyDB assets. For more information, see Required IAM roles and permissions for Knowledge Catalog.

Required IAM roles

This section describes the roles and permissions required to search for resources and to access the search results.

Required roles for accessing search results

To search for and view AlloyDB metadata in Knowledge Catalog, principals require permissions to view AlloyDB resources, including the dataplex.projects.search permission.

To grant principals—such as users, groups, or service accounts—these permissions, assign them the AlloyDB Viewer (roles/alloydb.viewer) IAM role on the project that contains the AlloyDB resources.

If you don't want to use the predefined AlloyDB Viewer role, assign a custom role that includes alloydb.clusters.get, alloydb.instances.get, and alloydb.databases.get permissions.

For more information about granting roles, see Manage access. For more information about AlloyDB IAM roles, see IAM roles and permissions for AlloyDB.

Required roles for searching entries

You must have at least one of the following IAM roles on the project used for search:

• Dataplex Catalog Admin (roles/dataplex.catalogAdmin)
• Dataplex Catalog Editor (roles/dataplex.catalogEditor)
• Dataplex Catalog Viewer (roles/dataplex.catalogViewer)

Permissions on search results are checked independently of the selected project. For more information, see Search for data assets with Knowledge Catalog.

Knowledge Catalog integration data freshness

By default, Knowledge Catalog ingests and discovers cluster and instance resources, and their metadata freshness is near real-time.

The Knowledge Catalog integration for database, schema, table, and view resources is enabled by default when you create a new AlloyDB cluster. To prevent this metadata from syncing, disable the integration.

Enabling the integration activates the export of AlloyDB metadata—such as databases, schemas, and tables—to Cloud Storage buckets for periodic sync or to Pub/Sub topics for near real-time sync, making it available to Knowledge Catalog. This feature is only applicable to primary clusters. Secondary clusters used for cross-region replication don't support Knowledge Catalog integration for database, schema, table, and view metadata.

The metadata freshness for these resources depends on when the cluster was created or restored:

• Near real-time: clusters created or restored on or after April 3, 2026, sync metadata to Knowledge Catalog in near real-time. Updates are available in Knowledge Catalog in up to 5 minutes. The extraction process typically takes a few seconds.

• Every few hours: clusters created or restored between February 26, 2026, and April 3, 2026 refresh metadata in Knowledge Catalog every few hours. Updates are available in Knowledge Catalog in up to 48 hours. The extraction process typically takes a few minutes, but time to completion depends on the CPU size and the table count.

Create AlloyDB with Knowledge Catalog integration disabled

You can control this integration when you create or update a cluster using the Google Cloud CLI or the AlloyDB API:

gcloud alloydb clusters create CLUSTER_ID \
    --password=PASSWORD \
    --region=REGION \
    --no-enable-dataplex-integration

{
  "databaseVersion": "DATABASE_VERSION",
  "initialUser": {
    "user": "INITIAL_USERNAME",
    "password": "INITIAL_USER_PASSWORD"
  },
  "labels": {
    "test": "alloydb-cluster-full"
  },
  "dataplexConfig" : {
    "enabled" : false
  }
}

POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
        "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID"
      

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID"| Select-Object -Expand Content

{
  "kind": "alloydb#operation",
  "targetLink": "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/clusters/CLUSTER_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2024-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "CLUSTER_ID",
  "selfLink": "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Enable the Knowledge Catalog integration for your AlloyDB cluster

To enable the Knowledge Catalog integration on an existing cluster, use one of the following procedures:

gcloud alloydb clusters update CLUSTER_ID \
    --region=REGION \
    --enable-dataplex-integration

PATCH https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID?updateMask=dataplexConfig.enabled

{
  "dataplexConfig": {
    "enabled": true
  }
}

    curl -X PATCH \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
        "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID?updateMask=dataplexConfig.enabled"
      

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID?updateMask=dataplexConfig.enabled"| Select-Object -Expand Content

{
  "kind": "alloydb#operation",
  "targetLink":