Manage a business glossary

This document describes how to create and manage business glossaries in Knowledge Catalog (formerly Dataplex Universal Catalog). When you create these resources, ensure their IDs comply with Knowledge Catalog resource naming guidelines. Use a business glossary to establish a standardized vocabulary for your data assets, which reduces ambiguity and improves data discovery and governance across your organization.

Knowledge Catalog business glossary use cases

By creating a common language for data using Knowledge Catalog business glossary, you can achieve the following:

  • Define a clear hierarchy of business categories and terms.
  • Link concepts using synonyms and show relationships between terms.
  • Search for data resources based on business concepts, not just technical names.

Knowledge Catalog business glossary helps streamline data discovery and reduce ambiguity, resulting in better governance, more accurate analysis, and faster insights.

Elements of a business glossary

This section describes the key elements that you can use to structure a business glossary.

Glossary

A glossary has the following properties:

  • Overview. Describes the purpose and contents of the business glossary. You can add images, links, and tables. While HTML formatting isn't supported, you can include HTML code formatted as code or add a link to an HTML page. You can also use rich text formatting options such as bold, italics, underline, bulleted lists, paragraphs, headings, and code blocks. The maximum supported size is 120 KB.

  • Description. Describes the glossary. The text in this field is indexed for search. The maximum supported size is 1 KB.

  • Region. Specifies the region where the glossary is located.

Category

A category lets you organize and structure various categories and terms. Categories are defined within a business glossary. You can nest categories up to three levels.

A category has the properties of a glossary as well as the following properties:

  • Contacts. Specifies the person responsible for maintaining the category. This property is descriptive and doesn't affect the permissions of the category.
  • Parent. Specifies a relationship that is used to establish the parent of the current category. You can nest up to three categories.

The region of a category is the same as the region of the glossary that contains it.

Term

A term (short for "glossary term") describes a concept that's used in a particular branch of business within your company. For example, the marketing department of a company might create a term that describes cost per click. Terms are defined within a business glossary, either in the glossary directly or within any category found in the glossary.

A term has the properties of a category as well as the following properties:

  • Synonyms. Specifies links between terms that have the same meaning. See Synonym terms.
  • Related terms. Specifies links between terms that are conceptually related to each other, but that have different meanings. See Related terms.
  • Related entries. Specifies links between terms and data assets, or between terms and columns within data assets.
  • Data quality rules. Specifies data quality requirements for the term. For more information, see Reuse data quality rules.
  • Contacts. Specifies the person responsible for maintaining the term. Terms don't inherit the contacts that are defined in categories.

The region of a term is the same as the region of the glossary that contains it.

Synonym terms

A synonym is a relationship that indicates equivalence between two different terms. Use synonyms when two terms with the same meaning are defined by different teams in different glossaries. For example, you can create a synonym to link the terms "profit" and "earnings."

A related term is a relationship that indicates that two terms are associated with each other, but have different meanings. For example, you can create a related term to link the terms "revenue" and "profit."

Limitations

Required roles

To get the permissions that you need to create and manage glossaries, ask your administrator to grant you the following IAM roles on your project:

  • For data administrators, get full access to glossaries, categories, terms, synonyms, and related terms, and to set IAM policies: Dataplex Catalog Admin (roles/dataplex.catalogAdmin)
  • For data stewards or data owners, get access to creating, editing or deleting glossaries, categories, terms, links between terms, links between terms and data assets, and search: Dataplex Catalog Editor (roles/dataplex.catalogEditor)
  • For data analysts or data consumers, get read-only access to glossaries, categories, terms, links between terms and between terms and data assets, and search: Dataplex Catalog Viewer (roles/dataplex.catalogViewer)

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

These predefined roles contain the permissions required to create and manage glossaries. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create and manage glossaries:

  • Create, read, update, and delete a business glossary, category, and terms in your project:
    • dataplex.glossaries.list
    • dataplex.glossaries.create
    • dataplex.glossaries.get
    • dataplex.glossaries.update
    • dataplex.glossaries.delete
    • dataplex.glossaryCategories.create
    • dataplex.glossaryCategories.list
    • dataplex.glossaryCategories.get
    • dataplex.glossaryCategories.update
    • dataplex.glossaryCategories.delete
    • dataplex.glossaryTerms.create
    • dataplex.glossaryTerms.list
    • dataplex.glossaryTerms.get
    • dataplex.glossaryTerms.update
    • dataplex.glossaryTerms.delete
  • Create, lookup, and delete synonym term-to-term links in your project:
    • dataplex.entryLinks.create on the Knowledge Catalog entry group in the project in which either of the glossary terms is present. The link is created in the entry group for which the permission is given.
    • dataplex.entryGroups.useSynonymEntryLink on the Knowledge Catalog entry group in the project in which either of the glossary terms is present. The link is created in the entry group for which the permission is given.
    • dataplex.glossaryTerms.use on the glossaries whose terms need to be associated.
    • dataplex.glossaryTerms.get on the term whose synonym links you are looking up. Knowledge Catalog redacts synonym terms in the response if you lack the dataplex.glossaryTerms.get permission for those terms.
    • dataplex.entryLinks.delete on the Knowledge Catalog entry group in the project in which the link is present.
  • Create, lookup, and delete related term-to-term links in your project:
    • dataplex.entryLinks.create on the Knowledge Catalog entry group in the project in which either of the glossary terms is present. The link is created in the entry group for which the permission is given.
    • dataplex.entryGroups.useRelatedEntryLink on the Knowledge Catalog entry group in the project in which either of the glossary terms is present. The link is created in the entry group for which the permission is given.
    • dataplex.entries.link on the Knowledge Catalog entry group in projects in which entries corresponding to glossary terms are present.
    • dataplex.glossaryTerms.get on the term whose related links you are looking up. Knowledge Catalog redacts related terms in the response if you lack the dataplex.glossaryTerms.get permission for those terms.
    • dataplex.entryLinks.delete on the Knowledge Catalog entry group in the project in which the link is present.
  • Create, lookup, and delete links between terms and data assets or columns in your project:
    • dataplex.entryLinks.create on the system entry group corresponding to data assets or columns in the project. The link is created in the project for which the permission is given.
    • dataplex.entryGroups.useDefinitionEntryLink on the system entry group corresponding to data assets or columns in the project. The link is created in the project for which permission is given.
    • dataplex.entries.link on the system entry group corresponding to data assets or columns in the project. The link is created in the project for which the permission is given.
    • dataplex.glossaryTerms.use on the glossary whose term needs to be associated.
    • Source system read permission (for example, bigquery.tables.get or dataplex.glossaryTerms.get) on the entry whose links you are looking up. Knowledge Catalog redacts data assets in the response if you lack the source system read permission for those assets.
    • dataplex.entryLinks.delete on the system entry group in which the link is present.

You might also be able to get these permissions with custom roles or other predefined roles.

For more information, see Knowledge Catalog IAM roles.

Create and manage business glossaries

The following sections describe how to create, view, edit, and delete a business glossary.

Create a business glossary

Console

  1. In the Google Cloud console, go to the Knowledge Catalog Glossaries page.

    Go to Glossaries

  2. Click Create business glossary.

  3. On the Create business glossary page, specify a name and location for the business glossary. After you create the glossary, you can't change the location.

  4. Click Create. The glossary is created under the current project.

  5. Optional: Add a short description in Description (up to 1024 characters) or a long description in Overview (up to 120 KB).

C#

C#

Before trying this sample, follow the C# setup instructions in the Knowledge Catalog quickstart using client libraries. For more information, see the Knowledge Catalog C# API reference documentation.

To authenticate to Knowledge Catalog, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

using Google.Api.Gax.ResourceNames;
using Google.Cloud.Dataplex.V1;
using Google.LongRunning;

public sealed partial class GeneratedBusinessGlossaryServiceClientSnippets
{
    /// <summary>Snippet for CreateGlossary</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void CreateGlossaryRequestObject()
    {
        // Create client
        BusinessGlossaryServiceClient businessGlossaryServiceClient = BusinessGlossaryServiceClient.Create();
        // Initialize request argument(s)
        CreateGlossaryRequest request = new CreateGlossaryRequest
        {
            ParentAsLocationName = LocationName.FromProjectLocation("[PROJECT]", "[LOCATION]"),
            GlossaryId = "",
            Glossary = new Glossary(),
            ValidateOnly = false,
        };
        // Make the request
        Operation<Glossary, OperationMetadata> response = businessGlossaryServiceClient.CreateGlossary(request);

        // Poll until the returned long-running operation is complete
        Operation<Glossary, OperationMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        Glossary result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Glossary, OperationMetadata> retrievedResponse = businessGlossaryServiceClient.PollOnceCreateGlossary(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Glossary retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

Go

Before trying this sample, follow the Go setup instructions in the Knowledge Catalog quickstart using client libraries. For more information, see the Knowledge Catalog Go API reference documentation.

To authenticate to Knowledge Catalog, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 


//go:build examples

package main

import (
	"context"

	dataplex "cloud.google.com/go/dataplex/apiv1"
	dataplexpb "cloud.google.com/go/dataplex/apiv1/dataplexpb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := dataplex.NewBusinessGlossaryClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &dataplexpb.CreateGlossaryRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/dataplex/apiv1/dataplexpb#CreateGlossaryRequest.
	}
	op, err := c.CreateGlossary(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

Java

Before trying this sample, follow the Java setup instructions in the Knowledge Catalog quickstart using client libraries. For more information, see the Knowledge Catalog Java API reference documentation.

To authenticate to Knowledge Catalog, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

import com.google.cloud.dataplex.v1.BusinessGlossaryServiceClient;
import com.google.cloud.dataplex.v1.CreateGlossaryRequest;
import com.google.cloud.dataplex.v1.Glossary;
import com.google.cloud.dataplex.v1.LocationName;

public class SyncCreateGlossary {

  public static void main(String[] args) throws Exception {
    syncCreateGlossary();
  }

  public static void syncCreateGlossary() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (BusinessGlossaryServiceClient businessGlossaryServiceClient =
        BusinessGlossaryServiceClient.create()) {
      CreateGlossaryRequest request =
          CreateGlossaryRequest.newBuilder()
              .setParent(LocationName.of("[PROJECT]", "[LOCATION]").toString())
              .setGlossaryId("glossaryId1849967577")
              .setGlossary(Glossary.newBuilder().build())
              .setValidateOnly(true)
              .build();
      Glossary response = businessGlossaryServiceClient.createGlossaryAsync(request).get();
    }
  }
}

Node.js

Node.js

Before trying this sample, follow the Node.js setup instructions in the Knowledge Catalog quickstart using client libraries. For more information, see the Knowledge Catalog Node.js API reference documentation.

To authenticate to Knowledge Catalog, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. The parent resource where this Glossary will be created.
 *  Format: projects/{project_id_or_number}/locations/{location_id}
 *  where `location_id` refers to a Google Cloud region.
 */
// const parent = 'abc123'
/**
 *  Required. Glossary ID: Glossary identifier.
 */
// const glossaryId = 'abc123'
/**
 *  Required. The Glossary to create.
 */
// const glossary = {}
/**
 *  Optional. Validates the request without actually creating the Glossary.
 *  Default: false.
 */
// const validateOnly = true

// Imports the Dataplex library
const {BusinessGlossaryServiceClient} = require('@google-cloud/dataplex').v1;

// Instantiates a client
const dataplexClient = new BusinessGlossaryServiceClient();

async function callCreateGlossary() {
  // Construct request
  const request = {
    parent,
    glossaryId,
    glossary,
  };

  // Run request
  const [operation] = await dataplexClient.createGlossary(request);
  const [response] = await operation.promise();
  console.log(response);
}