Como usar o SQL Runner para criar consultas e explorações

O SQL Runner oferece uma maneira de acessar diretamente o banco de dados e aproveitar esse acesso de várias maneiras. Com o SQL Runner, é fácil navegar nas tabelas do esquema, usar uma exploração ad hoc de uma consulta SQL, executar consultas descritivas pré-escritas nos dados, ver o histórico do SQL Runner, fazer o download de resultados, compartilhar consultas, adicionar a um projeto do LookML como uma tabela derivada e realizar outras tarefas úteis.

Esta página descreve como executar consultas no SQL Runner, criar explorações ad hoc e como usar o SQL Runner para depurar consultas. Consulte estas outras páginas de documentação para obter informações sobre:

Como executar consultas no SQL Runner

Para executar uma consulta no banco de dados, é possível gravar a consulta SQL do zero, usar uma exploração para criar a consulta ou executar uma consulta em um modelo LookML. Também é possível usar o histórico para executar novamente uma consulta anterior.

Como escrever uma consulta SQL do zero

Você pode usar o SQL Runner para escrever e executar suas próprias consultas SQL no banco de dados. O Looker passa a consulta ao banco de dados exatamente como você a escreveu. Portanto, verifique se a sintaxe da consulta SQL é válida para o dialeto do banco de dados. Por exemplo, cada dialeto tem funções SQL um pouco diferentes com parâmetros específicos que precisam ser transmitidos para a função.

  1. Insira uma consulta SQL na caixa de texto abaixo da barra Consulta.
  2. Opcionalmente, selecione um nome de tabela ou campo da lista de campos para incluí-lo na consulta no local do cursor.
  3. Selecione Executar para executar a consulta no seu banco de dados.
  4. Veja os resultados na área Results. O SQL Runner carregará até 5.000 linhas do conjunto de resultados da consulta. Para dialetos SQL compatíveis com streaming, faça o download dos resultados para ver todo o conjunto de resultados.

Alguns programas SQL permitem executar várias consultas em uma série. No entanto, só é possível executar uma consulta por vez no SQL Runner. O SQL Runner também tem um limite de 65.535 caracteres em consultas, incluindo espaço em branco.

Depois de executar uma consulta, é possível adicionar a consulta a um projeto, acessar o LookML de uma tabela derivada ou compartilhar a consulta.

Também é possível usar o SQL Runner para testar novas consultas ou realizar consultas. O destaque de erros do SQL Runner ajuda a testar e depurar consultas.

Como usar uma exploração para criar uma consulta SQL

Também é possível usar uma exploração para criar uma consulta e, em seguida, obter o comando SQL para essa consulta para usar no SQL Runner:

  1. Em uma guia "Explorar", selecione a guia SQL na barra Dados.
  2. A consulta SQL aparecerá na barra Dados.
  3. Selecione Abrir no SQL Runner ou Explicar no SQL Runner para abrir a consulta no SQL Runner.

Depois que uma consulta é adicionada à caixa de texto abaixo da barra Consulta, é possível selecionar Executar para consultar o banco de dados. Como alternativa, edite a consulta e, em seguida, execute a nova consulta.

Como criar visualizações com o SQL Runner

Se o administrador do Looker tiver ativado o recurso SQL Runner Vis Labs, você poderá criar visualizações diretamente no SQL Runner.

Com o SQL Runner Vis ativado, os painéis do SQL Runner são reorganizados. O painel de visualização aparece na parte superior, o painel de resultados está no meio e o painel de consulta aparece na parte inferior.

  1. Depois que uma consulta SQL é criada e executada, é possível abrir a guia Visualização para visualizá-la e escolher um tipo de visualização, assim como faria na página "Explorar".
  2. Você pode editar a visualização usando o menu Configurações.
  3. Para compartilhar as visualizações criadas com o SQL Runner, compartilhe o URL. Todas as personalizações que você fizer usando o menu Configurações da visualização serão salvas, e o link não será alterado.

Há alguns pontos a serem considerados sobre o funcionamento das visualizações do SQL Runner:

  • A tabela de resultados e a visualização interpretam qualquer campo numérico como uma medida.
  • O nome completo do campo é sempre usado na tabela de resultados e na visualização. Portanto, a opção Mostrar nome do campo completo no menu Configurações fica inativa.
  • Para usar campos personalizados, cálculos de tabela, tabelas dinâmicas, totais de colunas e subtotais, explore a partir da consulta do SQL Runner.
  • As visualizações de mapa estático (regiões) não são compatíveis com as visualizações do SQL Runner. No entanto, mapas que usam dados de latitude e longitude (visualizações de mapa e mapa estático (pontos)) são aceitos.
  • As visualizações da linha do tempo não são compatíveis com as visualizações do SQL Runner.

Dimensões de dinamização

É possível editar os resultados da consulta para pivot por uma ou mais dimensões nas visualizações do SQL Runner. Para dinamizar um campo:

  1. Selecione o menu de engrenagem de uma coluna na área Resultados para ver as opções.
  2. Selecione Coluna dinâmica.

Os resultados dinamizados são exibidos na visualização do SQL Runner.

Os resultados na área Resultados não parecem ser dinamizados.

Para remover a tabela dinâmica, selecione o menu de engrenagem da coluna dinâmica e selecione Coluna não dinâmica.

Como alterar o tipo de campo

Ao exibir os resultados e a visualização da sua consulta, o SQL Runner interpreta automaticamente qualquer campo numérico como uma medida e qualquer campo não numérico como uma dimensão. Você pode modificar o tipo de campo padrão e converter uma dimensão em uma medida (ou vice-versa) seguindo estas etapas:

  1. Selecione o menu de engrenagem de uma coluna na área Resultados para ver as opções.
  2. Selecione Converter para dimensão ou Converter para avaliar para alterar o tipo de campo.

A visualização exibirá o novo tipo de campo.

Como executar uma consulta em um modelo LookML

Você pode usar o SQL Runner para escrever e executar consultas SQL em um modelo LookML, em vez de diretamente no seu banco de dados. Ao criar sua consulta com base em um modelo, use operadores de substituição LookML, como ${view_name.field_name} ou ${view_name.SQL_TABLE_NAME}. Isso pode economizar tempo ao construir uma consulta para solucionar problemas de uma tabela derivada, por exemplo.

O Looker resolve todas as substituições do LookML e passa a consulta para o banco de dados. Assim, a consulta precisa estar em SQL válido para seu dialeto do banco de dados. Por exemplo, cada dialeto tem funções SQL um pouco diferentes com parâmetros específicos que precisam ser transmitidos para a função.

Para executar uma consulta no modelo LookML no SQL Runner:

  1. Selecione a guia Modelo.
  2. Selecione o modelo que você quer consultar.
  3. Na caixa de texto abaixo da barra Data, digite sua consulta SQL usando os campos LookML.
  4. Opcionalmente, selecione uma visualização na lista de visualizações para incluir a visualização na consulta no local do cursor.
  5. Para ver a lista de campos em uma visualização, selecione-a na seção Visualizações. Opcionalmente, você pode selecionar um campo na lista de campos para incluí-lo em sua consulta na localização do cursor.
  6. Na área Prepared SQL Query, você pode ver a consulta SQL resultante criada após a substituição de qualquer substituição do LookML para SQL.
  7. Selecione Executar para executar a consulta no modelo.
  8. Veja os resultados na área Results. O SQL Runner carrega até 5.000 linhas do conjunto de resultados da consulta. Para dialetos SQL compatíveis com streaming, faça o download dos resultados para ver todo o conjunto de resultados.

Use o SQL Runner para testar novas consultas, testar outras já existentes ou abrir um novo recurso Explorar nos resultados. O destaque de erros do SQL Runner ajuda a testar e depurar consultas.

Quando tiver interesse em uma consulta, será possível compartilhá-la e até mesmo adicioná-la a um projeto do LookML.

Como visualizar o LookML de um campo no SQL Runner

Na lista de campos da guia Modelo, você também pode ver o LookML de um campo. Passe o cursor sobre o campo na lista e selecione o ícone do Looker à direita do nome do campo.

O Looker abre o ambiente de desenvolvimento integrado LookML e carrega o arquivo em que o campo está definido.

Histórico do SQL Runner

Também é possível ver um histórico recente de todas as consultas executadas no SQL Runner.

Para ver seu histórico, selecione a guia Histórico na parte superior do painel de navegação. O SQL Runner exibe todas as consultas executadas na conexão do banco de dados. Vermelho indica uma consulta que não foi executada devido a um erro.

Selecione uma consulta no histórico para preenchê-la no SQL Runner e, em seguida, selecione Executar para executá-la novamente.

Como classificar sua consulta

A ordem de classificação de uma tabela é indicada por uma seta para cima ou para baixo ao lado do nome do campo classificado, dependendo se os resultados estão em ordem crescente ou decrescente. Você pode classificar por várias colunas mantendo pressionada a tecla Shift e selecionando os cabeçalhos das colunas na ordem em que deseja classificá-las. A ordem de classificação de um campo também é indicada por um número que distingue a ordem de classificação em comparação com outros campos, por uma seta ao lado do nome do campo que mostra a direção da classificação (ascendente ou decrescente) e por um pop-up que aparece quando você passa o mouse sobre o nome de um campo.

Para mais informações e exemplos, consulte a seção Como classificar dados da página de documentação Como explorar dados no Looker.

Compartilhamento de consultas

Você pode compartilhar uma consulta no SQL Runner com outro usuário que tenha acesso ao SQL Runner. Para compartilhar uma consulta, copie o URL na barra de endereço do seu navegador.

Fazendo o download dos resultados

Depois de executar a consulta SQL, é possível fazer o download dos resultados em vários formatos.

  1. Escreva uma consulta na caixa Consulta SQL. Você não precisa executar a consulta no SQL Runner neste momento.
  2. Selecione Fazer o download no menu de roda dentada no canto superior direito.
  3. Selecione o formato do arquivo do download (arquivo de texto, CSV, JSON etc.).

  4. Selecione Abrir no navegador para ver os resultados em uma nova janela do navegador ou Fazer download para salvar os resultados em um arquivo no seu computador.

    Quando você seleciona Abrir no navegador ou Fazer download, o Looker gera novamente a consulta e faz o download.

Para dialetos SQL compatíveis com streaming, a opção Download do SQL Runner fará o download de todo o conjunto de resultados. Para dialetos SQL não compatíveis com streaming, a opção Download do SQL Runner fará o download apenas das linhas da consulta mostradas na seção Resultados (até 5.000 linhas).

Como copiar valores de coluna

É possível copiar valores de coluna da seção Resultados no SQL Runner. Selecione o menu de roda dentada de uma coluna para copiar os valores para a área de transferência. A partir daí, você pode colar os valores da coluna em um arquivo de texto, uma planilha do Excel ou outro local.

Se o administrador do Looker ativou o recurso SQL Runner Vis Labs, você também tem outras opções no menu da engrenagem de coluna:

Também é possível mover, fixar e redimensionar manualmente as colunas da tabela de resultados.

Estimativas de custo para consultas do SQL Runner

Para conexões do BigQuery, MySQL, Amazon RDS for MySQL, Snowflake, Amazon Redshift, Amazon Aurora, PostgreSQL, Cloud SQL para PostgreSQL e Microsoft Azure PostgreSQL, o SQL Runner fornece uma estimativa do custo da consulta. Depois que você inserir a consulta SQL, o SQL Runner calculará a quantidade de dados necessária e exibirá as informações próximas ao botão Executar.

As estimativas de custo estão sempre ativadas para BigQuery, MySQL e Amazon RDS para conexões MySQL. Para as conexões de banco de dados do Snowflake, Amazon Redshift, Amazon Aurora, PostgreSQL, Cloud SQL para PostgreSQL e Microsoft Azure PostgreSQL, é preciso ativar a opção Estimativa de custo para a conexão. É possível ativar a Estimativa de custo ao criar a conexão. Para conexões existentes, é possível editar a conexão na página Conexões na seção Banco de dados do painel Administrador do Looker.

Como criar uma exploração ad hoc

No SQL Runner, você consegue insights rápidos sobre os dados por meio da criação de uma exploração ad hoc para uma consulta SQL ou tabela de banco de dados. Você pode usar o Looker Explore para selecionar campos, adicionar filtros, visualizar os resultados e criar consultas SQL.

Há duas maneiras de abrir uma exploração ad hoc do SQL Runner:

  • Explorar os resultados da consulta do SQL Runner
  • Explorar a lista de tabelas do SQL Runner

Como analisar os resultados da consulta do SQL Runner

O SQL Runner permite abrir uma exploração a partir de uma consulta SQL. Isso cria uma exploração temporária da consulta escrita no SQL Runner. Isso permite que você teste o que é retornado pela consulta e visualize os resultados. Isso pode ser usado para qualquer consulta, mas é especialmente útil para testar consultas que você planeja usar para tabelas derivadas.

Se o administrador do Looker tiver ativado o recurso SQL Runner Vis Labs, você poderá criar visualizações diretamente no SQL Runner.

  1. Use o SQL Runner para criar a consulta SQL que você quer usar.
  2. Selecione Explorar no menu de roda dentada no canto superior direito. Isso leva você a uma nova exploração, em que é possível explorar a consulta SQL como se ela fosse uma tabela salva no seu modelo.
  3. Você pode copiar o URL nesta exploração para compartilhar.
  4. Para adicionar essa consulta como uma tabela derivada no seu projeto diretamente daqui, selecione Adicionar visualização ao projeto.

Como criar campos personalizados ao explorar no SQL Runner

Se você tiver acesso ao recurso campos personalizados, poderá usar os campos personalizados para visualizar campos não modelados no SQL Runner. Conforme descrito na seção anterior, selecione Explorar no menu de roda dentada. Em seguida, no seletor de campo, siga estas etapas:

Como analisar uma tabela listada no SQL Runner

Use a opção Explorar tabela na guia Banco de dados para criar uma exploração ad hoc para qualquer tabela na conexão. Isso permite que você use o Looker em uma tabela antes de modelá-la, explorando a tabela como uma visualização do LookML.

Depois de abrir a opção "Explorar" para a tabela, você pode decidir se quer adicioná-la ao projeto. Você também pode usar a guia SQL do Explorar para ver as consultas SQL que o Looker envia ao banco de dados e, em seguida, usar o botão Abrir no SQL Runner para trazer a consulta de volta ao SQL Runner.

  1. Selecione a guia Banco de dados.
  2. No SQL Runner, selecione a engrenagem para uma tabela e, em seguida, Explore Table.
  3. O Looker gera um modelo temporário com uma visualização para a tabela e exibe o recurso "Explorar".
  4. O Looker fornece um campo de dimensão para cada coluna na tabela. É assim que o Looker gera um modelo no início de um projeto.
  5. O Looker inclui automaticamente os períodos de todos os campos de data.
  6. O Looker também inclui uma medida de contagem.

Ao usar a opção Explorar tabela, não há arquivos LookML associados à exploração. Ela é apenas uma visualização ad hoc da tabela.

Como depurar com o SQL Runner

O SQL Runner também é uma ferramenta útil para verificar erros de SQL em consultas.

Destaque do erro do SQL Runner

O SQL Runner destaca a localização dos erros no comando SQL e inclui a posição do erro na mensagem de erro:

As informações de posição fornecidas variam de acordo com o dialeto do banco de dados. Por exemplo, o MySQL fornece o número da linha que contém o erro, enquanto o Redshift fornece a posição do caractere do erro. Outros dialetos de banco de dados podem ter um desses comportamentos.

O SQL Runner também destaca o local do primeiro erro de sintaxe no comando SQL, sublinhando-o em vermelho e marcando a linha com um x. Passe o cursor sobre o x para ver mais informações sobre o erro. Depois de corrigir o problema, selecione Executar para ver se há mais erros na consulta.

Como usar o SQL Runner para verificar erros em "Explorar"

Se você encontrar erros de sintaxe SQL em uma exploração, poderá usar o SQL Runner para determinar o local e o tipo de erro, como erros de ortografia ou comandos ausentes.

  1. Em "Explorar", selecione a guia SQL da barra de dados.
  2. Selecione Abrir no SQL Runner para abrir a consulta no SQL Runner.

Isso copia o SQL gerado no Explorar no SQL Runner. Conforme mostrado acima, o SQL Runner destaca a localização dos erros no comando SQL e inclui a posição do erro na mensagem de erro. Em seguida, você pode fazer alterações e executar novamente a consulta no SQL Runner até corrigir os erros.

Como usar o SQL Runner para verificar erros em tabelas derivadas

Para mais informações sobre como usar o SQL Runner para verificar erros de SQL em tabelas derivadas, consulte a postagem Como usar o SQL Runner para testar tabelas derivadas (em inglês).