> For the complete documentation index, see [llms.txt](https://docs.upriverdata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.upriverdata.com/integrations/open-metadata.md).

# 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](https://docs.open-metadata.org/v1.12.x/api-reference/authentication):

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.

***