Implementation:Datahub project Datahub EntityClient Get

Property	Value
Implementation Name	EntityClient_Get
Workflow	Java_SDK_V2_Entity_Management
Type	API Doc
Principle	Principle:Datahub_project_Datahub_Entity_Retrieval
Repository	https://github.com/datahub-project/datahub
Last Updated	2026-02-09 17:00 GMT

Overview

Description

EntityClient_Get documents the EntityClient.get() method family for retrieving metadata entities from DataHub. The API fetches entity data via the GMS REST endpoint (GET /entitiesV2/{urn}?aspects=List(...)&systemMetadata=true), deserializes the response into strongly-typed entity objects, and returns them in a read-only state bound to the client for lazy-loading of additional aspects.

Two overloads are provided: one fetches an entity with its default aspects, and another fetches with a caller-specified list of aspect classes. Additionally, the getAspect() method allows fetching a single aspect with system metadata for optimistic locking scenarios.

Usage

Use client.entities().get(urn, EntityClass.class) to retrieve an entity. The returned entity is read-only; call .mutable() on it to obtain a writable copy for modifications.

Code Reference

Source Location

metadata-integration/java/datahub-client/src/main/java/datahub/client/v2/operations/EntityClient.java (Lines 460-533)

Signature

// Fetch entity with default aspects
public <T extends Entity> T get(
    @Nonnull String urn,
    @Nonnull Class<T> entityClass
) throws IOException, ExecutionException, InterruptedException

// Fetch entity with specified aspects
public <T extends Entity> T get(
    @Nonnull String urn,
    @Nonnull Class<T> entityClass,
    @Nonnull List<Class<? extends RecordTemplate>> aspects
) throws IOException, ExecutionException, InterruptedException

// Fetch single aspect with system metadata
public <T extends RecordTemplate> AspectWithMetadata<T> getAspect(
    @Nonnull com.linkedin.common.urn.Urn urn,
    @Nonnull Class<T> aspectClass
) throws IOException, ExecutionException, InterruptedException

Import

import datahub.client.v2.operations.EntityClient;
import datahub.client.v2.operations.AspectWithMetadata;
import datahub.client.v2.entity.Dataset;
import com.linkedin.data.template.RecordTemplate;

I/O Contract

Input (get with default aspects):

Parameter	Type	Required	Description
urn	String	Yes	Entity URN (e.g., "urn:li:dataset:(urn:li:dataPlatform:snowflake,my_table,PROD)")
entityClass	Class<T>	Yes	Entity class (e.g., Dataset.class)

Input (get with specified aspects):

Parameter	Type	Required	Description
urn	String	Yes	Entity URN
entityClass	Class<T>	Yes	Entity class
aspects	List<Class<? extends RecordTemplate>>	Yes	Aspect classes to fetch

Input (getAspect):

Parameter	Type	Required	Description
urn	Urn	Yes	Entity URN object
aspectClass	Class<T>	Yes	Aspect class to fetch

Output:

Method	Return Type	Description
get(urn, class)	T extends Entity	Entity populated with default aspects, bound to client, read-only
get(urn, class, aspects)	T extends Entity	Entity populated with specified aspects, bound to client, read-only
getAspect(urn, class)	AspectWithMetadata<T>	Wrapper containing aspect, system metadata, and version info

REST API Call:

GET {server}/entitiesV2/{encodedUrn}?aspects=List(aspect1,aspect2,...)&systemMetadata=true

Exceptions:

Exception	Cause
IOException	Network error, server error, or entity fetch failure
ExecutionException	Underlying HTTP future execution failure
InterruptedException	Thread interrupted while waiting for server response
AspectParseException	Failed to deserialize aspect JSON into RecordTemplate

Usage Examples

Fetch Entity with Default Aspects

import datahub.client.v2.entity.Dataset;

String urn = "urn:li:dataset:(urn:li:dataPlatform:snowflake,analytics.public.users,PROD)";

// Fetches with default aspects: Ownership, GlobalTags, GlossaryTerms,
// Domains, Status, InstitutionalMemory, DatasetProperties, EditableDatasetProperties
Dataset dataset = client.entities().get(urn, Dataset.class);

// Entity is read-only
String description = dataset.getDescription();

Fetch Entity with Specific Aspects

import com.linkedin.common.Ownership;
import com.linkedin.common.GlobalTags;
import com.linkedin.schema.SchemaMetadata;

List<Class<? extends RecordTemplate>> aspects = List.of(
    Ownership.class,
    GlobalTags.class,
    SchemaMetadata.class
);

Dataset dataset = client.entities().get(urn, Dataset.class, aspects);
SchemaMetadata schema = dataset.getSchema();

Read-Modify-Write Pattern

// Step 1: Fetch entity (read-only)
Dataset readOnly = client.entities().get(urn, Dataset.class);

// Step 2: Get mutable copy
Dataset mutable = readOnly.mutable();

// Step 3: Apply modifications
mutable.setDescription("Updated description");
mutable.addTag("verified");

// Step 4: Upsert back to DataHub
client.entities().upsert(mutable);

Fetch Single Aspect

import com.linkedin.common.Ownership;
import com.linkedin.common.urn.Urn;

Urn entityUrn = Urn.createFromString(urn);
AspectWithMetadata<Ownership> result = client.entities().getAspect(entityUrn, Ownership.class);

Ownership ownership = result.getAspect();
if (ownership != null) {
    // Access ownership data
}

Related Pages

• Principle:Datahub_project_Datahub_Entity_Retrieval
• Implementation:Datahub_project_Datahub_Entity_Mutable_Patch -- Making fetched entities mutable for modification
• Implementation:Datahub_project_Datahub_EntityClient_Upsert -- Persisting modified entities back
• Implementation:Datahub_project_Datahub_DataHubClientV2_Builder -- Client required for entity retrieval
• Environment:Datahub_project_Datahub_Java_Build