Gravar consultas e explorar dados no editor SQL

A interface do usuário do Azure Databricks inclui um Editor SQL que você pode usar para criar consultas, procurar dados disponíveis e criar visualizações. Você também pode compartilhar suas consultas salvas com outros membros da equipe no workspace. Este artigo explica como usar o editor SQL para escrever, executar e gerenciar consultas. Uma nova versão do editor SQL está em Visualização Pública. Para saber como habilitar e trabalhar com o novo editor SQL, consulte Colaborar com colegas usando o novo editor SQL.

Depois de abrir o editor, você pode criar uma consulta SQL ou procurar os dados disponíveis. O editor de texto dá suporte ao preenchimento automático, formatação automática e vários outros atalhos de teclado.

Você pode abrir várias consultas usando as guias de consulta na parte superior do editor de texto. Cada guia de consulta tem controles para executar a consulta, favoritar uma consulta e conectar-se a um SQL warehouse. Você também pode Salvar, Agendar ou Compartilhar consultas.

Abrir o editor SQL

Para abrir o editor SQL na interface do usuário do Azure Databricks, clique em Editor SQL na barra lateral.

O editor SQL abre com a sua última consulta aberta. Se não houver consulta ou todas as consultas tiverem sido fechadas explicitamente, uma nova consulta será aberta. Ele é automaticamente chamado de Nova Consulta e o carimbo de data/hora de criação é anexado ao título.

Conectar-se com a computação

Você deve ter pelo menos as permissões CAN USE em um depósito SQL em execução para executar consultas. Você pode usar o menu suspenso perto da parte superior do editor para ver as opções disponíveis. Para filtrar a lista, digite na caixa de texto.

Quando você cria uma consulta pela primeira vez, a lista de SQL warehouses disponíveis é exibida em ordem alfabética. O último SQL warehouse usado será selecionado na próxima vez que você criar uma consulta.

O ícone ao lado do SQL warehouse indica o status:

• Em execução
• Iniciando
• Interrompido

Observação

Se não houver SQL warehouses na lista, entre em contato com o administrador do workspace.

O depósito SQL selecionado será reiniciado automaticamente quando você executar a consulta. Consulte Iniciar um SQL warehouse para conhecer outras maneira de iniciar um SQL warehouse.

Procurar objetos de dados no editor de SQL

Se você tiver a permissão de leitura de metadados, o navegador de esquema no Editor SQL exibirá os bancos de dados e as tabelas disponíveis. Você também pode procurar objetos de dados no Explorador do Catálogo.

Você pode navegar pelos objetos de banco de dados controlados pelo Catálogo do Unity no Explorador de Catálogos sem computação ativa. Para explorar dados no hive_metastore e em outros catálogos não regidos pelo Catálogo do Unity, você deve anexar à computação com privilégios apropriados. Confira Governança de dados com o Catálogo do Unity.

Observação

Se nenhum objeto de dados existir no navegador de esquema ou no Explorador do Catálogo, entre em contato com o administrador do workspace.

Clique em próximo à parte superior do navegador de esquema para atualizar o esquema. Para filtrar o esquema, digite cadeias de caracteres de filtro na caixa de pesquisa.

Clique em um nome de tabela para mostrar as colunas dessa tabela.

Criar uma consulta

Você pode inserir texto para criar uma consulta no Editor SQL. Você pode inserir elementos do navegador de esquema para referenciar catálogos e tabelas.

1. Digite a consulta no editor de SQL.

   O Editor SQL dá suporte ao preenchimento automático. Conforme você digita, o preenchimento automático sugere preenchimentos. Por exemplo, se um preenchimento válido no local do cursor é uma coluna, o preenchimento automático sugere um nome de coluna. Se você digita select * from table_name as t where t., o preenchimento automático reconhece que t é um alias de table_name e sugere as colunas dentro de table_name.

   

2. (Opcional) Quando terminar a edição, clique em Salvar. Por padrão, a consulta é salva na pasta base do usuário ou você pode selecionar um local diferente. Em seguida, clique em Salvar.

Ativar e desativar o preenchimento automático

O preenchimento automático pode completar tokens de esquema, identificadores de sintaxe de consulta (como SELECT e JOIN) e os títulos de snippets de consulta. Ele é habilitado por padrão, a menos que o esquema de banco de dados exceda 5 mil tokens (tabelas ou colunas).

Use a alternância abaixo do editor SQL para desativar ou ativar o preenchimento automático em tempo real.

• Para desativar o preenchimento automático em tempo real, pressione Ctrl + Espaço ou clique no botão abaixo do Editor SQL.

Salvar consultas

O botão Salvar próximo ao canto superior do Editor SQL salva sua consulta.

Importante

Quando você modifica uma consulta, mas não clica explicitamente em Salvar, esse estado é mantido como um rascunho de consulta. Os rascunhos de consultas são mantidos por 30 dias. Após 30 dias, os rascunhos de consultas são excluídos automaticamente. Para manter suas alterações, você precisa salvá-las explicitamente.

Editar várias consultas

Por padrão, o Editor SQL usa guias para permitir a edição de várias consultas ao mesmo tempo. Para abrir uma nova guia, clique em + e escolha Criar nova consulta ou Abrir consulta existente. Clique em Abrir consulta existente para ver sua lista de consultas salvas. Clique em Minhas Consultas ou em Favoritos para filtrar a lista de consultas. Na linha que contém a consulta que você deseja ver, clique em Abrir.

Executar uma consulta ou várias consultas

Para executar uma consulta ou todas as consultas:

1. Selecione um SQL warehouse.

2. Realçar uma consulta no Editor SQL (se várias consultas estiverem no painel de consulta).

3. Pressione Ctrl/Cmd + Enter ou clique em Executar (1000) para exibir os resultados como uma tabela no painel de resultados.

   

Observação

Limit 1000 fica selecionado por padrão para todas as consultas para limitar o retorno da consulta a 1000 linhas. Se uma consulta for salva com a configuração Limit 1000, essa configuração se aplicará a todas as execuções da consulta (inclusive nos painéis). Para retornar todas as linhas dessa consulta, você pode desmarcar LIMIT 1000 clicando no menu suspenso Executar (1000). Para especificar um limite diferente para o número de linhas, você pode adicionar uma cláusula LIMIT em sua consulta com um valor de sua escolha.

Encerrar uma consulta

Para encerrar uma consulta em execução, clique em Cancelar. Administradores podem interromper consultas em execução que foram iniciadas por outro usuário. Siga as etapas de Encerrar uma consulta em execução.

Opções de consulta

Você pode usar o menu de contexto kebab próximo à parte superior do editor de consultas para acessar as opções de menu para clonar, reverter, formatar e editar informações de consulta.

Reverter para a consulta salva

Quando você edita uma consulta, uma opção Reverter alterações aparece no menu de contexto da consulta. Você pode clicar em Reverter e voltar para a versão salva.

Descartar e restaurar consultas

Para mover uma consulta para a lixeira:

• Clique no menu de contexto kebab ao lado da consulta no Editor SQL e selecione Mover para a lixeira.
• Clique em Mover para lixeira para confirmar.

Para restaurar uma consulta da lixeira:

1. Na lista Todas as consultas, clique em .
2. Clique em uma consulta.
3. Clique no menu de contexto kebab no canto superior direito do editor de SQL e clique em Restaurar.

Definir a descrição da consulta e exibir informações de consulta

Para definir a descrição de uma consulta:

1. Clique no menu de contexto kebab ao lado da consulta e clique em Editar informações da consulta.

   

2. Na caixa de texto Descrição, insira sua descrição. Em seguida, clique em Salvar. Nesta caixa de diálogo, você também pode exibir o histórico da consulta, inclusive quando ela foi criada e atualizada.

Favoritar e marcar consultas

Você pode usar favoritos e marcas para filtrar as listas de consultas e painéis exibidos na página de aterrissagem do workspace e em cada uma das páginas de listagem para painéis e consultas.

Favoritos: para favoritar uma consulta, clique na estrela à esquerda do título na lista Consultas. A estrela ficará amarela.

Marcas: você pode marcar consultas e painéis com qualquer cadeia de caracteres significativa para sua organização.

Adicionar uma marca

Adicionar marcas no editor de consultas.

1. Clique no menu de contexto kebab ao lado da consulta e clique em Editar informações da consulta. Uma caixa de diálogo de Informações de consulta é exibida.

2. Se a consulta não tiver marcas aplicadas, a opção Adicionar algumas marcas será exibida na caixa de texto em que as marcas serão exibidas. Para criar uma nova marca, digite-a na caixa. Para inserir várias marcas, pressione tab entre as entradas.

   

3. Clique em Salvar para aplicar as marcas e feche a caixa de diálogo.

Remover Marcas

1. Clique no menu de contexto kebab ao lado da consulta e clique em Editar informações da consulta.
2. Clique em X em qualquer marca que você deseja remover.
3. Clique em Salvar para fechar a caixa de diálogo.

Exibir resultados da consulta

Depois que uma consulta é executada, os resultados aparecem no painel abaixo dela. A Nova tabela de resultados está ATIVADA para novas consultas. Se necessário, clique no menu suspenso para desativá-la. As imagens nesta seção usam a nova tabela de resultados.

Você pode explorar e interagir com os resultados da consulta usando o painel de resultados. O painel de resultados inclui os seguintes recursos para explorar os resultados:

Visualizações, filtros e parâmetros

Clique no para adicionar uma visualização, um filtro ou parâmetro. As seguintes opções aparecem:

Visualização: as visualizações podem ajudar a explorar o conjunto de resultados. Consulte Tipos de visualização para obter uma lista completa de tipos de visualização disponíveis.

Filtro: os filtros permitem limitar o conjunto de resultados após a execução de uma consulta. Você pode aplicar filtros para mostrar seletivamente diferentes subconjuntos dos dados. Consulte Filtros de consulta para saber como usar filtros.

Parâmetro: os parâmetros permitem limitar o conjunto de resultados substituindo valores em uma consulta em runtime. Confira Trabalhar com parâmetros de consulta para saber como aplicar parâmetros.

Editar, baixar ou adicionar a um painel

Importante

• O Databricks recomenda o uso de painéis de IA/BI (anteriormente painéis do Lakeview). As versões anteriores dos painéis, anteriormente conhecidas como painéis SQL do Databricks, agora são chamadas de painéis herdados. O Databricks não recomenda a criação de novos dashboards herdados.
• Converta painéis herdados usando a ferramenta de migração ou API REST. Confira Clonar um painel herdado para um painel de IA/BI para obter instruções sobre como usar a ferramenta de migração interna. Veja Tutoriais de painéis para obter tutoriais sobre como criar e gerenciar painéis usando a API REST.

Clique no em uma guia de resultados para exibir mais opções.

1. Clique em Editar para personalizar os resultados mostrados na visualização.
2. Clique em Excluir para excluir a guia de resultados.
3. Clique em duplicar para clonar a guia de resultados.
4. Clique em Adicionar ao painel para copiar a consulta e a visualização para um novo painel.
   • Essa ação cria um novo painel que inclui todas as visualizações associadas à consulta. Consulte Painel para saber como editar seu painel.
   • Você será solicitado a escolher um nome para o novo painel. O novo painel é salvo na pasta inicial.
   • Você não pode adicionar resultados a um painel existente.
5. Clique em Adicionar ao painel herdado para adicionar a guia resultados a um painel herdado novo ou existente.
6. Clique em qualquer uma das opções de download para baixar os resultados. Confira a descrição a seguir para obter detalhes e limites.

Baixar resultados: você pode baixar resultados como um arquivo CSV, TSV ou Excel.

Você pode baixar até aproximadamente 1 GB de dados de resultados do Databricks SQL nos formatos CSV e TSV, e até 100.000 linhas de um arquivo do Excel.

O tamanho do download do arquivo final pode ser ou pouco maior ou menor que 1 GB, pois o limite de 1 GB é aplicado a uma etapa anterior ao download do arquivo final.

Observação

Se você não consegue baixar uma consulta, isso significa que o administrador do workspace desabilitou o download no seu workspace.

Execuções anteriores

Você pode exibir execuções anteriores da consulta, incluindo a sintaxe de consulta completa. Execuções anteriores são abertas no modo somente leitura e incluem botões para Clonar para nova consulta ou Retomar edição. Esta guia não mostra as execuções agendadas.

Explorar os resultados

Os resultados da consulta retornados aparecem abaixo da consulta. A guia Resultados brutos é preenchida com as linhas retornadas. Você pode usar os filtros internos para reordenar os resultados por valores crescentes ou decrescentes. Você também pode usar o filtro para pesquisar linhas de resultado que incluam um valor específico.

Você pode usar as guias no painel de resultados para adicionar visualizações, filtros e parâmetros.

Filtrar a lista de consultas salvas na janela de consultas

Na janela de consultas, filtre a lista de todas as consultas pela lista de consultas que você criou (Minhas Consultas), por favoritos e marcas.

Automatizar as atualizações

Você pode usar o botão Agendar para definir uma cadência automática para exceções de consulta. As atualizações automáticas podem ajudar a manter seus painéis e relatórios atualizados com os dados mais atuais. As consulta agendadas também podem habilitar alertas do Databricks SQL, um tipo especial de tarefa agendada que envia notificações quando um valor atinge um limite específico.

Consulte Agendar uma consulta.

Veja O que são alertas SQL do Databricks?.

Compartilhar consultas

O botão Compartilhar permite compartilhar sua consulta com outros usuários em seu workspace. Ao compartilhar, escolha entre as seguintes opções:

• Executar como proprietário (credenciais de proprietário): essa configuração significa que os visualizadores podem ver os mesmos resultados da consulta que o proprietário da consulta. Isso se aplica a execuções de consulta agendadas ou manuais.
• Executar como visualizador (credenciais de visualizadores): essa configuração limita os resultados às permissões atribuídas ao visualizador.

Veja Configurar permissões de consulta.

Próxima etapa

Consulte Acessar e gerenciar consultas salvas para saber como trabalhar com consultas com a interface do usuário do Azure Databricks.