> For the complete documentation index, see [llms.txt](https://docs.e6data.com/query-engine/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.e6data.com/query-engine/guides/catalogs/register-and-manage-catalogs.md).

# Register and manage catalogs

Registering a catalog connects e6data to a metastore so it can discover and query your tables. The Create flow is the same across catalog types - only the connection fields differ. After registration, you refresh, edit, or delete the catalog from the **Catalogs** page.

## Before you start

* Open your workspace's Compute Plane.
* Have your metastore connection details ready (host, port, credentials).
* For Serverless deployments, complete the cloud-specific storage access setup so e6data can read the underlying data - see [Deployment](/query-engine/guides/deployment/aws-serverless.md).

## Create a catalog

1. From the Compute Plane, go to **Catalogs** in the left navigation and click **Create Catalog**.
2. Enter a **Catalog Name** - unique within the workspace, up to 253 characters. Mixed case, letters, numbers, hyphens, and dots are allowed; spaces and underscores are accepted but normalized to hyphens in the name e6data stores internally, while dots are preserved (for example, `My Glue Catalog` becomes `my-glue-catalog`). See [resource naming conventions](/query-engine/reference/platform-reference/resource-naming-conventions.md) for the full rules.
3. Select a **Catalog Type**: Hive Metastore, AWS Glue, Databricks Unity, Microsoft Fabric, Apache Polaris, Iceberg REST, or AWS S3 Tables.
4. (Optional) Enable **Governance** to apply fine-grained access control via Ranger, OPA, Unity, or Lake Formation.
5. Fill in the **connection details** for your catalog type - see the per-catalog guides under [Catalogs](/query-engine/guides/catalogs.md).
6. (Optional) Enable **Cross-Account Access** if the storage or metastore is in a different cloud account - see [Cross-account access](/query-engine/guides/catalogs/cross-account.md).
7. Click **Test Connection** to verify connectivity.
8. After a successful test, **specify the schemas to include** - pick the databases you want this catalog to expose.
9. Click **Create Catalog**. The catalog appears in the catalogs list and is available to attach to clusters.

### Test Connection

**Test Connection** validates network reachability to the metastore, that authentication credentials are accepted, and that e6data can list schemas. A successful test is required before you can select schemas. If it fails, the error explains the cause - typically a credentials issue, a network/firewall block, or insufficient permissions.

### Schema selection

After a successful test, select only the schemas (databases) you want this catalog to expose - all schemas for an analytics-team catalog, a single schema for a tenant-specific catalog, or a curated subset. You can change the selection later by editing the catalog.

## Refresh a catalog

When tables or schemas change in your metastore, refresh the catalog to pick up the changes:

1. Open **Catalogs**, find the catalog, and click the **Refresh** icon.
2. Choose **Refresh all schemas** or **Refresh specific schemas**, then confirm.

Refresh runs in the background; the catalog status shows progress. Common triggers: new tables added, tables dropped, columns added/dropped, or bulk changes after a migration. For automated periodic refresh, use [scheduled refresh](#scheduled-refresh).

## Edit a catalog

1. Open **Catalogs** and click the row actions (⋮) for the catalog.
2. Click **Edit**, change the **Select Schemas** dropdown (or other fields), and click **Update Catalog**.

Changing fields that affect connectivity requires a successful re-test before saving.

## Delete a catalog

1. Open **Catalogs**, click the row actions, click **Delete**, and confirm.

Deletion removes the catalog from this workspace; attached clusters lose access. The underlying metastore and data are not modified.

## Scheduled refresh

Scheduled refresh keeps catalog metadata in sync with the metastore on a schedule, without manual intervention. Each run reconnects with the catalog's existing credentials, re-discovers schemas/tables/columns within scope, updates e6data's metadata cache, and logs the result. Refreshes run in the background and update metadata atomically - they don't interrupt queries.

Enable it when creating or editing a catalog:

1. Toggle **Scheduled refresh** on.
2. Pick a schedule:

   | Schedule         | Use for                                                              |
   | ---------------- | -------------------------------------------------------------------- |
   | Every 15 minutes | High-velocity environments (frequent table creation)                 |
   | Hourly           | Active development                                                   |
   | Every 6 hours    | Standard production analytics                                        |
   | Daily            | Stable production                                                    |
   | Custom cron      | Specific schedules (for example, `0 2 * * *` for daily at 02:00 UTC) |
3. Optionally scope the refresh to **specific schemas** rather than the full catalog (lighter and more targeted for large catalogs).
4. Save the catalog.

If a scheduled refresh fails, the catalog stays usable with its previous metadata snapshot, the error is recorded in the refresh history, and e6data retries on the next interval (predictable cadence, no backoff). Investigate persistent failures (expired credentials, unreachable metastore, changed permissions) using the refresh logs - see [Catalog errors](/query-engine/reference/error-codes/catalog.md).

## Error handling

If a catalog operation fails, the catalog row shows an **Error** status. Use the **Retry** icon for transient failures, the **Download log** icon to capture request/response/error details for support, and the **Refresh List** button to update statuses without re-fetching metadata.

## See also

* [Catalogs overview](/query-engine/guides/catalogs.md)
* [Cross-account access](/query-engine/guides/catalogs/cross-account.md)
* [Troubleshooting catalogs](/query-engine/guides/catalogs/troubleshooting-catalogs.md)
* [Catalog errors](/query-engine/reference/error-codes/catalog.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.e6data.com/query-engine/guides/catalogs/register-and-manage-catalogs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.