# DataHub

> Search and read DataHub data catalog metadata - entities, lineage, glossary terms - via GraphQL and OpenAPI.

Lets an agent read your DataHub data catalog through the GraphQL API: search entities, get an entity by URN, list entities of a type, query upstream / downstream lineage, and list glossary terms. A GraphQL passthrough and an OpenAPI REST passthrough cover anything else. Works with DataHub Cloud (Acryl) and self-hosted GMS. Useful for data-discovery and lineage questions from a workflow.

## What it can do

| Method | What it does |
| --- | --- |
| `datahub_search` | Search entities across the catalog (optionally by type). |
| `datahub_entity_get` | Get one entity by URN. |
| `datahub_entities_list` | List entities of a given type (e.g. `DATASET`). |
| `datahub_lineage` | Get upstream / downstream lineage for an entity. |
| `datahub_glossary_terms` | List glossary terms. |
| `datahub_graphql` | Run any raw GraphQL query / mutation. |
| `datahub_openapi_request` | Generic passthrough to any OpenAPI REST endpoint. |

## How to get your credentials

DataHub authenticates with a **Personal Access Token** sent as the `Authorization: Bearer <token>` header. You also need your **GMS (Metadata Service) URL**.

1. Open your DataHub instance.
2. Go to **Settings -> Access Tokens** and generate a Personal Access Token ([token docs](https://docs.datahub.com/docs/authentication/personal-access-tokens)). Copy it - it is shown once.
3. Find your **GMS URL**: for DataHub Cloud it is your environment with `/gms` (e.g. `https://your.acryl.io/gms`); for self-hosted it is the GMS server, e.g. `http://localhost:8080`.
4. Paste both into FlyMyAI.

## Fields to fill

| FlyMyAI field | Where it comes from |
| --- | --- |
| `DATAHUB_GMS_URL` | Your GMS URL, e.g. `https://your.acryl.io/gms` or `http://localhost:8080` |
| `DATAHUB_TOKEN` | DataHub -> Settings -> Access Tokens (Personal Access Token) |

## Troubleshooting

- **`401 Unauthorized`** - the token is wrong or expired. Generate a new Personal Access Token under Settings -> Access Tokens.
- **`403 Forbidden`** - your role lacks the privilege for that action; check the token owner's DataHub permissions.
- **Connection errors / 404 on every call** - the GMS URL is wrong. Use the GMS root (DataHub Cloud ends in `/gms`); do not append `/api/graphql` - FlyMyAI adds it.
- **`GraphQL errors`** - the query or URN is malformed. Validate URNs from `datahub_search`, or use `datahub_graphql` with a query you tested in the GraphQL Playground.

## Links

- [DataHub GraphQL API](https://docs.datahub.com/docs/api/graphql/overview)
- [DataHub OpenAPI guide](https://docs.datahub.com/docs/api/openapi/openapi-usage-guide)
- [Personal Access Tokens](https://docs.datahub.com/docs/authentication/personal-access-tokens)