> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to Databricks Unity Catalog

> Connect Wherobots to Databricks Unity Catalog to read your lakehouse data directly in Wherobots without replication or migration.

Wherobots now connects to Databricks Unity Catalog, allowing you to build spatial solutions with data directly from your lakehouse without replication or migration.

This integration empowers data teams working on Databricks to use Wherobots's best in-class geospatial capabilities while continuing to benefit from data governance capabilities of Unity Catalog.

<Note>
  **Databricks foreign catalogs use direct authentication, not a Wherobots Cloud connection**<br />

  When you add a Databricks Unity Catalog foreign catalog in Wherobots, you connect directly to your
  Databricks workspace URL. Unity Catalog **Delta** uses a **Personal Access Token (PAT)**. Unity Catalog
  **Iceberg** uses **OAuth client credentials** (`client_id` and `client_secret`).
</Note>

## Benefits

* **Zero-Copy architecture:** Read tables managed by Databricks Unity Catalog without moving or duplicating data.
* **Maintained governance:** Databricks Workspace Admins can retain catalog- and table-level access control when reading their Databricks catalogs.
* **Secure federation:** Connect securely using Databricks authentication credentials.
* **Accelerated innovation on the lakehouse:** Take spatial ideas to market faster using Wherobots' 300+ spatial functions, raster inference, and compute for physical world data on your Unity Catalog data.

## Supported workflows

Wherobots' integration with Databricks Unity Catalog supports the following workflows:

| Read Source (Unity Catalog) | Write Destination                            | Required Databricks Authentication                                           | Documentation                                                                                                                 |
| :-------------------------- | :------------------------------------------- | :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| Managed **Delta** Table     | Wherobots-Managed Catalog                    | Personal Access Token (PAT) (assigned to an individual or Service Principal) | [Workflow Configuration](/get-started/initial-storage/reading-and-writing-unity-catalog-tables#reading-from-a-delta-table)    |
| Managed **Delta** Table     | External **Delta** Table (in Unity Catalog)  | Personal Access Token (PAT) (assigned to an individual or Service Principal) | [Workflow Configuration](/get-started/initial-storage/reading-and-writing-unity-catalog-tables#reading-from-a-delta-table)    |
| Managed **Iceberg** Table   | Wherobots-Managed Catalog                    | **Service Principal** with OAuth                                             | [Workflow Configuration](/get-started/initial-storage/reading-and-writing-unity-catalog-tables#reading-from-an-iceberg-table) |
| Managed **Iceberg** Table   | Managed **Iceberg** Table (in Unity Catalog) | **Service Principal** with OAuth                                             | [Workflow Configuration](/get-started/initial-storage/reading-and-writing-unity-catalog-tables#reading-from-an-iceberg-table) |

## Setup and configuration

The following sections provide step-by-step instructions for connecting Wherobots to your Databricks Unity Catalog.

### Before you start

Before you can use this feature, make sure you have the following:

* A Wherobots **Account** within a Professional, Innovation, or Enterprise Edition Organization. Your Account needs to be assigned an **Admin** role to add the foreign catalog in Data Hub.
* A **pre-existing Managed Delta or Managed Iceberg table** within the Databricks platform.
* A **pre-existing Unity Catalog** in Databricks.
* The necessary permissions in Databricks, [as described below](#databricks-permissions).

### Databricks authentication

Databricks Unity Catalog foreign catalogs do **not** use a Wherobots Cloud connection intermediary. Wherobots authenticates directly to your Databricks workspace using the credentials for your table format:

* **Unity Delta:** Personal Access Token (PAT)
* **Unity Iceberg:** OAuth client credentials (`client_id` and `client_secret`)

Make sure you have the necessary permissions in Databricks, as described below.

#### Databricks permissions

The permissions you need depend on your read/write workflow.

<Tabs>
  <Tab title="Writing to Wherobots">
    * **If you're reading from a Managed Delta Table and writing to a Wherobots-managed Catalog**:

      * Create a **Personal Access Token (PAT)**.

          <Tip>
            **Best practice: Use a Databricks Service Principal**

            To mitigate security concerns, you should adhere to the principle of least privilege by attaching the PAT to a Databricks service principal instead of an individual user and granting it only the minimum permissions required.
          </Tip>

      * The following permissions are required:

        | Permission    | Granted On (Object Type)        | Target / Scope                                    |
        | :------------ | :------------------------------ | :------------------------------------------------ |
        | `USE CATALOG` | Catalog                         | The catalog containing the **source** Delta table |
        | `USE SCHEMA`  | Schema                          | The schema containing the **source** Delta table  |
        | `SELECT`      | Table                           | The **source** Delta table being read             |
        | `CAN USE`     | Service principal or individual |                                                   |

      * **If you're reading from a Managed Iceberg Table and writing to a Wherobots-managed Catalog**:
        * Use a **Service Principal with OAuth**. For more information, see [Authorize service principal access to Databricks with OAuth](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) in the Official Databricks Documentation.
        * Record the `<uc-catalog-name>`, `<workspace-url>`, `<oauth_client_id>`, and `<oauth_client_secret>` for the Wherobots UI.

      * The following permissions are required:

        | Permission            | Granted On (Object Type) | Target / Scope                                           |
        | :-------------------- | :----------------------- | :------------------------------------------------------- |
        | `USE CATALOG`         | Catalog                  | The catalog containing the **source** Iceberg table      |
        | `USE SCHEMA`          | Schema                   | The schema containing the **source** Iceberg table       |
        | `SELECT`              | Table                    | The **source** Iceberg table being read                  |
        | `EXTERNAL USE SCHEMA` | Schema                   | The schema containing the **source** Iceberg table       |
        | `READ VOLUME`         | External Volume          | The volume where the **source** table's files are stored |
  </Tab>

  <Tab title="Writing to Databricks Unity Catalog">
    * **If you're reading from a Managed Delta Table and writing to an External Delta Table**:
      * **Authentication:** You must use a **Personal Access Token (PAT)**.

      * The following permissions are required:

        | Permission              | Granted On (Object Type) | Target / Scope                                             |
        | :---------------------- | :----------------------- | :--------------------------------------------------------- |
        | `USE CATALOG`           | Catalog                  | Both the **source** and **destination** catalogs           |
        | `USE SCHEMA`            | Schema                   | Both the **source** and **destination** schemas            |
        | `SELECT`                | Table                    | The **source** Delta table being read                      |
        | `CREATE TABLE`          | Schema                   | The **destination** schema where the output is written     |
        | `MODIFY`                | Table                    | The **destination** table where the output is written      |
        | `CREATE EXTERNAL TABLE` | External Location        | The external location for the **destination** table's data |
        | `EXTERNAL USE LOCATION` | External Location        | The external location for the **destination** table's data |

      * **If you're reading from a Managed Iceberg Table and writing to a new Managed Iceberg Table**:
        * **Authentication:** You must use a **Service Principal with OAuth**.
        * The following permissions are required:

          | Permission            | Granted On (Object Type) | Target / Scope                                           |
          | :-------------------- | :----------------------- | :------------------------------------------------------- |
          | `USE CATALOG`         | Catalog                  | The catalog containing the **source** Iceberg table      |
          | `USE SCHEMA`          | Schema                   | The schema containing the **source** Iceberg table       |
          | `SELECT`              | Table                    | The **source** Iceberg table being read                  |
          | `EXTERNAL USE SCHEMA` | Schema                   | The schema containing the **source** Iceberg table       |
          | `READ VOLUME`         | External Volume          | The volume where the **source** table's files are stored |
  </Tab>
</Tabs>

### Add the catalog in Wherobots

To create a catalog based on your Databricks Unity Catalog, follow these steps:

1. In [Wherobots Cloud](https://cloud.wherobots.com/), open the [**Data Hub**](https://cloud.wherobots.com/data-hub).

2. Start adding a catalog using either the **Add Catalog** button or the **Data Hub explorer**:

   <Tabs>
     <Tab title="Data Hub explorer">
       Select the **Unity Catalog** card.

       <img src="https://mintcdn.com/wherobots/zFuwNrbDx6hJp2sg/get-started/get-started-images/data-hub-explorer.png?fit=max&auto=format&n=zFuwNrbDx6hJp2sg&q=85&s=080ebd0f59896f6e842557104dae1a16" alt="The Data Hub empty state showing the Unity Catalog, Amazon Glue, and Storage Integration cards" width="500" data-path="get-started/get-started-images/data-hub-explorer.png" />
     </Tab>

     <Tab title="Add Catalog button">
       Click **Add Catalog**, then under **Foreign Catalog** choose **Unity Catalog**.

       <img src="https://mintcdn.com/wherobots/I5uOx-MfHtHgKNWt/get-started/get-started-images/data-hub-add-catalog.png?fit=max&auto=format&n=I5uOx-MfHtHgKNWt&q=85&s=266d66ccb87a0a9316a632a8c7e5af53" alt="Add Catalog" width="350" data-path="get-started/get-started-images/data-hub-add-catalog.png" />

       <img src="https://mintcdn.com/wherobots/I5uOx-MfHtHgKNWt/get-started/get-started-images/data-hub-foreign-catalog.png?fit=max&auto=format&n=I5uOx-MfHtHgKNWt&q=85&s=de83cf69588b18f865a776f913f2e862" alt="Select a foreign catalog" width="350" data-path="get-started/get-started-images/data-hub-foreign-catalog.png" />
     </Tab>
   </Tabs>

   Either method opens the **Connect to Databricks Unity Catalog** dialog.

3. Enter a **Name** that exactly matches the catalog name in your Databricks Workspace, then enter your **Workspace URL** (`https://<workspace ID>.cloud.databricks.com`). Wherobots connects directly to this Databricks URL; no Wherobots Cloud connection is required.

4. Select **Delta** or **Iceberg** to match the format of your source table, then enter the credentials for that type:

   <Tabs>
     <Tab title="For Delta tables">
       * Enter your **Personal Access Token (PAT)**.

             <img src="https://mintcdn.com/wherobots/fmz9HKQh2odSNgX7/get-started/get-started-images/unity-catalog-delta-table.png?fit=max&auto=format&n=fmz9HKQh2odSNgX7&q=85&s=8a4cdde5e240e85fb0979f01b5020117" alt="Delta Table" width="350" data-path="get-started/get-started-images/unity-catalog-delta-table.png" />
     </Tab>

     <Tab title="For Iceberg tables">
       * Enter your **OAuth Client ID** and **OAuth Client Secret**.

             <img src="https://mintcdn.com/wherobots/fmz9HKQh2odSNgX7/get-started/get-started-images/unity-catalog-iceberg-table.png?fit=max&auto=format&n=fmz9HKQh2odSNgX7&q=85&s=447c0a8c70fb88e556c8e79247d42595" alt="Iceberg Table" width="350" data-path="get-started/get-started-images/unity-catalog-iceberg-table.png" />
     </Tab>
   </Tabs>

   * Click **Add**.

   <Info>
     **Runtime Restart Required After Data Integration**

     To use new storage integrations or catalogs in your notebooks, you must start a new runtime.
     Notebooks can only access storage integrations or catalogs that were created before the runtime started.
   </Info>

Once your catalog is connected, see [Reading and Writing Unity Catalog Tables](/get-started/initial-storage/reading-and-writing-unity-catalog-tables) to query and write your Unity Catalog data from a Wherobots Notebook.

## Next steps

After connecting your Databricks Unity Catalog, you can read and write tables from a Wherobots Notebook. Read more for instructions:

<CardGroup cols={2}>
  <Card title="Read and write Unity Catalog tables" icon="table" href="/get-started/initial-storage/reading-and-writing-unity-catalog-tables">
    Query Databricks Unity Catalog tables from a Wherobots Notebook and write results to supported destinations.
  </Card>

  <Card title="Try it in a notebook" icon="book-open" href="/tutorials/example-notebooks/unity-catalog-delta-tables">
    Walk through a hands-on tutorial reading Unity Catalog Delta tables in Wherobots.
  </Card>
</CardGroup>

## Usage and limitations

* **Catalog Naming:** You cannot use a local alias for a catalog. If you have a pre-existing catalog in your Wherobots Organization named `wherobots`, trying to connect a Databricks catalog with the name `wherobots` will cause a permanent naming conflict and must be avoided.
* **Catalog Limit:** The integration supports a limit of 10 foreign catalogs per Organization.
* **UniForm:** If you use Databricks' Universal Format (UniForm) to enable Iceberg reads on a Delta table, that table will be **read-only**.

### Workflows explained

The following table provides a detailed summary of each workflow and its intended use case.

| Use Case                                                                                                                                                                                                                         | Read Source (Unity Catalog) | Write Destination                            |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------- | :------------------------------------------- |
| **Preserve `GEOMETRY` columns** for continued complex spatial analysis and visualization within the Wherobots environment.                                                                                                       | Managed **Delta** Table     | Wherobots-Managed Catalog                    |
| **Generate spatial features for AI and BI in Databricks.** Complete complex spatial analysis in Wherobots and write spatially-enriched feature columns back to Unity Catalog for use in Databricks' ML models and BI dashboards. | Managed **Delta** Table     | External **Delta** Table (in Unity Catalog)  |
| **Preserve `GEOMETRY` columns** for continued complex spatial analysis and visualization within the Wherobots environment.                                                                                                       | Managed **Iceberg** Table   | Wherobots-Managed Catalog                    |
| **Generate spatial features for AI and BI in Databricks.** Complete complex spatial analysis in Wherobots and write spatially-enriched feature columns back to Unity Catalog for use in Databricks' ML models and BI dashboards. | Managed **Iceberg** Table   | Managed **Iceberg** Table (in Unity Catalog) |