Relatórios e métricas por plataforma

Esta página descreve o que um relatório expõe e como descobrir, na própria interface, quais métricas a sua conta oferece, já que o conjunto de relatórios e métricas é servido por conta, em tempo de execução, e não por um catálogo fixo.

Como um relatório é descrito

Um relatório é definido no servidor e chega ao dashboard com seus próprios metadados: descrição, parâmetros, colunas e métricas derivadas. O frontend não define métricas e não consegue acrescentar uma coluna que o relatório não serve, mas mantém nomes de exibição próprios em pt-BR para elas (veja Rótulos na tela).

Papel de cada coluna

Toda coluna de um relatório carrega exatamente um papel.

count_distinct se aplica a uma coluna BIGINT[] (uma lista de ids por linha): o resultado é o número de ids distintos na união das linhas que o widget cobre, então um período, uma semana ou um canal recebe a contagem distinta real, e não uma soma de contagens diárias. Essa contagem não pode ser somada de novo entre linhas. Exemplo entregue: o relatório dash.tgsr.distinct-users, métrica users (ids de visitante do cookie primário; cada navegador conta como um usuário, então uma pessoa em dois dispositivos conta duas vezes). O KPI "Usuários" do template Site (TagServer) lê essa métrica.

Tipos de coluna

O tipo servido de uma coluna é um de seis tokens escalares, servidos em maiúsculas: DATE, VARCHAR, INTEGER, BIGINT, DOUBLE, BOOLEAN.

Existe também a forma de contêiner JSON[T], onde T é um desses escalares (por exemplo JSON[DOUBLE]). Uma coluna JSON[T] é um mapa: nunca é selecionada nem agregada inteira. Você a endereça uma chave por vez como coluna[chave], o que extrai um T; a agregação da coluna então se aplica ao valor extraído. JSON puro não é um tipo, e aninhamento (JSON[JSON[...]]) é rejeitado.

Existe ainda a forma de lista BIGINT[]: uma lista de ids por linha, operando de count_distinct (veja Papel de cada coluna).

Formato de exibição

O formato não é propriedade da métrica. Você escolhe um por métrica, entre exatamente três tokens, com um ajuste opcional de casas decimais (decimals) e, onde disponível, a opção de abreviar (compact). Toda a formatação é pt-BR.

O botão "mil" abrevia grandezas em pt-BR (744,5 mil, 1,2 mi). A dica dele é "Abreviar grandezas (R$ 744,5 mil)" quando desligado e "Mostrar o valor cheio" quando ligado. Sem decimals, mostra no máximo uma casa decimal. Não está disponível para percentage.

Onde fica o controle:

Onde encontrar os relatórios e as métricas

Não existe seletor de relatório à parte. Cada widget trabalha sobre um único relatório, e esse relatório é inferido da primeira coluna que você escolhe.

• O seletor de colunas é um popover em cascata: plataforma, depois relatório, depois métrica. Cada nível tem sua busca ("Buscar plataforma…", "Buscar relatório…", "Buscar métrica…").
• A busca ignora acentos e entende sinônimos em pt-BR e em inglês: "custo" encontra spend, "revenue" encontra purchase_value.
• Enquanto nenhum relatório está travado, o seletor oferece as colunas de todos os relatórios. Assim que a primeira coluna entra, só as colunas daquele relatório continuam disponíveis, e a dica na tela passa a ser "Mostrando colunas de um relatório. Remova as colunas para trocar de relatório." No gráfico, a segunda frase é "Remova as séries".
• Ao salvar, o drawer adota a fonte do pool que serve o relatório inferido.
• As métricas que um relatório oferece são as suas medidas base (papel metric) seguidas das métricas derivadas que ele declara.
• No editor de expressão, digitar (ou Ctrl+Space) abre o autocompletar sobre as referências disponíveis no widget, cada linha mostrando a descrição ao lado. É o caminho mais direto para ver o que um relatório realmente oferece.

Plataformas e seus relatórios

Há quatro plataformas suportadas:

No Site (TagServer), a fonte é o hostname de um servidor (site) TagServer registrado na sua conta, não uma conexão OAuth com uma ferramenta externa.

Os relatórios de uma plataforma são calculados, não fixos: são todos os relatórios servidos cujo id começa pelo prefixo da plataforma. O conjunto varia com o backend e com a conta.

Parâmetros de um relatório:

• a conta (account_id), que vem da autenticação de quem chama e não é fornecida por você;
• o parâmetro de entidade da plataforma (a coluna "Parâmetro da fonte" acima);
• o intervalo de datas, nos relatórios datados. Todos os relatórios datados entregues hoje usam start_date/end_date. Os relatórios de consulta de conta (*/accounts) e facebook/custom-conversions não recebem intervalo de datas.

Rótulos na tela

Rótulo de uma métrica, na ordem em que é resolvido:

1. o dicionário pt-BR do frontend para o nome da coluna;
2. a descrição servida para a coluna naquele relatório (sem o ponto final);
3. o nome curto humanizado (underscores e hífens viram espaços, primeira letra maiúscula).

Um nome em inglês só aparece para uma coluna que o dicionário não cobre e cuja descrição servida está em inglês. Os valores do vocabulário padrão de rastreamento (nomes de eventos e parâmetros padrão, como page_view, que aparece como "Visualização de página") também aparecem em pt-BR; um evento personalizado aparece com o nome que você deu a ele.

Rótulo de um relatório: a entrada do dicionário pt-BR para o último segmento do id; sem entrada, a humanização mecânica (último segmento após o ponto, hífens viram espaços, primeira letra maiúscula).

Os segmentos de plataforma também são traduzidos: googleads vira "Google Ads", facebook vira "Meta Ads", ga4 vira "Google Analytics" e tgsr vira "Site (TagServer)".

O rótulo do relatório aparece no nível de relatório do seletor de colunas e, em listas planas de colunas, como sufixo de desambiguação quando nomes colidem: coluna · Nome do relatório.

Métricas derivadas do relatório

Um relatório pode declarar derived_metrics: um nome mapeado para uma fórmula aritmética sobre as medidas base do próprio relatório. As razões vivem aqui como fórmulas e nunca são armazenadas como colunas; o dashboard as calcula depois da agregação.

O campo é opcional; 21 das 45 definições de relatório entregues declaram métricas derivadas, incluindo os relatórios de performance sobre os quais um dashboard costuma ser montado. Na interface de autoria, essas métricas aparecem ao lado das medidas base.

Métricas por expressão

Além das métricas que o relatório entrega, você pode escrever a sua própria expressão direto no formulário do widget, num editor de código com autocompletar sobre as referências disponíveis.

• Na tabela e no gráfico: seção recolhível "Coluna calculada", com o botão "Adicionar coluna calculada" (os mesmos textos nos dois formulários). O placeholder do editor é facebook.ad_performance.spend / facebook.ad_performance.leads.
• No Summary: o campo "Métrica" é o seletor de colunas em cascata (placeholder "Escolher métrica"; sem opções, "Nenhuma métrica disponível"). O editor fica abaixo, na seção recolhível "Métrica calculada", que já abre expandida quando a métrica salva é uma expressão; o placeholder é googleads.campaign_performance.cost. Um botão de play roda a métrica sobre o período ativo como prévia: fica ao lado do seletor com a seção fechada e dentro do editor com ela aberta.

O editor aceita estes operandos:

Operadores (no formato SQL; palavras-chave não diferenciam maiúsculas de minúsculas):

Parênteses agrupam. A gramática aceita o sufixo @retro; a sintaxe completa está em Linguagem de expressões.

A expressão é salva na configuração do widget como uma entrada de metrics cujo ref é o próprio texto da expressão. O nome da coluna de saída (as) é gerado pelo formulário: o último segmento após o ponto quando a expressão é uma única referência simples, senão expr_ seguido de 8 caracteres hexadecimais; um nome já usado recebe o sufixo _2, _3 e assim por diante. Formato e casas decimais dessa coluna são escolhidos no mesmo lugar que os das outras métricas (veja Formato de exibição).

ROAS não é uma coluna armazenada; é uma fórmula que você escreve. No Meta, purchase_value / spend, ou, na forma qualificada, facebook.ad_performance.purchase_value / facebook.ad_performance.spend. No Google Ads, conversions_value / (cost_micros / 1e6).

Veja também

• Tipos de widgets: os widgets que consomem essas métricas.
• Filtros e datas: as dimensões que você pode filtrar.
• Linguagem de expressões: a referência completa das expressões.