# Unity Catalog Native API

Source: https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/api/

Everything you can do with a Unity Catalog Native datastore over the API: create one with a new or an existing connection, list the catalogs and schemas a credential can see, test the connection, read and list datastores, update or delete one, and create several at once from the schemas of a single catalog.

> **Tip: Complete API Reference**
>
> For the full interactive API documentation with all request and response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs).

**Endpoint**: `POST /api/datastores`

**Permission**: Manager role, with the **Editor** team permission on at least one of the teams in `teams`, or on the Public team when `teams` is omitted.

> **Warning: Source datastores only**
>
> Unity Catalog Native is read-only and cannot be used as an enrichment datastore. To link a separate enrichment datastore as the source's destination, see [Datastore API › Link Enrichment Destination](https://userguide.qualytics.io/source-datastore/datastore/api/#link-an-enrichment-destination).

---

## UI ↔ API field mapping

The API names several fields differently from the connection form, and the credential lands in a different place depending on the authentication type.

| UI form field | API field | Notes |
| --- | --- | --- |
| **Connection > URL** | `connection.parameters.uri` | The workspace URL or the Unity Catalog server URL |
| **Connection > Catalog** | `connection.catalog` | The catalog the connection monitors |
| **Connection > Type** | `connection.parameters.authentication_type` | `TOKEN` (the default when omitted) or `OAUTH` |
| **Connection > Access Token** | `connection.password` | With `TOKEN` |
| **Connection > Client ID** | `connection.username` | With `OAUTH` |
| **Connection > Client Secret** | `connection.password` | With `OAUTH` |
| **Connection > Token Endpoint** | `connection.parameters.oauth_uri` | Optional, with `OAUTH`. Defaults to the URL followed by `/oidc/v1/token` |
| **Location > Schema** | `schema` | The schema to monitor |

> **Note: The catalog travels with the connection**
>
> `catalog` is a connection field, not a datastore field, because a connection monitors one catalog. Every datastore created on the connection reads from it. To monitor a second catalog, create a second connection.

---

## Discover Catalogs and Schemas

Before saving anything, you can ask which catalogs a credential can see, and which schemas a catalog holds. This is what fills the **Catalog** and **Schema** dropdowns in the form. Send the connection object alone, without a datastore around it. The catalog may be left out while discovering catalogs.

**Permission**: Manager

**Tab: Catalogs**

**Endpoint**: `POST /api/connections/catalogs`

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/connections/catalogs" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "acme_prod_catalog",
>     "type": "unity_native",
>     "password": "<access token>",
>     "parameters": {
>       "uri": "https://acme.cloud.databricks.com",
>       "authentication_type": "TOKEN"
>     }
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> ["main", "prod", "samples"]
> ```

**Tab: Schemas**

**Endpoint**: `POST /api/connections/schemas?catalog={catalog}`

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/connections/schemas?catalog=prod" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "acme_prod_catalog",
>     "type": "unity_native",
>     "password": "<access token>",
>     "parameters": {
>       "uri": "https://acme.cloud.databricks.com",
>       "authentication_type": "TOKEN"
>     }
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> ["bronze", "finance", "sales", "silver"]
> ```

The lists hold only what the credential holds `USE CATALOG` and `USE SCHEMA` on. Nothing is saved by either call.

---

## Create a Unity Catalog Native Datastore

Both flows use the same endpoint and differ only in whether the connection travels inline or by reference.

**Tab: New Connection**

Pass the URL, the catalog, and the credential inline. Qualytics saves the connection and creates the datastore in a single call, so the connection is then available to reuse.

**Connection fields**

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `type` | string | Yes |  | `unity_native`. |
| `name` | string | Yes |  | A label for the saved connection. |
| `catalog` | string | Yes |  | The catalog the connection monitors. |
| `parameters.uri` | string | Yes |  | The workspace URL, for example `https://acme.cloud.databricks.com`, or the Unity Catalog server URL. |
| `parameters.authentication_type` | string | No | `TOKEN` | `TOKEN` for an access token, `OAUTH` for a service principal. |
| `password` | string | Yes |  | The access token with `TOKEN`, or the client secret with `OAUTH`. |
| `username` | string | With `OAUTH` |  | The service principal's client ID. |
| `parameters.oauth_uri` | string | No |  | With `OAUTH`, where access tokens are requested. Defaults to `parameters.uri` followed by `/oidc/v1/token`. |

**Datastore fields**

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Yes |  | The datastore name in Qualytics. |
| `schema` | string | Yes |  | The schema to monitor. |
| `teams` | array | No | The Public team | The teams that can work with this datastore. When omitted, the datastore is assigned to the Public team. |
| `trigger_sync` | boolean | No | `false` | Ask Qualytics to run the first Sync once the datastore is created, equivalent to ticking **Initiate Sync** in the form. |

> **Example: Example request and response**
>
> **Request** (access token):
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Prod Sales",
>     "connection": {
>       "name": "acme_prod_catalog",
>       "type": "unity_native",
>       "catalog": "prod",
>       "password": "<access token>",
>       "parameters": {
>         "uri": "https://acme.cloud.databricks.com",
>         "authentication_type": "TOKEN"
>       }
>     },
>     "schema": "sales",
>     "teams": ["Data Platform"],
>     "trigger_sync": true
>   }'
> ```
>
> **Request** (service principal), the `connection` object only:
>
> ```json
> {
>   "name": "acme_prod_catalog",
>   "type": "unity_native",
>   "catalog": "prod",
>   "username": "<client id>",
>   "password": "<client secret>",
>   "parameters": {
>     "uri": "https://acme.cloud.databricks.com",
>     "authentication_type": "OAUTH"
>   }
> }
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 42,
>   "name": "Prod Sales",
>   "type": "unity_native",
>   "store_type": "native",
>   "catalog": "prod",
>   "schema": "sales",
>   "connected": true
> }
> ```

**Tab: Existing Connection**

Reuse a Unity Catalog Native connection you already created, through this API or the connection form, by passing its `connection_id`. The URL, the catalog, and the credential come from the saved connection, so you supply only the datastore fields.

Reuse it whenever you are adding another schema from the same catalog. The credential stays in one place, and changing it later is a single edit rather than one per datastore.

**Datastore fields**

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Yes |  | The datastore name in Qualytics. |
| `connection_id` | integer | Yes |  | The ID of the saved Unity Catalog Native connection. |
| `schema` | string | Yes |  | The schema to monitor, in the connection's catalog. |
| `teams` | array | No | The Public team | The teams that can work with this datastore. When omitted, the datastore is assigned to the Public team. |
| `trigger_sync` | boolean | No | `false` | Ask Qualytics to run the first Sync once the datastore is created. |

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Prod Finance",
>     "connection_id": 7,
>     "schema": "finance",
>     "teams": ["Finance Team"],
>     "trigger_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 43,
>   "name": "Prod Finance",
>   "type": "unity_native",
>   "store_type": "native",
>   "catalog": "prod",
>   "schema": "finance",
>   "connected": true
> }
> ```

> **Tip: Run the first Sync**
>
> A datastore is only useful once Sync has discovered its tables. Send `trigger_sync` as `true` to start it with the datastore, or run a **Sync** yourself once the request returns.

---

## Test a Connection

Both tests run as the **Member** role. The second one also needs the **Editor** team permission on the datastore.

**Tab: Before saving**

Validates a create payload without persisting anything. Send the same body you would send to create the datastore.

**Endpoint**: `POST /api/datastores/connection`

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores/connection" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Prod Sales",
>     "connection": {
>       "name": "acme_prod_catalog",
>       "type": "unity_native",
>       "catalog": "prod",
>       "password": "<access token>",
>       "parameters": {
>         "uri": "https://acme.cloud.databricks.com",
>         "authentication_type": "TOKEN"
>       }
>     },
>     "schema": "sales",
>     "teams": ["Data Platform"]
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "connected": true,
>   "message": null
> }
> ```
>
> When the connection cannot be verified, the response is a **400 Bad Request** whose message names the failure. A `message` on a 200 is a warning, not an error.

**Tab: An existing datastore**

Re-checks a saved datastore. Because Unity Catalog Native is read-only, the check confirms that Qualytics can read from the catalog.

**Endpoint**: `POST /api/datastores/{id}/connection`

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores/42/connection" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "connected": true,
>   "message": null
> }
> ```
>
> A datastore that cannot be reached answers `"connected": false` with the reason in `message`.

> **Note**
>
> The catalog answering is not the same as the data being readable. A test can pass while the table files are still unreachable, or while the identity is not yet allowed to read them from outside Databricks, which shows up as a failed profile rather than a failed test. See [Troubleshooting](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/troubleshooting/).

---

## Get a Datastore

**Endpoint**: `GET /api/datastores/{id}`

**Permission**: Member

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/datastores/42" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 42,
>   "name": "Prod Sales",
>   "type": "unity_native",
>   "store_type": "native",
>   "connection_id": 7,
>   "catalog": "prod",
>   "schema": "sales",
>   "parameters": {
>     "uri": "https://acme.cloud.databricks.com",
>     "authentication_type": "TOKEN"
>   },
>   "has_password": true,
>   "connected": true,
>   "enrichment_only": false,
>   "enrichment_prefix": "_prod_sales",
>   "teams": [{ "name": "Data Platform" }]
> }
> ```

> **Note: The credential never comes back**
>
> `has_password` reports only whether an access token or a client secret is stored on the connection. Its value is never returned.

---

## List Datastores

**Endpoint**: `GET /api/datastores`

**Permission**: Member

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/datastores?datastore_type=unity_native&sort_name=asc" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "items": [
>     { "id": 43, "name": "Prod Finance", "type": "unity_native", "store_type": "native", "connected": true },
>     { "id": 42, "name": "Prod Sales", "type": "unity_native", "store_type": "native", "connected": true }
>   ],
>   "total": 2,
>   "page": 1,
>   "size": 50,
>   "pages": 1
> }
> ```

### Query Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | `list[int]` | Filter by datastore ID. |
| `name` | string | Filter by exact name. |
| `search` | string | Partial name match, case-insensitive, or an exact ID. |
| `datastore_type` | `list[string]` | Filter by connector type. `unity_native` returns only Unity Catalog Native datastores. |
| `tag` | `list[string]` | Filter by tag name. |
| `group` | `list[int]` | Filter by datastore group ID. |
| `enrichment_only` | boolean | `false` for source datastores (the default). Unity Catalog Native datastores are always source datastores. |
| `sort_name`, `sort_created`, `sort_favorite`, `sort_containers`, `sort_active_anomalies` | string | `asc` or `desc`. |

---

## Update a Datastore

Changes the datastore's own settings. Every request must include `name`, `connection_id`, `enrichment_only`, and `enrichment_prefix`, even when they are not changing, so send their current values from [Get a Datastore](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/api/#get-a-datastore). Most other parameters you leave out stay as they are, with two exceptions:

- `tags` and `teams` replace the whole list when sent.
- `enrichment_source_record_limit`, `enrichment_remediation_strategy`, and `high_count_rollup_threshold` go back to their defaults (`10`, `none`, and `10`) whenever they are left out. Send their current values on every update to keep them. The example below sends the values a datastore without a linked enrichment destination has.

**Endpoint**: `PUT /api/datastores/{id}`

**Permission**: Member role, with the **Editor** team permission on the datastore. Changing `teams` also takes the **Manager** or **Admin** role.

> **Note: What lives on the connection**
>
> The URL, the catalog, the authentication type, and the credential belong to the connection, not to the datastore. Change them through the connection, and the change reaches every datastore that shares it.

> **Tip: Favorites**
>
> Marking a datastore as a favorite has its own endpoint: send `{"favorite": true}` (or `false`) to `PATCH /api/datastores/{id}/favorite`, with the **Member** role. This update ignores a `favorite` property.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | The datastore name. |
| `connection_id` | integer | Yes | The Unity Catalog Native connection the datastore reads through. |
| `enrichment_only` | boolean | Yes | Always `false`. Unity Catalog Native datastores are source datastores. |
| `enrichment_prefix` | string | Yes | The prefix for the tables Qualytics writes to the linked enrichment destination. Send the current value to keep it. |
| `description` | string | No | Free text shown on the datastore. |
| `schema` | string | No | The schema to monitor, in the connection's catalog. |
| `tags` | `list[string]` | No | Replaces the datastore's tags. |
| `teams` | `list[string]` | No | Replaces the datastore's teams. Needs the **Manager** or **Admin** role. |
| `enrichment_source_record_limit`, `enrichment_remediation_strategy`, `enrichment_auto_profile`, `high_count_rollup_threshold` | mixed | No | Settings for the enrichment destination linked to this source. `enrichment_auto_profile` was previously named `enrichment_auto_sync`; the old name is deprecated, still accepted, and will be removed in a future release. |

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X PUT "https://your-instance.qualytics.io/api/datastores/42" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Prod Sales (EMEA)",
>     "connection_id": 7,
>     "enrichment_only": false,
>     "enrichment_prefix": "_prod_sales",
>     "enrichment_source_record_limit": 10,
>     "enrichment_remediation_strategy": "none",
>     "high_count_rollup_threshold": 10,
>     "schema": "sales_emea",
>     "tags": ["unity", "sales"],
>     "teams": ["Data Platform", "Sales Ops"]
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 42,
>   "name": "Prod Sales (EMEA)",
>   "type": "unity_native",
>   "store_type": "native",
>   "connection_id": 7,
>   "catalog": "prod",
>   "schema": "sales_emea",
>   "global_tags": [{ "name": "unity" }, { "name": "sales" }],
>   "teams": [{ "name": "Data Platform" }, { "name": "Sales Ops" }]
> }
> ```

---

## Delete a Datastore

**Endpoint**: `DELETE /api/datastores/{id}`

**Permission**: Admin

> **Example: Example request**
>
> ```bash
> curl -X DELETE "https://your-instance.qualytics.io/api/datastores/42" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**: `204 No Content`

> **Warning**
>
> Deletion permanently removes the datastore's containers, checks, anomalies, and operation history from Qualytics. Data already written to an enrichment destination stays there and must be removed separately. The connection stays, and so does every other datastore that uses it.

---

## Create Several Datastores at Once

A catalog usually holds more schemas than one. The bulk endpoints take a list of schemas and create one datastore per entry, sharing the same connection and settings.

**Permission**: Manager role, with the **Editor** team permission on at least one of the teams in `teams`, or on the Public team when `teams` is omitted.

**Tab: New Connection**

**Endpoint**: `POST /api/connections/datastores/bulk`

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/connections/datastores/bulk" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "connection": {
>       "name": "acme_prod_catalog",
>       "type": "unity_native",
>       "catalog": "prod",
>       "password": "<access token>",
>       "parameters": {
>         "uri": "https://acme.cloud.databricks.com",
>         "authentication_type": "TOKEN"
>       }
>     },
>     "schemas": ["sales", "finance", "inventory"],
>     "name_template": "prod_{{schema}}",
>     "teams": ["Data Platform"],
>     "trigger_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "created": [101, 102, 103],
>   "errors": [],
>   "connection_id": 12
> }
> ```

**Tab: Existing Connection**

**Endpoint**: `POST /api/connections/{connection_id}/datastores/bulk`

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/connections/7/datastores/bulk" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "schemas": ["marketing", "logistics"],
>     "name_template": "prod_{{schema}}",
>     "teams": ["Data Platform"],
>     "trigger_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "created": [110, 111],
>   "errors": [],
>   "connection_id": 7
> }
> ```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `connection` | object | New connection only | The same connection object as in [Create a Unity Catalog Native Datastore](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/api/#create-a-unity-catalog-native-datastore), including `catalog`. |
| `schemas` | `list[string]` | Yes | The schemas to create datastores for, one datastore each, all in the connection's catalog. |
| `name_template` | string | No | Naming pattern with `{{schema}}` standing for the schema name. Defaults to the connection name followed by the schema. |
| `teams` | `list[string]` | No | Teams assigned to every created datastore. |
| `tags` | `list[string]` | No | Tags applied to every created datastore. |
| `group_id` | integer | No | An existing datastore group to place them in. |
| `description` | string | No | Description applied to every created datastore. |
| `trigger_sync` | boolean | No | Run the first Sync on each datastore as it is created. |

> **Note**
>
> There is no `database` field to send: the catalog is on the connection, so `schemas` is the whole address. Creation is not atomic. Schemas that succeed are created even if others fail, and the response lists both the created IDs and, per failed schema, the reason. It also returns `connection_id`, the connection the datastores were created on. To retry the failed schemas, send them to that connection through the **Existing Connection** endpoint. When no datastore was created, a **New Connection** request still returns `connection_id` if the connection was saved anyway, for example when every schema was removed after its enrichment link was refused, so retry on it the same way. When `connection_id` is `null` after a **New Connection** request, the connection was not saved, so resend the whole request. After an **Existing Connection** request, `connection_id` is `null` when no datastore was created. Retry on the same connection ID.

*Last updated: October 13, 2026.*
