Transition from Data Catalog to Dataplex Universal Catalog

Dataplex Universal Catalog replaces Data Catalog, providing more complexmetadata management, advanced data governance features, more powerful datasearch, less complex access control, and a unified API to ease development.This document shows you how to transition your Data Catalog content andusage to Dataplex Universal Catalog.

If you're new to using catalog, start with Dataplex Universal Catalog byconfiguring it as your default catalog experience.

Dataplex Universal Catalog has a unified web interface and API. Transitioning toDataplex Universal Catalog lets your existing and future workloads and usersbenefit from its enhanced features and capabilities. For more information, seeAbout metadata management in Dataplex Universal Catalog.

For a comparison of Dataplex Universal Catalog and Data Catalog, refer toDataplex Universal Catalog versus Data Catalog.

Before you begin

Before you start the transition, review themetadata management features that aren't supported in Dataplex Universal Catalog.

Note: Policy tags and policy tag taxonomies, which are used forcolumn-level access control inBigQuery, aren't deprecated.

Transition overview

TheManage transition to Dataplex Universal Catalog page in the Google Cloud consoleprovides a single point of access for managing transition.

This section describes the various transition scenarios and outlines thetransition process for each of the scenarios.

If you don't have custom metadata in Data Catalog or if you have never used Data Catalog

If you're using Data Catalog and don't have custom metadata,such as tags, tag templates, custom entries, or entry groups,or if you have never used Data Catalog, then complete thetransition bysetting your default catalog UI experience to Dataplex Universal Catalog.

Note: If you don't have custom metadata in Data Catalog or ifyou have never used Data Catalog, skip all other tasks describedin this document.

If you have Data Catalog custom metadata or programmatic workloads

If you're using Data Catalog with custom metadata (such as tags,tag templates, custom entries, or entry groups), Dataplex Universal Catalog canautomatically import this custom metadataasread-only. To enable this capability, configuration changes are requiredas outlined in thepreparatory phase.

The second phase is theupgrade phase, where the active state (read-write)of your custom metadata is moved to Dataplex Universal Catalog. Duringthis phase, you must also update any programmatic workloads (such as API,client libraries, Terraform modules, and Google Cloud CLI commands) to interactwith Dataplex Universal Catalog.

The following provides further detail on each phase of thetransition process:

  1. Preparatory phase: perform necessary configuration tasks to make theData Catalog content simultaneously available inDataplex Universal Catalog asread-only. During this phase,Data Catalog remains the authoritative source for your metadatacontent.

    The preparatory phase includes the following tasks:

    1. Update the Data Catalog private tag templates to public.
    2. If your project is in Assured Workloads, opt in tag templatesand tags for simultaneous availability of metadata in Dataplex Universal Catalog.
    3. Configure Dataplex Universal Catalog IAM permissionsfor your custom metadata.

    For more information, seePreparatory phase.

  2. Upgrade phase: move your catalog usage and the active state (read-write)of your custom metadata to Dataplex Universal Catalog.

    The upgrade phase includes the following tasks:

    1. Set the default catalog UI experience to Dataplex Universal Catalog.

    2. Upgrade the Data Catalog custom metadata toDataplex Universal Catalog.

      You must wait at least 48 hours after you opt in tag templates and tagsand after making the tag templates public before you can upgrade thecustom metadata. This time is necessary for internal processing.

    3. Update programmatic workloads.

    When you complete the upgrade phase, Dataplex Universal Catalogbecomes the authoritative source for all your metadata and you don't need touse Data Catalog.

    For more information, seeUpgrade phase.

Required roles

To get the permissions that you need to transition fromData Catalog to Dataplex Universal Catalog, grant thefollowing IAM roles on the resource:

  • Update private tag templates to public:Data Catalog TagTemplate Owner(roles/datacatalog.tagTemplateOwner)

    This predefined role contains thedatacatalog.tagTemplates.update permission,which is required to update private tag templates to public.

  • Opt in public tag templates and tags for simultaneous availability of metadatain Dataplex Universal Catalog:DataCatalog Migration Config Admin(roles/datacatalog.migrationConfigAdmin)

    This predefined role contains thedatacatalog.migrationConfig.set permission,which is required to opt in tag templates and tags.

  • Set the default catalog UI experience to Dataplex Universal Catalog:DataCatalog Migration Config Admin(roles/datacatalog.migrationConfigAdmin)

    This predefined role contains thedatacatalog.migrationConfig.set permission,which is required to set the default catalog UI experience.

  • Upgrade Data Catalog public tag templates to Dataplex Universal Catalog:Data Catalog TagTemplate Owner(roles/datacatalog.tagTemplateOwner)

    This predefined role contains thedatacatalog.tagTemplates.update permission,which is required to upgrade public tag templates.

  • Upgrade Data Catalog entry groups to Dataplex Universal Catalog:DataCatalog EntryGroup Owner(roles/datacatalog.entryGroupOwner)

    This predefined role contains thedatacatalog.entryGroups.update permission,which is required to upgrade entry groups.

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions withcustom roles or otherpredefined roles.

Preparatory phase

Note: Perform the tasks described in this section only if you haveData Catalog custom metadata or programmatic workloads.

This phase involves tasks to make the Data Catalog metadatacontent simultaneously available in Dataplex Universal Catalog, in theread-only mode.

The following are the key points to remember during the preparatory phase:

  • Data Catalog remains the authoritative source for your custommetadata.
  • The Dataplex Universal CatalogSearch page points to Data Catalogsearch by default, which includes only Data Catalog metadata andnot Dataplex Universal Catalog metadata.
  • Dataplex Universal Catalog search might not include allData Catalog public tag templates and tags until you complete thepreparatory phase.

Learn more about simultaneous availability of Data Catalogmetadata in Dataplex Universal Catalog

Data Catalog custom entry groups and their entries are already madesimultaneously available in Dataplex Universal Catalog asread-only. When youopt-in public tag templates and tagsin the preparatory phase, their content will be made simultaneously available inDataplex Universal Catalog asread-only.

The following table shows mapping between Data Catalogand Dataplex Universal Catalog resources when theData Catalog resources are made simultaneously available inDataplex Universal Catalog:

Mapping between Data Catalog and Dataplex Universal Catalog
Data Catalog resourceCorresponding Dataplex Universal Catalog resourceDescription
Tag templateAspect type (global)

Tag templates in Data Catalog are regional resources.When youopt in tag templates, their content is madesimultaneously available as global aspect types inDataplex Universal Catalog. This is to preserve the cross-regionalreferences between tags and tag templates. Definitions of global aspect typesare replicated to all Google Cloud regions.

Standard concepts such asSchema are represented by systemaspect types, which Dataplex Universal Catalog provides. For more information, seeCategories of aspect types.

TagOptional aspectWhen youopt in tag templates, their tags are madesimultaneously available as optional aspects inDataplex Universal Catalog. For more information, seeCategories of aspects.
Entry groupEntry groupEntry groups for system entries are established per-project per-region inDataplex Universal Catalog. Entry groups created inData Catalog are made simultaneously available inDataplex Universal Catalog.
Custom entryCustom entryAll custom entries in Data Catalog are made simultaneouslyavailable as entries ofGenericEntryType inDataplex Universal Catalog.For more information, seeCategories of entry types.
System entry (Google Cloud)System entry required aspectMetadata describing system entries, such asSchema forBigQuery tables, is captured in required aspects of thesystem-defined aspect types.
Note: Typically, updates to the Data Catalog content arepropagated to Dataplex Universal Catalog within 10 minutes. In somecases, it might take longer. To verify data consistency, we recommendyou to stop all writes to Data Catalog, and verifyDataplex Universal Catalog resources against Data Catalogresources or the original source system before use.

Update Data Catalog private tag templates to public

Note: Perform this task only if you're using private tag templates andtags in Data Catalog.
Data stewards or data administrators mustperform this task.

Dataplex Universal Catalog doesn't support the concept of privateaspects (counterparts to private tags). Therefore, private tag templates and tagsaren't made simultaneously available in Dataplex Universal Catalog. Topropagate private tag templates and tags in Dataplex Universal Catalog,you must update them to public.

Before you proceed, review the structure of private tag templates to verify thattheir structure and metadata are consistent with the visibility of public tags.

To update private tag templates and tags to public, follow these steps:

Console

  1. In the Google Cloud console, go to the Dataplex Universal CatalogCatalog page.

    Go to Catalog

  2. ClickManage transition to Dataplex Universal Catalog.

  3. Click thePrivate tag templates tab.

  4. ClickManage tag templates.

  5. On theTag templates page, click the private tag template that youwant to update.

  6. On theTemplate details page, clickEdit.

  7. In theVisibility section, selectPublic.

  8. ClickUpdate.

REST

To update the private tag templates to public, use thetagTemplates.patchmethod.

Opt in public tag templates and tags for simultaneous availability of metadata in Dataplex Universal Catalog

Note: Perform this task only if your projects are in Assured Workloads and have public tag templates and tags in Data Catalog.
If you have a Google Cloud organization, the organization administrator can configure this setting at the organizational level, so that it applies to all tag templates within the organization.
To migrate the tag templates only within a specific project, you can configure this setting for individual projects, without affecting settings for the whole organization.
For projects without an organization, the project administrator must configure this setting for individual projects, and it applies to all tag templates within the project.

When you provide opt-in, the content of Data Catalog public tagtemplates and tags is automatically and continuously propagated toDataplex Universal Catalog across your Google Cloud organizationor project. The Data Catalog public tagtemplates and tags are propagated to Dataplex Universal Catalogas public aspect types and aspects respectively. Definitions of global aspecttypes are replicated to all Google Cloud regions.

To opt in public tag templates and tags, follow these steps:

Console

  1. In the Google Cloud console, go to the Dataplex Universal CatalogCatalogpage.

    Go to Catalog

  2. ClickManage transition to Dataplex Universal Catalog.

  3. Click theOpt-in tab.

  4. ClickProvide opt-in.

  5. In the confirmation dialog, enter the text displayed, and clickConfirm.

REST

To opt-in tag templates and tags, use thesetConfigmethod.

For both Google Cloud organizations and for projects, you can revoke theoriginally provided opt-in, by clickingRevoke opt-in. When you revokeopt-in, the process of propagation of Data Catalog tag templates andtags to Dataplex Universal Catalog stops. TheDataplex Universal Catalog aspect types and aspects that are created bythe opt-in process but aren't upgraded to Dataplex Universal Catalog,are deleted. The deletion process might take up to 12 hours.

Note: If you revoke opt-in for your project, but the organization administratorprovides opt-in on the organization level, the organization's configuration takesprecedence and the tag templates in all projects under the organization are migrated.

Configure Dataplex Universal Catalog IAM permissions for your custom metadata

Dataplex Universal Catalog aspect types and custom entry groups thatrepresent tag templates and entry groups from Data Catalogdon't inherit the original Data Catalog IAMpermissions. The specific IAM permissions required also differbetween Dataplex Universal Catalog and Data Catalog.

For example, if you want to create aspects using a propagated aspect type (thatrepresents a Data Catalog tag template), you must configurenecessary IAM permissions for that aspect type. Similarly, whenyou ingest custom metadata, to create custom entries within a propagatedcustom entry group, you must configure necessary IAM permissionsfor that entry group.

If you're using Data Catalog IAM roles to manageaccess in Data Catalog at a project level or higher, then thenecessary Dataplex Universal Catalog permissions are automatically included.However, if you're using custom roles or assigning IAM rolesdirectly to specific resources, you must manually configure theDataplex Universal Catalog permissions for those specific aspects and customentry groups.

For more information on how IAM permissions inData Catalog correspond to those in Dataplex Universal Catalog,seeIAM permissions mapping between Data Catalog and Dataplex Universal Catalog.

To configure necessary Dataplex Universal Catalog IAM permissions foraspect types and custom entry groups, follow these steps:

Console

  1. In the Google Cloud console, go to the Dataplex Universal CatalogCatalog page.

    Go to Catalog

  2. ClickManage transition to Dataplex Universal Catalog.

  3. Click theDataplex IAM permissions tab.

  4. To configure Dataplex Universal Catalog IAM permissions foraspect types, clickAspect types and tag templates.

    1. For the tag template propagated from Data Catalog, click>Permissions.

    2. ClickAdd principals.

    3. Add a new principal, and assign the required roles.

    4. ClickSave.

  5. To configure Dataplex Universal Catalog IAM permissions forentry groups, clickEntry groups.

    1. For the entry group propagated from Data Catalog, click>Permissions.

    2. ClickAdd principals.

    3. Add a new principal, and assign the required roles.

    4. ClickSave.

REST

To configure Dataplex Universal Catalog IAM permissions foraspect types, use theaspectTypes.setIamPolicymethod.

To configure Dataplex Universal Catalog IAM permissions forentry groups, use theentryGroups.setIamPolicymethod.

Upgrade phase

Note: Perform the tasks described in this section only if you haveData Catalog custom metadata or programmatic workloads.

This phase involves tasks to move the active state (read-write) of yourData Catalog custom metadata to Dataplex Universal Catalog.

The following are the key points to remember during the upgrade phase:

  • The Dataplex Universal CatalogSearch page points toDataplex Universal Catalog search by default.
  • You can discover and read both the Data Catalog andDataplex Universal Catalog metadata inDataplex Universal Catalog.
  • To update metadata in the Google Cloud console, you will be redirected toits source. For example, if you're updating Data Catalog tagtemplates, you will be redirected to the tag templates page inData Catalog.

Set the default catalog UI experience to Dataplex Universal Catalog

Note: For a Google Cloud organization, the organization administrator mustconfigure this setting at the organizational level. You can also configure itfor your own project, without affecting settings for the whole organization. Forprojects without an organization, the project administrator must configure thissetting for individual projects.

Setting the default catalog UI experience to Dataplex Universal Catalogmeans the following:

  • When you go to the Dataplex Universal CatalogSearch page in theGoogle Cloud console, Dataplex Universal Catalog (DataplexCatalog) search is displayedby default. Dataplex Universal Catalog search operates overDataplex Universal Catalog and finds all your metadata content,including content created in Dataplex Universal Catalog and contentbrought in from Data Catalog.

    Data Catalog search finds only Data Catalogcontent, not Dataplex Universal Catalog content. Therefore, werecommend using Dataplex Universal Catalog search.

  • The web interface encourages you to create new resources inDataplex Universal Catalog. For example, it defaults toCreate Aspect Types instead ofCreate Tag Templates, andCreate Entry Group (Dataplex Universal Catalog) instead ofCreate Entry Group (Data Catalog).

  • Setting the default catalog UI experience to Dataplex Universal Catalogis typically a one-way operation. However, Dataplex Universal Catalog lets yourevert changes in exceptional cases, for example, when you want to switchthe default Catalog UI experience back to Data Catalog.If you revert the changes, you can't access any content created inDataplex Universal Catalog, in the Data Catalog webinterface.

To set the default catalog UI experience to Dataplex Universal Catalog,follow these steps:

Console

  1. In the Google Cloud console, go to the Dataplex Universal CatalogCatalog page.

    Go to Catalog

  2. ClickManage transition to Dataplex Universal Catalog.

  3. Click theDefault catalog UI experience tab.

  4. ClickSet the default catalog UI experience to Dataplex Universal Catalog.

REST

To set the default catalog UI experience to Dataplex Universal Catalog,use thesetConfigmethod.

Upgrade Data Catalog custom metadata to Dataplex Universal Catalog

Note: Data administrators, data stewards, or data engineers must perform this task.

You can upgrade the Data Catalog public tag templates (that youopted in for) and custom entry groups toDataplex Universal Catalog. Make sure that you upgrade each tag templateand custom entry group separately.

Warning: The upgrade action is irreversible. After you upgrade your existingData Catalog tag templates and entry groups toDataplex Universal Catalog, you can't update them inData Catalog. However, you can delete them inData Catalog because it has no impact on the version upgradedto Dataplex Universal Catalog.

The following summarizes the upgrade process:

  • Effect

    • Transfers the active state for resources from Data Catalog toDataplex Universal Catalog. After upgrade, to modify the resourceor access its current state, you must use Dataplex Universal Catalog.

  • Changes to the data content and flow

    • Marks the resource asread-only in Data Catalog.
    • Marks the resource asread-write in Dataplex Universal Catalog.
    • Stops simultaneous availability of this resource.

  • Dependencies

    • Upgrading a tag template also upgrades all of the tags that use thattemplate.
    • Upgrading entry groups also upgrades all of the entries within thatgroup.
    • Upgrading entries doesn't affect the upgrade status of theirtags and respective tag templates.

Before upgrade, to modify the business context of an entry (for example,overview,contacts), you can use both the Data Catalog APIand the Dataplex API. After upgrade, you must use only theDataplex API.

The following describes what operations are allowed for a customData Catalog entry that is tagged, depending on the upgradestatus of the related custom entry group and tag template:

  • When a tag template is active in Data Catalog, you can usethat tag template to create tags. After you upgrade the tag template toDataplex Universal Catalog, you can't use it to create tags inData Catalog.
  • You can create aspects using aspect types that are propagated fromData Catalog tag templates, only after you upgrade the tagtemplates.

To upgrade the Data Catalog tag templates and custom entry groupsto Dataplex Universal Catalog, follow these steps:

Console

  1. Make sure that at least 48 hours have passed after theopt inand after the tag templates were made public before upgrading the Data Catalog tag templates toDataplex Universal Catalog. This time is necessary for internalprocessing.

  2. In the Google Cloud console, go to the Dataplex Universal CatalogCatalog page.

    Go to Catalog

  3. ClickManage transition to Dataplex Universal Catalog.

  4. Click theUpgrade to Dataplex tab.

  5. To upgrade Data Catalog tag templates toDataplex Universal Catalog, clickView aspect types and tag templates.

    1. Select the tag templates that you want to upgrade.

    2. ClickUpgrade.

    3. In the confirmation dialog, clickConfirm.

  6. To upgrade Data Catalog custom entry groups toDataplex Universal Catalog, clickView entry groups.

    1. Select the entry groups that you want to upgrade.

    2. ClickUpgrade.

    3. In the confirmation dialog, clickConfirm.

REST

Make sure that at least 48 hours have passed after theopt inand making the tag templates public before upgrading the Data Catalogtag templates to Dataplex Universal Catalog. This time is necessary for internalprocessing.

Then, to upgrade Data Catalog tag templates and custom entry groupsto Dataplex Universal Catalog, use thetagTemplates.patchmethod.

When you complete the upgrade phase, Dataplex Universal Catalog becomesthe authoritative source for all your metadata, and you don't need to useData Catalog.

Note: There might be a short delay after the upgrade, before allData Catalog changes are reflected inDataplex Universal Catalog. To verify data consistency intime-critical workloads, we recommend verifying theDataplex Universal Catalog resources against theData Catalog resources or the original source system before use.

Update programmatic workloads

Dataplex Universal Catalog comes with a newAPI, client libraries,Terraform modules, and Google Cloud CLI commands.Therefore, you must update any existing workloads with programmatic usage ofData Catalog to Dataplex Universal Catalog.Seecode samples for Dataplex Universal Catalog.

Make sure that you align updating programmatic workloads with upgrading thedependent resources, such as tag templates and custom entry groups. This isnecessary because upgrading moves the active (read-write) state of aresource from Data Catalog to Dataplex Universal Catalog.

The following is an example sequence of updating programmatic workloads tointeract with Dataplex Universal Catalog, coordinated with upgradingthe dependent resources:

  1. If your workloads can tolerate eventual consistency, moveread operationsof workloads to Dataplex Universal Catalog.

  2. Move workloads performing taggingwrite operations toDataplex Universal Catalog coordinated with upgrading theircorresponding tag templates.

  3. Move workloads performing custom ingestionwrite operations toDataplex Universal Catalog coordinated with upgrading therespective custom entry groups.

If you need to decouple updating workloads and upgrading correspondingresources, consider implementing logic within the workloads to routeread-write to Data Catalog or Dataplex Universal Catalogon the resource upgrade status. Thus, workloads will operate independently ofthe related resource's upgrade status.

Note: Dataplex Universal Catalog doesn't support managing custom entriesand aspects using Terraform. Instead, you can programmatically manage yourcustom metadata at scale by using amanaged connectivity pipelineor themetadata import API methods.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.