# How the data catalog works (/docs/data/data-catalog/how-it-works)



The data catalog is the discovery surface for governed tables on BullSequana AI. Data scientists and data engineers search it in the Portal, and applications query it through the BSQAI API. It is distinct from the **Connectors** list under **Data Ingestion** in Studio, which lists ingestion connectors rather than governed tables.

The catalog combines what a user is allowed to see, what a table's structure and location look like, and optional business context into one view instead of requiring separate lookups against each underlying service.

## What the catalog provides [#what-the-catalog-provides]

Without a catalog, discovering a table means knowing which catalog and schema it lives in, checking authorization separately, and reading raw metastore metadata to understand its structure. That approach doesn't scale once a tenant has more than a handful of datasets, and it gives data consumers no way to tell whether a table is governed, who owns it, or what it contains before they query it.

The data catalog closes that gap. It:

* gives users a single place to discover the tables they're authorized to see, scoped to their identity
* shows table structure (columns, partitions, storage location) without requiring direct access to the metastore or the authorization service
* surfaces business context, such as descriptions, tags, glossary terms, and lineage, where that context is available
* shows table owners who holds direct access to each table

By aggregating these concerns behind one API, the catalog keeps authorization, storage metadata, and business metadata as separate systems of record while presenting them to users as one coherent experience.

## Use the catalog in the Portal [#use-the-catalog-in-the-portal]

Users browse and search the catalog in Studio under **Discover** > **Data
Catalog**. See [Data catalog](/docs/data/data-catalog) for the user guide.

## What the catalog aggregates [#what-the-catalog-aggregates]

The data catalog aggregates data from three sources and merges the results per table.

| Source                | What it provides                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| Authorization service | Which tables a user can discover, each table's owner, and direct authorization grants on a table |
| Metastore             | Table structure (columns and types), partition layout, and storage location                      |
| Metadata API          | Description, tags, glossary terms, quality score, and upstream and downstream lineage            |

The authorization service and the metastore are required dependencies. The Metadata API is an optional enrichment source and is not configured by default. Without it, the catalog still returns authorization and structure data, just without the enrichment fields.

## How it works [#how-it-works]

<Mermaid
  chart="flowchart TD
    UI[&#x22;Portal Data Catalog or API client with a Keycloak token&#x22;] --> API[&#x22;BSQAI API /v1/data-catalog: data.catalog.read in the active tenant&#x22;]
    API -->|caller token| TUP[&#x22;Tuples: discoverable tables, grants, and space ownership&#x22;]
    API -->|caller token| LAKE[&#x22;Lakekeeper: columns, partitions, and location&#x22;]
    API -. when configured .-> OM[&#x22;OpenMetadata: description, tags, glossary, quality, and lineage&#x22;]"
/>

The BSQAI API checks the `data.catalog.read` permission in the active tenant for every catalog request. It then forwards the caller's own access token to the authorization service and the metastore. Those services run their own per-table authorization against that token, so the response contains only the tables the caller is allowed to discover.

## Call the catalog API [#call-the-catalog-api]

The catalog is part of the [BSQAI API](/docs/ai/components/bsqai-api), reachable at `https://api.<platform-domain>/v1/data-catalog`. Call it with a Keycloak access token in the `Authorization: Bearer` header. Because the token is forwarded to the services behind the catalog, an API key cannot replace it.

| Route                                                              | Returns                                                                                                               |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/data-catalog/tables?search=<text>`                        | The tables the caller can discover, with dataset, space, owner, columns, partitions, location and optional enrichment |
| `GET /v1/data-catalog/tables/<space>/<dataset>/<table>/grants`     | The direct grants stored for one table                                                                                |
| `GET /v1/data-catalog/tables/<space>/<dataset>/<table>/can-manage` | Whether the caller owns the table, directly or through its dataset or space                                           |

The `search` filter matches the table identifier, name, and dataset. The can-manage check tells whether the caller owns the table, directly or through its dataset or space. The Portal shows the **Permissions** panel only when it does. The grants route itself answers any caller who can discover the table.

## Graceful degradation [#graceful-degradation]

The catalog depends on the authorization service: if it's unreachable, catalog requests fail, since authorization is required for every catalog operation. A metastore failure is scoped to the affected table, which is returned with a metadata error instead of its structure. A Metadata API failure, or the Metadata API not being configured, is treated as unavailable enrichment, never as a request failure.

## Related pages [#related-pages]

* [BSQAI API](/docs/ai/components/bsqai-api)
* [Tuples (authorization service)](/docs/data/components/tuples)
* [Data catalog](/docs/data/data-catalog)
* [Metastore](/docs/data/developer-workspace/metastore)
* [Multi-tenancy and tiered access in Data](/docs/data/multi-tenancy-and-tiered-rbac)
* [API reference](/docs/reference#api-endpoints)
