Como usar o SQL Runner para criar consultas e análises detalhadas

O SQL Runner oferece uma maneira de acessar diretamente seu banco de dados e aproveitar esse acesso de várias maneiras. Com o SQL Runner, é fácil navegar pelas tabelas no seu esquema, usar uma análise ad hoc de uma consulta SQL, executar consultas descritivas pré-gravadas nos seus dados, conferir o histórico do SQL Runner, baixar resultados, compartilhar consultas, adicionar a um projeto 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 saber mais sobre:

Como executar consultas no SQL Runner

Para executar uma consulta no seu banco de dados, você pode escrever a consulta SQL do zero, usar uma Análise para criar a consulta ou executar uma consulta em um modelo LookML. Você também pode usar o histórico para executar uma consulta anterior.

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 transmite sua 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 ligeiramente diferentes com parâmetros específicos que precisam ser transmitidos para a função.

  1. Insira uma consulta SQL no campo abaixo da barra Consulta.
  2. Se quiser, selecione um nome de tabela ou campo na lista para incluir na consulta na posição do cursor.
  3. Selecione Executar para executar a consulta no banco de dados.
  4. Confira os resultados na área Resultados. O SQL Runner carrega até 5.000 linhas do conjunto de resultados da consulta. Para dialetos SQL que oferecem suporte a streaming, é possível baixar os resultados para conferir todo o conjunto de resultados.

Depois de executar uma consulta, você pode adicionar a consulta a um projeto, receber o LookML de uma tabela derivada ou compartilhar a consulta.

Você também pode usar o SQL Runner para testar consultas novas ou atuais. O destaque de erros do SQL Runner ajuda a testar e depurar consultas.

Usar uma Análise para criar uma consulta SQL

Você também pode usar uma análise detalhada para criar uma consulta e depois receber o comando SQL dela para usar no SQL Runner:

  1. Em uma Análise, selecione a guia SQL na barra Dados.
  2. A consulta SQL vai 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 ao campo abaixo da barra Consulta, é possível selecionar Executar para consultar o banco de dados. Como alternativa, edite e execute a nova consulta.

Como criar visualizações com o SQL Runner

Se o administrador do Looker tiver ativado o recurso do Labs Visualização do SQL Runner, 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 de cima, o painel de resultados fica no meio, e o painel de consulta aparece na parte de baixo.

  1. Depois de criar e executar uma consulta SQL, abra a guia Visualização para conferir a visualização e escolher um tipo, assim como na página "Explorar".
  2. Para editar a visualização, use o menu Configurações.
  3. Para compartilhar visualizações criadas com o SQL Runner, basta compartilhar o URL. Todas as personalizações feitas usando o menu Configurações da visualização serão salvas, e o link não vai mudar.

Alguns pontos importantes sobre como as visualizações do SQL Runner funcionam:

  • A tabela de resultados e a visualização interpretam qualquer campo numérico como uma métrica.
  • O nome completo do campo é sempre usado na tabela de resultados e na visualização. Portanto, a opção Mostrar nome completo do campo no menu Configurações fica inativa.
  • Para usar campos personalizados, cálculos de tabela, tabelas dinâmicas, totais de colunas e subtotais, analise a 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, os 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 as visualizações do SQL Runner.

Dimensões de representação dinâmica

É possível editar os resultados da consulta para criar uma tabela dinâmica por uma ou mais dimensões nas visualizações do SQL Runner. Para criar uma tabela dinâmica de um campo:

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

Os resultados de transposição aparecem na visualização do SQL Runner.

Para desfazer a rotação dos resultados, selecione o menu de engrenagem da coluna rotacionada e escolha Desfazer a rotação da coluna.

Como mudar o tipo de campo

Ao mostrar os resultados e a visualização da sua consulta, o SQL Runner interpreta automaticamente qualquer campo numérico como uma métrica e qualquer campo não numérico como uma dimensão. Para substituir o tipo de campo padrão e converter uma dimensão em uma métrica (ou vice-versa), siga estas etapas:

  1. Selecione o menu de engrenagem de uma coluna na área Resultados para mostrar as opções de coluna.
  2. Selecione Converter em dimensão ou Converter em métrica para mudar o tipo de campo.

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

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 banco de dados. Ao criar uma consulta em um modelo, você pode usar operadores de substituição da LookML, como ${view_name.field_name} ou ${view_name.SQL_TABLE_NAME}. Isso pode economizar tempo ao criar uma consulta para resolver problemas em uma tabela derivada, por exemplo.

O Looker resolve todas as substituições do LookML e transmite a consulta ao banco de dados. Portanto, ela precisa estar em 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 precisam ser transmitidos 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 campos da LookML.
  4. Se quiser, selecione uma visualização na lista para incluir na consulta no local do cursor.
  5. Para conferir a lista de campos em uma visualização, selecione-a na seção Visualizações. Se quiser, selecione um campo na lista para incluir na consulta no local do cursor.
  6. Na área Consulta SQL preparada, é possível conferir a consulta SQL resultante criada depois que todas as substituições de LookML são traduzidas para SQL.
  7. Selecione Executar para executar a consulta no 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 que oferecem suporte a streaming, é possível baixar os resultados para conferir todo o conjunto de resultados.

Você pode usar o SQL Runner para testar novas consultas, testar as atuais ou abrir uma nova análise detalhada com base nos resultados. O destaque de erros do SQL Runner ajuda a testar e depurar consultas.

Quando você tiver uma consulta que goste, poderá compartilhá-la e até mesmo adicioná-la a um projeto do LookML.

Como acessar a LookML de um campo no SQL Runner

Na lista de campos da guia Modelo, também é possível conferir o LookML de um campo. Mantenha o ponteiro sobre o campo na lista e selecione o ícone do Looker à direita do nome do campo.

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

Histórico do SQL Runner

Você também pode conferir um histórico recente de todas as consultas executadas no SQL Runner.

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

Selecione uma consulta no histórico para preencher o SQL Runner e clique em Executar para executar a consulta 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. Para ordenar por várias colunas, mantenha a tecla Shift pressionada e selecione os cabeçalhos na ordem desejada. 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 (crescente ou decrescente) e por um pop-up que aparece quando você mantém o ponteiro sobre um nome de campo.

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

Compartilhamento de consultas

É possível compartilhar uma consulta no SQL Runner com outro usuário que tenha acesso a ele. Para compartilhar uma consulta, copie o URL na barra de endereço do navegador.

Baixando resultados

Depois de executar a consulta SQL, você pode baixar os resultados em vários formatos.

  1. Escreva uma consulta na caixa Consulta SQL. Não é necessário 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 arquivo de download (arquivo de texto, CSV, JSON etc.).

  4. Selecione Abrir no navegador para ver os resultados em uma nova janela do navegador ou Baixar para fazer o download dos resultados em um arquivo no computador.

Para dialetos SQL que oferecem suporte a streaming, a opção Download do SQL Runner baixa todo o conjunto de resultados. Para dialetos SQL que não oferecem suporte a streaming, a opção Download do SQL Runner baixa apenas as linhas da consulta mostradas na seção Resultados (até 5.000 linhas).

Como copiar valores de colunas

É possível copiar 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. De lá, 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 do Labs Visualização do SQL Runner, você também terá outras opções no menu de engrenagem da coluna:

Também é possível mover, fixar e redimensionar colunas manualmente 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 fornece uma estimativa do custo da consulta. Depois que você inserir a consulta SQL, o SQL Runner vai calcular a quantidade de dados necessária e mostrar 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 do Snowflake, Amazon Redshift, Amazon Aurora, PostgreSQL, Cloud SQL para PostgreSQL e Microsoft Azure PostgreSQL, é necessário ativar a opção Estimativa de custo para a 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 na seção Banco de dados do painel Administrador do Looker.

Criar uma análise detalhada específica

No SQL Runner, é possível criar uma análise detalhada ad hoc para uma consulta SQL ou tabela de banco de dados e ter insights rápidos sobre os dados. Você pode usar a Análise do Looker para selecionar campos, adicionar filtros, visualizar os resultados e criar consultas SQL.

Há duas maneiras de abrir uma análise ad hoc do SQL Runner:

  • Analisar os resultados da consulta do SQL Runner
  • Analisar na lista de tabelas do SQL Runner

Como analisar os resultados da consulta do SQL Runner

Com o SQL Runner, é possível abrir uma análise detalhada com base em uma consulta SQL. Isso cria uma análise temporária com base na consulta escrita no SQL Runner. Assim, é possível testar o que é retornado pela consulta e visualizar os resultados. Isso pode ser usado para qualquer consulta, mas é especialmente útil para testar consultas que você planeja usar em tabelas derivadas.

  1. Use o SQL Runner para criar a consulta SQL que você quer usar.
  2. Selecione Análise no menu de engrenagem no canto superior direito. Isso leva você a uma nova Análise detalhada, em que é possível analisar a consulta SQL como se fosse uma tabela salva no modelo.
  3. Você pode copiar o URL para compartilhar essa análise.
  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 analisar no SQL Runner

Se você tiver acesso ao recurso campos personalizados, poderá usá-los para visualizar campos não modelados no SQL Runner. Conforme descrito na seção anterior, selecione Analisar no menu de engrenagem. Em seguida, no seletor de campos, siga estas etapas:

Analisar uma tabela listada no SQL Runner

Use a opção Analisar tabela na guia Banco de dados para criar uma análise ad hoc de qualquer tabela na conexão. Isso permite usar o Looker em uma tabela antes de modelá-la, explorando a tabela como uma visualização do LookML.

Depois de abrir uma análise detalhada da tabela, você pode decidir se quer adicioná-la ao projeto. Você também pode usar a guia SQL da análise detalhada para conferir 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 de uma tabela e clique em Analisar tabela.
  3. O Looker gera um modelo temporário com uma visualização para a tabela e depois mostra a Análise.
  4. O Looker fornece um campo de dimensão para cada coluna na tabela. É a mesma forma como o Looker gera um modelo no início de um projeto.
  5. O Looker inclui automaticamente períodos para todos os campos de data.
  6. O Looker também inclui uma medida de contagem.

Depuração usando o SQL Runner

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

Destaque de erros do SQL Runner

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

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, sublinhando-o em vermelho e marcando a linha com um x. Mantenha o ponteiro sobre o x para ver mais informações sobre o erro. Depois de corrigir o problema, selecione Executar para verificar se há mais erros na consulta.

Usar o SQL Runner para verificar erros em análises detalhadas

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

  1. Na Análise, 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 da Análise para o SQL Runner. Como mostrado na seção Destaque de erros do SQL Runner, o SQL Runner destaca o local dos erros no comando SQL e inclui a posição do erro na mensagem de erro. Em seguida, faça as mudanças e execute a consulta novamente no SQL Runner até corrigir os erros.

Usar o SQL Runner para verificar erros em tabelas derivadas

Para informações sobre como usar o SQL Runner para verificar erros de SQL em tabelas derivadas, consulte a postagem da comunidade do Looker Como usar o SQL Runner para testar tabelas derivadas.