Collate Python SDK quickstart

Collate uses the openmetadata-ingestion Python package for typed metadata operations. Match the package release line to your Collate server release.

Which Python SDK Should I Use?

The openmetadata-ingestion package contains two Python clients. Both call the same Collate API.

	Original client	SDK 2.0
Import	`metadata.ingestion.ometa.ometa_api.OpenMetadata`	`metadata.sdk`
Setup	Build an `OpenMetadataConnection` and pass it to `OpenMetadata(...)`	Call `configure(host=..., jwt_token=...)` once
Style	Generic methods that take an entity type, such as `metadata.get_by_name(entity=Table, fqn=...)`	One class per entity, such as `Tables.retrieve_by_name(fqn)`
Available since	Every release	`openmetadata-ingestion` 1.10.0

For new scripts and jobs, use SDK 2.0. It needs less setup and reads more simply. Use the original client when you need an operation that SDK 2.0 doesn’t offer, or when you maintain existing code that already uses it.

Use Both Clients in One Script

Both ship in the same package, so one script can use both. Set up each one separately: call configure() for SDK 2.0 and build an OpenMetadata client for the original client.

Migrate an Existing Job

Change one call at a time:

Original client	SDK 2.0
`metadata.create_or_update(data=request)`	`Tables.create(request)`
`metadata.get_by_id(entity=Table, entity_id=id)`	`Tables.retrieve(id)`
`metadata.get_by_name(entity=Table, fqn=fqn)`	`Tables.retrieve_by_name(fqn)`
`metadata.list_all_entities(entity=Table)`	`Tables.list_all()`
`metadata.list_entities(entity=Table, params={...})`	`Tables.list(filters={...})`
`metadata.delete(entity=Table, entity_id=id)`	`Tables.delete(id)`

Tables.create(request) also updates an existing table, the same as create_or_update. Keep these differences in mind:

Host URL: In configure(host=...), end the URL with /api, the same as hostPort in the original client. Without /api, the connection fails.
Listing: Pass query filters as filters={"databaseSchema": "service.database.schema"}.
Authentication: With the original client, set authProvider="openmetadata" when you authenticate with a JWT token. SDK 2.0 doesn’t need an authProvider.
Updates: Tables.update(table) sends only the changed fields as a JSON Patch. If nothing changed, it sends no request, doesn’t change the version number, and returns None.

Install the SDK

For Collate 2.0.5, install a package from the matching server patch line:

pip install "openmetadata-ingestion~=2.0.5.0"

Configure the connection

Set the Collate API URL and an ingestion bot JSON Web Token (JWT):

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

Call configure() once when the application starts. Entity classes reuse the configured client.

from metadata.sdk import configure

configure()

Pass credentials directly when environment variables aren’t available:

from metadata.sdk import configure

configure(
    host="https://your-company.getcollate.io/api",
    jwt_token="your-jwt-token",
)

Manage a table

The following example creates, retrieves, updates, and soft-deletes a table. Replace sample_data.ecommerce_db.shopify with the fully qualified name of an existing database schema.

from metadata.generated.schema.api.data.createTable import CreateTableRequest
from metadata.generated.schema.entity.data.table import Column, DataType
from metadata.generated.schema.type.basic import Markdown
from metadata.sdk import Tables, configure

configure()

schema_fqn = "sample_data.ecommerce_db.shopify"

# Create or update the table.
created = Tables.create(
    CreateTableRequest(
        name="customers",
        databaseSchema=schema_fqn,
        description="Customer master data",
        columns=[
            Column(name="id", dataType=DataType.BIGINT),
            Column(name="email", dataType=DataType.VARCHAR, dataLength=320),
            Column(name="created_at", dataType=DataType.TIMESTAMP),
        ],
    )
)
print(f"Created: {created.fullyQualifiedName}")

# Retrieve by fully qualified name.
table = Tables.retrieve_by_name(f"{schema_fqn}.customers")
if table is None:
    raise RuntimeError("Table was not found")

# Update the description.
table.description = Markdown("Customer master data managed with the Python SDK")
updated = Tables.update(table)
print(f"Updated: {updated.description}")

# Soft-delete the table. Soft-deleted entities remain recoverable.
Tables.delete(updated.id)

Tables.create() is idempotent. It creates the table when it doesn’t exist and updates it when the fully qualified name already exists. Tables.update() sends only the fields you changed. When no field changed, it makes no request and returns None, so check the result before you read from it.

Avoid hard_delete=True unless permanent removal is intended. Hard deletes can’t be undone.

SDKs and APIs

Collate Python SDK quickstart

Collate Python SDK quickstart

Which Python SDK Should I Use?

Use Both Clients in One Script

Migrate an Existing Job

Install the SDK

Configure the connection

Manage a table

Next steps

​Collate Python SDK quickstart

​Which Python SDK Should I Use?

​Use Both Clients in One Script

​Migrate an Existing Job

​Install the SDK

​Configure the connection

​Manage a table

​Next steps

Collate Python SDK quickstart

Which Python SDK Should I Use?

Use Both Clients in One Script

Migrate an Existing Job

Install the SDK

Configure the connection

Manage a table

Next steps