Databricks SQL

info

Visualização

Esse recurso está em Pré-lançamento público.

O servidor MCP do Databricks SQL é um servidor MCP gerenciado pelo Databricks que permite aos agentes realizar a execução de SQL gerado por AI em suas tabelas do Unity Catalog para ler e gravar dados, com acesso governado pelas permissões do Unity Catalog. As queries têm execução assíncrona: o agente chama a ferramenta para começar uma query e, em seguida, faz o polling até que a resposta seja concluída.

Use este servidor para desenvolvimento e engenharia de dados: execução de uma query específica que você ou seu agente de codificação escreveu, inspeção de esquemas, validação de sintaxe SQL e criação de pipelines de dados a partir de ferramentas de codificação de AI. Ele oferece controle determinístico sobre o SQL exato que é executado.

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

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

Servidores MCP Genie One vs. servidores MCP do Databricks SQL

Para casos de uso de analítica, onde um usuário faz uma pergunta de negócios em linguagem natural, use o servidor MCP Genie One em vez disso. O Genie resolve termos de negócios por meio da Genie Ontology, sua camada semântica governada, portanto, ele produz respostas mais precisas do que um agente escrevendo SQL diretamente em tabelas brutas.

Use o servidor Databricks SQL MCP quando precisar realizar a execução de uma query específica que você já escreveu, como validar a sintaxe ou criar um pipeline.

_meta parâmetros

_meta parâmetros são valores de configuração que você predefine no código do seu agente para definir o comportamento do servidor MCP de forma determinística, em vez de deixar que o LLM os gere dinamicamente no momento da chamada da ferramenta. O servidor MCP do Databricks SQL aceita o seguinte parâmetro _meta:

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

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

Exemplo: especificar um SQL warehouse para queries do Databricks SQL

Este exemplo mostra como usar o parâmetro warehouse_id _meta para especificar qual SQL Warehouse realiza a execução de queries do servidor Databricks SQL MCP usando o Python MCP SDK oficial.

Nesse cenário, você deseja:

• Use um SQL warehouse específico para a execução da query em vez de deixar o sistema selecionar um automaticamente
• Verifique o desempenho consistente roteando queries para um warehouse dedicado

Para execução deste exemplo, configure seu ambiente Python para desenvolvimento de MCP gerenciado:

Para encontrar o ID do seu SQL warehouse, consulte Conectar a um SQL warehouse.

Python

# 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
                    &quot;name&quot;: &quot;execute_sql&quot;,

                    # Dynamic arguments - typically provided by your AI agent
                    &quot;arguments&quot;: {
                        &quot;query&quot;: &quot;SELECT * FROM my_catalog.my_schema.my_table LIMIT 10&quot;
                    },

                    # Meta parameters - specify which warehouse to use
                    &quot;_meta&quot;: {
                        &quot;warehouse_id&quot;: &quot;a1b2c3d4e5f67890&quot;  # 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())

Limitações

• Sem contexto semântico. O servidor executa o SQL que lhe é fornecido. Ele não resolve termos de negócios, definições de métricas ou relacionamentos de tabelas, portanto, um agente deve inferi-los apenas a partir de esquemas. Para perguntas de analítica feitas em linguagem natural, use o servidor MCP do Genie One, que fundamenta as respostas na Ontologia do Genie.
• Tamanho do resultado. O servidor trunca grandes conjuntos de resultados nas respostas da ferramenta para evitar esgotar a janela de contexto do modelo. Retorne menos linhas e colunas, ou agregue em SQL, para manter os resultados dentro do limite.
• Execução assíncrona. As queries não retornam de forma síncrona. O agente inicia uma query e, em seguida, faz o polling até que ela seja concluída; portanto, ele deve lidar com estados em andamento.