为json字段添加含义说明需先确保其为string类型，再在schema中填写业务语义描述；推荐对关键子字段用缩进列举或建虚拟说明字段；批量更新时通过csv导入并严格匹配字段名。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在火山引擎DataFinder或ByteHouse等数据平台中为JSON字段添加含义说明，是为了让下游用户快速理解嵌套字段的实际业务意义，避免因JSON结构模糊导致解析错误或语义误读。
确认JSON字段已作为STRING类型接入
进入DataFinder → 数据源管理 → 找到目标表 → 点击【编辑Schema】→ 检查该JSON字段的类型是否为STRING。如果不是，【必须先改为STRING】，因为火山引擎不支持直接对JSON类型字段添加字段级描述；只有STRING、VARCHAR等基础类型才能在Schema中填写“字段描述”栏。
若强行保留JSON类型并试图填写描述，保存时会静默失败，且无任何提示。
在Schema编辑页为JSON字段填写业务含义
点击字段右侧的铅笔图标 → 在“字段描述”输入框中填写自然语言说明。例如：“用户行为事件原始JSON，包含event_type、timestamp、props（自定义属性对象）、user_id等字段，详情见内部《埋点协议v3.2》第4.1节”。
这里不要写技术定义如“JSON格式字符串”，而要写清楚它装的是什么业务内容、谁产出、何时更新、关键子字段有哪些——下游开发或分析师靠这段话决定是否值得解析、怎么解析。
为JSON内部关键子字段补充独立描述（推荐做法）
方法一：在字段描述中用缩进+冒号列出核心子键
例如：“用户订单快照JSON（下单时刻完整快照）：→ order_id：全局唯一订单号；→ status：枚举值（created/paid/shipped/cancelled）；→ items：商品列表数组，每项含sku_id、quantity、price”。
方法二：新建虚拟字段（仅用于文档说明）
在同张表中新增若干STRING类型字段，命名如“json_order_status_desc”“json_items_count_desc”，字段描述写明对应JSON路径及含义。虽然不存真实数据，但能在元数据页面形成可检索、可排序的语义索引。注意：这类字段需在名称末尾加“_desc”后缀，并在描述首行注明【纯说明字段，无实际数据】。
【切勿将虚拟字段设为NOT NULL或参与JOIN】，否则会引起SQL执行异常。
批量更新多个JSON字段描述（适用于中大型数仓表）
第一步：导出当前Schema为CSV → 使用Excel筛选出所有类型为STRING且字段名含“json”“raw”“ext”“detail”的列。
第二步：在“字段描述”列批量填充模板句式：“{业务实体}原始JSON，关键路径：$.xxx（说明），$.yyy（说明）；更新频率：{T+0/T+1}；数据来源：{上游系统名}”。
第三步：保存CSV → 回到DataFinder Schema编辑页 → 点击【导入Schema】→ 选择更新模式为“按字段名匹配更新” → 上传文件。
导入前务必检查CSV中字段名与线上完全一致（包括大小写和下划线），否则会被识别为新字段而非更新。
