Guia de introdução ao SQL no Composer e no servidor MCP da Klaviyo
O que você vai aprender
Aprenda a fazer perguntas de análise sobre seus dados do Klaviyo em linguagem simples usando o Composer ou o servidor Klaviyo Model Context Protocol (MCP). O SQL do Klaviyo Data Platform reúne perfis, públicos, campanhas, produtos e eventos para responder a perguntas que envolvem vários conjuntos de dados. Você não precisa escrever SQL.
No momento, o SQL está em beta e está disponível para todos os clientes.
Antes de começar
Escolha onde você quer fazer suas perguntas:
- Use o Composer para trabalhar no chat dentro do Klaviyo. Não há nenhuma configuração adicional de SQL.
- Use o servidor MCP da Klaviyo para trabalhar em um cliente de IA conectado, como o Claude ou o ChatGPT. Se você já conectou a Klaviyo, não precisa instalar outra ferramenta, embora talvez seja necessário atualizar a lista de ferramentas do cliente.
As duas opções usam os mesmos dados e oferecem suporte aos mesmos tipos de perguntas de análise. O SQL é desenvolvido para análise. Para exportações de dados em massa, use outras ferramentas da Klaviyo, como relatórios personalizados.
Normalmente, os dados ficam cerca de 30 minutos atrás da atividade na sua conta. Para um pedido, envio ou alteração de assinatura bem recente, verifique diretamente no Klaviyo.
Faça sua primeira pergunta de análise
Use o Composer
- Abra o Composer na Klaviyo. Se precisar de ajuda para encontrá-lo, consulte o Guia de introdução do Composer.
- Faça uma pergunta de análise em linguagem simples. Inclua a métrica, o intervalo de datas e quaisquer detalhes de público ou produto. Por exemplo: “Quais são meus 5 principais produtos por unidades vendidas nos últimos 90 dias?”
- Revise a resposta e, em seguida, faça perguntas complementares na mesma conversa para se aprofundar.
O Composer decide quando usar SQL. Você não precisa nomear uma ferramenta nem alterar uma configuração.
Use o servidor MCP do Klaviyo
Para conectar um cliente de IA, você precisa ter a função de Proprietário, Administrador ou Gerente na conta da Klaviyo que você quer usar. Quando a conexão usa uma chave de API, a chave precisa ter acesso aos conjuntos de dados envolvidos na sua pergunta. Por exemplo, uma pergunta sobre pedidos e segmentos precisa de acesso a eventos e segmentos.
- Conecte o Klaviyo usando o guia para o seu cliente ou configuração:
- Documentação para desenvolvedores do servidor MCP da Klaviyo para conexões de terminal e servidor remoto
- FAQ do app da Klaviyo para Claude
- Como usar o app da Klaviyo para ChatGPT
- Guia do servidor MCP da Klaviyo para agências para trabalhar em várias contas de clientes
- Faça uma pergunta detalhada de análise no seu cliente conectado. Você não precisa nomear a ferramenta ask_analytics_question. Seu cliente a seleciona quando apropriado para a pergunta.
- Revise a resposta e continue com perguntas complementares. Se a ferramenta não estiver disponível, atualize a lista de ferramentas do Klaviyo do seu cliente usando as etapas de solução de problemas abaixo.
Se você se conectar via OAuth, siga o guia do seu cliente para revisar e conceder as permissões solicitadas.
Use uma resposta como base e confira o cálculo
O SQL é útil quando uma pergunta precisa de informações de vários conjuntos de dados. Por exemplo, uma contagem de pedidos se torna uma análise de público mais detalhada quando você adiciona clientes, participação em segmento e país.
Comece com uma pergunta e, em seguida, desenvolva a resposta na mesma conversa:
- “Quantos pedidos fizemos no mês passado?”
- “Quantos clientes fizeram esses pedidos?”
- “Divida esses pedidos pelos segmentos aos quais os clientes pertencem no momento.”
- “Divida os resultados por segmento e país e inclua a receita de cada grupo.”
- “Para compradores de primeira viagem, quanto de navegação de produtos aconteceu nos 10 dias antes do primeiro pedido?”
Pergunte como a resposta foi calculada antes de compartilhar um número importante ou usá-lo para tomar uma decisão. Por exemplo:
- “Quais conjuntos de dados você usou?”
- “Qual intervalo de datas e quais filtros você aplicou?”
- “Como você definiu a receita nesse cálculo?”
- “Me explique como você calculou isso.”
Use a explicação para verificar se a resposta corresponde à pergunta que você pretendia fazer. Se não corresponder, esclareça a métrica, as datas ou os filtros e pergunte novamente.
Sobre quais dados você pode perguntar
O SQL pode responder a perguntas sobre esses conjuntos de dados, sujeito às permissões na sua conexão.
Conjunto de dados | O que você pode analisar |
|---|---|
Perfis | Atributos do cliente, identificadores, valor da vida útil previsto, engajamento de canal, Propriedades do perfil personalizadas e consentimento para marketing por e-mail e SMS |
Segmentos | Públicos dinâmicos com a associação recalculada com base em condições salvas; a análise usa a associação atual |
Listas | Públicos cuja associação atual você pode conectar a perfis e eventos |
Campanhas | Envios únicos, mensagens, variantes incluindo testes A/B e segmentos de envio |
Catálogo | Produtos sincronizados da sua plataforma de e-commerce, incluindo categorias e variantes de produtos |
Eventos | Atividade de comércio, mensagens, consentimento, fluxo, avaliações, cupom, suporte, Klaviyo Customer Hub e integrações, além de contagens e taxas de marketing |
Eventos e detalhes dentro dos eventos
Os dados de eventos disponíveis incluem:
- Atividade de comércio, como adicionar ao carrinho, fazer ou cancelar um pedido, reembolsos e visualizações de produtos
- Atividade de e-mail, incluindo recebimentos, aberturas, cliques, devoluções, descartes e cancelamentos de inscrição
- Atividade de SMS e WhatsApp, incluindo recebimentos, cliques, falhas, consentimento e cancelamentos de inscrição
- Atividade de push, incluindo recebimentos, aberturas e rejeições
- Alterações de consentimento e supressão, incluindo inscrições, cancelamentos de inscrição, adições ou remoções de supressão e atualizações de preferências
- Atividade do fluxo, incluindo entradas, remoções, atendimento, pulos e inícios
- Mesclagens de perfis
- Envios, edições, exclusões e prontidão para revisar avaliações e classificações
- Atribuições e usos de cupom
- Atividade de conversas de suporte, incluindo inícios, mensagens recebidas ou enviadas, escalonamentos, resoluções e criação ou fechamento de tickets
- Atividade do Klaviyo Customer Hub, como logins, favoritos, cliques em produtos ou cupons e visualizações de blocos de conteúdo
- Eventos de integrações de fontes como sua API, Shopify e Lightspeed, incluindo atividades de checkout, envios de formulários, inscrições no programa de fidelidade, pesquisas e entregas
- Métricas de marketing, incluindo contagens e taxas de entrega, destinatário, abertura, clique, rejeição, cancelamento de inscrição, denúncia de spam e engajamento humano
Alguns eventos contêm valores aninhados: grupos de detalhes relacionados dentro de um evento. Por exemplo, um pedido pode conter uma lista de itens, cada um com um SKU, uma quantidade e um preço. O SQL pode ler esses detalhes, então você pode perguntar quantos pedidos incluíram um SKU específico ou qual foi o número médio de itens por pedido.
Combine conjuntos de dados
O SQL pode conectar conjuntos de dados relacionados para responder a uma pergunta. Isso se chama join, mas você não precisa solicitar um join explicitamente. Por exemplo, você pode:
- Conecte mensagens de campanha aos nomes de campanha e aos dados de engajamento para comparar campanhas nomeadas.
- Conecte a associação atual a lista ou segmento a perfis e pedidos para analisar a atividade de compra de um público.
- Divida um público por país, status de consentimento ou valor previsto do cliente.
- Conecte produtos a categorias ou variantes a produtos principais para analisar o desempenho do produto ou da categoria.
- Conecte atribuições de cupom aos usos de cupom para calcular o resgate e identificar cupons não resgatados.
Perguntas de exemplo
Adapte as datas, os produtos, os segmentos e os detalhes da campanha à sua conta.
Objetivo | Pergunta de exemplo |
|---|---|
Compare pedidos ao longo do tempo | “Quantos pedidos recebemos no 2º trimestre de 2025, no 1º trimestre de 2026 e no 2º trimestre de 2026?” |
Analisar detalhes do pedido | “Quantos pedidos nos últimos 90 dias incluíram o SKU FACEBUND01?” |
Resuma a receita e os reembolsos | “Resuma os pedidos de junho: total de pedidos, receita total, número de pedidos reembolsados e valor total dos reembolsos.” |
Entenda as compras repetidas | “Que porcentagem de clientes fez apenas 1 pedido?” |
Meça o tempo entre compras | “Qual é o número médio de dias entre a primeira e a segunda compra de um cliente?” |
Compare o valor do cliente | “Compare o valor da vida útil de clientes com interações por e-mail com o de clientes que não interagem.” |
Encontrar principais produtos | “Quais são meus 5 principais produtos por unidades vendidas nos últimos 90 dias?” |
Compare o engajamento da campanha | “Qual dia da semana tem as melhores taxas de abertura de campanha?” |
Explore o desempenho de e-mail | “Quais foram meus 10 e-mails mais abertos, excluindo campanhas de promoção?” |
Analisar dispositivos | “Qual é a divisão de dispositivos entre dispositivos móveis e desktop para as aberturas dos meus e-mails?” |
Revisar atividade do fluxo | “Quais fluxos enviaram mensagens no último ano?” |
Comparar desempenho de SMS | “Qual foi minha taxa de cliques (CR) e minha taxa de cancelamento de inscrição para SMS em abril, maio e junho?” |
Investigue devoluções | “Minha newsletter de 2 de julho teve 5.514 rejeições. Elas vieram de 1 provedor de e-mail?” Quais foram os tipos de rejeição?” |
Verificar frequência de envio | “Quantos perfis receberam 2 ou mais e-mails em 1 dia?” |
Entenda os limites
Dados indisponíveis
No momento, o SQL não oferece suporte a:
- Associação a lista ou segmento em um momento anterior
- Formulário de registro ou o desempenho dele
- Objetos personalizados
- Modelos de e-mail ou SMS
Eventos de integrações podem incluir envios de formulários, mas isso não significa que o SQL ofereça suporte à análise de formulário de registro ou do desempenho dele. Se a sua pergunta depender de dados indisponíveis, a resposta pode ficar incompleta ou o cliente pode não conseguir responder.
Atualização dos dados e diferenças em relação aos relatórios do Klaviyo
Os dados normalmente ficam cerca de 30 minutos atrás da sua conta. Atividades recentes talvez não apareçam imediatamente.
Em geral, os números devem ser consistentes com os da Klaviyo, mas podem ocorrer pequenas diferenças por causa de diferenças nas definições, otimizações de consulta ou atualização dos dados. O SQL usa uma fonte de dados diferente de outras formas de acessar os dados da Klaviyo. A Klaviyo verificou que esses dados foram 99% consistentes nos últimos 3 anos.
Pergunte sobre o cálculo, o intervalo de datas e os filtros quando um número for diferente do relatório. A explicação pode ajudar você a identificar se está comparando a mesma métrica e o mesmo período.
Consultas geradas e tempos limite
O SQL gera uma consulta a partir da sua pergunta. No momento, não existe um ponto de extremidade onde você possa enviar sua própria consulta SQL e receber um resultado garantido e repetível. Formulações diferentes podem gerar consultas diferentes e resultados ligeiramente diferentes. Verifique o cálculo para números importantes.
Um cliente MCP pode parar de esperar por uma resposta mais cedo do que o Composer. Claude, por exemplo, tem uma janela de tempo limite de 60 segundos. Se uma pergunta expirar, restrinja o intervalo de datas, reduza o número de detalhamentos ou divida a análise em perguntas menores.
Solução de problemas
A ferramenta de análises não está disponível
Se você não vir ask_analytics_question no seu cliente de IA, confirme se o SQL está ativado para a sua conta e atualize a lista de ferramentas do Klaviyo do cliente.
No Claude:
- Acesse Personalizar > Conectores > Klaviyo.
- Abra o menu de três pontos no canto superior direito.
- Clique em Atualizar lista de ferramentas e tente fazer sua pergunta novamente.
O SQL não consegue retornar dados que você sabe que estão na sua conta
Verifique se o conjunto de dados é compatível e considere o atraso típico de 30 minutos. Se a sua conexão usa uma chave de API, verifique se ela tem acesso a todos os conjuntos de dados envolvidos, como perfis, segmentos, listas, campanhas, catálogos ou eventos. Atualize as permissões ausentes no Klaviyo, atualize a lista de ferramentas do Klaviyo do cliente e tente a pergunta novamente.
Para uma conexão OAuth, revise as permissões usando o guia de conexão do cliente.
Uma pergunta atingiu o tempo limite
Experimente um intervalo de datas mais curto ou menos detalhamentos, ou divida a pergunta em perguntas menores. Tente novamente com a pergunta mais específica e, em seguida, avance com perguntas de acompanhamento.
Um número não corresponde ao da Klaviyo
Pergunte como o SQL calculou o número, incluindo os conjuntos de dados, o intervalo de datas e os filtros. Verifique se as definições de métricas e a atualização dos dados explicam a diferença. Se a diferença for grande, entre em contato com o suporte da Klaviyo e compartilhe a pergunta, o número retornado e o número que você esperava.
O Composer recusa uma pergunta
Reformule a pergunta com uma métrica específica, um intervalo de datas e um público. Verifique se ela usa um dos conjuntos de dados compatíveis e tente novamente.