调用 ModifyIndex 接口修改索引配置。 ## 使用说明本接口用于修改日志主题的索引配置信息。调用频率限制为 20 次/s，超出频率限制会报错 ExceedQPSLimit。 :::tip * 全文索引与键值索引至少要开启一项，索引关闭时采集的日志数据将无法被检索。 * 日志服务单词存在 32766 字符限制，对于全文或单词过长的日志，如果未开启分词符，可能导致日志被丢弃。 * 配置索引后可以随时修改索引，修改索引时请注意： * 如果修改索引，新索引仅对修改之后采集到的新数据生效，已构建好的旧数据索引不会更新。 * 检索和分析仅基于一种索引规则。因此，修改索引配置可能会导致之前相同的查询分析语句计算出不同结果，因为新的索引配置导致查询分析的数据范围发生了变化。 ::: ## 请求说明 * 请求方式：PUT * 请求地址：https://{tls\-endpoint}/ModifyIndex ## 请求参数下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见[公共参数](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` |检索时，是否对日志的中文内容按照中文语法进行分词。|\ | | | | ||\ | | | | |* 启用：|\ | | | | | * 日志内的中文字符：根据常见的中文语法对日志进行分词，不支持自定义中文内容的分词符。|\ | | | | | * 日志内的非中文字符：按照**分词符**参数中指定的分词符对日志进行分词。|\ | | | | |* 未启用：按照**分词符**参数中指定的分词符对日志进行分词。 | |IndexSQLAll |Boolean |否 |`false` |是否为 JSON 字段开启自动索引和统计功能。|\ | | | | ||\ | | | | |* `true`：开启自动索引和统计功能。|\ | | | | |* `false`：不开启自动索引和统计功能。 | |AutoIndexFlag |Boolean |否 |`false` |该索引是否是自动索引添加。|\ | | | | ||\ | | | | |* true：该索引为自动添加。|\ | | | | |* false：该索引非自动添加。 | ## 返回参数本接口无特有的返回参数。更多信息请见[返回结构](https://www.volcengine.com/docs/6470/112169)。 ## 请求示例 1 **全文索引示例** ```JSON PUT https://{tls-endpoint}/ModifyIndex 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 {} ``` ## 请求示例 2 **全文索引和键值索引示例** ```JSON PUT https://{tls-endpoint}/ModifyIndex HTTP/1.1 Content-Type: application/json { "TopicId": "4a*********", "FullText": { "Delimiter": ", ;/\\n\\t", "CaseSensitive": false, "IncludeChinese": false }, "KeyValue": [ { "Key": "test-key1", "Value": { "ValueType": "text", "Delimiter": "", "CaseSensitive": true, "IncludeChinese": false, "SqlFlag": false, "IndexAll": false, "JsonKeys": [], "IndexSQLAll": false, "AutoIndexFlag": false } } ], "UserInnerKeyValue": [ { "Key": "__content__", "Value": { "ValueType": "text", "Delimiter": "", "CaseSensitive": true, "IncludeChinese": false, "SqlFlag": false, "IndexAll": false, "JsonKeys": [], "IndexSQLAll": false, "AutoIndexFlag": false } } ], "MaxTextLen": 2048, "EnableAutoIndex": true } ``` ## 返回示例 2 ```JSON HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {} ``` ## 请求示例 3 **键值索引和预留字段索引示例** ```JSON PUT https://{tls-endpoint}/ModifyIndex HTTP/1.1 Content-Type: application/json { "TopicId": "4a*********", "FullText": { "Delimiter": ", ;/\\n\\t", "CaseSensitive": false, "IncludeChinese": false }, "KeyValue": [ { "Key": "test-key1", "Value": { "ValueType": "text", "Delimiter": "", "CaseSensitive": true, "IncludeChinese": false, "SqlFlag": false, "IndexAll": false, "JsonKeys": [], "IndexSQLAll": false, "AutoIndexFlag": false } } ], "UserInnerKeyValue": [], "MaxTextLen": 2048, "EnableAutoIndex": true } ``` ## 返回示例 3 ```JSON HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 {} ``` ## 错误码下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见[公共错误码](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 |索引已存在。 | |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__索引配置冲突。 |