Enterprise data environments often contain hundreds of datasets, tables, and data models across multiple storage systems. Understanding who owns each dataset, whether it contains sensitive information like personally identifiable information (PII), or if it meets quality standards usually requires you to manually investigate data sources or track down scattered documentation.
Aspects and aspect types in Knowledge Catalog (formerly Dataplex Universal Catalog) solve this problem by providing you a standardized, extensible way to attach structured business context, governance policies, and operational attributes directly to data assets.
This document describes the architectural concepts, scoping rules, and governance boundaries for aspect types and aspects in Knowledge Catalog. To attach aspects to existing entries or create custom aspect types, see Manage aspects and enrich metadata.
Aspect types
An aspect type (AspectType) is a reusable schema template that defines the metadata fields, data types, and validation rules for an aspect. Before you can create or attach an aspect, you must have an aspect type that defines its schema.
When you create a custom aspect type, you must specify an ID that complies with Knowledge Catalog resource naming guidelines.
Categories of aspect types
Aspect types are divided into two categories based on ownership and scope: custom aspect types and system aspect types.
Custom aspect types
Custom aspect types are schema templates created and managed by your organization. You use them to capture domain-specific metadata, such as business ownership, SLA tiers, data retention policies, or compliance classifications.
Custom aspect types apply to entries and columns, but not to entry links. This means you can use custom aspect types to define your own organization-specific taxonomy for data assets and individual schema fields. Because custom aspect types don't apply to entry links, you can't use them to define custom relationship metadata between entries. Entry links only support specific system aspect types. You can define a custom aspect type in a specific regional location or as a global resource:
- Global aspect types: Replicated across all Google Cloud regions and can be attached to entries residing in any region. Defining a global aspect type lets you enforce a single standardized schema across your entire distributed estate without managing duplicates. However, because schema definitions are replicated globally, choose a regional aspect type if your organization's compliance or data residency policies require metadata definitions to remain strictly confined to a specific geographic boundary.
- Regional aspect types: Stored in a specific region, such as
us-central1oreurope-west1, and can only be attached to entries that reside in that same region. Choose a regional aspect type to comply with data sovereignty requirements or when metadata structures are unique to a regional workload. If you require the same metadata structure across multiple isolated regions, you must create and maintain separate aspect type definitions in each target region.
For more information about resource scoping, see Project and location constraints.
System aspect types
System aspect types are predefined templates that Google Cloud provides and maintains. System aspect types are always global and are stored in a Google-managed project with the project number 655216118709 and the alias dataplex-types. For example:
projects/655216118709/locations/global/aspectTypes/schema
System aspect types fall into two functional groups:
- Reusable system aspect types: First-party templates that you can attach to entries or columns to record standardized metadata, such as schema definitions, automated data profiling, or data quality scorecards.
- Restricted system aspect types: Managed automatically by Google Cloud services to represent underlying infrastructure attributes, such as BigQuery table layouts or Cloud Storage bucket configurations. You can view aspects under restricted types, but you can't manually create, modify, or delete them.
Each system aspect type has its own IAM permissions. For more information, see IAM permissions for system aspect types, entry types, and entry link types.
The following table lists the system aspect types that Knowledge Catalog provides:
| Category | Description | Aspect types provided by Knowledge Catalog |
|---|---|---|
| Reusable system aspect type | Predefined templates that you can attach to entries, columns, or entry links. |
|
| Restricted system aspect type | Infrastructure templates managed automatically by Google Cloud services. Aspects are read-only. |
Including but not limited to:
|
Custom aspect types and Gemini in BigQuery
Gemini in BigQuery grounds SQL generation and data reasoning on standard schema definitions, table constraints, and native table or column description fields. User-defined custom aspect types in Knowledge Catalog are stored in the catalog plane for governance, search, and API retrieval, but aren't dynamically injected into Gemini's contextual prompt retrieval pipeline.
What this means for your workflow is that generative AI features in BigQuery can't automatically read metadata stored in custom aspect fields when generating SQL queries or answering questions about your data.
Recommended best practice
To help ensure that generative AI models in BigQuery incorporate business context into generated queries, you should populate native table descriptions and column descriptions in BigQuery alongside custom catalog aspects. This dual approach helps to ensure that operational AI assistants retrieve table context interactively while catalog governance pipelines enforce enterprise metadata policies.
Aspects
An aspect (Aspect) is a concrete instance of an aspect type attached to a specific entry, column, or relationship, containing the actual metadata values. Aspects are encapsulated directly within their parent resources, which lets you perform atomic read and write operations alongside entry updates. This means you can retrieve or update an entry and all of its associated metadata in a single API call, avoiding multi-call consistency issues.
Aspect placement and target levels
You can attach aspects at three distinct target levels within Knowledge Catalog:
- Entry-level aspects: Describe the data asset as a whole. Use entry-level aspects for asset-level ownership (
contacts), executive summaries (overview), dataset usage metrics (usage), and aggregate quality scores (data-quality-scorecard). - Column-level aspects (schema paths): Describe individual columns or nested fields within a structured table. When referencing a column, attach the aspect using the schema path notation
@Schema.<column_name>(for example,@Schema.email_addressor@Schema.billing_address.postal_code). Use column-level aspects for PII classification, column-level data quality rules, and semantic tags. - Entry link-level aspects: Describe the relationship between two linked entries. You can attach aspects to directional or non-directional entry links (except for
schema-joinlinks) to record relationship metadata. Use entry link-level aspects for join confidence scores, transformation rules, or mapping lineage notes.
The following table summarizes supported aspect placement:
| Target level | Target resource | Key identifier syntax | Common aspect types |
|---|---|---|---|
| Entry level | Data asset (table, model, fileset) | <aspect_type_id> |
contacts, overview, data-profile, custom SLAs |
| Column level | Field or column within an entry schema | <aspect_type_id>@Schema.<column_name> |
PII classification, column masking rules, field validation scores |
| Entry link level | Semantic relationship between entries | <aspect_type_id> |
Relationship confidence, join criteria, mapping lineage |
Categories of aspects
Depending on the governing EntryType, aspects attached to an entry are classified as required or optional:
- Required aspects: Defined as mandatory by the entry's
EntryType. Required aspects must be populated when the entry is created and can't be deleted as long as the entry exists. For system entries (such as BigQuery tables), required aspects likeSchemaare populated and synchronized automatically by Google Cloud. - Optional aspects: Supplemental metadata attached by data stewards, automated pipelines, or AI agents to enrich an entry beyond its baseline template requirements. Optional aspects can be added, updated, or removed at any time without affecting the entry's lifecycle.
Specialized system aspect types
Knowledge Catalog provides specialized reusable system aspect types that record data profiling, data quality, and relationship extraction results:
- Data quality scorecard (
data-quality-scorecard): Records overall data quality scores, evaluation status, and per-column dimension scores generated by Dataplex data quality scans. - Data rules (
data-rules) and rule templates (data-quality-rule-template): Store and manage reusable data validation rules and templates that can be applied across multiple datasets. - Data profile (
data-profile): Stores statistical metrics about table data, such as null percentages, distinct values, and distribution frequencies. - Graph profile (
graph-profile): Captures AI-extracted entities, relationship edges, and knowledge graphs extracted from unstructured documents.
Project and location scoping constraints
To maintain data governance boundaries and prevent accidental cross-region metadata dependencies, Knowledge Catalog enforces the following scoping constraints:
| Resource | Location rule | Project rule |
|---|---|---|
| Entries | The entry's location must match the location of its EntryType,
or the EntryType must be global. |
Can reference global or same-project entry types. |
| Aspects on entries | The aspect's AspectType must be in the same location as the
entry, or the AspectType must be global. |
Can reference global system aspect types or same-project custom aspect types. |
| Entry links | The entry link's location must match its EntryLinkType, or
the EntryLinkType must be global. |
Can link entries residing across different projects within the same organization. |
| Entry types | Composed of aspect types stored in the same location as the entry type,
or aspect types that are global. |
If an entry type references custom aspect types, the aspect types must reside in the same project and location. |
What's next
Manage aspects and enrich metadata
Attach aspects to entries, columns, and entry links, and manage custom aspect types using the console, gcloud CLI, or APIs.
About metadata in Knowledge Catalog
Explore the unified metamodel, including entry groups, entries, aspect types, and active context graphs.
Add metadata to a table
Follow a step-by-step tutorial to discover assets and attach custom aspect metadata to a BigQuery table.
Search and discover assets
Find resources across Google Cloud and custom sources using aspect-based search predicates.