schema-discovery

スキーマの探索

目的

プロファイルのスキーマを取得して解釈し、自然言語の説明に一致するフィールドを見つけます。他のスキル（特に audience-builder）が、ユーザーの意図を実際のスキーマフィールドに対応付けるために使用します。

環境

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

入力

• 検索するデータの概念を表す自然言語の説明（例：「国」、「購入履歴」、「メールのエンゲージメント」）
• テーブル名（デフォルト：user）

API エンドポイント

すべてのフィールドを一覧表示

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

すべてのフィールドと、その型、説明、マージ操作を返します。

軽量なフィールド名一覧

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

フィールド名のみを返します。手早く一覧を確認する場合に使用します。

値の分布を含むフィールド情報

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

値の分布とサンプルデータを含むフィールド情報を返します。

フィールド値の候補

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/${TABLE:-user}/fieldsuggest/${FIELD}?q=${QUERY}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

クエリの部分文字列に一致する、指定したフィールドの値の候補を返します。q パラメーターは必須です。フィールド値に対して大文字小文字を区別せず部分一致検索を行います。

ID 設定

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

使用可能なストリーム

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

動作

ステップ 1：フィールド一覧を取得する

フィールド名のエンドポイントを呼び出し、使用可能なフィールドの完全な一覧を取得します。

ステップ 2：候補フィールドをスコアリングする

ユーザーの説明に含まれる各概念について、次の基準で候補フィールドを評価します。

1. 名前の一致（最優先）：フィールド名の完全一致または部分一致
2. 型の互換性：フィールドの型が意図された操作に対応していること（../references/field-types.md を参照）
3. 説明の一致：フィールドの ShortDesc または LongDesc が一致すること

ステップ 3：値の分布で確認する

各概念の上位 2～3 個の候補について、フィールド値の候補を取得し、次の点を確認します。

• フィールドに想定される種類のデータが含まれていること
• サンプル値がユーザーの説明と一致すること（例：国のフィールドに「US」の値がある）

ステップ 4：フィールドの対応関係を返す

次の内容を対応付けて返します。

• 概念 -> 選択したフィールド名、フィールドの型、信頼度、サンプル値
• ユーザーへの確認が必要な曖昧な点

フィールド照合のヒューリスティクス

自然言語からフィールド名への一般的な対応パターン：

• 「国」 -> country、geo_country、country_code
• 「メール」 -> email、_e
• 「購入した／買った」 -> products_purchased、purchase_categories、orders
• 「訪問した／閲覧した」 -> urls_visited、pages_viewed、visit_count
• 「登録した／アカウントを作成した」 -> created、signup_date、joined
• 「クリックした」 -> click_count、clicks
• 「スコア」 -> scores.*、engagement_score

エラー処理

• 概念に一致するフィールドがない場合は、そのことを明確に伝え、ユーザーに言い換えるか、使用可能なフィールドを確認するよう提案します
• 同程度に有力な候補が複数ある場合は、ユーザーが選択できるよう提示します
• テーブルが存在しない場合は、そのことを伝え、デフォルトとして user を提案します

依存関係

• 参照先：../references/auth.md、../references/api-client.md、../references/field-types.md