REST API

API 版本 ​

所有 API 终端都以 api/v1/ 前缀开始。 v1 表示我们当前正在使用 API 的第 1 版。

OpenAPI 规范 ​

REST API 的 OpenAPI 规范可在 /openapi.json 访问，Swagger UI 版本可在 /ui/api-playground 访问。

参 数 ​

URL 中传递的参数必须正确进行 URL 编码，对于非 ASCII 字符使用 UTF-8 编码。

GET [..]/search?query=barack%20obama

错误处理 ​

成功的请求返回 2xx HTTP 状态码。

失败的请求返回 4xx HTTP 状态码。失败请求的响应体包含一个 JSON 对象，其中有一个描述错误的 message 字段。

{
 "message": "Failed to parse query"
}

搜索 API ​

在索引中搜索 ​

在给定索引 api/v1/<index id>/search 中搜索与查询匹配的文档。只要集群中至少有一个运行搜索服务的节点，此终端就可用。 搜索终端接受 GET 和 POST 请求。 参数 对于 GET 请求是 URL 参数，而对于 POST 请求是 JSON 键值对。

GET api/v1/<index id>/search?query=searchterm

POST api/v1/<index id>/search




    

{
  "query": searchterm
}

Path 变量 ​

Response ​

响应是一个 JSON 对象，内容类型为 application/json; charset=UTF-8 。

搜索多个索引 ​

接受 index id 请求路径参数的搜索 API 也支持多目标语法。

多目标语法 ​

在多目标语法中，您可以使用逗号或其 URL 编码版本 '%2C' 分隔的列表来在多个索引上运行请求：test1,test2,test3。您也可以使用 glob-like 通配符 ( * ) 表达式来针对符合模式的索引：test* 或 test 或 te t 或 test 。

以下是关于多目标表达式的几个约束条件。

GET api/v1/stackoverflow-000001,stackoverflow-000002/search
{
    "query": "search AND engine",
}

GET api/v1/stackoverflow*/search
{
    "query": "search AND engine",
}

在索引中搜索流 ​

GET api/v1/<index id>/search/stream?query=searchterm&fast_field=my_id

从目标索引 <index id> 中所有匹配搜索查询的文档中流式传输字段值，并以以下指定的输出格式之一输出：

fast_field 和 partition_by_field 必须是类型为 i64 或 u64 的快速字段。

只要集群中至少有一个运行搜索服务的节点，此终端就可用。

Path 变量 ​

GET 参数 ​

Response ​

响应是一个 HTTP 流。根据客户端的能力，它可能是 HTTP1.1 分块传输编码流 或 HTTP2 流。

它返回所有匹配查询的文档中的字段值列表。字段必须在索引配置中标记为“快速”才能生效。 格式基于指定的输出格式。

如果出现错误，将通过尾部通道发送包含错误信息的 "X-Stream-Error" 标头，并通过 sender.abort() 关闭流。 根据客户端的不同，带有错误详情的尾部标头可能不会显示。错误也会在 quickwit 中记录（“流式传输搜索结果时出错”）。

向索引中导入数据 ​

POST api/v1/<index id>/ingest -d \
'{"url":"https://en.wikipedia.org/wiki?id=1","title":"foo","body":"foo"}
{"url":"https://en.wikipedia.org/wiki?id=2","title":"bar","body":"bar"}
{"url":"https://en.wikipedia.org/wiki?id=3","title":"baz","body":"baz"}'

向给定的 <index id> 导入一批文档，使其可被搜索。目前，NDJSON 是唯一接受的有效载荷格式。此终端仅在运行索引服务的节点上可用。

控制索引文档何时可用于搜索 ​

新添加的文档直到被添加到一个切片并提交该切片后才会出现在搜索结果中。这个过程是自动的，并由 split_num_docs_target 和 commit_timeout_secs 参数控制。默认情况下，导入命令会在记录被添加到索引队列后立即退出，这意味着此时新文档不会出现在搜索结果中。可以通过在查询中添加 commit=wait_for 或 commit=force 参数来改变这种行为。 wait_for 参数会使命令等待文档根据 标准时间和文档数量规则被提交。 force 参数会在处理完请求中的所有文档后触发一次提交，并且在返回前等待此次提交完成。请注意， force 选项可能会导致显著的性能开销，特别是在用于小批量文档时。

POST api/v1/<index id>/ingest?commit=wait_for -d \
'{"url":"https://en.wikipedia.org/wiki?id=1","title":"foo","body":"foo"}
{"url":"https://en.wikipedia.org/wiki?id=2","title":"bar","body":"bar"}
{"url":"https://en.wikipedia.org/wiki?id=3","title":"baz","body":"baz"}'

Path 变量 ​

Query 参数 ​

Response ​

响应是一个 JSON 对象，内容类型为 application/json; charset=UTF-8 。

索引 API ​

创建索引 ​

POST api/v1/indexes

通过发布 IndexConfig 负载来创建索引。API 接受带有 content-type: application/json 的 JSON 和带有 content-type: application/yaml 的 YAML。

POST 负载 ​

Payload Example

curl -XPOST http://localhost:7280/api/v1/indexes --data @index_config.json -H "Content-Type: application/json"

{
    "version": "0.8",
    "index_id": "hdfs-logs",
    "doc_mapping": {
        "field_mappings": [
            {
                "name": "tenant_id",
                "type": "u64",
                "fast": true
            },
            {
                "name": "app_id",
                "type": "u64",
                "fast": true
            },
            {
                "name": "timestamp",
                "type": "datetime",
                "input_formats": ["unix_timestamp"],
                "fast_precision": "seconds",
                "fast": true
            },
            {
                "name": "body",
                "type": "text",
                "record": "position"
            }
        ],
        "partition_key": "tenant_id",
        "max_num_partitions": 200,
        "tag_fields": ["tenant_id"],
        "timestamp_field": "timestamp"
    },
    "search_settings": {
        "default_search_fields": ["body"]
    },
    "indexing_settings": {
        "merge_policy": {
            "type": "limit_merge",
            "max_merge_ops": 3,
            "merge_factor": 10,
            "max_merge_factor": 12
        }
    },
    "retention": {
        "period": "7 days",
        "schedule": "@daily"
    }
}

Response ​

响应是创建的索引的元数据，内容类型为 application/json; charset=UTF-8 。

更新索引 ​

PUT api/v1/indexes/<index id>

更新索引的配置。此终端遵循 PUT 语义，这意味着当前配置的所有字段将被此请求中指定的值或相关默认值替换。特别是，如果字段是可选的（例如 retention_policy ），省略它将会删除相关的配置。如果新的配置文件包含无法应用的更新，则请求失败，且不应用任何更新。API 接受带有 content-type: application/json 的 JSON 和带有 content-type: application/yaml 的 YAML。

更新文档映射不会重新索引现有数据。在查询旧切片时，查询和答案会尽力进行映射。 此外，无法更新时间戳字段，也无法修改或移除现有的非默认分词器（但可以更改字段使用的分词器）。

PUT 负载 ​

Payload Example

curl -XPUT http://localhost:7280/api/v1/indexes/hdfs-logs --data @updated_index_update.json -H "Content-Type: application/json"

{
    "version": "0.8",
    "index_id": "hdfs-logs",
    "doc_mapping": {
        "field_mappings": [
            {
                "name": "tenant_id",
                "type": "u64",
                "fast": true
            },
            {
                "name": "app_id",




    

                "type": "u64",
                "fast": true
            },
            {
                "name": "timestamp",
                "type": "datetime",
                "input_formats": ["unix_timestamp"],
                "fast_precision": "seconds",
                "fast": true
            },
            {
                "name": "body",
                "type": "text",
                "record": "position"
            }
        ],
        "partition_key": "tenant_id",
        "max_num_partitions": 200,
        "tag_fields": ["tenant_id"],
        "timestamp_field": "timestamp"
    },
    "search_settings": {
        "default_search_fields": ["body"]
    },
    "indexing_settings": {
        "merge_policy": {
            "type": "limit_merge",
            "max_merge_ops": 3,
            "merge_factor": 10,
            "max_merge_factor": 12
        }
    },
    "retention": {
        "period": "30 days",
        "schedule": "@daily"
    }
}

Response ​

响应是更新后的索引的元数据，内容类型为 application/json; charset=UTF-8 。

获取索引元数据 ​

GET api/v1/indexes/<index id>

获取 ID 为 index id 的索引元数据。

Response ​

响应是请求的索引元数据，内容类型为 application/json; charset=UTF-8 。

描述索引 ​

GET api/v1/indexes/<index id>/describe

描述 ID 为 index id 的索引。

Response ​

响应是请求的索引统计信息，内容类型为 application/json; charset=UTF-8 。

获取切片 ​

GET api/v1/indexes/<index id>/splits

获取 ID 为 index id 的索引的切片。

Path 变量 ​

查询参数 ​

Response ​

响应是请求的索引统计信息，内容类型为 application/json; charset=UTF-8 。

GET /api/v1/indexes/stackoverflow/splits?offset=0&limit=10

{
  "offset": 0,
  "size": 1,
  "splits": [
    {
      "split_state": "Published",
      "update_timestamp": 1695642901,
      "publish_timestamp": 1695642901,
      "version": "0.7",
      "split_id": "01HB632HD8W6WHNM7CZFH3KG1X",
      "index_uid": "stackoverflow:01HB6321TDT3SP58D4EZP14KSX",
      "partition_id": 0,
      "source_id": "_ingest-api-source",
      "node_id": "jerry",
      "num_docs": 10000,
      "uncompressed_docs_size_in_bytes": 6674940,
      "time_range": {
        "start": 1217540572,
        "end": 1219335682
      },
      "create_timestamp": 1695642900,
      "maturity": {
        "type": "immature",
        "maturation_period_millis": 172800000
      },
      "tags": [],
      "footer_offsets": {
        "start": 4714989,
        "end": 4719999
      },
      "delete_opstamp": 0,
      "num_merge_ops": 0
    }
  ]
}

清空索引 ​

PUT api/v1/indexes/<index id>/clear

清空 ID 为 index id 的索引：所有切片将被删除（元存储 + 存储），并且所有来源检查点将被重置。

返回一个空的响应体。

删除索引 ​

DELETE api/v1/indexes/<index id>

删除 ID 为 index id 的索引。

Response ​

响应是已删除的切片文件列表；内容类型为 application/json; charset=UTF-8 。

[
    {
        "split_id": "01GK1XNAECH7P14850S9VV6P94",
        "num_docs": 1337,
        "uncompressed_docs_size_bytes": 23933408,
        "file_name": "01GK1XNAECH7P14850S9VV6P94.split",
        "file_size_bytes": 2991676
    }
]

获取所有索引元数据 ​

GET api/v1/indexes

检索元存储中存在的所有索引的元数据。

Response ​

响应是一个 IndexMetadata 数组，内容类型为 application/json; charset=UTF-8 。

创建来源 ​

POST api/v1/indexes/<index id>/sources

通过发布来源配置 JSON 负载来创建来源。

POST 负载 ​

curl -XPOST http://localhost:7280/api/v1/indexes/my-index/sources --data @source_config.json -H "Content-Type: application/json"

{
    "version": "0.8",
    "source_id": "kafka-source",
    "source_type": "kafka",
    "params": {
        "topic": "quickwit-fts-staging",
        "client_params": {
            "bootstrap.servers": "kafka-quickwit-server:9092"
        }
    }
}

Response ​

响应是创建的来源配置，内容类型为 application/json; charset=UTF-8 。

切换来源 ​

PUT api/v1/indexes/<index id>/sources/<source id>/toggle

切换（启用/禁用）ID 为 index id 的索引中的来源 source id 。

返回一个空的响应体。

PUT 负载 ​

重置来源检查点 ​

PUT api/v1/indexes/<index id>/sources/<source id>/reset-checkpoint

重置 ID 为 index id 的索引中的来源 source id 的检查点。

返回一个空的响应体。

删除来源 ​

DELETE api/v1/indexes/<index id>/sources/<source id>

删除 ID 为 <source id> 的来源。

集群 API ​

此端点允许您从处理请求的节点的角度检查集群的状态。

GET api/v1/cluster?format=pretty_json

删除 API ​

删除 API 允许删除匹配查询的文档。

创建删除任务 ​

POST api/v1/<index id>/delete-tasks

创建一个删除任务，该任务将删除给定索引 <index id> 中与提供的查询匹配的所有文档。 此端点仅将您的删除任务添加到元存储中的删除任务队列中。删除操作最终会被执行。

Path 变量 ​

POST 负载 DeleteQuery ​

{
    "query": "body:trash",
    "start_timestamp": "1669738645",
    "end_timestamp": "1669825046",
}

Response ​

响应是创建的删除任务的 JSON 表示， DeleteTask ，内容类型为 application/json; charset=UTF-8 。