schema-optimizer

スキーマオプティマイザー

目的

スキーマの品質上の問題を分析し、改善策を提案します。未使用フィールド、誤って設定されたマージ操作、不足しているマッピング、ID 解決の不足、PII の露出リスクを特定します。実行可能な推奨事項を提示する読み取り専用の分析です。

環境

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

入力

• テーブル（デフォルト：user）
• 任意の重点領域：unused-fields、coverage、identity、merge-ops、mappings、pii、all

分析フロー

すべてのチェック（または特定の重点領域）を実行してから、統合レポートを提示します。

ステップ 1：データを収集する

3 つのコアデータセットを並行して取得します。

# All fields with metadata
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/field" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# All mappings
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/mapping" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# All segments (to find field references)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

ステップ 2：フィールドのカバレッジを収集する

# Field info with presence/absence counts
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/user/fieldinfo" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

ステップ 3：ID 設定を収集する

# Identity resolution config and ranks
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/rank" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/idconfig" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

分析チェック

チェック 1：未使用フィールド

フィールドとセグメントの FilterQL を照合し、スキーマに存在するものの、どのセグメントでも参照されていないフィールドを見つけます。

1. すべてのセグメントから segment_ql を解析し、参照されているフィールド名を抽出します
2. すべてのスキーマフィールドと照合します
3. 次のフィールドにフラグを付けます。
   • どのセグメントでも参照されておらず、ents_present がゼロまたは非常に少ない
   • どのセグメントでも参照されていないものの、データがある（今後のセグメントで役立つ可能性があります）

### Unused Fields (12 found)

Never referenced in segments AND empty:
  legacy_score        -- 0 profiles, created 2024-03-01, no mappings
  old_campaign_tag    -- 0 profiles, created 2024-06-15, 1 stale mapping

Never referenced but have data:
  browser_version     -- 45,000 profiles (31%), not in any segment
  referrer_domain     -- 89,000 profiles (61%), not in any segment
  (these may be useful -- review before removing)

チェック 2：不活性フィールド（マッピングなし）

マッピングのないフィールドには、どのストリームからもデータが届きません。

1. すべてのフィールドとマッピングを取得します
2. そのフィールド名を対象とするマッピングがないフィールドを見つけます
3. システム管理フィールド（ManagedBy = "lytics" など）を除外します

### Inert Fields -- No Mappings (3 found)

  custom_score    -- type: number, created 2025-01-10, no mapping exists
  user_tier       -- type: string, created 2025-02-20, no mapping exists
  (these fields will never receive data until a mapping is added)

チェック 3：フィールドのカバレッジ

セグメントで使用されているもののカバレッジが非常に低いフィールドを特定します。これにより、オーディエンスへのリーチが制限されます。

### Low Coverage Fields Used in Segments

  phone           -- 12% coverage, used in 2 segments
  company_name    -- 8% coverage, used in 1 segment
  (segments using these fields are limited to at most N% of profiles)

チェック 4：ID 解決

ID フィールドの設定を確認します。

• ID としてマークされたフィールドはありますか？（プロファイル解決には少なくとも 1 つ必要です）
• ランクの順序は適切ですか？（優先度の高いフィールドほど、安定した識別子である必要があります）
• 全フィールド数に対して、ID フィールドはいくつありますか？

### Identity Resolution

Identity fields: 3 configured
  1. email        -- rank 1, coverage: 92%
  2. _uid         -- rank 2, coverage: 100%
  3. user_id      -- rank 3, coverage: 45%

Observations:
  3 identity fields configured -- looks reasonable
  email is rank 1 with 92% coverage -- good primary identifier
  user_id has 45% coverage -- only useful for profiles from sources that provide it

注：IDConfig（圧縮設定）は任意であり、ほとんどのアカウントでは必要ありません。ユーザーが ID 圧縮について具体的に尋ねた場合にのみ言及してください。

チェック 5：マージ操作の確認

フィールドのデータ型や使用パターンに対して、誤って設定されている可能性のあるマージ操作にフラグを付けます。

フィールド型	一般的な MergeOp	不適切な場合の問題
string（名前、メールアドレス）	latest	sum／count は意味をなしません
int（訪問回数）	sum または count	latest では累積値が失われます
number（スコア）	latest または max	sum では際限なく増加する可能性があります
[]string（タグ、カテゴリ）	merge	latest では履歴が失われます
date（last_visit）	latest または max	min では最初の値に固定されます
map[string]int（アクション数）	merge または mapmax	latest ではデータが失われます

### Merge Operation Review

Potential issues:
  visit_count (int, merge_op: latest)
    -> Recommendation: consider 'sum' or 'count' to accumulate visits

  tags ([]string, merge_op: latest)
    -> Recommendation: consider 'merge' to accumulate tag values

  engagement_score (number, merge_op: sum)
    -> Recommendation: consider 'latest' or 'max' -- summing scores causes unbounded growth

チェック 6：PII の露出

PII としてマークされ、セグメントの FilterQL に含まれているフィールドにフラグを付けます（セグメント定義を通じてデータが露出する可能性があります）。

### PII in Segments

  email (PII) -- referenced in 3 segments
    "Email Subscribers": EXISTS email
    (EXISTS checks are generally safe -- no value exposure)

  phone (PII) -- referenced in 1 segment
    "Phone Contacts": phone CONTAINS "+1"
    WARNING: FilterQL contains a literal value match on PII field

チェック 7：容量と保持

セット型およびマップ型のフィールドについて、容量が設定されているか、実際のカーディナリティに対して適切かを確認します。

### Capacity Review

  products_purchased ([]string, capacity: 100, actual cardinality: 2,340)
    -> WARNING: Cardinality far exceeds capacity. Values are being dropped.
    -> Recommendation: increase capacity or review if all values are needed

  action_counts (map[string]int, capacity: 0)
    -> WARNING: No capacity limit. Map will grow unbounded.
    -> Recommendation: set a capacity limit

出力形式

## Schema Optimization Report (user table)

### Summary
- Total fields: 145
- Unused fields: 12 (8%)
- Inert fields (no mapping): 3
- Low-coverage fields in segments: 5
- Identity issues: 1
- Merge op concerns: 3
- PII exposure warnings: 1
- Capacity warnings: 2

### Priority Recommendations
1. HIGH: 3 fields have no mappings and will never receive data -- add mappings or remove fields
2. MEDIUM: visit_count uses 'latest' merge -- consider 'sum' to accumulate
3. MEDIUM: products_purchased capacity (100) exceeded by cardinality (2,340) -- values being dropped
4. LOW: 12 fields are unused -- review and archive if no longer needed

[Detailed findings per check follow...]

エラー処理

• 大規模なスキーマ：フィールド数が 500 を超える場合、fieldinfo リクエストを分割して実行します。時間がかかる可能性があることをユーザーに伝えてください。
• セグメントなし：セグメントが存在しない場合、使用状況の分析をスキップし、その旨を記載します。
• Fieldinfo を利用できない場合：fieldinfo エンドポイントが失敗した場合、メタデータのみの分析を続行します（カバレッジと容量のチェックはスキップします）。

依存関係

• 組み合わせるもの：schema-manager skill、segment-manager skill
• 参照：../references/field-types.md、../references/auth.md、../references/api-client.md