profile-investigator

プロファイル調査

目的

プロファイルを深く診断し、詳しく調査します。次のような質問に答えます。

• 「このユーザーがセグメント X に属しているのはなぜですか？」
• 「このユーザーがセグメント Y に属していないのはなぜですか？」
• 「このユーザーに何が起きましたか？」（データリネージ）
• 「このユーザーのプロファイルはどのようなものですか？」（プロファイル全体と所属セグメント）

基本的なプロファイル検索にとどまらず、プロファイルデータとセグメントの FilterQL を照合し、どの条件に一致するか、または一致しないかを正確に示します。

環境

認証済みの API アクセスが必要です。認証情報の解決については ../references/auth.md を参照してください。

入力

• ID フィールドと値（例：email、[email protected]）
• 所属診断の場合は、セグメント名または ID
• または、自然言語による診断の質問

診断フロー

フロー A：「このユーザーがセグメント X に属している／属していないのはなぜですか？」

ステップ 1：プロファイルを検索する

セグメントへの所属情報を含むプロファイル全体を取得します。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/user/${FIELD}/${VALUE}?segments=true&allsegments=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

次の情報が返されます。

• プロファイルのすべてのフィールドとその値
• segments -- ユーザーが所属するセグメント名の一覧
• segments_all -- すべてのセグメント ID の一覧

すぐに、対象のセグメントが所属一覧にあるか確認します。

ステップ 2：セグメントの FilterQL を取得する

すべての INCLUDE ディレクティブが展開された FilterQL を含むセグメントを取得します。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}?inline=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

ql_resolved フィールドには、ネストされたセグメントが展開された完全なフィルター式が含まれています。

ステップ 3：各条件をプロファイルと照合する

FilterQL を個別の条件に分解し、それぞれをプロファイルの実際のフィールド値と照合します。

FilterQL の各条件について、次のように報告します。

ユーザーがセグメントに属している場合：

## Why [email protected] IS in "High Value Customers"

FilterQL: FILTER AND (visit_count >= 5, email_engagement > 0.3, country = "US") FROM user

All conditions PASS:
  visit_count >= 5        PASS  (actual: 12)
  email_engagement > 0.3  PASS  (actual: 0.72)
  country = "US"          PASS  (actual: "US")

ユーザーがセグメントに属していない場合：

## Why [email protected] is NOT in "High Value Customers"

FilterQL: FILTER AND (visit_count >= 5, email_engagement > 0.3, country = "US") FROM user

Condition results:
  visit_count >= 5        PASS  (actual: 12)
  email_engagement > 0.3  FAIL  (actual: 0.15, required: > 0.3)
  country = "US"          PASS  (actual: "US")

The user fails the email_engagement condition. Their value (0.15) is below
the threshold (0.3). This is the reason they are excluded from the segment.

ステップ 4：含まれるセグメントを確認する

FilterQL が INCLUDE を使って他のセグメントを参照している場合、それらのセグメントへの所属も確認します。

Segment "High Value Customers" includes "Email Subscribers":
  Email Subscribers membership: YES

  Combined evaluation:
    INCLUDE Email Subscribers   PASS
    visit_count >= 5            PASS  (actual: 12)
    last_purchase > "now-90d"   FAIL  (actual: 2025-01-15, ~63 days ago -- outside 90d window)

フロー B：「このユーザーに何が起きましたか？」（データリネージ）

ステップ 1：説明モードでエンティティを取得する

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/user/${FIELD}/${VALUE}?explain=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

次の情報が返されます。

• entity -- 解決済みのプロファイル
• fragments -- 各データの出所を示すデータフラグメントの配列
• keys -- ソース参照（フラグメントのエイリアス）

ステップ 2：データリネージを提示する

## Data Lineage: [email protected]

### Identity Resolution
Linked identities:
  email: [email protected]
  _uid: abc-def-123
  user_id: 98765

### Data Sources (N fragments)
Fragment 1: stream "web_events" (last seen: 2026-03-18)
  -> visit_count, pages_viewed, last_visit, referrer

Fragment 2: stream "salesforce_contacts" (last seen: 2026-03-15)
  -> first_name, last_name, company, phone

Fragment 3: stream "email_events" (last seen: 2026-03-19)
  -> email_engagement, newsletters, last_email_open

フロー C：プロファイル全体の概要

ステップ 1：プロファイルとセグメントを取得する

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/entity/user/${FIELD}/${VALUE}?segments=true&allsegments=true&meta=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

ステップ 2：構造化された概要を提示する

## Profile: [email protected]

### Identity
  email: [email protected]
  _uid: abc-def-123

### Key Attributes
  Name: Jane Smith
  Country: US
  Created: 2024-01-15
  Last Active: 2026-03-18
  Visit Count: 12

### Segment Memberships (5 segments)
  - High Value Customers (segment)
  - Email Subscribers (aspect)
  - US Users (aspect)
  - Q1 Campaign (list)
  - Active Last 30 Days (segment)

### NOT in these commonly-checked segments
  [If the user asks about specific segments, show which they're not in and why]

条件の評価

FilterQL の条件をプロファイルデータと照合する際は、各演算子の種類に応じて処理します。

FilterQL の条件	確認方法
field = "value"	プロファイルのフィールド値をリテラルと比較します
field > N	プロファイルの値と数値で比較します
field > "now-Nd"	プロファイルの日付フィールドを計算したしきい値と比較します
EXISTS field	プロファイルにフィールドが存在し、値が空でないことを確認します
NOT EXISTS field	フィールドが存在しないか、値が空であることを確認します
field INTERSECTS ("a", "b")	プロファイルの集合型フィールドに、指定された値のいずれかが含まれているか確認します
field NOT INTERSECTS ("a")	プロファイルの集合型フィールドに、指定された値が一つも含まれていないか確認します
field CONTAINS "substr"	プロファイルの文字列型フィールドに部分文字列が含まれているか確認します
field IN ("a", "b")	プロファイルの値が一覧に含まれているか確認します
INCLUDE segment_slug	ユーザーが参照先のセグメントに所属しているか確認します

各条件について、必ず次の情報を示します。

• 条件そのもの
• PASS または FAIL
• プロファイルの実際の値（存在しない場合は「フィールドが存在しません」）
• FAIL の場合：PASS するために必要な値

エラー処理

• プロファイルが見つからない場合：別の ID フィールドを試し、スペルを確認するよう案内します。特殊文字を含む値は URL エンコードします。
• セグメントが見つからない場合：名前が似ているセグメントを一覧表示し、スラッグを確認するよう案内します。
• FilterQL が複雑な場合：深くネストされた式では、まず最上位の条件を評価し、その後、失敗した分岐を詳しく確認します。
• フィールドが見つからない場合：FilterQL で参照されているプロファイルフィールドがプロファイルに存在しない場合は、そのことを明確に報告します。これが根本原因であることもよくあります。

Dependencies

• Composes: entity-lookup skill, segment-manager skill
• References: ../references/filterql-grammar.md, ../references/auth.md, ../references/api-client.md