Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Der Databricks SQL MCP-Server ermöglicht es Agenten, KI-generiertes SQL gegen Ihre Unity-Catalog-Tabellen auszuführen, um Daten zu lesen und zu schreiben, wobei der Zugriff durch Unity Catalog-Berechtigungen geregelt ist. Abfragen laufen asynchron: Der Agent ruft das Tool auf, um eine Abfrage zu starten, und fragt dann ab, bis die Antwort abgeschlossen ist.
Important
system.ai.dbsql, system.ai.sandbox, und system.ai.web_search befinden sich in der Beta. Um sie zu nutzen, muss ein Kontoadministrator die Vorschau des Enhanced Unity Gateway auf der Seite Previews der Kontokonsole aktivieren. Unity Gateway selbst ist jetzt verfügbar. Siehe Kontovorschauen verwalten.
Wenn die Beta nicht aktiviert ist, geben Aufrufe an system.ai.dbsqlThe MCP service is administratively suspended. (HTTP 400) zurück. Nutze stattdessen den Workspace-Endpunkt/api/2.0/mcp/sql .
Nutzen Sie diesen Server für Entwicklung und Data Engineering: Führen Sie eine bestimmte Abfrage aus, die Sie oder Ihr Codierer geschrieben haben, inspizieren Sie Schemas, validieren Sie SQL-Syntax und erstellen Sie Datenpipelines mit KI-Codingtools. Es gibt dir deterministische Kontrolle über das genaue SQL, das ausgeführt wird.
Das MCP erlaubt standardmäßig Lesen und Schreiben. Um es schreibgeschützt zu machen, setzen Sie disallow_writes in der integrierten true-Richtlinie auf system.ai.dbsql_policy. Weitere Informationen finden Sie unter Eine Richtlinie anwenden.
Genie One MCP versus Databricks SQL MCP Server
Für Geschäftsfragen, die in natürlicher Sprache gestellt werden, empfiehlt Databricks den Genie One MCP-Server. Genie löst Geschäftsbegriffe über die Genie-Ontologie auf, Ihre verwaltete semantische Schicht. Das liefert genauere Antworten als ein Agent, der SQL direkt gegen Rohtabellen schreibt.
Nutzen Sie den MCP-Server von Databricks-SQL, wenn Sie eine bestimmte Abfrage ausführen müssen, die Sie oder Ihr Coding-Agent geschrieben haben, zum Beispiel die Syntax validieren oder eine Pipeline erstellen.
Um Fragen zu stellen, die auf einen einzelnen kuratierten Genie-Agenten zugeschnitten sind, nutzen Sie den Genie Agent MCP-Server. Für einen Vergleich aller drei Server siehe Wählen Sie zwischen Genie One, Genie Agent und Databricks SQL MCP Servern.
Agent verbinden
Verwenden Sie diese URL mit dem Setup-Guide Ihres Coding-Agenten oder der Python-Agenten-Einrichtung:
| URL-Muster | OAuth-Bereich |
|---|---|
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql |
ai-gateway |
Bitten Sie Ihren Agent, SELECT 1 AS result auszuführen. Bestätigen Sie, dass es das MCP-Tool aufruft und 1 zurückgibt.
Tools
Der Databricks SQL MCP-Server bietet folgende Werkzeuge:
| Tool | Arguments | Description |
|---|---|---|
execute_sql |
query |
Führt eine SQL-Anweisung aus, einschließlich Anweisungen, die Daten schreiben. Schreibvorgänge werden blockiert, wenn disallow_writes in der Serverrichtlinie auf true gesetzt ist. |
execute_sql_read_only |
query |
Führt eine schreibgeschützte SQL-Anweisung aus, wie SELECT, SHOW, oder DESCRIBE. |
poll_sql_result |
statement_id |
Gibt den aktuellen Zustand und die Ergebnisse einer Anweisung, die execute_sql oder execute_sql_read_only gestartet hat, zurück. |
Jedes Tool liefert JSON-Text, der status.state und statement_id enthält. Wenn der Zustand SUCCEEDED ist, liegen die Zeilen in result.data_typed_array.
_meta Parameter
_meta Parameter sind Konfigurationswerte, die Sie in Ihrem Agentencode voreingestellt haben, um das Verhalten des MCP-Servers deterministisch festzulegen, anstatt das LLM sie dynamisch zur Tool-Call-Zeit generieren zu lassen. Der Databricks SQL MCP-Server unterstützt folgenden _meta Parameter:
| Parametername | Typ | Description |
|---|---|---|
warehouse_id |
str |
Die ID des SQL-Warehouses, das zum Ausführen von Abfragen verwendet werden soll. Beispiel: "a1b2c3d4e5f67890"Wenn nicht angegeben, wählt das System automatisch ein Lager basierend auf Ressourcen und Berechtigungen aus. |
Beispiel: Spezifizieren Sie ein SQL-Warehouse für Databricks-SQL-Abfragen
In diesem Beispiel wird gezeigt, wie sie mithilfe des warehouse_id_meta Parameters angeben können, welche SQL-Warehouse Abfragen vom SQL MCP-Server von Databricks mithilfe des offiziellen Python MCP SDK ausführt.
In diesem Szenario möchten Sie:
- Verwenden Sie ein bestimmtes SQL-Warehouse, um Abfragen auszuführen, anstatt das System automatisch eines auswählen zu lassen
- Überprüfen der konsistenten Leistung durch Weiterleiten von Abfragen an ein dediziertes Lager
Um dieses Beispiel auszuführen, richten Sie Ihre Python-Umgebung für die verwaltete MCP-Entwicklung ein:
pip install --upgrade databricks-mcp databricks-sdk "mcp>=1.24,<2"
Informationen zum Auffinden Ihrer SQL-Lagerhaus-ID finden Sie unter Herstellen einer Verbindung mit einem SQL-Lagerhaus.
# Import required libraries for MCP client and Databricks authentication
import asyncio
import json
from databricks.sdk import WorkspaceClient
from databricks_mcp.oauth_provider import DatabricksOAuthClientProvider
from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession
from mcp.types import CallToolRequest, CallToolResult
async def run_dbsql_tool_call_with_meta():
# Initialize Databricks workspace client for authentication
workspace_client = WorkspaceClient()
# Construct the MCP server URL for DBSQL
# Replace <workspace-hostname> with your workspace hostname
mcp_server_url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"
# Establish connection to the MCP server with OAuth authentication
async with streamablehttp_client(
url=mcp_server_url,
auth=DatabricksOAuthClientProvider(workspace_client),
) as (read_stream, write_stream, _):
# Create an MCP session for making tool calls
async with ClientSession(read_stream, write_stream) as session:
# Initialize the session before making requests
await session.initialize()
# Create the tool call request with warehouse_id in _meta
request = CallToolRequest(
method="tools/call",
params={
# Tool name for executing SQL queries
"name": "execute_sql",
# Dynamic arguments - typically provided by your AI agent
"arguments": {
"query": "SELECT * FROM my_catalog.my_schema.my_table LIMIT 10"
},
# Meta parameters - specify which warehouse to use
"_meta": {
"warehouse_id": "a1b2c3d4e5f67890" # Your SQL warehouse ID
}
}
)
# Send the request and parse the JSON text in the response
response = await session.send_request(request, CallToolResult)
result = json.loads(response.content[0].text)
# Poll until the statement leaves the PENDING or RUNNING state
while result["status"]["state"] in ("PENDING", "RUNNING"):
await asyncio.sleep(1)
poll_request = CallToolRequest(
method="tools/call",
params={
"name": "poll_sql_result",
"arguments": {"statement_id": result["statement_id"]},
}
)
response = await session.send_request(poll_request, CallToolResult)
result = json.loads(response.content[0].text)
if result["status"]["state"] != "SUCCEEDED":
raise RuntimeError(f"Query ended in state {result['status']['state']}: {result}")
# The rows are in result.data_typed_array
return result["result"]["data_typed_array"]
# Execute the async function and get the rows
rows = asyncio.run(run_dbsql_tool_call_with_meta())
print(rows)
FAILED und CANCELED sind terminale Zustände, sodass das Beispiel die Abfrage stoppt und einen Fehler hervorruft.
Einschränkungen
- Kein semantischer Kontext. Der Server führt die ihm gegebene SQL aus. Sie löst keine Geschäftsbegriffe, Metrikdefinitionen oder Tabellenbeziehungen auf, sodass ein Agent diese allein aus Schemata ableiten muss. Für analytische Fragen in natürlicher Sprache verwenden Sie den Genie One MCP-Server, der Antworten in Genie-Ontologie verankert.
- Ergebnisgröße. Der Server verkürzt große Ergebnismengen in Tool-Antworten, um das Kontextfenster des Modells nicht zu erschöpfen. Geben Sie weniger Zeilen und Spalten zurück oder aggregieren Sie in SQL, um die Ergebnisse innerhalb der Grenze zu halten.
- Asynchrone Ausführung. Anfragen werden nicht synchron zurückgegeben. Eine noch laufende Abfrage liefert den Zustand
PENDINGoderRUNNINGund einstatement_id. Rufepoll_sql_resultmit dieser ID auf, bis sich der Status ändert. Siehe Beispiel: Angeben eines SQL-Warehouse.
Workspace-Endpunkt
Dieser Endpunkt befindet sich in der öffentlichen Vorschauversion.
Für bestehende Integrationen verwenden Sie https://<workspace-hostname>/api/2.0/mcp/sql mit dem sql OAuth-Scope. Dieser Endpunkt verwendet die Managed MCP Servers Workspace-Vorschau und die zugrundeliegenden Ressourcenberechtigungen. Anrufe umgehen Unity Gateway Tracing, MCP-Berechtigungen, Richtlinien und Schutzmechanismen. Für neue Integrationen verwenden Sie system.ai.dbsql.