About importing and exporting glossaries and entry links

This document provides an overview of how to import and export business glossaries and entry links in Knowledge Catalog (formerly Dataplex Universal Catalog).

Knowledge Catalog business glossary lets you define a common business vocabulary and associate those terms with physical data assets. As your catalog grows, managing these terms and their relationships individually in the Google Cloud console can become difficult.

To manage your business glossary at scale, you can import and export glossaries (categories and terms) and entry links (the associations between terms and data assets) in bulk.

Terminology

Before working with the import and export utilities, familiarize yourself with the following key components:

  • Glossary resources: Consist of categories and terms that establish your business vocabulary.

  • Entry links: The relationships or associations between resources. Knowledge Catalog supports three types of entry links:

    • definition: associates a glossary term with a specific data asset (for example, a BigQuery column)
    • related: establishes a relationship between two related glossary terms
    • synonym: establishes a relationship between two synonymous glossary terms

Methods for importing and exporting glossaries and entry links

Knowledge Catalog supports two primary methods for bulk glossary management. Choose the method that best aligns with your automation needs and preferred interface:

  • JSON-based metadata import
  • Google Sheets-based utilities for import and export

JSON-based metadata import

This is the built-in, fully-managed Knowledge Catalog mechanism. You use the Dataplex API to import glossary terms and their associations defined in JSON-formatted metadata files.

Example use case: Automatically update your Knowledge Catalog metadata as part of a daily scheduled data pipeline—such as synchronize terms directly from an external enterprise database.

For more information, see Import glossaries and entry links using JSON files.

Google Sheets-based utilities for import and export

This is an open-source, script-based approach provided in the dataplex-labs repository. It uses a Python script to sync glossary metadata between a Google Sheet and Knowledge Catalog.

Example use case: A data governance team wants to collaboratively draft and review dozens of new business terms with non-technical business stakeholders. The team uses this spreadsheet-based method so everyone can edit, comment on, and approve the terms in Google Sheet before an administrator runs the script to upload them to Knowledge Catalog in bulk.

For more information, see the following documents:

Common use case: round-trip editing with Google Sheets

A common administrative workflow is to perform round-trip editing. This involves exporting your existing catalog setup, making bulk modifications, and applying those changes back to Knowledge Catalog.

The following workflow illustrates how to execute this process:

  1. Export existing metadata from Knowledge Catalog to Google Sheets.

    Use the glossary export and entry links export utilities to extract your existing glossary structure and entry links into a Google Sheet.

  2. Modify the metadata within Google Sheets.

    Make the required changes in the Google Sheet. Because symmetric links (such as synonym and related entry links) are simplified to a single direction during export to avoid duplicate rows, you only need to manage them once.

    You can add new rows to the respective sheet following the required column schema. You can also modify details such as descriptions or display names directly in the rows.

  3. Stage and import changes from Google Sheets back to Knowledge Catalog.

    Run the glossary import utility first. This ensures that any new terms or categories are successfully created in the business glossary before you attempt to link them.

    Run the entry links import utility. This utility reads your updated associations, stages them in your Cloud Storage bucket, and applies the definition, related, and synonym links to your newly updated glossary.

What's next