SQL do Databricks

Importante

Esse recurso está em Visualização Pública.

O servidor SQL MCP do Databricks é um servidor MCP gerenciado pelo Azure Databricks que permite que agentes executem SQL gerado por IA em suas tabelas do Catálogo Unity para ler e gravar dados, com acesso regido pelas permissões do Catálogo Unity. Consultas rodam de forma assíncrona: o agente chama a ferramenta para iniciar uma consulta, depois faz sondeios até que a resposta seja concluída.

Use este servidor para desenvolvimento e engenharia de dados: executando uma consulta específica que você ou seu agente de codificação escreveu, inspecionando esquemas, validando a sintaxe SQL e criando pipelines de dados a partir de ferramentas de codificação de IA. Isso te dá controle determinístico sobre o SQL exato que roda.

Padrão de URL Escopo do OAuth
https://<workspace-hostname>/api/2.0/mcp/sql sql

Genie One MCP vs. servidores MCP do Databricks SQL

Para casos de uso de análise, em que um usuário faz uma pergunta de negócios em linguagem natural, use o servidor MCP do Genie One em vez disso. O Genie resolve termos de negócio por meio da Ontologia Genie, sua camada semântica governada, então produz respostas mais precisas do que um agente escrevendo SQL diretamente sobre tabelas brutas.

Use o servidor SQL MCP do Databricks quando precisar executar uma consulta específica que já escreveu, como validar a sintaxe ou criar um pipeline.

Parâmetros _meta

_meta os parâmetros são valores de configuração que você pré-define no código do seu agente para definir o comportamento do servidor MCP de forma determinista, em vez de deixar o LLM gerá-los dinamicamente no momento da chamada de ferramenta. O servidor SQL MCP do Databricks suporta o seguinte _meta parâmetro:

Nome do parâmetro Tipo Description
warehouse_id str O ID do SQL Warehouse a ser usado para executar consultas.
Exemplo: "a1b2c3d4e5f67890"
Se não for especificado, o sistema selecionará automaticamente um warehouse com base em recursos e permissões.

Exemplo: especificar um SQL Warehouse para consultas SQL do Databricks

Este exemplo mostra como usar o parâmetro warehouse_id_meta para especificar qual SQL warehouse executa consultas do servidor MCP do Databricks SQL usando o SDK MCP oficial para Python.

Nesse cenário, você deseja:

  • Use um sql warehouse específico para execução de consulta em vez de permitir que o sistema selecione um automaticamente
  • Verificar o desempenho consistente roteando consultas para um warehouse dedicado

Para executar este exemplo, configure o ambiente do Python para o desenvolvimento gerenciado do MCP:

Para encontrar sua ID do SQL Warehouse, consulte Conectar-se a um SQL Warehouse.

# Import required libraries for MCP client and Databricks authentication
import asyncio
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>/api/2.0/mcp/sql"

    # 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 get the response
            response = await session.send_request(request, CallToolResult)
            return response

# Execute the async function and get results
response = asyncio.run(run_dbsql_tool_call_with_meta())

Limitations

  • Sem contexto semântico. O servidor roda o SQL que ele recebe. Ele não resolve termos de negócios, definições métricas ou relações de tabelas, então um agente deve inferir esses termos apenas a partir dos esquemas. Para perguntas de análise feitas em linguagem natural, use o servidor MCP do Genie One, que fundamenta as respostas no Genie Ontology.
  • Tamanho do resultado. O servidor trunca grandes conjuntos de resultados nas respostas das ferramentas para evitar esgotar a janela de contexto do modelo. Retorne menos linhas e colunas, ou faça agregações em SQL, para manter os resultados dentro do limite.
  • Execução assíncrona. As consultas não retornam de forma síncrona. O agente inicia uma consulta e, em seguida, consulta até que ela seja concluída, logo, ele deve manipular estados em andamento.
  • Last updated on