调用 CreateIndex 接口创建索引。 ## 使用说明本接口用于创建日志主题的索引。调用频率限制为 20 次/s，超出频率限制会报错 ExceedQPSLimit。 :::tip * 全文索引与键值索引至少要开启一项，索引关闭时采集的日志数据将无法被检索。 * 日志服务单词存在 32766 字符限制，对于全文或单词过长的日志，如果未开启分词符，可能导致日志被丢弃。 * 某个字段开启键值索引但未开启统计时，如果未配置分词符或者包含中文，则字段不分词。 * 某个字段开启键值索引和统计时，分词符属性不生效。 ::: ## 请求说明 * 请求方式：POST * 请求地址：https://{tls\-endpoint}/CreateIndex ## 请求参数下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见[公共参数](https://www.volcengine.com/docs/6470/112170)。 ### Body |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |TopicId |String |是 |`4a*********` |日志主题 ID。 | |FullText |Object of [FullTextInfo](#fulltextinfo) |否 |`/` |全文索引配置。|\ | | | | ||\ | | | | |* 此字段为 null 或者未配置，表示不开启全文索引。|\ | | | | |* 全文索引配置和键值索引配置至少配置一项，即 FullText 和 KeyValue 之间应至少指定一个参数。 | |KeyValue |Array of [KeyValueInfo](#keyvalueinfo) |否 |`/` |键值索引配置。|\ | | | | ||\ | | | | |* 此字段数组长度为 0 或者未配置，表示不开启键值索引。|\ | | | | |* 全文索引配置和键值索引配置至少配置一项，即 FullText 和 KeyValue 之间应至少指定一个参数。 | |UserInnerKeyValue |Array of [KeyValueInfo](#keyvalueinfo) |否 |`/` |预留字段索引配置。|\ | | | | ||\ | | | | |* 此字段数组长度为 0 或者未配置，表示不开启预留字段索引。|\ | | | | |* 不能同时开启全文索引和预留字段 `__content__` 的键值索引，即如果通过 UserInnerKeyValue 参数设置`__content__` 索引，则不能同时设置参数 FullText。|\ | | | | |* 预留字段中，目前仅支持为 `__content__` 手动开启索引。其他预留字段的索引设置请参考[预留字段](/docs/6470/1208475)。 | |MaxTextLen |Integer |否 |`2048` |统计字段值的最大长度，默认为 2048，取值范围为 64~16384，单位为字节。|\ | | | | |:::tip|\ | | | | ||\ | | | | |* 单个字段值的长度超过您所指定的最大长度时，超出部分将被截断，不参与分析。|\ | | | | |* 字段最大长度更新后，只对增量数据有效。|\ | | | | ||\ | | | | |:::| |EnableAutoIndex |Boolean |否 |`true` |是否开启索引自动更新，开启后系统将根据新出现的字段自动添加到键值索引。|\ | | | | ||\ | | | | |* true：开启自动更新。|\ | | | | |* false：不开启自动更新。 | ### FullTextInfo |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Delimiter |String |是 |`, ;/\n\t` |全文索引的分词符。|\ | | | | ||\ | | | | |* 字符串中每个字符代表一个分词符。|\ | | | | |* 长度为 1~256 字节。|\ | | | | |* 仅支持以下字符中的一种或者多种：|\ | | | | | 大小写字母、数字以及 `!@#%^&*()-_=\\\"', <>/?\|;:\n\t\r[]{}.`。|\ | | | | |* 支持同时配置包含中文和分词符。 | |CaseSensitive |Boolean |是 |`false` |是否大小写敏感。|\ | | | | ||\ | | | | |* true：大小写敏感。|\ | | | | |* false：大小写不敏感。 | |IncludeChinese |Boolean |否 |`false` |检索时，是否对日志的中文内容按照中文语法进行分词，默认为 false。|\ | | | | ||\ | | | | |* true：|\ | | | | | * 日志内的中文字符：根据常见的中文语法对日志进行分词，不支持自定义中文内容的分词符。|\ | | | | | * 日志内的非中文字符：按照**分词符**参数中指定的分词符对日志进行分词。|\ | | | | |* false：按照**分词符**参数中指定的分词符对日志进行分词。 | ### KeyValueInfo |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Key |String |是 |`"Key": "test-key1"` |需要配置键值索引的字段名称，最多添加 100 个字段。|\ | | | | ||\ | | | | |* 仅支持字母、数字、空格、下划线（_）、连字符（\-）和斜线（/），并且不支持以空格开头或结尾。|\ | | | | |* 同一个索引中 key 名称唯一。|\ | | | | |* 长度为 1~128 字符。|\ | | | | ||\ | | | | |:::tip|\ | | | | |对于 JSON 类型键值索引的子字段，需要通过.表示 JSON 字段之间的层级关系，例如 JSON 字段 namelist 中包含 text 类型的子字段 totalcount 和 JSON 类型的 info，info 中又包含字段 name，各个字段名称应分别配置为totalcount 和 info.name。|\ | | | | ||\ | | | | |:::| |Value |Object of [Value](#value) |是 |`"Value": { "ValueType": "text", "Delimiter": "", "CaseSensitive": true, "IncludeChinese": false, "SqlFlag": false }` |需要配置键值索引的字段描述信息。 | ### Value |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |SqlFlag |Boolean |否 |`false` |字段是否开启分析功能。默认为 false。|\ | | | | |开启统计分析功能后，支持配置分词符和包含中文。 | |IndexAll |Boolean |否 |`false` |是否为 JSON 字段中所有值为文本的字段创建索引。 | |JsonKeys |Array of [KeyValueInfo](#keyvalueinfo) |否 |`[ { "Key":"key1", "Value":{ "ValueType":"text", "SqlFlag":true } }, { "Key":"key2", "Value":{ "ValueType":"long", "SqlFlag":true } }, { "Key":"key3.key4.key5", "Value":{ "ValueType":"double", "SqlFlag":true } } ]` |当 ValueType 为 json 时，可通过 JsonKeys 字段配置 JSON 子字段键值索引，其值为 KeyValueInfo 数组。|\ | | | | ||\ | | | | |* JsonKeys 列表中每个元素为 KeyValueInfo，可进一步嵌套定义 text、long、double 类型子字段。|\ | | | | |* 对于 JSON 类型键值索引的子字段，需要通过`.`表示 JSON 字段之间的层级关系，例如 JSON 字段 namelist 中包含 text 类型的子字段 totalcount 和 JSON 类型的 info，info 中又包含字段 name，各个字段名称应分别配置为`totalcount` 和 `info.name`。|\ | | | | |* JsonKeys 中定义的子字段键值索引的 SqlFlag 设置应与其父字段设置保持一致，即需要同时开启或关闭，默认为关闭状态。子字段不支持单独设置 Delimiter、CaseSensitive 和 IncludeChinese，对于 text 类型的字段，CaseSensitive、Delimiter 和 IncludeChinese 固定沿用父字段设置。|\ | | | | |* 仅当 ValueType 为 json 时设置。 | |Delimiter |String |否 |`, ;/\n\t` |字段的分词符。默认为空（""）。|\ | | | | ||\ | | | | |* 字符串中每个字符代表一个分词符。|\ | | | | |* 长度为 0~256 字节，长度为 0 时表示不分词。|\ | | | | |* 仅支持以下字符中的一种或者多种：|\ | | | | | 大小写字母、数字以及 `!@#%^&*()-_=\\\"', <>/?\|;:\n\t\r[]{}.`。|\ | | | | |* 支持同时配置包含中文和分词符。 | |ValueType |String |是 |`text` |字段类型。|\ | | | | ||\ | | | | |* 目前支持 long、double、text 和 json。|\ | | | | |* long 和 double 类型不支持配置分词符、包含中文、大小写敏感。|\ | | | | |* 仅 json 类型支持进一步配置 JsonKeys 子字段。 | |CaseSensitive |Boolean |否 |`true` |是否区分大小写。默认为 false。 | |IncludeChinese |Boolean |否 |`false` |检索时，是否对日志的中文内容按照中文语法进行分词。|\ | | | | ||\ | | | | |* 启用：|\ | | | | | * 日志内的中文字符：根据常见的中文语法对日志进行分词，不支持自定义中文内容的分词符。|\ | | | | | * 日志内的非中文字符：按照**分词符**参数中指定的分词符对日志进行分词。|\ | | | | |* 未启用：按照**分词符**参数中指定的分词符对日志进行分词。 | ## 返回参数下表仅列出本接口特有的返回参数。更多信息请参见[返回结构](https://www.volcengine.com/docs/6470/112169)。 |**参数** |**类型** |**示例值** |**描述** | |---|---|---|---| |TopicId |String |`3***********` |日志主题 ID。 | ## 请求示例 1 **全文索引示例** ```json POST https://{tls-endpoint}/CreateIndex HTTP/1.1 Content-Type: application/json { "TopicId": "3***********", "FullText": { "Delimiter": ",-;", "CaseSensitive": false, "IncludeChinese": false } } ``` ## 返回示例 1 ```json HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "TopicId": "39**********" } ``` ## 请求示例 2 **全文索引和键值索引示例** ```json POST https://{tls-endpoint}/CreateIndex HTTP/1.1 Content-Type: application/json { "TopicId": "39********", "FullText": { "Delimiter": ",-;" }, "EnableAutoIndex": true, "KeyValue": [ { "Key": "test1", "Value": { "ValueType": "text", "Delimiter": "", "CaseSensitive": true, "IncludeChinese": false, "SqlFlag": false } }, { "Key": "test2", "Value": { "ValueType": "long", "Delimiter": "", "CaseSensitive": false, "IncludeChinese": false, "SqlFlag": true } }, { "Key": "test3", "Value": { "ValueType": "json", "Delimiter": "", "CaseSensitive": false, "IncludeChinese": false, "SqlFlag": true, "JsonKeys": [ { "Key": "key1", "Value": { "ValueType": "text", "SqlFlag": true } }, { "Key": "key2", "Value": { "ValueType": "long", "SqlFlag": true } }, { "Key": "key3.key4.key5", "Value": { "ValueType": "double", "SqlFlag": true } } ] } } ] } ``` ## 返回示例 2 ```json HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "TopicId": "39**********" } ``` ## 请求示例 3 **键值索引和预留字段索引示例** ```json POST https://{tls-endpoint}/CreateIndex HTTP/1.1 Content-Type: application/json { "TopicId": "39********", "EnableAutoIndex": true, "KeyValue": [ { "Key": "test1", "Value": { "ValueType": "text", "Delimiter": "", "CaseSensitive": true, "IncludeChinese": false, "SqlFlag": false } }, { "Key": "test2", "Value": { "ValueType": "long", "Delimiter": "", "CaseSensitive": false, "IncludeChinese": false, "SqlFlag": true } }, { "Key": "test3", "Value": { "ValueType": "json", "Delimiter": "", "CaseSensitive": false, "IncludeChinese": false, "SqlFlag": true, "JsonKeys": [ { "Key": "key1", "Value": { "ValueType": "text", "SqlFlag": true } }, { "Key": "key2", "Value": { "ValueType": "long", "SqlFlag": true } }, { "Key": "key3.key4.key5", "Value": { "ValueType": "double", "SqlFlag": true } } ] } } ]， "UserInnerKeyValue": [ { "Key": "__content__", "Value": { "ValueType": "json", "Delimiter": ",:-/ ", "CaseSensitive": false, "IncludeChinese": false, "SqlFlag": false, "JsonKeys": [ { "Key": "name", "Value": { "ValueType": "text", "SqlFlag": false } }, { "Key": "age", "Value": { "ValueType": "long", "SqlFlag": false } }, { "Key": "education.master.college", "Value": { "ValueType": "text", "SqlFlag": false } } ] } } ] } ``` ## 返回示例 3 ```json HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "TopicId": "39**********" } ``` ## 错误码下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见[公共错误码](https://www.volcengine.com/docs/6470/112173)文档。 |**HTTP 状态码** |**错误码** |**错误信息** |**说明** | |---|---|---|---| |400 |InvalidArgument |Invalid argument key %s, value %s, please check argument. |分词符和中分分词不能同时配置。 | |400 |InvalidArgument |At least one of full\-text indexing and key\-value indexing must be turned on. |全文索引与键值索引至少要开启一项。 | |400 |InvalidArgument |Index key value_type:%s conflict with [includeChinese:%t, casSensitive:%t, delimiter:%s], please check argument. |long/double 类型不支持配置包含中文、大小写敏感和分词符。 | |400 |InvalidIndexJsonKeys |Non\-JSON field %s configures JsonKeys, please check argument. |非 JSON 字段配置子字段 | |400 |ConflictIndexJsonKeys |JsonKeys %s and %s have conflict prefix, please check argument. |JsonKeys 键名存在前缀冲突 | |400 |InvalidArgument |Index key sqlFlag:%t conflict with [includeChinese:%t, delimiter:%s], please check argument. |开启统计后，不支持配置包含中文和分词符。 | |400 |IndexKeyValueQuotaExceed |Exceeded index key\-value quota. |超过键值索引限额。 | |400 |IndexKeyDuplicate |The %dth index key name:%s is duplicate, please check argument. |索引的键值名称重复。 | |400 |InvalidArgument |Index key delimiter:%s conflict with includeChinese:%t, please check argument. |分词符和中分分词不能同时配置。 | |400 |IndexKVNULL |Index key value index is open, but the key value list is null, please check argument. |键值索引配置的键值个数为 0。 | |404 |TopicNotExist |Topic does not exist. |日志主题不存在。 | |409 |IndexAlreadyExist |Index already exist |Index 已存在。 | |500 |InternalServerError |We encountered an unexpected server error, please try again later. |服务器内部错误。 | |400 |IndexInnerKeyUnSupport |key\-value indexing for inner key: %v, doesn't support |不支持为 %v 字段设置预留字段索引。 | |400 |IndexInnerKeyConflict |full\-text indexing and content indexing can't be set together |全文索引与__content__索引配置冲突。 |