Python Fluent API - Collate Documentation

Overview

The Collate Python SDK provides entity-specific classes for reading and writing metadata. Each class — Tables, Databases, Users, etc. — shares the same CRUD interface and connects to a globally-configured client.

Installation

pip install collate-ingestion

Tip: Match the SDK version to your Collate instance version.

Configuration

from metadata.sdk import configure

# Explicit credentials
configure(
    host="https://your-instance.getcollate.io/api",
    jwt_token="your-jwt-token",
)

Call configure() once at startup — all entity class calls use it automatically. You can also read credentials from environment variables:

export OPENMETADATA_HOST="https://your-instance.getcollate.io/api"
export OPENMETADATA_JWT_TOKEN="your-jwt-token"

from metadata.sdk import configure

configure()  # reads from env

Global Functions

Function	Description
`configure(host, jwt_token)`	Initialize the SDK with server credentials.
`client()`	Return the active `OpenMetadata` client.
`reset()`	Close and clear the cached client.
`to_entity_reference(entity)`	Convert an entity to an `EntityReference` dict.

Entity references

Many metadata fields (owners, domains, etc.) expect EntityReference dicts rather than full entity objects. Use to_entity_reference() to convert:

from metadata.sdk import configure, to_entity_reference, Users, Databases

configure(host="...", jwt_token="...")

user = Users.retrieve_by_name("alice")
db = Databases.retrieve_by_name("my_service.my_db", fields=["owners"])
db.owners = [to_entity_reference(user)]
Databases.update(db)

BaseEntity Operations

All entity classes inherit these methods:

Method	Description
`Entity.create(request)`	Create or upsert an entity.
`Entity.retrieve(id, *, fields)`	Fetch by UUID.
`Entity.retrieve_by_name(fqn, *, fields)`	Fetch by fully-qualified name.
`Entity.list(*, limit, after, fields, filters)`	Fetch one page.
`Entity.list_all(*, batch_size, fields, filters)`	Fetch all (auto-paginated).
`Entity.update(entity)`	Patch using source/destination diff.
`Entity.delete(id, *, recursive, hard_delete)`	Soft or hard delete.
`Entity.search(query, *, size)`	Search by FQN substring.
`Entity.export_csv(name).execute()`	Export as CSV.
`Entity.import_csv(name).with_data(csv).execute()`	Bulk import from CSV.
`Entity.get_versions(id)`	All historical versions.
`Entity.get_specific_version(id, version)`	One specific version.
`Entity.restore(id)`	Restore a soft-deleted entity.

Entity Classes

Class	Description
Tables	Database tables
Databases	Databases
DatabaseSchemas	Database schemas
DatabaseServices	Database service connections
Dashboards	BI dashboards
Pipelines	Data pipelines
Users	Users