schema-manager

架构管理器

用途

浏览和修改用户档案架构——字段、映射、身份配置和字段排名。用户想了解其数据模型、添加新字段或修改字段映射时，请使用此工具。

环境

需要经过身份验证的 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 表达式将源流字段连接到目标架构字段。没有至少一个映射的字段处于非活动状态——它永远不会接收数据。

# 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	为提供上下文而纳入，未更改实时架构

身份配置

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）

立即执行。以易读的表格形式展示字段，包括：

• 字段名称、类型、描述、合并操作、身份／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：Schema 补丁（启用时）

如果账户启用了 Schema 补丁，所有 Schema 变更都必须通过补丁进行。直接编辑字段／映射将无法生效。

添加带映射新字段的完整工作流：

1. 创建补丁，并为其指定描述性名称
2. 将字段添加到补丁
3. 将字段的映射添加到补丁——没有映射的字段不会生效，也永远不会接收数据。务必询问：“应由哪个数据流填充此字段？源字段名称是什么？”
4. 检查补丁差异（GET 补丁以查看相对于实时 Schema 的所有变更）
5. 向用户确认（展示差异摘要）
6. 应用补丁（这会发布新的 Schema 版本）

如果用户不知道数据流名称，请列出可用的数据流：

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

写入工作流 B：直接发布（未启用补丁时）

如果账户不使用 Schema 补丁，编辑内容会进入共享的未发布草稿，必须手动发布。 Schema 变更会暂存，直到发布后才生效。

创建新字段时，务必询问映射信息——没有映射的字段不会生效。然后将两者一并发布。

每次写入操作都必须遵循以下顺序：

1. 确认：使用确认门模式。展示变更内容并征得用户批准。
2. 执行：通过 API 修改字段／映射。
3. 发布：立即发布变更。发布成功前，Schema 写入都不算完成。

   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. 验证：确认发布成功。如果失败，报告错误——变更仍处于暂存状态，必须先发布才会生效。

**如果未发布，绝不能将 Schema 写入操作视为已完成。**如果要依次进行多项变更，可以将它们批量处理并在最后发布一次，但务必在报告成功前完成发布。

错误处理

• 字段已存在（409）：展示现有字段详情，并询问用户是否要改为更新
• 类型无效：列出 ../references/field-types.md 中的有效类型
• 发布失败：展示错误详情，并建议检查字段是否有效

依赖项

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