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

# Connecting Databricks to Omni

> Learn how to generate credentials, retrieve connection details, and connect your Databricks workspace to Omni.

export const BaseAccess = () => {
  return <span>
      <ParamField path="Base Access" required>
        Select the <a href="/administration/users/permissions">minimum level of access</a> users should have to models in the connection.
      </ParamField>
    </span>;
};

export const QueryTimeout = ({defaultValue}) => {
  return <span>
      <ParamField path="Query Timeout" default={defaultValue}>
        Maximum time in seconds before a query times out.
      </ParamField>
    </span>;
};

export const AlwaysScopeViewNames = () => {
  return <span>
      <ParamField path="Always Scope View Names" default="enabled">
        When enabled, Omni will prefix generated view names with schema and catalog, e.g. <code>my_catalog_public__orders</code> instead of <code>orders</code>. Defaults to enabled. See <a href="/connect-data/view-name-generation">View name generation</a> for more information.
      </ParamField>
    </span>;
};

export const AllowUserSpecificTimezones = () => {
  return <span>
      <ParamField path="Allow User-Specific Timezones">
        When enabled, users can override the connection timezone with their own when querying.
      </ParamField>
    </span>;
};

export const QueryTimezone = () => {
  return <span>
      <ParamField path="Query Timezone" required>
        The timezone to use for Omni queries. If a timezone is specified, data will be converted from the <strong>Database Timezone</strong> to the selected timezone.
      </ParamField>
    </span>;
};

export const DatabaseTimezone = () => {
  return <span>
      <ParamField path="Database Timezone" required>
        The timezone used by the database.
      </ParamField>
    </span>;
};

export const TableUploads = ({label = "Schema for Table Uploads", term = "schema"}) => {
  return <span>
      <ParamField path={label}>
        The name of the {term} to use for table (CSV) uploads. If left blank, you can upload tables but they won't be pushed to the database or be available for use in joins.
      </ParamField>
    </span>;
};

export const Offloaded = ({term = "Schemas"}) => {
  const lower = term.toLowerCase();
  return <span>
      <ParamField path={`Offloaded ${term}`}>
        A comma-separated list of {lower} to include in the connection, which will only load on demand. This setting is good for large {lower} or dbt dev {lower}.
      </ParamField>
    </span>;
};

export const IncludeOther = ({term = "Schemas"}) => {
  const lower = term.toLowerCase();
  return <span>
      <ParamField path={`Include Other ${term}`}>
        A comma-separated list of other {lower} to include in the connection.
      </ParamField>
    </span>;
};

export const Include = ({term = "Schemas"}) => {
  const lower = term.toLowerCase();
  return <span>
      <ParamField path={`Include ${term}`}>
        A comma-separated list of {lower} to include in the connection.
      </ParamField>
    </span>;
};

export const Default = ({term = "Schema", required = true, defaultValue}) => {
  const lower = term.toLowerCase();
  return <span>
      <ParamField path={`Default ${term}`} required={required} default={defaultValue}>
        The default {lower} for the connection.
      </ParamField>
    </span>;
};

export const Host = () => {
  return <span>
      <ParamField path="Host" required>
        The address of the database server.
      </ParamField>
    </span>;
};

export const DisplayName = () => {
  return <span>
      <ParamField path="Display Name" required>
        A user-friendly name for the connection, which will be used throughout Omni.
      </ParamField>
    </span>;
};

<Note>
  If your Databricks workspace is in a private network and requires PrivateLink access, refer to the [Databricks PrivateLink guide](/connect-data/databricks-privatelink) instead.
</Note>

## Requirements

To follow the steps in this guide, you'll need **Organization Admin permissions in Omni**.

## Setup

<Steps>
  <Step title="Generate credentials" titleSize="h3">
    Omni can use either personal access token (PAT) or OAuth machine-to-machine (M2M) credentials to authenticate to Databricks.

    * **To use a <Tooltip tip="Personal Access Token">PAT</Tooltip>** - Follow the Databricks [Access Token for a service principal guide](https://docs.databricks.com/en/dev-tools/auth/pat.html#databricks-personal-access-tokens-for-service-principals). When you create the connection in Omni, you'll select the **Personal Access Token** as the **Authentication type**.

    * **To use an <Tooltip tip="OAuth machine-to-machine">M2M</Tooltip>** - Follow the Databricks [Authenticate as a service principal guide](https://docs.databricks.com/en/dev-tools/auth/oauth-m2m). When you create the connection in Omni, you'll select the **OAuth M2M Authentication** as the **Authentication type**.
  </Step>

  <Step title="Grant permissions to the service principal" titleSize="h3">
    The Databricks service principal or user must have the following privileges on each catalog and schema Omni will access:

    ```sql theme={null}
    GRANT USE CATALOG ON CATALOG <catalog> TO `omni_user`; 
    GRANT USE SCHEMA ON SCHEMA <catalog>.<schema> TO `omni_user`;
    GRANT SELECT ON SCHEMA <catalog>.<schema> TO `omni_user`;
    ```

    Repeat the schema-level grants for each schema you want Omni to query. The `SELECT ON SCHEMA` grant covers all current and future tables and views within that schema.
  </Step>

  <Step title="Retrieve database connection details" titleSize="h3">
    Next, you'll need to retrieve your database's connection details from Databricks. Follow the steps in [this Databricks guide](https://docs.databricks.com/en/integrations/compute-details.html), specifically the **getting connection details for a Databricks SQL warehouse** section.
  </Step>

  <Step title="Create the connection in Omni" titleSize="h3">
    1. In Omni, click **Settings > Connections**.

    2. Click the **Databricks** option.

    3. On the connection setup page, fill in the connection details:
           <DisplayName />
           <Host />
           <ParamField path="HTTP Path" required>
             The HTTP path for the Databricks SQL warehouse.
           </ParamField>
           <Default term="Catalog" />
           <IncludeOther term="Catalogs" />
           <Include />
           <Offloaded />
           <TableUploads />
           <Default required={false} />
           <ParamField path="Authentication Type" required>
             Select the authentication type you chose in step 1 and enter the credentials into their corresponding fields.
           </ParamField>
           <DatabaseTimezone />
           <QueryTimezone />
           <AllowUserSpecificTimezones />
           <QueryTimeout defaultValue="900" />
           <ParamField path="Enable DW Metric View Integration">
             When enabled, Omni will sync metrics and metric views defined in your [Databricks Unity Catalog](/connect-data/databricks-unity-catalog-integration) into your Omni model.
           </ParamField>
           <AlwaysScopeViewNames />
           <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection