Usar parâmetros em uma consulta personalizada

Os parâmetros permitem criar relatórios responsivos e personalizáveis transmitindo parâmetros de uma fonte de dados de volta para a consulta SQL subjacente. Para usar um parâmetro na consulta personalizada, siga as diretrizes de sintaxe documentadas em Executar consultas parametrizadas.

Parâmetros padrão

É possível usar os seguintes parâmetros em qualquer consulta personalizada:

Parâmetro

Finalidade

@DS_START_DATE

Define o início do período do relatório.

@DS_END_DATE

Define o fim do período do relatório.

@DS_USER_EMAIL

Define o endereço de e-mail do usuário conectado.

Para usar esses parâmetros, siga estas etapas:

  1. Na seção Parâmetros do painel de conexão, ative os parâmetros que você quer usar. O Data Studio pede que você conceda acesso ao seu endereço de e-mail ao ativar o parâmetro @DS_USER_EMAIL.
  2. Na consulta, use letras maiúsculas ao digitar os nomes dos parâmetros.

O Data Studio transmite todos os valores de parâmetro como strings de texto. Para processar strings de parâmetro como datas de calendário, números ou outros tipos de dados, use uma função de conversão SQL apropriada, como PARSE_DATE, PARSE_TIMESTAMP ou CAST.

Usar parâmetros de data para enviar os períodos à consulta

Se o relatório incluir um controle de período, os leitores poderão usar esse controle para solicitar datas de início e término diferentes diretamente do banco de dados.

Usar o parâmetro de e-mail para dar acesso aos dados no nível da linha

Com o parâmetro de e-mail, você pode mostrar somente os dados associados ao usuário conectado de um relatório, fonte de dados ou análise detalhada. Esse usuário precisa ter feito login em uma Conta do Google e autorizar o compartilhamento do e-mail com o Data Studio. Caso o leitor não aceite informar o e-mail, todos os gráficos do relatório que usam essa fonte de dados vão mostrar um erro de autorização.

Parâmetros personalizados

Você pode usar qualquer parâmetro criado na interface do usuário do Data Studio na sua consulta personalizada.

Criar um parâmetro na página de conexão

  1. Na seção Parâmetros do editor de consultas personalizadas, clique em +ADICIONAR PARÂMETRO.
  2. Configure as opções de parâmetro.
  3. Clique em OK.

Ocultar parâmetros personalizados na fonte de dados

Por padrão, os editores de relatórios podem modificar parâmetros personalizados diretamente nos relatórios. Você pode ocultar um parâmetro para impedir que os editores de relatórios mudem o valor dele diretamente na configuração da fonte de dados:

  1. Clique em Mais opções.
  2. Clique em Ocultar.

Saiba mais sobre como permitir parâmetros da fonte de dados em relatórios.

Usar um parâmetro em uma consulta personalizada

No corpo da consulta SQL personalizada, substitua um valor codificado por um identificador que comece com o caractere @ (por exemplo, @param_name).

Exemplos de parâmetros

Confira alguns exemplos de uso de parâmetros:

Exemplo de parâmetro personalizado

SELECT word FROM `TABLE` WHERE corpus = @corpus;

String com CONTAINS e um limite numérico

SELECT * FROM `bigquery-public-data.baseball.games_post_wide`
WHERE REGEXP_CONTAINS(gameId, @s)
AND attendance > @attendance LIMIT 100;

Parâmetro de string de seleção múltipla

Observe como UNNEST simplifica a lista de valores de parâmetros de seleção múltipla:

SELECT * from user.users as user WHERE display_name in UNNEST(@name);

Parâmetro de data usando formatação padrão

SELECT creation_date, age, display_name from user.users as user
WHERE creation_date > PARSE_DATE('%Y%m%d', @DS_START_DATE)
AND creation_date < PARSE_DATE('%Y%m%d', @DS_END_DATE);

Parâmetro de data usando carimbo de data/hora Unix em microssegundos

SELECT creation_date, age, display_name from user.users as use
WHERE creation_date > UNIX_MICROS(PARSE_TIMESTAMP('%Y%m%d', @DS_START_DATE))
AND creation_date < UNIX_MICROS(PARSE_TIMESTAMP('%Y%m%d', @DS_END_DATE))

Exemplo de parâmetro de e-mail

SELECT * FROM Sales WHERE sales-rep-email = @DS_USER_EMAIL;