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

# Databricks integration guide

[Databricks](https://www.databricks.com/) is a data and AI platform. Its Unity Gateway governs access to language models through model provider services, and a **Custom** provider can point at any OpenAI-compatible endpoint. SambaCloud is one, so a Databricks workspace can serve SambaNova models without any partnership or code change. This guide covers two routes: a Unity Gateway provider service that you call from Python, and a Model Serving endpoint that you call from SQL with `ai_query`.

> [!NOTE]
>
> This guide was tested on a Databricks Free Edition workspace on AWS in November 2026. Databricks marks Model Serving external model endpoints as legacy and points new work to Unity Gateway, so menu names and options can change. Check the [Databricks documentation](https://docs.databricks.com/aws/en/ai-gateway/model-provider-services) if a screen looks different.

## Prerequisites

* A [SambaCloud](https://cloud.sambanova.ai/?utm_source=databricks\&utm_medium=external\&utm_campaign=cloud_signup) account and [API key](https://cloud.sambanova.ai/apis?utm_source=databricks\&utm_medium=external\&utm_campaign=cloud_signup)
* A [Databricks](https://www.databricks.com/) workspace with **AI Gateway** (Unity Gateway) in the sidebar and a SQL warehouse
* A Databricks personal access token. Create one under **Settings → User → Developer → Access tokens**.
* Python 3.9 or higher

## Create a provider service for SambaCloud

A model provider service stores the SambaCloud endpoint and key. Databricks calls it by its three-part Unity Catalog name, `catalog.schema.name`.

**1. Open the new provider form**

In the Databricks sidebar, open **AI Gateway**, select the **Providers** tab, and click **+ Provider**.

**2. Choose the Custom provider and enter the SambaCloud endpoint**

Set **Catalog** to `workspace`, **Schema** to `default`, and **Name** to `sambanova`. Under **Provider**, select **Custom**, then fill in:

* **Provider endpoint**: `https://api.sambanova.ai/v1`
* **Auth method**: **Bearer token**, with the type set to **Plaintext**
* **Bearer token**: your SambaCloud API key

**3. Register the model with an endpoint route**

Under **Models**, enter these values and click **Add model**:

* **Model name**: `MiniMax-M3.1-Flash`
* **Provider api types**: `/openai/v1/chat/completions`
* **Endpoint route**: `chat/completions`

![Edit model provider service dialog showing MiniMax-M3.1-Flash invoked at https://api.sambanova.ai/v1/chat/completions, the provider endpoint https://api.sambanova.ai/v1, and a stored bearer token](https://mintcdn.com/sambanova-systems/BMgjqhr69q9ZEtui/images/docs/integrations/databricks/provider-config.png?fit=max\&auto=format\&n=BMgjqhr69q9ZEtui\&q=85\&s=ceed04d3ef0142a5738265deb1f10659)

> [!WARNING]
>
> Without the endpoint route, Databricks calls the provider endpoint itself, `https://api.sambanova.ai/v1`, which is a base URL and not a chat route. Check that the model line reads "Invoked at `https://api.sambanova.ai/v1/chat/completions`". See [Troubleshooting](#troubleshooting).

**4. Create the service**

Click **Create**. The provider service page lists `MiniMax-M3.1-Flash` as one available model.

![Unity Gateway provider service sambanova with one custom model, MiniMax-M3.1-Flash, and a Get started panel with a cURL request](https://mintcdn.com/sambanova-systems/BMgjqhr69q9ZEtui/images/docs/integrations/databricks/provider-overview.png?fit=max\&auto=format\&n=BMgjqhr69q9ZEtui\&q=85\&s=0d226c5504066b5a23865343bcb1a141)

## Call the model from Python

Requests go to your workspace, not to SambaCloud. The `Databricks-Model-Provider-Service` header names the provider service you created, and the `model` is the model name you registered.

**1. Install the client**

```bash macOS / Linux theme={}
python3 -m venv .venv
source .venv/bin/activate
pip install openai
```

```powershell Windows theme={}
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install openai
```

This guide was tested with `openai` 2.48.0 on Python 3.9.

**2. Set your workspace URL and token**

```bash macOS / Linux theme={}
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="your-databricks-token"
```

```powershell Windows theme={}
$env:DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
$env:DATABRICKS_TOKEN="your-databricks-token"
```

**3. Send a request**

```python query.py theme={}
import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DATABRICKS_TOKEN"],
    base_url=f"{os.environ['DATABRICKS_HOST']}/ai-gateway/openai/v1",
    default_headers={"Databricks-Model-Provider-Service": "workspace.default.sambanova"},
)

response = client.chat.completions.create(
    model="MiniMax-M3.1-Flash",
    messages=[{"role": "user", "content": "What can you do?"}],
    max_completion_tokens=1024,
)
print(response.choices[0].message.content)
```

```bash theme={}
python query.py
```

```text Output theme={}
I can help you think, write, learn, and solve problems. For example:

- **Answer questions** and explain complex topics in simple terms
- **Write and edit** emails, essays, stories, résumés, and reports
- **Brainstorm** ideas, names, plans, and creative projects
- **Write or debug code** and explain how software works
- **Summarize** articles, notes, or long conversations
- **Translate** or rewrite text for different audiences and tones
- **Plan** projects, trips, schedules, and study routines
- **Practice** interviews, presentations, debates, or language skills

I work with text and can’t independently access live systems or take real-world actions, but I can help you prepare the steps. I may occasionally make mistakes, so it’s worth double-checking important details.

What would you like to work on?
```

> [!NOTE]
>
> `MiniMax-M3.1-Flash` is a reasoning model, so it thinks before it answers. Requests in this test took about 4 to 11 seconds end to end. The Databricks **Get started** panel on the provider service page also shows a ready-made request for your own workspace.

## Use the model in SQL with ai\_query

`ai_query` calls a Model Serving endpoint by name. In the workspace used for this guide, `ai_query` did not accept the Unity Gateway provider service: `SELECT ai_query('workspace.default.sambanova', ...)` failed with "ai\_query through UC Model Services is not enabled". To call SambaCloud from SQL, create a Model Serving endpoint with a custom provider.

**1. Create the serving endpoint**

In the sidebar, open **Serving** and click **Create serving endpoint**. Set **Name** to `sambanova-minimax`. Click the **Entity** field, select **Foundation models**, choose **Custom Provider** from the list, and click **Confirm**. When Databricks suggests Unity Gateway, click **Continue creating in Serving**, then fill in:

* **Custom Provider Model URL**: `https://api.sambanova.ai/v1/chat/completions`
* **Custom Provider Authentication Type**: **Bearer Token Authentication**, with the type set to **Plaintext**
* **Bearer Token**: your SambaCloud API key
* **Model Name**: `MiniMax-M3.1-Flash`
* **Task**: **Chat**

Here the URL must be the full path. This form has no separate endpoint route.

**2. Wait for the endpoint to be ready**

Click **Create**. The endpoint page shows **Ready** when the endpoint can take requests.

![Serving endpoint sambanova-minimax in the Ready state with a Custom Provider pointing to https://api.sambanova.ai/v1/chat/completions](https://mintcdn.com/sambanova-systems/BMgjqhr69q9ZEtui/images/docs/integrations/databricks/serving-endpoint.png?fit=max\&auto=format\&n=BMgjqhr69q9ZEtui\&q=85\&s=71307bd2e8b79d8c34b89ad80a1081e4)

**3. Query it from the SQL editor**

Open the **SQL Editor**, attach the serverless starter warehouse, and run:

```sql theme={}
SELECT ai_query('sambanova-minimax', 'What can you do?') AS answer
```

The first run can take longer while the warehouse starts. The query in this test finished in about 5 seconds once the warehouse was running.

![SQL editor result of ai\_query against sambanova-minimax, returning a MiniMax-M3.1-Flash answer in one row](https://mintcdn.com/sambanova-systems/BMgjqhr69q9ZEtui/images/docs/integrations/databricks/ai-query-result.png?fit=max\&auto=format\&n=BMgjqhr69q9ZEtui\&q=85\&s=2af2b056430450a7d02bdda2acdfaa97)

## Troubleshooting

> [accordion] 503 ... The service at /v1 is temporarily unavailable, or 404 ... 404 page not found
>
> The provider service has no endpoint route, so Databricks posts to `https://api.sambanova.ai/v1` itself. Edit the provider service, remove the model, add it again with the route `chat/completions`, and save. The model line must read "Invoked at `https://api.sambanova.ai/v1/chat/completions`".

> [accordion] 401 ... Incorrect API key provided: dapi\*\*\*\*\*
>
> A value starting with `dapi` is a Databricks token, so the provider service holds a Databricks token instead of your SambaCloud key. Edit the provider service and paste your SambaCloud key into **Bearer token**, then save. If you leave that field blank, Databricks keeps the credential it already stores.

> [accordion] ai\_query through UC Model Services is not enabled
>
> You passed the name of a Unity Gateway provider service to `ai_query`. Pass the name of a Model Serving endpoint instead, as described in [Use the model in SQL with ai\_query](#use-the-model-in-sql-with-ai_query).

## Additional resources

* [Databricks model provider services](https://docs.databricks.com/aws/en/ai-gateway/model-provider-services)
* [Create a model provider service](https://docs.databricks.com/aws/en/ai-gateway/create-model-provider-services)
* [Databricks ai\_query function](https://docs.databricks.com/aws/en/sql/language-manual/functions/ai_query)
* [Databricks external models](https://docs.databricks.com/aws/en/generative-ai/external-models/)
* [Supported SambaCloud models](https://docs.sambanova.ai/docs/en/models/sambacloud-models.md)
