Como usar o SQL Runner para criar consultas e Explores

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 pelas tabelas do esquema, usar uma Análise ad hoc de uma consulta SQL, executar consultas descritivas pré-escritas nos dados, ver o histórico do SQL Runner, fazer o download dos resultados, compartilhar consultas, adicionar a um projeto do LookML como uma tabela derivada e realizar outras tarefas úteis.

Nesta página, descrevemos como executar consultas no SQL Runner, criar Análises ad hoc e usar o SQL Runner para depurar consultas. Consulte estas outras páginas de documentação para mais informações sobre:

Como executar consultas no SQL Runner

Para executar uma consulta no seu banco de dados, escreva a consulta SQL do zero, use uma Análise para criar a consulta ou execute uma consulta em um modelo do LookML. Também é possível usar o histórico para executar novamente uma consulta anterior.

Como escrever uma consulta SQL do zero

É possível usar o SQL Runner para escrever e executar suas próprias consultas SQL no banco de dados. O Looker transmite a consulta para o 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 ligeiramente diferentes com parâmetros específicos que devem ser passados para a função.

  1. Insira uma consulta SQL na caixa de texto abaixo da barra Consulta.
  2. Também é possível selecionar um nome de tabela ou campo na lista de campos para incluí-lo na sua consulta no local do cursor.
  3. Selecione Executar para executar a consulta no seu banco de dados.
  4. Confira os resultados na área Resultados. O SQL Runner carregará até 5.000 linhas do conjunto de resultados da consulta. Para dialetos SQL compatíveis com streaming, você pode fazer 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 testar as atuais. O destaque de erros do SQL Runner ajuda a testar e depurar consultas.

Como usar uma Análise para criar uma consulta SQL

Também é possível usar uma Análise para criar uma consulta e receber o comando SQL dela para usar no SQL Runner:

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

Quando uma consulta é adicionada à caixa de texto abaixo da barra Consulta, é possível selecionar Executar para consultar o banco de dados. Como alternativa, é possível editar e executar a nova consulta.

Como criar visualizações com o SQL Runner

Se o administrador do Looker tiver ativado o recurso de laboratórios SQL Runner Vis, 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 de criar e executar uma consulta SQL, abra a guia Visualização para escolher um tipo, assim como faria na página "Explorar".
  2. Edite-a usando o menu Configurações.
  3. Compartilhe o URL das visualizações criadas com o SQL Runner. Todas as personalizações feitas usando o menu Configurações da visualização serão salvas, e o link não será alterado.

É preciso ter em mente alguns detalhes sobre o funcionamento das visualizações do SQL Runner:

  • A tabela e a visualização de resultados interpretam qualquer campo numérico como uma medida.
  • O nome completo do campo sempre é usado na tabela e visualização de resultados. Portanto, a opção Mostrar nome completo do campo no menu Configurações está inativa.
  • Para usar campos personalizados, cálculos de tabelas, tabelas dinâmicas, totais de colunas e subtotais, explore a consulta do SQL Runner.
  • As visualizações de mapas estáticos (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 compatíveis.
  • As visualizações de linha do tempo não são compatíveis com visualizações do SQL Runner.

Dimensões dinâmicas

É possível editar os resultados da consulta para pivot em 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 exibir as opções de coluna.
  2. Selecione Coluna dinâmica.

Os resultados dinâmicos são mostrados na visualização do SQL Runner.

Os resultados na área Resultados não aparecem dinamizados.

Para resultados unpivot, selecione o menu de engrenagem da coluna dinâmica e escolha 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. É possível substituir 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 exibir as opções de coluna.
  2. Selecione Converter em dimensão ou Converter em medida para alterar o tipo de campo.

A visualização vai mostrar o novo tipo de campo.

Como executar uma consulta em um modelo LookML

É possível usar o SQL Runner para escrever e executar consultas SQL em um modelo LookML, em vez de diretamente no banco de dados. Ao construir sua consulta em um modelo, você pode usar 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 transmite a consulta ao banco de dados. Assim, a consulta precisa estar em um SQL válido para o dialeto do banco de dados. Por exemplo, cada dialeto tem funções SQL ligeiramente diferentes com parâmetros específicos que devem ser passados para a função.

Para executar uma consulta no seu 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 Dados, insira sua consulta SQL usando os campos do LookML.
  4. Também é possível selecionar uma visualização na lista para incluí-la na sua consulta na localização do cursor.
  5. Para consultar a lista de campos em uma visualização, selecione a visualização na seção Visualizações. Também é possível selecionar um campo na lista de campos para incluí-lo na sua consulta na localização do cursor.
  6. Na área Consulta SQL preparada, é possível ver a consulta SQL resultante que foi criada após todas as substituições do LookML terem sido convertidas em SQL.
  7. Selecione Executar para executar a consulta no seu modelo.
  8. Confira os resultados na área Resultados. O SQL Runner carrega até 5.000 linhas do conjunto de resultados da consulta. Para dialetos SQL compatíveis com streaming, você pode fazer o download dos resultados para ver todo o conjunto de resultados.

Use o SQL Runner para testar novas consultas ou abrir uma nova Análise com os resultados. O destaque de erros do SQL Runner ajuda a testar e depurar consultas.

Quando você tiver uma consulta de que gostar, é 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, também é possível ver o LookML de um campo. Passe o cursor sobre o campo na lista e selecione o ícone do Looker à direita do nome dele.

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

Histórico do SQL Runner

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

Para acessar seu histórico, selecione a guia Histórico na parte superior do painel de navegação. O SQL Runner exibe todas as consultas que foram 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 selecione Executar para executar de novo.

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. Para classificar por várias colunas, mantenha a tecla Shift pressionada e selecione os cabeçalhos das colunas na ordem em que você quer que elas sejam classificadas. A ordem de classificação de um campo também é indicada por um número que distingue sua ordem de classificação em comparação com outros campos, por uma seta ao lado do nome do campo que mostra a direção de classificação (crescente ou decrescente) e por um pop-up que aparece quando você passa o cursor sobre um nome de campo.

Confira mais informações e exemplos na seção Como classificar dados da página de documentação Como analisar dados no Looker.

Compartilhamento de consultas

É possível 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 sua 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 engrenagem no canto superior direito.
  3. Selecione o formato do download (arquivo de texto, CSV, JSON etc.).

  4. Selecione Abrir no navegador para abrir 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 o download, o Looker executa a consulta novamente e faz o download.

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

Copiando valores de coluna

É possível copiar os valores de coluna da seção Resultados no SQL Runner. Selecione o menu de engrenagem 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 tiver ativado o recurso de laboratórios SQL Runner Vis, você também terá outras opções no menu de engrenagem da coluna:

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

Estimativas de custo para consultas do SQL Runner

Para conexões do BigQuery, MySQL, Amazon RDS para MySQL, Snowflake, Amazon Redshift, Amazon Aurora, PostgreSQL, Cloud SQL para PostgreSQL e Microsoft Azure PostgreSQL, o SQL Runner apresenta uma estimativa do custo da consulta. Depois que você insere a consulta SQL, o SQL Runner calcula a quantidade de dados necessária para a consulta e exibe as informações perto do botão Executar.

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

Como criar um Explore ad hoc

Com o SQL Runner, você pode receber insights rápidos dos dados criando uma Análise ad hoc para uma consulta SQL ou tabela de banco de dados. É possível usar essa ferramenta para selecionar campos, adicionar filtros, conferir os resultados e criar consultas SQL.

Há duas maneiras de abrir uma Análise ad hoc no SQL Runner:

  • Explore pelos resultados da consulta do SQL Runner
  • Explore na lista de tabelas do SQL Runner

Como explorar a partir dos resultados da consulta do SQL Runner

O SQL Runner permite abrir uma Análise em uma consulta SQL. Isso cria um Explore temporário a partir da consulta escrita no SQL Runner. Isso permite testar o que é retornado pela consulta e visualizar os resultados. Isso pode ser usado para qualquer consulta, mas é especialmente útil para testar as consultas que você planeja usar para tabelas derivadas.

Se o administrador do Looker tiver ativado o recurso de laboratórios SQL Runner Vis, crie visualizações diretamente no SQL Runner.

  1. Use o SQL Runner para criar a consulta SQL que quer usar.
  2. Selecione Explorar no menu de engrenagem no canto superior direito. Isso leva você a um novo Explore, em que é possível analisar a consulta SQL como se ela fosse uma tabela salva no seu modelo.
  3. Você pode copiar o URL para este Explore para compartilhamento.
  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 de campos personalizados, poderá usar campos personalizados para visualizar campos não modelados no SQL Runner. Conforme descrito na seção anterior, selecione Explorar no menu de engrenagem. Em seguida, no seletor de campo, siga estas etapas:

Como explorar uma tabela listada no SQL Runner

Use a opção Explore Table na guia Database para criar uma Análise ad hoc para qualquer tabela na conexão. Assim, é possível usar o Looker em uma tabela antes de criar a modelagem, explorando a tabela como uma visualização do LookML.

Depois de abrir uma tabela para explorar a tabela, você pode decidir se quer adicioná-la ao projeto. Também é possível usar a guia SQL da Análise para conferir as consultas SQL que o Looker envia ao banco de dados e usar o botão Abrir no SQL Runner para retornar a consulta ao SQL Runner.

  1. Selecione a guia Banco de dados.
  2. No SQL Runner, selecione a engrenagem de uma tabela e, em seguida, Explore Table.
  3. O Looker gera um modelo temporário com uma visualização da tabela e mostra a Análise.
  4. O Looker tem um campo de dimensão para cada coluna da tabela. É da mesma maneira que o Looker gera um modelo no início de um projeto.
  5. O Looker inclui automaticamente períodos para qualquer campo de data.
  6. O Looker também inclui uma medida de contagem.

Ao usar a opção Explore Table, não há um arquivo LookML associado à ferramenta Explore. Ela é apenas uma visualização pontual da tabela.

Como depurar usando o SQL Runner

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

Destaque de erros no SQL Runner

O SQL Runner destaca o local 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 ou outros comportamentos.

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

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

Se você encontrar erros de sintaxe SQL em uma Análise, use o SQL Runner para determinar o local e o tipo de erro, como erros de ortografia ou comandos ausentes.

  1. Em "Explore", 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 pela Análise para o SQL Runner. Conforme mostrado acima, o SQL Runner destaca o local dos erros no comando SQL e inclui a posição do erro na mensagem de erro. 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 saber como usar o SQL Runner para verificar erros de SQL em tabelas derivadas, consulte Como usar o SQL Runner para testar tabelas derivadas na comunidade do Looker.