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 变量

变量	描述
index id	索引 ID

参数

变量	类型	描述	默认值
query	String	查询文本。详见 查询语言文档	必需
start_timestamp	i64	如果设置，则限制搜索 timestamp >= start_timestamp 的文档，利用潜在的时间剪枝机会。值必须以秒为单位。
end_timestamp	i64	如果设置，则限制搜索 timestamp < end_timestamp 的文档，利用潜在的时间剪枝机会。值必须以秒为单位。
start_offset	Integer	要跳过的文档数量	0
max_hits	Integer	要返回的最大命中数（默认为 20）	20
search_field	[String]	如果查询中未指定字段名称，则在此字段中进行搜索。逗号分隔列表，例如 "field1,field2"	index_config.search_settings.default_search_fields
snippet_fields	[String]	提取片段的字段。逗号分隔列表，例如 "field1,field2"
sort_by	[String]	排序查询结果的字段。您可以根据一个或两个快速字段或 BM25 _score（需要 fieldnorms）进行排序。默认情况下，命中结果按文档 ID 排序。
format	Enum	输出格式。允许的值为 "json" 或 "pretty_json"	pretty_json
aggs	JSON	聚合请求。有关支持的聚合，请参阅 聚合文档

info

start_timestamp 和 end_timestamp 应以秒为单位指定，无论时间戳字段的精度如何。

Response

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

字段	描述	类型
hits	查询结果	[hit]
num_hits	匹配总数	number
elapsed_time_micros	查询处理时间	number

搜索多个索引

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

多目标语法

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

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

• 必须遵循正则表达式 ^[a-zA-Z\*][a-zA-Z0-9-_\.\*]{0,254}$。
• 不能包含连续的星号 (*)。
• 如果包含星号 (*)，长度必须大于等于 3 个字符。

示例

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> 中所有匹配搜索查询的文档中流式传输字段值，并以以下指定的输出格式之一输出：

• CSV
• ClickHouse RowBinary。如果设置了 partition_by_field，Quickwit 会为每个分区字段值返回数据块。每个数据块以 16 字节的分区值和内容长度开始，然后是以 RowBinary 格式的 fast_field 值。

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

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

note

如果 1000 万份文档匹配查询，此终端将返回 1000 万个值。这是预期的，此终端旨在支持匹配数百万份文档的查询，并在合理的响应时间内返回字段值。

Path 变量

变量	描述
index id	索引 ID

GET 参数

变量	类型	描述	默认值
query	String	查询文本。详见 查询语言文档	必需
fast_field	String	从文档中检索的字段名称。此字段必须是类型为 i64 或 u64 的快速字段。	必需
search_field	[String]	要搜索的字段。逗号分隔列表，例如 "field1,field2"	index_config.search_settings.default_search_fields
start_timestamp	i64	如果设置，则限制搜索 timestamp >= start_timestamp 的文档。值必须以秒为单位。
end_timestamp	i64	如果设置，则限制搜索 timestamp < end_timestamp 的文档。值必须以秒为单位。
partition_by_field	String	如果设置，则终端返回每个分区字段值的数据块。此字段必须是类型为 i64 或 u64 的快速字段。
output_format	String	响应输出格式。csv 或 clickHouseRowBinary	csv

info

start_timestamp 和 end_timestamp 应以秒为单位指定，无论时间戳字段的精度如何。

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"}'

info

有效载荷大小限制为 10MB，因为此终端旨在批量接收文档。

Path 变量

变量	描述
index id	索引 ID

Query 参数

变量	类型	描述	默认值
commit	String	提交行为：auto、wait_for 或 force	auto

Response

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

字段	描述	类型
num_docs_for_processing	将要处理的文档总数。这些文档可能尚未被处理。API 不会返回索引错误，请检查服务器日志以获取错误信息。	number

索引 API

创建索引

POST api/v1/indexes

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

POST 负载

变量	类型	描述	默认值
version	String	配置格式版本，使用与您的 Quickwit 版本相同的版本。	必需
index_id	String	索引 ID，参见标识符的 验证规则。	必需
index_uri	String	定义索引文件存储的位置。此参数期望一个 存储 URI。	{default_index_root_uri}/{index_id}
doc_mapping	DocMapping	文档映射对象，具体定义参见 索引配置文档。	必需
indexing_settings	IndexingSettings	索引设置对象，具体定义参见 索引配置文档。
search_settings	SearchSettings	搜索设置对象，具体定义参见 索引配置文档。
retention	Retention	保留策略对象，具体定义参见 索引配置文档。

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。

字段	描述	类型
version	当前索引配置格式版本。	string
index_uid	服务器生成的索引 UID。	string
index_config	发布的索引配置。	IndexConfig
checkpoint	按来源划分的检查点映射。	IndexCheckpoint
create_timestamp	索引创建时间戳	number
sources	索引来源配置列表。	Array<SourceConfig>

更新索引

PUT api/v1/indexes/<index id>

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

• 保留策略更新会在下次状态刷新时被 janitor 服务自动检测。
• 搜索设置更新会在执行下一个查询时被搜索节点自动检测。
• 索引设置更新不会被索引节点自动检测，需要手动重启索引节点。
• 文档映射更新不会被索引节点自动检测，需要手动重启索引节点。

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

PUT 负载

变量	类型	描述	默认值
version	String	配置格式版本，使用与您的 Quickwit 版本相同的版本。	必需
index_id	String	索引 ID，必须与请求 URI 中的索引相同。	必需
index_uri	String	定义索引文件存储的位置。无法更新。	{current_index_uri}
doc_mapping	DocMapping	文档映射对象，具体定义参见 索引配置文档。	必需
indexing_settings	IndexingSettings	索引设置对象，具体定义参见 索引配置文档。
search_settings	SearchSettings	搜索设置对象，具体定义参见 索引配置文档。
retention	Retention	保留策略对象，具体定义参见 索引配置文档。

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。

字段	描述	类型
version	当前服务器配置版本。	string
index_uid	服务器生成的索引 UID。	string
index_config	发布的索引配置。	IndexConfig
checkpoint	按来源划分的检查点映射。	IndexCheckpoint
create_timestamp	索引创建时间戳	number
sources	索引来源配置列表。	Array<SourceConfig>

获取索引元数据

GET api/v1/indexes/<index id>

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

Response

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

字段	描述	类型
version	当前服务器配置版本。	string
index_uid	服务器生成的索引 UID。	string
index_config	发布的索引配置。	IndexConfig
checkpoint	按来源划分的检查点映射。	IndexCheckpoint
create_timestamp	索引创建时间戳	number
sources	索引来源配置列表。	Array<SourceConfig>

描述索引

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

描述 ID 为 index id 的索引。

Response

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

字段	描述	类型
index_id	索引的索引 ID	String
index_uri	索引的 URI	String
num_published_splits	已发布的切片数量	number
size_published_splits	已发布的切片大小	number
num_published_docs	已发布的文档数量	number
size_published_docs_uncompressed	已发布文档的大小（未压缩，以字节为单位）	number
timestamp_field_name	时间戳字段名称	String
min_timestamp	时间戳的起始时间	number
max_timestamp	时间戳的结束时间	number

获取切片

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

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

Path 变量

变量	描述
index id	索引 ID

查询参数

变量	类型	描述
offset	number	如果设置，限制跳过的切片数量。
limit	number	如果设置，限制检索的最大切片数量。
split_states	usize	如果设置，过滤特定的切片状态。
start_timestamp	number	如果设置，限制具有 timestamp >= start_timestamp 的文档的切片。
end_timestamp	number	如果设置，限制具有 timestamp < end_timestamp 的文档的切片。
end_create_timestamp	number	如果设置，限制创建日期在此日期之前的切片。

Response

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

字段	描述	类型
offset	偏移量	number
size	返回的切片数量	number
splits	切片列表	List

示例

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 负载

变量	类型	描述	默认值
version	String	配置格式版本，填写您当前的 Quickwit 版本。	必需
source_id	String	来源 ID。参见 ID 验证规则。	必需
source_type	String	来源类型：kafka、kinesis 或 pulsar。	必需
num_pipelines	usize	对于此来源每个节点运行的索引流水线数量。	1
params	object	如 来源配置文档 中定义的来源参数。	必需

负载示例

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 负载

变量	类型	描述
enable	bool	如果为 true 则启用来源，否则禁用它。

重置来源检查点

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

参数

名称	类型	描述	默认值
format	String	响应的输出格式：json 或 pretty_json	pretty_json

删除 API

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

创建删除任务

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

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

Path 变量

变量	描述
index id	索引 ID

POST 负载 DeleteQuery

变量	类型	描述	默认值
query	String	查询文本。参见 查询语言文档	必需
search_field	[String]	搜索字段。逗号分隔的列表，例如 "field1,field2"	index_config.search_settings.default_search_fields
start_timestamp	i64	如果设置，限制搜索具有 timestamp >= start_timestamp 的文档。值必须以秒为单位。
end_timestamp	i64	如果设置，限制搜索具有 timestamp < end_timestamp 的文档。值必须以秒为单位。

示例

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

Response

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

字段	描述	类型
create_timestamp	删除查询的创建时间戳（秒）	i64
opstamp	与删除任务关联的唯一操作标识符	u64
delete_query	发布的删除查询	DeleteQuery

获取删除查询列表

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

获取给定 index_id 的删除任务列表。

Response

响应是一个 DeleteTask 数组。