Principle:Datahub project Datahub V2 Client Setup
| Property | Value |
|---|---|
| Principle Name | V2_Client_Setup |
| Workflow | Java_SDK_V2_Entity_Management |
| Scope | Client initialization and configuration |
| Implementation | Implementation:Datahub_project_Datahub_DataHubClientV2_Builder |
| Repository | https://github.com/datahub-project/datahub |
| Last Updated | 2026-02-09 17:00 GMT |
Overview
Description
V2 Client Setup is the principle of initializing a type-safe client for metadata platform entity management. The DataHub Java SDK V2 provides a centralized entry point for all metadata operations through a single client object that encapsulates connection configuration, authentication, retry policies, and emission modes. This principle ensures that all interactions with the DataHub metadata platform originate from a properly configured, reusable, and thread-safe client instance.
The client acts as a gateway to entity operations, providing access to an EntityClient that handles CRUD operations for all supported entity types. By centralizing configuration in the client, downstream operations inherit consistent behavior for timeouts, retries, SSL verification, and synchronization semantics without requiring per-call configuration.
Usage
This principle applies whenever a Java application needs to interact with the DataHub metadata platform. Common scenarios include:
- Metadata ingestion pipelines that need to push discovered metadata into DataHub
- Data governance tools that read and update ownership, tags, and glossary terms
- CI/CD integrations that register datasets, pipelines, or dashboards as part of deployment
- Administrative scripts that perform bulk metadata operations
The client should be created once at application startup and reused throughout the application lifecycle. It implements AutoCloseable, enabling deterministic resource cleanup when the client is no longer needed.
Theoretical Basis
The V2 Client Setup principle is grounded in the Builder pattern for object construction. The Builder pattern separates the construction of a complex object from its representation, allowing the same construction process to create different configurations. This is particularly well-suited for client initialization because:
- Many optional parameters: The client accepts server URL, authentication token, timeout, SSL settings, retry count, and emit mode. A telescoping constructor would be unwieldy and error-prone.
- Validation at construction time: The builder validates that required parameters (such as server URL) are present before creating the client, failing fast rather than at first use.
- Environment-aware initialization: The
buildFromEnv()method provides an alternative construction path that reads configuration from environment variables (DATAHUB_SERVER,DATAHUB_GMS_URL,DATAHUB_TOKEN,DATAHUB_GMS_TOKEN), supporting twelve-factor app configuration.
The client also follows the Facade pattern, providing a simplified interface to the complex subsystem of REST emitters, entity clients, server configuration caching, and patch transformers. Users interact with a single DataHubClientV2 object that internally manages:
- RestEmitter: The HTTP transport layer for sending Metadata Change Proposals
- EntityClient: The operations layer for entity CRUD and patch operations
- ServerConfig: Cached server metadata with TTL-based refresh for version-aware behavior
| Builder Parameter | Type | Default | Description |
|---|---|---|---|
server |
String | required | DataHub GMS server URL |
token |
String | optional | Authentication token |
timeoutMs |
int | 10000 | HTTP request timeout in milliseconds |
disableSslVerification |
boolean | false | Disable SSL certificate verification |
maxRetries |
int | 3 | Maximum retry count for failed requests |
emitMode |
EmitMode | SYNC_PRIMARY | Emission synchronization mode (SYNC_PRIMARY, SYNC_WAIT, ASYNC) |
Sensible defaults allow minimal configuration for common use cases. A production client can be created with only a server URL and token, while testing scenarios can disable SSL verification and adjust timeouts as needed.
Related Pages
- Implementation:Datahub_project_Datahub_DataHubClientV2_Builder
- Principle:Datahub_project_Datahub_Client_Resource_Cleanup -- Deterministic cleanup of client resources
- Principle:Datahub_project_Datahub_Entity_Construction -- Building entity objects to use with the client
- Principle:Datahub_project_Datahub_Entity_Upsert -- Persisting entities through the client