Send inspection results to Knowledge Catalog as aspects

This document describes how to inspect a BigQuery table for sensitive data and send the inspection results to Knowledge Catalog. This action automatically adds an aspect to the Knowledge Catalog entry that's associated with your BigQuery table.

This document also provides example queries that you can use to find data across your organization and projects with specific aspect values.

This feature is useful if you want to enrich your metadata in Knowledge Catalog with sensitive data classifications from Sensitive Data Protection inspection jobs.

About Knowledge Catalog

Knowledge Catalog lets you use aspects to add business and technical metadata to your data to capture context and knowledge about your resources. You can then search and discover data across your organization and enable data governance over your data assets. For more information, see Aspects.

How it works

To automatically create Knowledge Catalog aspects based on inspection job results, follow this high-level workflow:

Sensitive Data Protection adds or updates the Sensitive Data Protection job result aspect of the Knowledge Catalog entry associated with the BigQuery table. You can then search Knowledge Catalog for all data in your organization or project with specific aspect values. For example queries, see Example search queries in this document.

The resulting Knowledge Catalog aspect is stored in the same project and region as the BigQuery table.

Aspect fields

Enable the Dataplex API

The Dataplex API must be enabled in each project that contains data that you want to add aspects for. This section describes how to enable the Dataplex API in a single project or in all projects in an organization or folder.

Enable the Dataplex API in a single project

Enable the Dataplex API in all projects in an organization or folder

This section provides a script that searches for all projects in an organization or folder and enables the Dataplex API in each of those projects.

To get the permissions that you need to enable the Dataplex API in all projects in an organization or folder, ask your administrator to grant you the following IAM roles:

These predefined roles contain the permissions required to enable the Dataplex API in all projects in an organization or folder. To see the exact permissions that are required, expand the Required permissions section:

To enable the Dataplex API in all projects in an organization or folder, follow these steps:

Roles and permissions for viewing aspects

To get the permissions that you need to search for aspects associated with your BigQuery table, ask your administrator to grant you the following IAM roles on the table:

These predefined roles contain the permissions required to search for aspects associated with your BigQuery table. To see the exact permissions that are required, expand the Required permissions section:

Configure and run a Sensitive Data Protection inspection job

You can configure and run a Sensitive Data Protection inspection job by using the Google Cloud console or the DLP API.

Console

In the Google Cloud console, go to the Create job or job trigger page.

Go to Create job or job trigger
Select your project.
Enter the required inspection job details and the details of the BigQuery table that you want to inspect. For instructions, see Inspect a BigQuery table. For a full list of information types that Sensitive Data Protection can inspect for, see InfoType detector reference.
For Add actions, enable Publish to Dataplex Universal Catalog.
Click Create. The job runs immediately.

REST

The following example sends a projects.locations.dlpJobs.create request to inspect a BigQuery table and send the results to Knowledge Catalog.

Before using any of the request data, make the following replacements:

PROJECT_ID: your Google Cloud project ID. Project IDs are alphanumeric strings
LOCATION: the region or multi-region where you want to process the request—for example, europe-west1 or us. For available locations, see Sensitive Data Protection locations.
BIGQUERY_DATASET_NAME: name of the BigQuery dataset that contains the table to inspect
BIGQUERY_TABLE_NAME: name of the BigQuery table to inspect

HTTP method and URL:

POST https://dlp.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/dlpJobs

Request JSON body:

{
              "inspectJob":
              {
                "storageConfig":
                {
                  "bigQueryOptions":
                  {
                    "tableReference":
                    {
                      "projectId": "PROJECT_ID",
                      "datasetId": "BIGQUERY_DATASET_NAME",
                      "tableId": "BIGQUERY_TABLE_NAME"
                    }
                  }
                },
                "inspectConfig":
                {
                  "infoTypes":
                  [
                    {
                      "name": "EMAIL_ADDRESS"
                    },
                    {
                      "name": "PERSON_NAME"
                    },
                    {
                      "name": "US_SOCIAL_SECURITY_NUMBER"
                    },
                    {
                      "name": "PHONE_NUMBER"
                    }
                  ],
                  "includeQuote": true,
                  "minLikelihood": "UNLIKELY",
                  "limits":
                  {
                    "maxFindingsPerRequest": 100
                  }
                },
                "actions":
                [
                  {
                    "publishFindingsToDataplexCatalog": {}
                  }
                ]
              }
            }

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named inspect-request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @inspect-request.json \
     "https://dlp.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/dlpJobs"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named inspect-request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile inspect-request.json `
    -Uri "https://dlp.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/dlpJobs" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/dlpJobs/JOB_ID",
  "type": "INSPECT_JOB",
  "state": "PENDING",
  "inspectDetails": {
    "requestedOptions": {
      "snapshotInspectTemplate": {},
      "jobConfig": {
        "storageConfig": {
          "bigQueryOptions": {
            "tableReference": {
              "projectId": "PROJECT_ID",
              "datasetId": "BIGQUERY_DATASET_NAME",
              "tableId": "BIGQUERY_TABLE_NAME"
            }
          }
        },
        "inspectConfig": {
          "infoTypes": [
            {
              "name": "EMAIL_ADDRESS"
            },
            {
              "name": "PERSON_NAME"
            },
            {
              "name": "US_SOCIAL_SECURITY_NUMBER"
            },
            {
              "name": "PHONE_NUMBER"
            }
          ],
          "minLikelihood": "UNLIKELY",
          "limits": {
            "maxFindingsPerRequest": 100
          },
          "includeQuote": true
        },
        "actions": [
          {
            "publishFindingsToDataplexCatalog": {}
          }
        ]
      }
    },
    "result": {}
  },
  "createTime": "2025-09-09T00:29:55.951374Z",
  "lastModified": "2025-09-09T00:29:58.022967Z"
}

For information about how to get the inspection job results using the DLP API, see Get a job.

Example search queries

This section provides example search queries that you can use in Knowledge Catalog to find data in your organization or project with specific aspect values.

You can find only the data that you have access to. Data access is controlled through IAM permissions. For more information, see Roles and permissions for viewing aspects in this document.

You can enter these example queries in the Search field on the Knowledge Catalog Search page.

Find the entries of all tables that have the Sensitive Data Protection job result aspect

Find the entries of inspected tables that have findings

Find the entries of inspected tables that have no findings

Find the entries of tables that were inspected fully

The following query returns the entries of tables that Sensitive Data Protection inspected row by row.

Find the entries of tables that weren't inspected fully

The following query returns the entries of tables that Sensitive Data Protection inspected through sampling.

Migrate to the Publish to Dataplex Universal Catalog action

To migrate a job trigger that is configured to use the deprecated Publish to Data Catalog action, follow these steps: