Open Metadata

OpenMetadata integration for Upriver

Upriver uses OpenMetadata as a read-only source of table lineage for Trino data assets. We do not ingest metadata into OpenMetadata, modify entities, or write lineage back.

This document describes what your team needs to provide, which OpenMetadata permissions are required, and how to validate the setup before or after connecting Upriver.

Supported OpenMetadata version: 1.12.x (the API paths and auth model Upriver targets).

---

What you need to provide

1. Connection details

Field	Required	Default	Description
Host	Yes	—	DNS name or IP of the OpenMetadata server (e.g. openmetadata.example.com)
Port	Yes	8585	OpenMetadata API port
HTTP scheme	Yes	https	-
Bot token	Yes	—	JWT generated for a dedicated OpenMetadata bot (see below)

These are entered in Upriver under Settings → Integrations → OpenMetadata.

2. OpenMetadata prerequisites

Before Upriver can read lineage, OpenMetadata must already contain:

Prerequisite	Why it matters
Trino registered as a Database Service	Upriver lists Trino services via GET /api/v1/services/databaseServices and picks the correct one.
Trino tables ingested	Tables must exist in OpenMetadata so Upriver can resolve catalog.schema.table to an entity FQN.
Lineage populated	Upstream edges must exist in OpenMetadata (ingestion, dbt, Spark, manual lineage, etc.). Upriver only reads lineage; it does not create it.

If you run multiple Trino database services in OpenMetadata, tell Upriver which service name to use (openmetadata_service_name on the Trino lineage configuration). When only one Trino service exists, Upriver auto-discovers it.

3. Link OpenMetadata to Trino in Upriver

1. Create an OpenMetadata integration (host, port, scheme, bot token).

2. Create or edit a Trino integration and select that OpenMetadata integration.

Lineage extraction runs as part of Trino context extraction in the Upriver deployment that processes your tenant.

4. Network access

The Upriver runtime that performs Trino context extraction must reach your OpenMetadata server:

• Direction: Outbound from Upriver → OpenMetadata

• Destination: {host}:{port} on the scheme you configure

• Path: /api/v1/*

Allowlist the Upriver egress IPs or VPC/security-group rules as you would for any other internal metadata API. TLS certificate validation uses the system trust store; use a publicly trusted cert or ensure your cluster trusts your internal CA.

---

OpenMetadata bot setup

Create a dedicated bot

Follow the OpenMetadata authentication guide:

1. In OpenMetadata: Settings → Bots → Add Bot (e.g. upriver-lineage-reader).

2. Assign a read-only role with the permissions described below.

3. Generate Token and copy the JWT.

4. Store the token securely and provide it to Upriver when creating the integration.

Use a dedicated bot per environment (staging vs production). Rotate the token by generating a new one in OpenMetadata and updating the Upriver integration.

---

Required permissions (read-only)

Upriver needs view access only. The bot must not require Create, Edit, Delete, or ingestion permissions.

API operations Upriver performs

Upriver action	OpenMetadata API	Minimum permission
List Trino database services	GET /api/v1/services/databaseServices?serviceType=Trino	View database services
Check table exists	GET /api/v1/tables/name/{fqn}	View tables
Search tables by name	GET /api/v1/search/query?index=table_search_index	Search + view tables
Read table lineage	GET /api/v1/lineage/table/name/{fqn}	View tables (lineage is read against the table)

Authentication uses Authorization: Bearer <bot_jwt> on every request.

Bot token permissions

Create a bot token backed by a role that grants at least:

Resource	Minimum permission
Database Service	ViewBasic
Table	ViewBasic

Recommended: Grant ViewAll on All resources instead of scoping only Database Service and Table. This avoids subtle 403 errors when Upriver resolves tables via search or reads lineage for upstream tables the bot must also see, and is still read-only.

If Search RBAC is enabled under Settings → Preferences → Search, the bot must be allowed to view every table asset it should resolve. Either grant view on those assets/teams or disable Search RBAC for this bot's scope.

What success and failure look like

HTTP status	Meaning
401	Missing, invalid, or expired bot token
403	Token is valid but the bot role lacks permission for that API
404	Entity not found in OpenMetadata (often missing ingestion, not a permissions issue)

---

Validate the setup

Before or after connecting Upriver, confirm the following in the OpenMetadata UI with the bot's role (or by testing the APIs with the bot JWT):

1. Trino database service — The Trino service Upriver should use is visible under Settings → Services → Databases.

2. Tables — A sample Trino table (catalog.schema.table) appears in search and opens without 403.

3. Lineage — That table's Lineage tab shows upstream tables if lineage has been ingested.

If any step returns 403, update the bot role permissions (see above) and regenerate the token if needed.

---