Dashboards — referência do contrato

Esta página é a referência compacta da especificação de dashboards e das operações expostas pelo produto. Use-a quando precisar conferir nomes de campos, valores aceitos, padrões, limites ou códigos de erro.

Os guias de painéis [blocked] e de períodos e filtros [blocked] explicam como interpretar cada escolha.

Objeto de dashboard

O plano compilado não faz parte do objeto público do dashboard.

Especificação do dashboard

{  "version": 1,  "panels": []}

Somente version e panels são aceitos nesse nível. O contrato da API não define mínimo nem máximo de painéis, embora o editor exija pelo menos um para salvar.

Especificação completa de um painel

{  "version": 1,  "panel_id": "00000000-0000-4000-8000-000000000001",  "event_name": "pix_recebido",  "event_version": 1,  "time": {    "kind": "relative",    "amount": 7,    "unit": "day"  },  "max_buckets": 30,  "metric": {    "op": "sum",    "field": {      "source": "properties",      "path": "amount"    }  },  "group_by": [    { "kind": "time" },    {      "kind": "property",      "field": {        "source": "properties",        "path": "origin"      }    }  ],  "filters": [    {      "field": {        "source": "properties",        "path": "currency"      },      "op": "EQ",      "value": "BRL"    }  ],  "viz": "line",  "sort": {    "by": "time",    "direction": "asc"  },  "limit": 100,  "metadata": {    "x": 0,    "y": 0,    "w": 12,    "h": 4,    "value_format": "currency_brl"  }}

O exemplo usa campos já apresentados no guia público de eventos. A configuração só será válida em um app se a combinação pix_recebido versão 1 e esses campos existirem no catálogo desse app.

Campos do painel

Campos adicionais não são aceitos, exceto dentro de metadata.

Referência de campo

{  "source": "properties",  "path": "amount"}

source aceita properties ou context. path aceita de 1 a 64 letras, números ou _. O campo precisa existir no catálogo para o nome e a versão do evento selecionado.

Períodos

Relativo:

{  "kind": "relative",  "amount": 15,  "unit": "minute"}

amount é inteiro positivo. unit aceita minute, hour, day ou week.

Absoluto:

{  "kind": "absolute",  "from": "2026-09-01T00:00:00.000-03:00",  "to": "2026-09-02T00:00:00.000-03:00"}

from e to precisam ser datas e horas ISO 8601 válidas. from deve ser anterior a to.

Métrica

{ "op": "count" }

ou:

{  "op": "avg",  "field": {    "source": "properties",    "path": "amount"  }}

Operações: count, sum, avg, min, max, uniq, p50, p90, p95.

count proíbe field. Todas as outras operações exigem field. Operações numéricas exigem um campo numérico. uniq proíbe JSON.

Dimensões

Tempo:

{ "kind": "time" }

Propriedade:

{  "kind": "property",  "field": {    "source": "context",    "path": "device_type"  }}

Uma dimensão de propriedade precisa estar marcada como agrupável no catálogo. A mesma dimensão não pode ser repetida.

Filtro

Com valor:

{  "field": {    "source": "properties",    "path": "amount"  },  "op": "GTE",  "value": 100}

Sem valor:

{  "field": {    "source": "context",    "path": "device_type"  },  "op": "EXISTS"}

Operadores: EQ, NEQ, IN, NIN, EXISTS, NOT_EXISTS, GT, GTE, LT, LTE, CONTAINS.

EXISTS e NOT_EXISTS proíbem value. Todos os outros exigem value. IN e NIN exigem uma lista homogênea, não vazia, com até 100 itens. Os demais exigem texto, número ou booleano escalar.

Ordenação

{  "by": "value",  "direction": "desc"}

by aceita time, dimension ou value. time exige dimensão temporal; dimension exige dimensão de propriedade. direction aceita asc ou desc.

Metadados de apresentação

metadata aceita outras chaves para evolução da apresentação. Essas chaves são persistidas, mas não alteram o plano analítico. O contrato central valida x, y, w e h; value_format desconhecido volta a automatic na interface.

Operações disponíveis

Todas as operações trabalham no app atual e exigem a capacidade correspondente.

A base pública da API é /v1/dashboard. Atualizar, publicar e arquivar exigem a versão esperada no cabeçalho If-Match-Version.

Paginação e busca

As listas usam cursor opaco de até 2.048 caracteres e retornam next_cursor e total.

Requisição de consulta

Painel ad hoc:

{  "panel": {},  "timezone": "America/Sao_Paulo",  "time_override": {    "kind": "relative",    "amount": 7,    "unit": "day"  }}

Painel ou dashboard salvo:

{  "timezone": "America/Sao_Paulo",  "time_override": {    "kind": "relative",    "amount": 7,    "unit": "day"  }}

timezone é obrigatório e aceita um nome IANA de até 100 caracteres. time_override é opcional.

Resultado de painel

Cada row exige value numérico. bucket é uma string opcional e dimension é uma string ou null opcional.

effective_granularity_seconds é null e bucket_count é 0 sem dimensão de tempo. data_quality é null para métricas não numéricas.

Na consulta conjunta, a resposta possui panels. Cada item contém panel_id, outcome: "ok" e result, ou outcome: "error" e error.code.

Códigos de erro de operação

Códigos de validação da especificação

Erros de validação trazem code, path, message e, quando aplicável, reason. path aponta para o campo inválido; dentro do dashboard, começa com panels e o índice do painel.

Em field_not_groupable, reason pode ser high_cardinality, distinct_value_limit, unsupported_json ou unsupported_path.

Assuntos relacionados

• Dashboards — fundamentos, criação e ciclo de vida [blocked]
• Painéis, métricas, dimensões e visualizações [blocked]
• Períodos, filtros, ordenação e resultados [blocked]