Implementation:Datahub project Datahub AspectWithMetadata

Knowledge Sources	Datahub_project_Datahub
Domains	Java_SDK, Metadata_Management
Last Updated	2026-02-10 00:00 GMT

Overview

Description

AspectWithMetadata is an immutable value class (Lombok @Value) that wraps an aspect together with its system metadata and version string. It is used to return both the aspect value and version information from EntityClient.getAspect(). The version string is used for optimistic locking via the "If-Version-Match" header in subsequent write operations.

The class is parameterized with T extends RecordTemplate to preserve the specific aspect type.

Version extraction logic:

• Uses systemMetadata.getVersion() if the version field is present
• Returns "-1" if the aspect does not exist (used for CREATE operations)
• Returns "-1" if no version information is available

Usage

AspectWithMetadata is returned by EntityClient.getAspect() and consumed by write operations that need optimistic concurrency control. It provides factory methods: nonExistent() for aspects that do not yet exist, and from() for wrapping existing aspects with their system metadata.

Code Reference

Source Location

metadata-integration/java/datahub-client/src/main/java/datahub/client/v2/operations/AspectWithMetadata.java

Signature

@Value
public class AspectWithMetadata<T extends RecordTemplate> {

    @Nullable T aspect;
    @Nullable SystemMetadata systemMetadata;
    @Nonnull String version;

    public static <T extends RecordTemplate> AspectWithMetadata<T> nonExistent()

    public static <T extends RecordTemplate> AspectWithMetadata<T> from(
        @Nonnull T aspect, @Nullable SystemMetadata systemMetadata)
}

Import

import datahub.client.v2.operations.AspectWithMetadata;

I/O Contract

Inputs

Factory Method	Parameter	Type	Description
from	aspect	T	The aspect value
from	systemMetadata	SystemMetadata (nullable)	System metadata containing version info
nonExistent	(none)	-	Creates a wrapper representing a non-existent aspect

Outputs

Method/Field	Return Type	Description
aspect	T (nullable)	The aspect value; null if the aspect does not exist
systemMetadata	SystemMetadata (nullable)	System metadata for the aspect
version	String	Version string for optimistic locking; "-1" for non-existent aspects
nonExistent	AspectWithMetadata<T>	Wrapper with null aspect and version "-1"
from	AspectWithMetadata<T>	Wrapper with aspect and extracted version

Usage Examples

// Factory method for non-existent aspect (CREATE scenario)
AspectWithMetadata<Ownership> result = AspectWithMetadata.nonExistent();
// result.getAspect() == null
// result.getVersion() == "-1"

// Factory method for existing aspect with system metadata
AspectWithMetadata<Ownership> result = AspectWithMetadata.from(
    ownershipAspect, systemMetadata);
String version = result.getVersion(); // Used for "If-Version-Match" header

// Returned by EntityClient
AspectWithMetadata<Ownership> fetched = entityClient.getAspect(
    entityUrn, "ownership", Ownership.class);
if (fetched.getAspect() != null) {
    Ownership ownership = fetched.getAspect();
    String currentVersion = fetched.getVersion();
}

Related Pages

• Datahub_project_Datahub_AspectCache - Cache for storing fetched aspects
• Datahub_project_Datahub_VersionAwarePatchTransformer - Uses version info for optimistic locking in patch transformations
• Datahub_project_Datahub_PatchTransformer - Interface for transforming patch MCPs