# 创建数据范式 创建一个数据范式。 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/search/v2/schemas HTTP Method | POST 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 查询、创建、修改和删除自定义搜索数据源、数据范式或数据项(search:data_source)
查询自定义搜索数据源、数据范式或数据项(search:data_source:readonly) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) Content-Type | string | 是 | **固定值**："application/json; charset=utf-8" ### 查询参数 名称 | 类型 | 必填 | 描述 ---|---|---|--- validate_only | boolean | 否 | 是否只用来校验合法性
**示例值**：true
**默认值**：`false` ### 请求体 名称 | 类型 | 必填 | 描述 ---|---|---|--- properties | schema_property\[\] | 是 | 数据范式的属性定义 name | string | 是 | 属性名
**示例值**："summary"
**数据校验规则**：
- 长度范围：`0` ～ `20` 字符 type | string | 是 | 属性类型
**示例值**："text"
**可选值有**：
- text：长文本类型
- int：64位整数类型
- tag：标签类型
- timestamp：Unix 时间戳类型（单位为秒）
- double：浮点数类型（小数）
- tinytext：短文本类型，（utf8 编码）长度小于 140 的文本。在设置 search_options 时，与 text 类型有区别，支持更多召回策略
**数据校验规则**：
- 长度范围：`0` ～ `60000` 字符 is_searchable | boolean | 否 | 该属性是否可用作搜索，默认为 false
**示例值**：true is_sortable | boolean | 否 | 该属性是否可用作搜索结果排序，默认为 false。如果为 true，需要再配置 sortOptions
**示例值**：false is_returnable | boolean | 否 | 该属性是否可用作返回字段，为 false 时，该字段不会被召回和展示。默认为 false
**示例值**：true sort_options | schema_sort_options | 否 | 属性排序的可选配置，当 is_sortable 为 true 时，该字段为必填字段 priority | int | 否 | 排序的优先级，可选范围为 0~4，0为最高优先级。如果优先级相同，则随机进行排序。默认为0
**示例值**：0
**可选值有**：
- 0：最高优先级
- 1：次高优先级
- 2：次次高优先级
- 3：次低优先级
- 4：最低优先级
**默认值**：`0`
**数据校验规则**：
- 取值范围：`0` ～ `4` order | string | 否 | 排序的顺序。默认为 desc
**示例值**："asc"
**可选值有**：
- asc：升序
- desc：降序
**默认值**：`desc` type_definitions | schema_type_definitions | 否 | 相关类型数据的定义和约束 tag | schema_tag_options\[\] | 否 | 标签类型的定义
**数据校验规则**：
- 最大长度：`100` name | string | 是 | tag 对应的枚举值名称
**示例值**："status"
**数据校验规则**：
- 最大长度：`20` 字符 color | string | 是 | 标签对应的颜色
**示例值**："blue"
**可选值有**：
- red：含警示性、敏感性的提示信息
- green：表示成功、完成、完毕的提示信息
- blue：组件架构、职能等中性信息
- grey：中立系统提示信息（慎重使用）
- yellow：焦点信息、推广性信息 text | string | 是 | 标签中展示的文本
**示例值**："PASS"
**数据校验规则**：
- 最大长度：`8` 字符 search_options | schema_search_options | 否 | 属性搜索的可选配置，当 is_searchable 为 true 时，该字段为必填参数 enable_semantic_match | boolean | 否 | 是否支持语义切词召回。默认不支持（推荐使用在长文本的场景）
**示例值**：true enable_exact_match | boolean | 否 | 是否支持精确匹配。默认不支持（推荐使用在短文本、需要精确查找的场景）
**示例值**：false enable_prefix_match | boolean | 否 | 是否支持前缀匹配（短文本的默认的分词/召回策略。前缀长度为 1-12）
**示例值**：false enable_number_suffix_match | boolean | 否 | 是否支持数据后缀匹配。默认不支持（推荐使用在短文本、有数字后缀查找的场景。后缀长度为3-12）
**示例值**：false enable_camel_match | boolean | 否 | 是否支持驼峰英文匹配。默认不支持（推荐使用在短文本，且包含驼峰形式英文的查找场景）
**示例值**：false display | schema_display | 是 | 数据展示相关配置 card_key | string | 是 | 搜索数据的展示卡片
卡片详细信息请参考 [通用模块接入指南](/document/uAjLw4CM/ukTMukTMukTM/search-v2/common-template-intergration-handbook) "请求创建数据范式"部分
**示例值**："search_common_card"
**可选值有**：
- search_common_card：普通 common 卡片 fields_mapping | schema_display_field_mapping\[\] | 否 | 数据字段名称和展示字段名称的映射关系。如果没有设置，则只会展示 与展示字段名称同名的 数据字段 display_field | string | 是 | 展示字段名称，与 card_key 有关，每个模版能展示的字段不同。该字段不能重复
**示例值**："summary" data_field | string | 是 | 数据字段的名称。需要确保该字段对应在 schema 属性定义中的 is_returnable 为 true，否则无法展示。需要使用 ${xxx} 的规则来描述
**示例值**："${description}" schema_id | string | 是 | 用户自定义数据范式的唯一标识
**示例值**："jira_schema"
**数据校验规则**：
- 最大长度：`40` 字符
- 正则校验：`^[a-zA-Z][a-zA-Z0-9-_].*$` ### 请求体示例 ```json { "display": { "card_key": "search_common_card", "fields_mapping": [ { "data_field": "${priority}", "display_field": "tag1" }, { "data_field": "${description}", "display_field": "summary" }, { "data_field": "创建时间：${create_time}", "display_field": "footer" } ] }, "properties": [ { "is_returnable": true, "is_searchable": true, "name": "description", "type": "text", "search_options": { "enable_camel_match": false, "enable_exact_match": false, "enable_number_suffix_match": false, "enable_prefix_match": false, "enable_semantic_match": true } }, { "is_returnable": true, "name": "icon_url", "type": "text" }, { "name": "rank", "type": "int", "sort_options": { "order": "asc", "priority": 0 } }, { "is_returnable": true, "name": "priority", "type": "tag", "type_definitions": { "tag": [ { "color": "red", "name": "HIGH", "text": "紧急" }, { "color": "green", "name": "NORMAL", "text": "正常" }, { "color": "grey", "name": "LOW", "text": "低优" } ] } } ], "schema_id": "example_schema", "validate_only": false } ``` ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- schema | schema | 数据范式实例 properties | schema_property\[\] | 数据范式的属性定义 name | string | 属性名 type | string | 属性类型
**可选值有**：
- text：长文本类型
- int：64位整数类型
- tag：标签类型
- timestamp：Unix 时间戳类型（单位为秒）
- double：浮点数类型（小数）
- tinytext：短文本类型，（utf8 编码）长度小于 140 的文本。在设置 search_options 时，与 text 类型有区别，支持更多召回策略 is_searchable | boolean | 该属性是否可用作搜索，默认为 false is_sortable | boolean | 该属性是否可用作搜索结果排序，默认为 false。如果为 true，需要再配置 sortOptions is_returnable | boolean | 该属性是否可用作返回字段，为 false 时，该字段不会被召回和展示。默认为 false sort_options | schema_sort_options | 属性排序的可选配置，当 is_sortable 为 true 时，该字段为必填字段 priority | int | 排序的优先级，可选范围为 0~4，0为最高优先级。如果优先级相同，则随机进行排序。默认为0
**可选值有**：
- 0：最高优先级
- 1：次高优先级
- 2：次次高优先级
- 3：次低优先级
- 4：最低优先级 order | string | 排序的顺序。默认为 desc
**可选值有**：
- asc：升序
- desc：降序 type_definitions | schema_type_definitions | 相关类型数据的定义和约束 tag | schema_tag_options\[\] | 标签类型的定义 name | string | tag 对应的枚举值名称 color | string | 标签对应的颜色
**可选值有**：
- red：含警示性、敏感性的提示信息
- green：表示成功、完成、完毕的提示信息
- blue：组件架构、职能等中性信息
- grey：中立系统提示信息（慎重使用）
- yellow：焦点信息、推广性信息 text | string | 标签中展示的文本 search_options | schema_search_options | 属性搜索的可选配置，当 is_searchable 为 true 时，该字段为必填参数 enable_semantic_match | boolean | 是否支持语义切词召回。默认不支持（推荐使用在长文本的场景） enable_exact_match | boolean | 是否支持精确匹配。默认不支持（推荐使用在短文本、需要精确查找的场景） enable_prefix_match | boolean | 是否支持前缀匹配（短文本的默认的分词/召回策略。前缀长度为 1-12） enable_number_suffix_match | boolean | 是否支持数据后缀匹配。默认不支持（推荐使用在短文本、有数字后缀查找的场景。后缀长度为3-12） enable_camel_match | boolean | 是否支持驼峰英文匹配。默认不支持（推荐使用在短文本，且包含驼峰形式英文的查找场景） display | schema_display | 数据展示相关配置 card_key | string | 搜索数据的展示卡片
卡片详细信息请参考 [通用模块接入指南](/document/uAjLw4CM/ukTMukTMukTM/search-v2/common-template-intergration-handbook) "请求创建数据范式"部分
**可选值有**：
- search_common_card：普通 common 卡片 fields_mapping | schema_display_field_mapping\[\] | 数据字段名称和展示字段名称的映射关系。如果没有设置，则只会展示 与展示字段名称同名的 数据字段 display_field | string | 展示字段名称，与 card_key 有关，每个模版能展示的字段不同。该字段不能重复 data_field | string | 数据字段的名称。需要确保该字段对应在 schema 属性定义中的 is_returnable 为 true，否则无法展示。需要使用 ${xxx} 的规则来描述 schema_id | string | 用户自定义数据范式的唯一标识 ### 响应体示例 ```json { "code": 0, "data": { "schema": { "display": { "card_key": "search_common_card", "fields_mapping": [ { "data_field": "${priority}", "display_field": "tag1" }, { "data_field": "${description}", "display_field": "summary" }, { "data_field": "创建时间：${create_time}", "display_field": "footer" } ] }, "properties": [ { "is_returnable": true, "is_searchable": true, "name": "description", "search_options": { "enable_camel_match": false, "enable_exact_match": false, "enable_number_suffix_match": false, "enable_prefix_match": false, "enable_semantic_match": true }, "type": "text" }, { "is_returnable": true, "name": "icon_url", "type": "text" }, { "name": "rank", "sort_options": { "order": "asc" }, "type": "int" }, { "is_returnable": true, "name": "priority", "type": "tag", "type_definitions": { "tag": [ { "color": "red", "name": "HIGH", "text": "紧急" }, { "color": "green", "name": "NORMAL", "text": "正常" }, { "color": "grey", "name": "LOW", "text": "低优" } ] } } ], "schema_id": "example_schema" } }, "msg": "success" } ``` ### 错误码 HTTP状态码 | 错误码 | 描述 | 排查建议 ---|---|---|--- 500 | 1270001 | 系统内部错误 | 联系系统开发人员协助定位 400 | 1270002 | 参数错误 | 根据错误信息和文档排查非法参数 500 | 1270003 | 调用失败 | 如果重试后仍然失败，请联系系统开发人员 400 | 1270005 | 该功能仅对旗舰版可用 | 请联系销售人员升级套餐以使用此高级功能 400 | 1274001 | 未定义的特殊字段 | 检查以下划线开头的字段是否是[_item_id,_update_time,_update_time,_title] 之一 400 | 1274002 | 定义的字段名称重复 | 修改重复字段 400 | 1274003 | 定义了特殊字段(如:_title,_create_time,_update_time)，但是类型属性未定义 | 完善对应字段的类型 400 | 1274004 | 字段可搜索属性配置错误 | 根据返回信息变更字段属性 400 | 1274005 | 字段可排序属性配置错误 | 根据返回信息变更字段属性 400 | 1274006 | 特定类型字段的type_definitions属性为空 | 完善字段 400 | 1274007 | 超过数量限制 | 根据返回信息修改请求参数 400 | 1274009 | 字段搜索表现冲突 | 字段is_searchable和is_isreturnable保持一致 400 | 1274008 | 字段和类型不匹配 | 检查字段的名称是否可以设置为对应类型 400 | 1274010 | 字段名称不符合规范 | 检查对应字段是否包含非法字符和长度是否合规