Dashboards — períodos, filtros, ordenação e resultados

Período, filtros, dimensões, ordenação e limite determinam quais eventos participam da consulta e quais grupos chegam ao painel. Este guia detalha essas regras e mostra como interpretar a resposta.

O período seleciona ocorrências

Cada painel possui um período em sua especificação. Uma consulta também pode enviar um período temporário, chamado time_override, que substitui o período salvo sem alterar o dashboard.

O visualizador usa esse override para aplicar um único período a todos os painéis. As opções rápidas atuais são 15 minutos, 1 hora, 6 horas, 24 horas, 7 dias e 30 dias. Também é possível escolher início e fim absolutos.

O intervalo pode ter no máximo 31 dias exatos. O início precisa ser anterior ao fim.

Período relativo

Um período relativo combina uma quantidade inteira positiva com uma unidade:

• minute;
• hour;
• day;
• week.

A janela termina no limite compartilhado de cinco minutos mais recente. Isso estabiliza consultas iguais e pode fazer o instante final ficar alguns minutos atrás do relógio atual.

Período absoluto

Um período absoluto informa from e to como data e hora completas com offset. A engine normaliza os instantes e considera:

• início inclusivo: timestamp >= from;
• fim exclusivo: timestamp < to.

Esse formato evita contar duas vezes um evento ao colocar janelas consecutivas lado a lado.

Fuso horário

A consulta exige um nome de fuso IANA, como America/Sao_Paulo ou UTC. Um offset isolado, como -03:00, não é aceito.

O navegador fornece o fuso usado pelo visualizador. O fuso afeta a formação e a exibição dos intervalos de uma série temporal, mas não muda o instante real dos eventos.

A granularidade temporal é automática

Um painel com dimensão de tempo informa max_buckets, o orçamento máximo de intervalos. A engine escolhe o menor intervalo, em segundos, que mantém a janela dentro desse orçamento:

intervalo em segundos = teto(duração da janela / max_buckets)

O valor pode ficar entre 1 e 1.500. Ele é obrigatório quando existe dimensão de tempo e proibido quando não existe.

O editor usa 30 intervalos ao ativar a série temporal. A resposta informa:

• effective_granularity_seconds: intervalo realmente usado;
• bucket_count: quantos intervalos distintos apareceram no resultado.

Intervalos sem ocorrências não são preenchidos automaticamente com zero. Por isso, bucket_count pode ser menor que max_buckets.

Todos os filtros são combinados com E

Um painel aceita até 20 filtros. Todos precisam passar na mesma ocorrência do evento. Não existe agrupamento OU ou NÃO entre filtros no contrato atual.

Cada filtro escolhe uma propriedade de properties ou context, um operador e, quando necessário, um valor.

CONTAINS procura o trecho informado e diferencia maiúsculas de minúsculas.

Operadores por tipo de propriedade

O valor precisa ter o tipo do campo. Datas são textos interpretáveis como data e hora. Números precisam ser finitos.

Nos operadores IN e NIN, a lista:

• aceita de 1 a 100 valores;
• precisa conter apenas texto, apenas número ou apenas booleano;
• precisa ser compatível com o tipo da propriedade.

O editor recebe listas como valores separados por vírgula e remove espaços nas extremidades de cada item.

Filtros idênticos — mesma fonte, caminho, operador e valor — não podem ser repetidos.

Campos ausentes e comparações negativas

NOT_EXISTS seleciona explicitamente um campo ausente. Nas outras comparações, um valor ausente não passa.

Isso também vale para NEQ e NIN: “diferente de X” não inclui automaticamente uma ocorrência que não possui o campo. Combine a pergunta com EXISTS quando a presença também for uma exigência explícita.

Ordenação

O painel escolhe uma chave e uma direção:

A direção pode ser asc ou desc. O padrão do contrato é valor decrescente.

Quando tempo e propriedade estão juntos, a ordenação escolhe uma única chave principal. A visualização de linha reorganiza os pontos cronologicamente para desenhar o eixo, mas o limite já foi aplicado pela consulta.

Limite de linhas

limit define quantas linhas agregadas podem voltar. O intervalo permitido é de 1 a 1.000, com padrão 100.

Uma linha representa uma combinação agregada:

• sem dimensões: no máximo uma linha;
• somente tempo: uma linha por intervalo com dados;
• somente propriedade: uma linha por categoria;
• tempo e propriedade: uma linha por combinação de intervalo e categoria.

O limite é aplicado depois da agregação e da ordenação. Ele não limita quantos eventos entram no cálculo. Em painéis com tempo e propriedade, 100 linhas podem representar, por exemplo, apenas parte das combinações existentes.

Estrutura do resultado

Uma consulta bem-sucedida informa:

Cada item de rows possui value e pode possuir:

• bucket, quando há dimensão de tempo;
• dimension, quando há dimensão de propriedade. O valor pode ser null para a categoria sem valor.

Qualidade de dados

Para sum, avg, min, max, p50, p90 e p95, data_quality informa:

• total_rows: ocorrências que passaram pelo evento, período e filtros;
• ignored_rows: ocorrências cujo campo métrico não pôde ser usado como número.

O valor considerado é total_rows - ignored_rows. A qualidade é global para o painel, mesmo quando o resultado possui vários intervalos ou categorias.

Para count e uniq, data_quality é null.

Consulta conjunta e tentativa individual

Ao abrir um dashboard, o visualizador consulta todos os painéis em uma única operação. Cada item retorna ok com seu resultado ou error com um código.

Isso permite mostrar os painéis que funcionaram mesmo quando um painel falhou. A interface oferece uma nova tentativa individual para o painel com erro.

Assuntos relacionados

• Dashboards — fundamentos, criação e ciclo de vida [blocked]
• Painéis, métricas, dimensões e visualizações [blocked]
• Referência do contrato de dashboards [blocked]