Partilhar via

Databricks Driver para SQLTools para Visual Studio Code

  • Artigo

Importante

Esta funcionalidade está em Pré-visualização Pública.

O Databricks Driver for SQLTools permite que você use a extensão SQLTools para Visual Studio Code para procurar objetos SQL e executar consultas SQL em espaços de trabalho remotos do Azure Databricks.

Antes de começar

Antes de poder usar o Databricks Driver for SQLTools, seu espaço de trabalho do Azure Databricks e sua máquina de desenvolvimento local devem atender aos seguintes requisitos.

Requisitos do espaço de trabalho

Você deve ter pelo menos um espaço de trabalho do Azure Databricks disponível e o espaço de trabalho deve atender aos seguintes requisitos:

  • O espaço de trabalho deve conter pelo menos um armazém SQL Databricks.

    Nota

    Os clusters do Azure Databricks não são suportados pelo Databricks Driver for SQLTools.

  • Para espaços de trabalho habilitados para o Unity Catalog, o espaço de trabalho deve conter pelo menos um catálogo, com pelo menos um esquema (formalmente chamado de banco de dados) dentro desse catálogo.

  • Para espaços de trabalho que não estão habilitados para o Unity Catalog, o espaço de trabalho deve conter pelo menos um esquema (anteriormente chamado de banco de dados).

Requisitos da máquina de desenvolvimento local

Você deve ter o seguinte em sua máquina de desenvolvimento local:

Para instalar a extensão SQLTools, vá para SQLTools e clique em Instalar ou:

  1. No Visual Studio Code, clique em Exibir > extensões no menu principal.

  2. Na caixa Extensões de Pesquisa no Marketplace , digite SQLTools.

  3. Clique na entrada SQLTools de Matheus Teixeira.

    Nota

    Pode haver várias entradas SQLTools listadas. Não deixe de clicar na entrada de Matheus Teixeira.

  4. Clique em Install (Instalar).

Para instalar a extensão Databricks Driver for SQLTools, vá para Databricks Driver for SQLTools e clique em Instalar ou:

  1. No Visual Studio Code, clique em Exibir > extensões no menu principal.
  2. Na caixa Extensões de Pesquisa no Marketplace , digite Databricks Driver for SQLTools.
  3. Clique na entrada Databricks Driver for SQLTools .
  4. Clique em Install (Instalar).

Autenticação

Você deve configurar a autenticação para o driver Databricks para SQLTools da seguinte maneira.

O Driver Databricks para SQLTools dá suporte aos seguintes tipos de autenticação do Azure Databricks:

Nota

O driver Databricks para SQLTools não suporta tokens de ID do Microsoft Entra.

Autenticação de token de acesso pessoal do Azure Databricks

Para usar o Driver Databricks para SQLTools com a autenticação de token de acesso pessoal do Azure Databricks, você deve ter um token de acesso pessoal do Azure Databricks. Para criar um token de acesso pessoal, faça o seguinte:

  1. No seu espaço de trabalho do Azure Databricks, clique no seu nome de utilizador do Azure Databricks na barra superior e, em seguida, selecione Definições na lista pendente.
  2. Clique em Desenvolvedor.
  3. Ao lado de Tokens de acesso, clique em Gerenciar.
  4. Clique em Gerar novo token.
  5. (Opcional) Insira um comentário que o ajude a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem tempo de vida (não recomendado), deixe a caixa Tempo de vida (dias) vazia (em branco).
  6. Clique em Generate (Gerar).
  7. Copie o token exibido para um local seguro e clique em Concluído.

Nota

Certifique-se de salvar o token copiado em um local seguro. Não partilhe o seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente o mesmo token. Em vez disso, você deve repetir esse procedimento para criar um novo token. Se você perder o token copiado ou acreditar que o token foi comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu espaço de trabalho clicando no ícone da lixeira (Revogar) ao lado do token na página de tokens do Access.

Se você não conseguir criar ou usar tokens em seu espaço de trabalho, isso pode ser porque o administrador do espaço de trabalho desabilitou tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do espaço de trabalho ou os seguintes tópicos:

Autenticação de máquina a máquina (M2M) OAuth do Azure Databricks

Você pode usar a autenticação de máquina a máquina (M2M) OAuth do Azure Databricks para autenticar com o Driver Databricks para SQLTools, da seguinte maneira:

Nota

A autenticação Azure Databricks OAuth M2M está disponível no Databricks Driver para SQLTools versões 0.4.2 e superiores.

  1. Conclua as etapas de configuração para autenticação OAuth M2M. Consulte Autenticação OAuth máquina-a-máquina (M2M).
  2. Crie um perfil de configuração do Azure Databricks com suas definições de configuração de autenticação OAuth M2M. Consulte a seção "Config" da autenticação OAuth machine-to-machine (M2M).
  3. Instale e abra a extensão Databricks para Visual Studio Code em sua máquina de desenvolvimento local.
  4. Na extensão Databricks para Visual Studio Code, clique no botão Configurar no painel Configuração . Se o botão Configurar não for exibido, clique no ícone de engrenagem (Configurar espaço de trabalho).
  5. Na Paleta de Comandos, para Databricks Host, insira sua URL do Azure Databricks por espaço de trabalho, por exemplohttps://adb-1234567890123456.7.azuredatabricks.net, e pressione Enter.
  6. Selecione a entrada do perfil de configuração que corresponde àquela que você criou na etapa 2.
  7. Conclua as instruções na tela em seu navegador da Web para concluir a autenticação com sua conta do Azure Databricks.

Autenticação U2M (U2M) do Azure Databricks OAuth

Você pode usar a autenticação de usuário para máquina (U2M) do Azure Databricks OAuth para autenticar com o driver Databricks para SQLTools, da seguinte maneira:

Nota

A autenticação U2M do Azure Databricks OAuth está disponível no Databricks Driver para SQLTools versões 0.4.2 e superiores.

  1. Instale e abra a extensão Databricks para Visual Studio Code em sua máquina de desenvolvimento local.
  2. Na extensão Databricks para Visual Studio Code, clique no botão Configurar no painel Configuração . Se o botão Configurar não for exibido, clique no ícone de engrenagem (Configurar espaço de trabalho).
  3. Na Paleta de comandos, para Databricks Host, insira sua URL do Azure Databricks por espaço de trabalho, por exemplohttps://adb-1234567890123456.7.azuredatabricks.net. Em seguida, prima Enter.
  4. Selecione OAuth (usuário para máquina).
  5. Conclua as instruções na tela em seu navegador da Web para concluir a autenticação com sua conta do Azure Databricks. Se solicitado, permita all-apis o acesso.

Autenticação da CLI do Azure

Você pode usar a CLI do Azure para autenticar com o Databricks Driver for SQLTools, da seguinte maneira:

Nota

A autenticação com a CLI do Azure está em um estado de recurso Experimental . Este recurso está disponível no Databricks Driver para SQLTools versões 0.4.2 e superiores.

  1. Instale a CLI do Azure em sua máquina de desenvolvimento local, se ainda não tiver feito isso.
  2. Instale e abra a extensão Databricks para Visual Studio Code em sua máquina de desenvolvimento local.
  3. Na extensão Databricks para Visual Studio Code, clique no botão Configurar no painel Configuração . Se o botão Configurar não for exibido, clique no ícone de engrenagem (Configurar espaço de trabalho).
  4. Na Paleta de comandos, para Databricks Host, insira sua URL do Azure Databricks por espaço de trabalho, por exemplohttps://adb-1234567890123456.7.azuredatabricks.net. Em seguida, prima Enter.
  5. Selecione CLI do Azure.
  6. Siga as instruções na tela para concluir a autenticação com a CLI do Azure.

Conectar-se a um esquema

  1. No Visual Studio Code, na barra lateral, clique no ícone SQLTools .
  2. Na visualização SQLTools, se esta for a primeira vez que você usa a extensão SQLTools, clique em Adicionar Nova Conexão no painel Conexões. Caso contrário, clique no ícone Adicionar Nova Conexão na barra de título do painel.
  3. Na guia Configurações SQLTools, para a etapa Selecionar um driver de banco de dados, clique no ícone Databricks.
  4. Para a etapa Configurações de conexão, insira as seguintes informações sobre seu depósito, catálogo e esquema:

    1. Em Nome da conexão, insira algum nome exclusivo para essa conexão.

    2. (Opcional) Em Grupo de conexões , insira o nome de um grupo de conexões existente para adicionar a nova conexão a esse grupo. Ou insira um nome exclusivo para criar um novo grupo de conexões com a nova conexão. Os grupos de conexão facilitam a localização de conexões na extensão.

    3. Para Conectar usando, selecione uma das seguintes opções:

      • Para usar um token de acesso pessoal do Azure Databricks para autenticação, selecione Nome do host e Token.
      • Para Databricks Driver for SQLTools versões 0.4.2 e superiores, para usar OAuth U2M ou M2M ou autenticação CLI do Azure, selecione VS Code extension (beta).

    4. Se você selecionou Nome do host e Token para Conectar usando, em seguida, para Host, insira a configuração Nome do host do servidor do depósito. Para obter a configuração de nome de host do servidor de um depósito, consulte Obter detalhes de conexão para um recurso de computação do Azure Databricks.

    5. Em Caminho, insira a configuração de caminho HTTP do depósito ou cluster. Para obter a configuração de caminho HTTP de um depósito, consulte Obter detalhes de conexão para um recurso de computação do Azure Databricks.

    6. Se você selecionou Nome do host e Token para conectar usando, insira o valor do token de acesso pessoal do Azure Databricks em Token.

    7. Em Catálogo, insira o nome do catálogo.

      Nota

      Para espaços de trabalho que não estão habilitados para o Unity Catalog, você pode deixar Catalog em branco para usar o valor padrão de hive_metastore.

    8. Em Esquema, insira o nome do esquema.

    9. (Opcional) Para Mostrar limite padrão de registros, deixe o padrão de 50 para mostrar apenas até as primeiras 50 linhas para cada consulta ou insira um limite diferente.

  5. Clique em Testar Ligação.
  6. Se o teste de conexão for bem-sucedido, clique em Salvar conexão.

Alterar as configurações de uma conexão

Este procedimento pressupõe que você tenha se conectado com êxito a pelo menos um depósito.

  1. Se o modo de exibição SQLTools não estiver visível, em Visual Studio Code, na barra lateral, clique no ícone SQLTools .
  2. No painel Conexões, expanda o grupo de conexões, se existir um para a conexão de destino.
  3. Clique com o botão direito do rato na ligação e clique em Editar Ligação.
  4. Altere as configurações de destino.
  5. Clique em Testar Ligação.
  6. Se o teste de conexão for bem-sucedido, clique em Salvar conexão.

Procurar objetos de um esquema

  1. No painel Conexões, expanda o grupo de conexões, se existir um para a conexão de destino.
  2. Clique duas vezes ou expanda a conexão de destino para seu depósito.
  3. Expanda o banco de dados de destino (esquema), se existir um para sua conexão.
  4. Expanda Tabelas ou Exibições, se existir uma ou mais tabelas ou exibições para seu banco de dados (esquema).
  5. Expanda qualquer tabela ou vista de destino para ver as colunas da tabela ou vista.

Exibir as linhas ou o esquema de uma tabela ou modo de exibição

Com Tabelas ou Modos de Exibição expandidos no painel Conexões, siga um destes procedimentos:

  • Para mostrar as linhas da tabela ou vista, clique com o botão direito do rato na tabela ou vista e clique em Mostrar Registos de Tabela ou Mostrar Registos de Vista.
  • Para mostrar o esquema da tabela ou vista, clique com o botão direito do rato na tabela ou vista e clique em Descrever Tabela ou Descrever Vista.

Gerar uma consulta de inserção para uma tabela

  1. Coloque o cursor em um editor existente no local onde deseja que a consulta de inserção seja adicionada.
  2. Com Tabelas expandidas no painel Conexões, clique com o botão direito do mouse na tabela e clique em Gerar Inserir Consulta. A definição da consulta insert é adicionada no ponto de inserção do cursor.

Criar e executar uma consulta

Este procedimento pressupõe que você tenha se conectado com êxito a pelo menos um depósito.

  1. No painel Conexões, expanda o grupo de conexões, se existir um para a conexão de destino.
  2. Clique duas vezes ou expanda a conexão de destino para seu depósito.
  3. Com a conexão selecionada, clique em Novo Arquivo SQL na barra de título do painel Conexões . Uma nova guia do editor é exibida.
  4. Insira sua consulta SQL no novo editor.
  5. Para executar a consulta SQL, clique em Executar na conexão ativa no editor. Os resultados da consulta são exibidos em uma nova guia do editor.

Executar uma consulta existente

Este procedimento pressupõe que você tenha se conectado com êxito a pelo menos um depósito.

  1. No painel Conexões, expanda o grupo de conexões, se existir um para a conexão de destino.
  2. Clique duas vezes ou expanda a conexão de destino para seu depósito.
  3. Com a conexão selecionada, abra qualquer arquivo com a extensão de arquivo de .sql, ou selecione qualquer grupo de instruções SQL contínuas em qualquer editor que tenha sido aberto anteriormente.
  4. Para executar a consulta SQL a partir de um arquivo aberto .sql , com .sql o conteúdo do arquivo exibido no editor, clique em Executar na conexão ativa no editor. Os resultados da consulta são exibidos em uma nova guia do editor.
  5. Para executar um grupo selecionado de instruções SQL contínuas em um editor que foi aberto anteriormente, clique com o botão direito do mouse em sua seleção e clique em Executar Consulta Selecionada. Os resultados da consulta são exibidos em uma nova guia do editor.

Enviar logs de uso para o Databricks

Se você encontrar problemas ao usar o driver Databricks para SQLTools, você pode enviar logs de uso e informações relacionadas para o Suporte do Databricks fazendo o seguinte:

  1. Instale a extensão Databricks para Visual Studio Code em sua máquina de desenvolvimento local.
  2. Ative o registro marcando a configuração Logs: Enabled ou a configuração databricks.logs.enabled como true, conforme descrito em Configurações para a extensão Databricks para Visual Studio Code Certifique-se de reiniciar o Visual Studio Code depois de ativar o log.
  3. Tente reproduzir o seu problema.
  4. Na Paleta de Comandos (Exibir > Paleta de Comandos no menu principal), execute o comando Databricks: Abrir logs completos.
  5. Envie o , databricks-cli-logs.jsone sdk-and-extension-logs.json os arquivos que aparecem para o Databricks Logs.logSuporte do Databricks.
  6. Copie também o conteúdo do Terminal (View > Terminal) no contexto do problema e envie esse conteúdo para o Suporte do Databricks.

O modo de exibição Saída (Exibir > Saída, Logs do Databricks) mostrará informações truncadas se Logs: Enabled estiver marcado ou databricks.logs.enabled definido como true. Para mostrar mais informações, altere as seguintes configurações, conforme descrito em Configurações para a extensão Databricks para Visual Studio Code:

  • Logs: Comprimento máximo da matriz ou databricks.logs.maxArrayLength
  • Logs: Comprimento máximo do campo ou databricks.logs.maxFieldLength
  • Logs: Profundidade de truncamento ou databricks.logs.truncationDepth

Recursos adicionais