ComposerとKlaviyo MCPサーバーでSQLを始めるスタートガイド

このページで学べること

ComposerまたはKlaviyo Model Context Protocol（MCP）サーバーを使用して、Klaviyoデータに関する分析の質問を平易な言葉で行う方法をご確認ください。KlaviyoデータプラットフォームSQLは、プロファイル、オーディエンス、キャンペーン、商品、イベントを統合し、複数のデータセットにまたがる質問に回答します。SQLを書く必要はありません。

SQLは現在ベータ版で、すべての顧客が利用できます。

始める前に

質問をどこで行うかを選択してください：

• Composerを使用して、Klaviyo内のチャットで作業します。追加のSQL設定は必要ありません。
• KlaviyoのMCPサーバーを使用して、ClaudeやChatGPTなどの接続されたAIクライアントで作業できます。すでにKlaviyoを接続している場合、別のツールをインストールする必要はありません。ただし、クライアントのツールリストを更新する必要がある場合があります。

どちらのオプションも同じデータを使用し、同じ種類の分析に関する質問に対応しています。SQLは分析向けに設計されています。一括データのエクスポートには、カスタムレポートなど、他のKlaviyoツールを使用してください。

データは通常、アカウント内のアクティビティより約30分遅れて反映されます。ごく最近の注文、送信、またはメンバーシップの変更については、Klaviyoで直接確認してください。

最初の分析に関する質問をしてみましょう

Composerを使用してください

1. KlaviyoでComposerを開きます。見つからない場合は、Composerのスタートガイドをご覧ください。
2. 平易な言葉で分析に関する質問をしてください。メトリック、日付範囲、およびオーディエンスや商品の詳細を含めてください。例：「過去90日間で、販売数量別の上位5商品は何ですか？」
3. 回答を確認したうえで、同じ会話内でフォローアップの質問をして、さらに深掘りしてください。

ComposerがSQLを使用するタイミングを決定します。ツールに名前を付けたり、設定を変更したりする必要はありません。

Klaviyo MCPサーバーを使用してください

AIクライアントを接続するには、使用するKlaviyoアカウントでオーナー、管理者、またはマネージャーのロールが必要です。接続でAPIキーを使用する場合、そのキーには質問に関連するデータセットへのアクセス権限が必要です。例えば、注文とセグメントに関する質問には、イベントとセグメントへのアクセス権限が必要です。

1. クライアントまたはセットアップ用のガイドを使用してKlaviyoを接続します：
   • ターミナルとリモートサーバー接続向けのKlaviyo MCPサーバー開発者ドキュメント
   • Claude向けKlaviyoアプリのよくある質問
   • ChatGPTでKlaviyoアプリを使用する方法
   • 代理店向けKlaviyo MCPサーバーガイド：クライアントのアカウント全体での運用
2. 接続済みのクライアントで、詳細な分析に関する質問をしてください。ask_analytics_questionツールに名前を付ける必要はありません。クライアントは、質問に応じて適切な場合にそれを選択します。
3. 回答を確認し、フォローアップの質問を続けてください。ツールが利用できない場合は、以下のトラブルシューティング手順に従って、クライアントのKlaviyoツールリストを更新してください。

OAuth経由で接続する場合は、クライアントのガイドに従って、リクエストされた権限を確認し、付与してください。

回答に基づいて計算を確認します

SQLは、質問に複数のデータセットからの情報が必要な場合に役立ちます。たとえば、注文数のカウントも、顧客、セグメントへの所属状況、国を追加することで、より詳細なオーディエンス分析になります。

まず質問から始め、同じ会話内でその回答を基に内容を展開してください：

1. 「先月の注文数はいくつでしたか？」
2. 「それらの注文を確定した顧客は何人ですか？」
3. 「それらの注文を、顧客が現在所属しているセグメント別に分類してください。」
4. 「結果をセグメントと国別に分け、各グループの売上を含めてください。」
5. 「初回購入者について、初回注文の前10日間にどの程度商品閲覧が行われましたか？」

重要な数値を共有したり、その数値を意思決定に使用したりする前に、回答がどのように算出されたのかを確認してください。例：

• 「どのデータセットを使用しましたか？」
• 「どの日付範囲とフィルターを適用しましたか？」
• 「この計算では、売上をどのように定義しましたか？」
• 「どのように計算したのか、手順を説明してください。」

説明を使用して、回答がお客様の意図した質問と一致していることを確認してください。一致しない場合は、メトリック、日付、またはフィルターを明確にして、もう一度質問してください。

質問できるデータ

SQLでは、接続に設定されている権限に応じて、これらのデータセットに関する質問に回答できます。

イベントとイベント内の詳細

利用可能なイベントデータには以下が含まれます：

• カートへの追加、注文の確定またはキャンセル、返金、商品の閲覧などのコマースアクティビティ
• 受信、開封、クリック、バウンス、ドロップ、購読解除などのメールアクティビティ
• 受信、クリック、失敗、同意、購読解除などのSMSおよびWhatsAppアクティビティ
• 受信、開封、バウンスなどのプッシュアクティビティ
• 購読、購読解除、送信抑制の追加または削除、設定の更新など、同意と送信抑制の変更
• エントリ、削除、フルフィルメント、スキップ、開始を含むフローアクティビティ
• プロファイルのマージ
• レビューと評価の送信、編集、削除、およびレビュー準備状況
• クーポンの付与と使用
• 開始、受信または送信したメッセージ、エスカレーション、解決、チケットの作成またはクローズなど、サポート会話アクティビティ
• カスタマーハブのアクティビティ（ログイン、お気に入り、商品またはクーポンのクリック、コンテンツブロックの閲覧など）
• チェックアウトアクティビティ、フォーム送信、ロイヤルティ登録、検索、出荷などを含む、API、Shopify、Lightspeedなどのソースからの外部連携イベント
• 配信、受信者数、開封、クリック、バウンス、購読解除、スパム報告、ユーザーのエンゲージメントの件数と率などのマーケティングメトリック

一部のイベントにはネストされた値が含まれます。これは、イベント内にある関連する詳細情報のグループです。たとえば、注文には商品のリストが含まれることがあり、各商品にはSKU、数量、価格が含まれます。SQLでそれらの詳細情報を読み取れるため、特定のSKUを含む注文数や、注文あたりの平均商品数を確認できます。

データセットを組み合わせる

SQLは、関連するデータセットを接続して質問に回答できます。これはジョインと呼ばれますが、明示的にジョインをリクエストする必要はありません。例：

• キャンペーンメッセージをキャンペーン名とエンゲージメントデータに関連付けて、名前付きキャンペーンを比較します。
• 現在のリストまたはセグメントのメンバーシップをプロファイルと注文に関連付け、オーディエンスの購入アクティビティを分析します。
• 国、同意ステータス、または予測顧客価値別にオーディエンスを分類します。
• 商品をカテゴリに、またはバリエーションを親商品に紐付けて、商品またはカテゴリのパフォーマンスを分析します。
• クーポンの割り当てをクーポンの使用と連携し、利用状況を算出して、未利用のクーポンを特定します。

質問例

日付、商品、セグメント、キャンペーンの詳細をアカウントに合わせて調整してください。

制限を理解する

利用できないデータ

SQLは現在、次をサポートしていません：

• 過去の特定時点におけるリストまたはセグメントへの登録状況
• サインアップフォームまたはそのパフォーマンス
• カスタムオブジェクト
• メールまたはSMSテンプレート

外部連携イベントにはフォーム送信が含まれる場合がありますが、だからといってSQLがサインアップフォームやそのパフォーマンスの分析をサポートしているわけではありません。質問が利用できないデータに依存している場合、回答が不完全になるか、クライアントが回答できない可能性があります。

データの鮮度とKlaviyoレポートとの違い

データは通常、アカウントより約30分遅れて反映されます。最近のアクティビティはすぐに表示されない場合があります。

数値は通常Klaviyoと一致しているはずですが、定義、クエリの最適化、またはデータの鮮度の違いにより、わずかな差異が生じる場合があります。SQLは、Klaviyoデータにアクセスする他の方法とは異なるデータソースを使用します。Klaviyoは、過去3年間にわたりこのデータの一貫性が99％であることを確認しました。

数値がレポートと異なる場合は、計算方法、日付範囲、フィルターを確認してください。この説明は、同じメトリックと期間を比較しているかどうかの特定に役立ちます。

生成されたクエリとタイムアウト

SQLは、質問からクエリを生成します。現在、独自のSQLクエリを送信し、保証された再現可能な結果を受け取れるエンドポイントはありません。表現が異なると、生成されるクエリも異なり、結果もわずかに変わる場合があります。重要な数値について、計算内容を確認してください。

MCPクライアントは、Composerよりも早く応答待ちを停止できます。たとえばClaudeには、60秒のタイムアウトウィンドウがあります。質問がタイムアウトした場合は、日付範囲を狭める、内訳の数を減らす、または分析をより小さな質問に分岐してください。

トラブルシューティング

分析ツールは利用できません

AIクライアントにask_analytics_questionが表示されない場合は、アカウントでSQLが有効になっていることを確認し、クライアントのKlaviyoツールリストを更新してください。

Claudeで：

1. カスタマイズ＞コネクター＞Klaviyoに移動します。
2. 右上隅にある3点メニューを開きます。
3. ツールリストを更新をクリックし、もう一度質問をお試しください。

SQLでは、アカウント内にあると分かっているデータを返せません。

データセットがサポートされているかどうかを確認し、通常の30分の待機を考慮してください。接続でAPIキーを使用している場合は、プロファイル、セグメント、リスト、キャンペーン、カタログ、またはイベントなど、関係するすべてのデータセットにアクセスできることを確認してください。Klaviyoで不足している権限を更新し、クライアントのKlaviyoツールリストを更新してから、質問を再試行してください。

OAuth接続の場合は、クライアントの接続ガイドを使用して権限を確認してください。

質問がタイムアウトしました

日付範囲を短くするか、内訳を少なくするか、または質問を小さな質問に分けてください。より絞り込んだ質問でもう一度試し、その結果をもとに追加の質問で深掘りしてください。

番号がKlaviyoと一致しません

SQLが数値をどのように算出したのかについて、データセット、期間、フィルターを含めて確認してください。メトリックの定義とデータの鮮度によって差異が説明できるか確認してください。差が大きい場合は、Klaviyoサポートにお問い合わせのうえ、質問内容、返された数値、および想定していた数値を共有してください。

Composerが質問を拒否する

特定のメトリック、日付範囲、オーディエンスを含めて質問を言い換えてください。サポートされているデータセットのいずれかを使用していることを確認してから、再試行してください。

その他のリソース

• Composerのスタートガイド
• Klaviyo MCPサーバーの開発者向けドキュメント
• Claude向けKlaviyoアプリのよくある質問
• ChatGPTでKlaviyoアプリを使用する方法
• 代理店向けKlaviyo MCPサーバーガイド
• Klaviyo でカスタムレポートを始める