Criar Gráfico do Amplitude
Crie gráficos a partir de linguagem natural, descobrindo eventos, construindo definições de gráfico e verificando resultados.
Planejamento Primeiro (Crítico)
Antes de qualquer chamada de ferramenta, decomponha a solicitação:
1. Identifique os componentes do gráfico:
- Tipo de gráfico e métrica (o que está sendo medido)
- Intervalo de tempo (padrão: Últimos 30 Dias, se não especificado)
- Evento principal (a ação sendo contada)
- Condições de segmento (filtros/grupos de usuários)
- Filtros, agrupamentos, divisões
- Etapas do funil (se for análise de conversão)
2. Planeje as pesquisas de eventos:
- UMA pesquisa por conceito de evento distinto
- Nunca combine múltiplos conceitos em uma única pesquisa
- Exemplo: "compra" e "cadastro" precisam de pesquisas separadas
3. Planeje chamadas de ferramenta paralelas:
- Obter contexto, pesquisar eventos, encontrar coortes podem ser executados juntos
- Aguarde os resultados antes de construir a definição
Descoberta de Eventos (Crítico: Descoberta Primeiro)
IMPORTANTE: Lance uma rede ampla antes de restringir
Quando a solicitação do usuário for ambígua ou puder mapear para múltiplos eventos:
- Pesquise AMPLAMENTE primeiro para descobrir opções relevantes
- Revise os resultados relevantes - procure por eventos relacionados, eventos personalizados, meta-eventos
- Apresente opções ao usuário OU explique sua lógica de seleção
- Tente não assumir que um único evento é a única resposta sem exploração
Pesquise por eventos:
Amplitude:search com entity_types=['EVENT', 'CUSTOM_EVENT']
- Pesquise UM conceito por vez
- Use termos de pesquisa amplos primeiro (ex.: "IA" não apenas "chat IA")
- ✓ Bom: "usuário conclui compra"
- ✗ Ruim: "eventos de cadastro ou compra"
Tome decisões informadas e explique:
- Pesquise amplamente para descobrir todas as opções
- Revise os resultados e identifique a abordagem mais abrangente/precisa
- Faça seu melhor julgamento (prefira eventos personalizados agregados a eventos únicos)
- Sempre explique: "Encontrei as opções X, Y, Z. Escolhi [X] porque [motivo]. Isso inclui/exclui [escopo]."
- O usuário pode corrigir se sua suposição estiver errada
Critérios de decisão:
- Prefira eventos personalizados que agreguem atividades relacionadas (ex.: "[2026] Métrica de Ativação [apenas eventos de IA]")
- Se não existir evento agregado, escolha o evento de interação principal
- Considere o que "usuário ativo" tipicamente significa para aquela área do produto
- Por padrão, use escopo mais amplo, a menos que o usuário especifique um foco restrito
Exemplos:
- ❌ RUIM: Usuário pergunta "usuários semanais de IA" → escolher imediatamente "ia-chat: enviar mensagem" sem explorar, sem explicação
- ✅ BOM: Usuário pergunta "usuários semanais de IA" → pesquisar "IA", encontrar Ask AI, Agents, Visibility, evento personalizado agregado. Responder: "Encontrei atividade de IA em Ask AI, Agents e Visibility. Estou usando o evento personalizado '[2026] Métrica de Ativação [apenas eventos de IA]' que inclui todas as interações de produtos de IA. Isso fornece o total de usuários de IA em todos os recursos. Avise-me se quiser focar em um produto de IA específico."
Verifique antes de usar:
- Obtenha gráficos existentes que usam o evento via pesquisa
- Verifique se o evento tem volume real (não zero/desatualizado)
- Procure por eventos personalizados que agreguem atividades relacionadas
- Se resultados zero, pesquise alternativas
Obtenha propriedades:
Amplitude:get_event_properties para nomes/valores exatos de propriedades
Encontre coortes:
Amplitude:search com entity_types=['COHORT']
Amplitude:get_cohorts para obter definições completas
Seleção do Tipo de Gráfico
| Tipo de Gráfico | Use Quando |
|---|---|
eventsSegmentation | Contar eventos/usuários ao longo do tempo, tendências, comparações, KPIs, distribuições, análise de propriedades |
funnels | Análise de conversão em múltiplas etapas com uma sequência conhecida, análise de abandono, tempo entre eventos específicos, métricas de tempo para conversão |
retention | Comportamento de retorno de usuários, curvas de retenção de coorte, análise de churn |
dataTableV2 | Comparações tabulares, rankings, divisões multidimensionais |
customerJourney | Exploração de caminhos, descoberta de caminhos desconhecidos que os usuários percorrem, comparação de caminhos convertidos vs. abandonados |
sessions | Duração da sessão, frequência da sessão, tempo gasto por usuário, distribuições de duração da sessão |
Referência Rápida
eventsSegmentation - O mais versátil. Use para:
- Contagens de usuários (DAU, WAU, MAU) com métrica
uniques - Totais de eventos, médias, somas de propriedades
- Percentis, distribuições, fórmulas
- Séries temporais com janelas móveis
Escopo de Agregação (eventsSegmentation):
PROPSUM(A)/metric: "sums"= Soma global em TODOS os eventosmetric: "frequency"= Distribuição de contagens de eventos por usuário (quantos usuários fizeram 1x, 2x, 3x)- Para "distribuição da soma de propriedade por usuário": o Amplitude não oferece suporte direto a isso. Use
metric: "frequency"para distribuições de contagem de eventos, ou use dataTableV2 agrupado por user_id com PROPSUM e exporte para análise externa.
funnels - Análise de conversão com etapas predefinidas. Use para:
- Taxas de conversão passo a passo quando você conhece a sequência esperada
- Sequências ordenadas ou não ordenadas
- Tempo para conversão (tempo mediano entre eventos)
- Eventos de exclusão, janelas de conversão
- Eventos sobrepostos: Para encontrar usuários que realizaram múltiplos eventos (em qualquer ordem), use um funil com "qualquer ordem" e defina a janela de conversão para corresponder ao intervalo de datas do gráfico
- Nota: Se você deseja descobrir quais caminhos os usuários percorrem, use
customerJourney
retention - Comportamento de retorno. Use para:
- Curvas de retenção de N dias ou retenção contínua
- Análise de coorte (novos vs. usuários recorrentes)
- Padrões de Evento inicial → Evento de retorno
dataTableV2 - Dados tabulares. Use para:
- Divisões por dimensões (país, plataforma, etc.)
- Comparações de múltiplas métricas em formato de tabela
customerJourney - Exploração e descoberta de caminhos. Use para:
- Entender os caminhos reais que os usuários percorrem (vs. caminhos esperados em funis)
- Analisar caminhos começando com, terminando com ou entre dois eventos específicos
- Comparar caminhos de usuários convertidos vs. abandonados lado a lado
- Descobrir padrões de navegação inesperados ou pontos de atrito
- Explorar frequência de caminhos, similaridade ou tempo médio para conclusão
- Preencher a lacuna entre as jornadas ideais do cliente e o comportamento real do usuário
sessions - Métricas de engajamento baseadas em sessão. Use para:
- Análise de duração da sessão (duração média, tempo gasto, distribuições)
- Frequência da sessão (média de sessões por usuário, total de sessões)
- Tempo gasto por usuário ao longo do tempo
- Eventos realizados dentro das sessões (média de eventos por sessão)
- Comparar comportamento de sessão entre segmentos de usuários
Métricas especiais:
- Contagens de usuários:
metric: "uniques" - Contagens de eventos:
metric: "totals" - Somas de propriedades:
metric: "sums"com propriedade emgroup_by - Taxas/percentuais: Use ao comparar grupos de tamanhos diferentes
Meta-eventos:
_active: Qualquer evento ativo (DAU, MAU)_new: Novos usuários (evento de primeira vez)_any_revenue_event: Eventos de receita
Estrutura da Definição do Gráfico
Parâmetros principais (todos os tipos de gráfico):
{
"name": "Título Descritivo do Gráfico",
"projectId": "12345",
"definition": {
"app": "12345",
"type": "eventsSegmentation",
"params": {
"range": "Últimos 30 Dias",
"events": [{
"event_type": "Compra Concluída",
"filters": [],
"group_by": []
}],
"metric": "uniques",
"countGroup": "Usuário",
"interval": 1,
"segments": [{"conditions": []}]
}
}
}
Parâmetros principais:
countGroup: "Usuário" (usuários únicos) ou "Evento" (ocorrências de evento)interval: 1 (diário), 7 (semanal), 30 (mensal)segments: Filtros/grupos de usuários (array vazio = todos os usuários)
Filtros de evento (lógica OU inline):
"filters": [{
"group_type": "Usuário",
"subprop_key": "país",
"subprop_op": "é",
"subprop_type": "evento",
"subprop_value": ["Estados Unidos", "Canadá"]
}]
Segmentos de usuário (lógica E de condições):
"segments": [{
"name": "Usuários Ativos",
"conditions": [{
"type": "propriedade",
"group_type": "Usuário",
"prop_type": "usuário",
"prop": "plano",
"op": "é",
"values": ["Pro", "Enterprise"]
}]
}]
Segmentos de coorte: Pesquise pela coorte, obtenha o ID, depois:
"segments": [{
"name": "Minha Coorte",
"conditions": [{
"type": "coorte",
"group_type": "Usuário",
"cohort_id": "abc123",
"op": "está_em"
}]
}]
Fluxo de Trabalho: Criar Gráfico
- Obtenha contexto:
Amplitude:get_context (para projectId)
- Descubra eventos (pesquisa AMPLA primeiro):
Amplitude:search para cada conceito distinto
- Use termos de pesquisa amplos inicialmente
- Procure por todos os eventos relacionados, eventos personalizados, coortes
- Revise TODOS os resultados antes de selecionar
- Avalie e decida:
- Revise todos os eventos e eventos personalizados descobertos
- Tome uma decisão informada (prefira eventos agregados)
- Prepare uma explicação clara do que você encontrou e sua escolha
- Encontre gráficos semelhantes (veja exemplos):
Amplitude:search entity_types=['CHART'] consulta="conceito similar"
Amplitude:get_charts para ver a estrutura da definição
- Obtenha propriedades, se necessário:
Amplitude:get_event_properties
- Construa a definição usando nomes descobertos
- Explique a lógica de seleção do evento na resposta
- Crie o gráfico:
Amplitude:query_dataset com definição completa
-
Verifique os resultados - confirme se os dados fazem sentido
-
Salve o gráfico:
Amplitude:save_chart_edits com editId de query_dataset
Tratamento de Erros
Se query_dataset falhar:
- Leia a mensagem de erro cuidadosamente
- Problemas comuns: nomes de eventos incorretos, filtros inválidos, tipos de parâmetros errados
- Corrija a definição e tente novamente
- Verifique se os eventos existem via pesquisa primeiro
Se resultados zero:
- Verifique se os filtros não são muito restritivos
- Verifique se o evento tem dados (pesquise por gráficos que o usam)
- Tente um intervalo de tempo mais amplo
- Verifique as condições do segmento
Melhores Práticas
Nomenclatura:
- Inclua métrica + contexto de tempo: "Usuários Ativos Semanais Últimos 90 Dias"
- Não: "WAU" ou "Usuários"
Intervalos de tempo:
- Padrão para "Últimos 30 Dias"
- Use intervalos inclusivos para períodos específicos
- Declare explicitamente o intervalo interpretado
Verificação:
- Sempre verifique se o evento existe antes de usar
- Consulte gráficos semelhantes para entender o uso do evento
- Confirme propriedades com get_event_properties
Comparações:
- Use segmentos para comparar grupos de usuários no mesmo gráfico
- Use taxas/percentuais para grupos de tamanhos diferentes
Sempre inclua:
- URL do gráfico na resposta
- O que o gráfico mostra
- Principais insights dos dados iniciais
- Metodologia utilizada