schema-manager

スキーママネージャー

目的

プロファイルスキーマ（フィールド、マッピング、ID 設定、フィールドランキング）を参照および変更します。データモデルの理解、新しいフィールドの追加、フィールドマッピングの変更をユーザーが希望する場合に使用します。

環境

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

API エンドポイント

スキーマの概要

# List all schemas (tables)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

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

フィールド

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

# Get field names only
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/fieldnames" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

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

# Create field
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/field" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "Field": "field_name",
    "Type": "string",
    "ShortDesc": "Brief description",
    "MergeOp": "latest",
    "IsIdentifier": false,
    "IsPII": false
  }'

# Update field -- requires the full field definition, not just changed fields.
# At minimum, include Field, Type, and the fields you're changing.
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/field/${FIELD_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "Field": "field_name",
    "Type": "string",
    "ShortDesc": "Updated description",
    "MergeOp": "latest",
    "IsIdentifier": true,
    "IsPII": false
  }'

# Delete field
curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/field/${FIELD_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

マッピング

マッピングは、LQL 式を介してソースストリームのフィールドをターゲットスキーマのフィールドに接続します。少なくとも 1 つのマッピングがないフィールドは機能しません。データが取り込まれることはありません。

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

# Get specific mapping
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/mapping/${MAPPING_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Create mapping -- all three fields (field, stream, expr) are required
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/mapping" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "email",
    "stream": "default",
    "expr": "email(email_address)"
  }'

# Create mapping with guard condition
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/mapping" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "hashed_email",
    "stream": "click_stream",
    "expr": "hash.sha256(email(email))",
    "guard_expr": "email != '\'\''"
  }'

# Update mapping
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/mapping/${MAPPING_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "email",
    "stream": "new_stream",
    "expr": "email(raw_email)"
  }'

# Delete mapping
curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/mapping/${MAPPING_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

マッピングのペイロードフィールド：

フィールド	必須	説明
field	はい	ターゲットスキーマのフィールド名。既存のフィールドを参照する必要があります
stream	はい	ソースストリーム名（例：default、salesforce_contacts）
expr	はい	値を抽出／変換する LQL 式（例：set(raw_field)、email(email_address)）
guard_expr	いいえ	このマッピングを適用する条件（省略可能）。「IF」を前置しないでください

マッピングでよく使用される LQL 式：

• 単純な受け渡し：raw_field_name
• セット／配列：set(raw_field)
• メールアドレスの正規化：email(email_address)
• ハッシュ化：hash.sha256(email(email))
• URL の解析：url(page_url)
• 型変換：todate(timestamp_field)

スキーマパッチ

スキーマパッチは、関連する変更を名前付きの変更セットにまとめ、レビューして一括で適用できるようにします。スキーマ変更用の git ブランチのようなものです。enable_schema_patches: true が設定されているアカウントでは、スキーマ変更に必ずパッチを使用する必要があります。「書き込みワークフローの判定」セクションを参照してください。

パッチのライフサイクル：パッチの作成 -> 変更の追加 -> 差分のレビュー -> 適用

# List all patches for a table
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Create a new patch -- `tag` (kebab-case identifier) and `description` are both required.
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "add-purchase-fields",
    "description": "Add purchase tracking fields and mappings for Shopify integration"
  }'

# Get a specific patch (includes diffs against live schema)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Update patch metadata
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

# Delete a patch (discard all changes)
curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Apply a patch (publishes a new schema version with all changes)
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}/apply" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

パッチへのフィールドの追加：

パッチエンドポイントのペイロード形式は小文字です。 id（フィールド名）、type、shortdesc、mergeop、is_identifier、is_pii を使用してください。以下のパッチを使用しない直接書き込みの例に示されている大文字始まりの形式（Field、Type、ShortDesc など）は、ここでは受け付けられません。大文字のキーを送信すると、パッチエンドポイントは Attribute 'Field' is required for Field を返します。

# Add or update a field in the patch
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}/field" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "purchase_total",
    "type": "number",
    "shortdesc": "Total purchase amount",
    "mergeop": "sum",
    "is_identifier": false,
    "is_pii": false
  }'

# Update an existing field in the patch
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}/field/${FIELD_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... full field definition ... }'

# Get a field from the patch (shows diff against live)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}/field/${FIELD_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

パッチへのマッピングの追加：

# Add a mapping in the patch
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}/mapping" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "purchase_total",
    "stream": "shopify_orders",
    "expr": "total_price"
  }'

# Update an existing mapping in the patch
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}/mapping/${MAPPING_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... mapping definition ... }'

パッチへのランキング変更の追加：

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/patch/${TABLE}/${PATCH_ID}/rank" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... rank config ... }'

パッチ内でのステータスの編集：

ステータス	意味
new	ライブスキーマに存在しません。作成されます
modified	ライブスキーマに存在し、プロパティが変更されています
deleted	パッチ適用時に削除されるようマークされています
unmodified	コンテキスト用に含まれており、ライブスキーマからの変更はありません

ID 設定

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

フィールドランキング

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

# Update field rankings
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/rank" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... ranking config ... }'

スキーマ変更の公開

公開にはタグと説明が必要です。どちらも必須です。

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/publish" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "short-kebab-tag",
    "description": "Human-readable description of what changed"
  }'

tag には、短い kebab-case の識別子（例：add-phone-identifier）を指定してください。description には、監査用に変更内容を説明してください。

スキーマからの LQL の生成

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/lql" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... schema config ... }'

フィールドタイプ

完全な型リファレンス（以下を含む）については、../references/field-types.md を参照してください。

• スカラー：string、bool、int、number、date
• 複合型：[]string、map[string]int、map[string]string など
• 特殊型：geolocation、embedding、membership

動作

読み取り操作（list、get、browse）の場合

すぐに実行します。フィールド名、型、説明、マージ操作、ID／PII フラグを示す、読みやすい表形式でフィールドを提示します。

書き込みワークフローの判定

スキーマパッチが必要なアカウント（アカウント設定 enable_schema_patches: true）もあれば、直接公開ワークフローを使用するアカウントもあります。スキーマ変更を行う前に、アカウントがどちらのモードを使用しているか必ず判定してください。

パッチの一覧取得を試して確認します：

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

正常に応答した場合（リストが空の場合も含む）、そのアカウントではパッチを使用します。エラーまたは 404 が返された場合は、直接公開ワークフローを使用します。

書き込みワークフロー A：スキーマパッチ（有効な場合）

アカウントでスキーマパッチが有効になっている場合、スキーマの変更はすべてパッチ経由で行う必要があります。フィールドやマッピングを直接編集しても反映されません。

マッピングを含む新しいフィールドを追加するための完全なワークフロー：

1. パッチを作成し、内容が分かる名前を付けます
2. パッチにフィールドを追加します
3. パッチにそのフィールドのマッピングを追加します。マッピングのないフィールドは機能せず、データを受け取ることはありません。必ず「このフィールドにデータを取り込むストリームはどれで、ソースフィールド名は何ですか？」と確認してください
4. パッチの差分を確認します（パッチを GET して、稼働中のスキーマとのすべての変更を確認します）
5. 差分の概要を表示して、ユーザーに確認します
6. パッチを適用します（これにより、新しいスキーマバージョンが公開されます）

ユーザーがストリーム名を知らない場合は、利用可能なストリームを一覧表示します：

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

書き込みワークフロー B：直接公開（パッチが有効でない場合）

アカウントでスキーマパッチを使用していない場合、編集内容は共有の未公開ドラフトに保存され、手動で公開する必要があります。 スキーマの変更は公開されるまでステージング状態であり、公開するまで有効になりません。

新しいフィールドを作成する場合は、必ずマッピングを確認してください。マッピングのないフィールドは機能しません。その後、フィールドとマッピングを一緒に公開します。

すべての書き込み操作では、必ず次の手順に従ってください。

1. 確認：確認ゲートのパターンを使用します。変更内容を提示し、ユーザーの承認を得ます。
2. 実行：API を使用して、フィールドまたはマッピングを変更します。
3. 公開：変更を直ちに公開します。公開が成功するまでは、スキーマの書き込みは完了していません。

   curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/${TABLE}/publish" \
     -H "Authorization: ${LYTICS_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"tag": "descriptive-tag", "description": "What changed and why"}'
   

4. 検証：公開が成功したことを確認します。失敗した場合はエラーを報告します。変更はステージング状態のままなので、有効にするには公開する必要があります。

**公開せずにスキーマの書き込み操作を完了したと見なしてはいけません。**複数の変更を続けて行う場合は、まとめて最後に一度だけ公開してもかまいませんが、成功を報告する前に必ず公開してください。

エラー処理

• フィールドがすでに存在する（409）：既存のフィールドの詳細を表示し、代わりに更新するかユーザーに確認します
• 無効な型：../references/field-types.md に記載されている有効な型を一覧表示します
• 公開の失敗：エラーの詳細を表示し、フィールドの有効性を確認するよう提案します

依存関係

• 使用：../references/auth.md、../references/api-client.md、../references/confirmation-gate.md
• 参照：../references/field-types.md