Skip to main content

与 Elasticsearch 兼容的 API

In order to facilitate migrations and integrations with existing tools, Quickwit offers an Elasticsearch/Opensearch compatible API. This API is incomplete. This page lists the available features and endpoints.

支持的端点​

所有 API 端点都以 api/v1/_elastic/ 前缀开始。

_bulk   批量摄入端点​

POST api/v1/_elastic/_bulk
POST api/v1/_elastic/<index>/_bulk

批量摄入 API 可以在一个请求中索引一批文档，可能针对多个索引。

Request Body 示例​

{ "create" : { "_index" : "wikipedia", "_id" : "1" } }
{"url":"https://en.wikipedia.org/wiki?id=1","title":"foo","body":"foo"}
{ "create" : { "_index" : "wikipedia", "_id" : "2" } }
{"url":"https://en.wikipedia.org/wiki?id=2","title":"bar","body":"bar"}
{ "create" : { "_index" : "wikipedia", "_id" : "3" } }
{"url":"https://en.wikipedia.org/wiki?id=3","title":"baz","body":"baz"}'

使用 Elasticsearch 的批量 API 吞吐一批文档，使其可被搜索。此端点提供了与已经将数据发送到 Elasticsearch 进行索引的工具或系统的兼容性。目前，仅支持批量 API 的 create 操作，其他如 delete 或 update 操作被忽略。

如果通过 URL 路径指定了索引，则它将作为 _index 属性的默认值。

支持 refresh 参数。

caution

Quickwit API 不会报告错误，您需要检查服务器日志。

在 Elasticsearch 中，当摄入的文档包含标识符（_id 字段）时，create 操作具有特定的行为。它只插入之前未插入的此类文档。这对于实现 At-Most-Once 索引非常有用。 Quickwit 没有文档 ID 的概念，不支持此功能。

info

请求负载大小限制为 10MB，因为此端点旨在批量接收文档。

Query 参数​

变量类型描述默认值
refreshString提交行为：空白字符串、true、wait_for 或 falsefalse

Response​

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

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

_search   索引搜索端点​

POST api/v1/_elastic/<index_id>/_search
GET api/v1/_elastic/<index_id>/_search

Request Body 示例​

{
  "size": 10,
  "query": {
    "bool": {
      "must": [
        {
          "query_string": {
            "query": "bitpacking"
          }
        },
        {
          "term": {
            "actor.login": {
              "value": "fulmicoton"
            }
          }
        }
      ]
    }
  },
  "sort": [
    {
      "actor.id": {
        "order": null
      }
    }
  ],
  "aggs": {
    "event_types": {
      "terms": {
        "field": "type",
        "size": 5
      }
    }
  }
}

使用 Elasticsearch 搜索 API 在特定索引中进行搜索。

某些参数可以通过查询字符串参数传递，也可以通过 JSON 负载传递。 如果一个参数同时出现在查询字符串参数和 JSON 负载中，查询字符串参数的值将优先。

支持的查询字符串参数​

变量类型描述默认值
default_operatorAND 或 OR用于组合搜索项的默认运算符。应该是 AND 或 OR。OR
fromInteger返回的第一个命中结果的排名。这对分页很有用。0
qString搜索查询。（可选）
sizeInteger要返回的命中结果数量。10
sortString描述如何对文档进行排序。参见 排序顺序（可选）
scrollDuration为“存活时间”创建滚动上下文。参见 滚动（可选）

支持的请求体参数​

变量类型描述默认值
default_operator"AND" 或 "OR"用于组合搜索项的默认运算符。应该是 AND 或 OR。OR
fromInteger返回的第一个命中结果的排名。这对分页很有用。0
queryJson object描述搜索查询。参见 查询 DSL（可选）
sizeInteger要返回的命中结果数量。10
sortJsonObject[]描述如何对文档进行排序。参见 排序顺序[]
search_afterAny[]忽略排序值小于或等于参数的文档（可选）
aggsJson object聚合定义。参见 聚合{}

排序顺序​

您可以定义最多两个排序标准。第二个标准仅在第一个标准出现平局时使用。

每个标准可以是：

  • 快速字段的名称（在模式中明确定义或通过动态模式捕获）
  • _score 用于按 BM25 排序

默认情况下，快速字段的排序顺序为 ascending，而 _score 的排序顺序为 descending。

当按快速字段排序且该字段在单个文档中包含多个值时，仅使用第一个值进行排序。

可以使用以下语法设置排序顺序为 descending/ascending(降序或升序)。

{
  // ...
  "sort" : [
    { "timestamp" : {"order" : "asc"}},
    { "serial_number" : "desc" }
  ]
  // ...
}

也可以不提供排序顺序，并依赖默认顺序，使用以下语法。

{ //...
  "sort" : ["_score", "timestamp"]
  // ...
}

如果未提供时间戳格式，默认返回毫秒精度的时间戳。

如果您需要纳秒精度，可以使用 epoch_nanos_int 格式。请注意，这意味着生成的 JSON 可能包含很高的数字，在使用所有数字都是浮点数的语言（如 JavaScript）时可能会导致精度损失。

{
  // ...
  "sort" : [
    { "timestamp" : {"format": "epoch_nanos_int","order" : "asc"}},
    { "serial_number" : "desc" }
  ]
  // ...
}

#### Search after

在对结果进行排序时，响应看起来像下面这样：

```json
{
  // ...
  "hits": {
    // ...
    "hits": [
      // ...
      {
        // ...
        "sort": [
          1701962929199
        ]
      }
    ]
  }
}

您可以将最后一个命中的 sort 值传递到后续请求中，其中其他字段保持不变：

{
  // keep all fields from the original request
  "search_after": [
    1701962929199
  ]
}

这允许您对结果进行分页。

_msearch   Multi search API​

POST api/v1/_elastic/_msearch

Request Body 示例​

{"index": "gharchive" }
{"query" : {"match" : { "author.login": "fulmicoton"}}}
{"index": "gharchive"}
{"query" : {"match_all" : {}}}

多搜索端点 Elasticsearch API 参考

一次运行多个搜索请求。

请求负载应交替包含：

  • 一个 header JSON 对象，包含目标索引 ID。
  • 一个 搜索请求体，如 [_search 端点部分] 所定义。

_search/scroll   Scroll API​

GET api/v1/_elastic/_search/scroll

支持的 Request Body 参数​

变量类型描述默认值
scroll_id滚动 ID（从搜索响应中获得）必需

_search/scroll 端点与 _search API 结合使用，可以请求连续的搜索结果页面。 首先，客户端需要调用带有 scroll 查询参数的 search api，然后将响应负载中返回的 scroll_id 传递给 _search/scroll 端点。

每次后续调用 _search/scroll 端点都会返回一个新的 scroll_id，指向下一页。

_cat   Cat API​

GET api/v1/_elastic/_cat/indices/<index>
GET api/v1/_elastic/_cat/indices

支持的查询字符串参数​

变量类型描述默认值
formatString响应格式。目前仅支持 JSON。
hString[]逗号分隔的列名列表，用于显示。（可选）
healthString过滤健康状态：green、yellow 或 red。（可选）
bytesString用于显示字节值的单位。目前不支持。（可选）
sString逗号分隔的列名或列别名列表，用于对响应进行排序。目前不支持。（可选）
vBoolean如果为 true，响应包括列标题。目前不支持。（可选）

使用 cat indices API 获取集群中每个索引的以下信息：

  • 分片数量
  • 文档数量
  • 已删除文档数量
  • 主存储大小
  • 总存储大小

Response​

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

字段描述类型
uuid索引 UUIDString
index索引名称String
health索引健康状态 green、yellow 或 redString
status索引状态 openString
rep复制因子Number
pri主分片数量Number
pri.store.size主分片存储大小String
store.size索引存储大小String
dataset.size索引数据大小String
docs.count索引中的记录数量Number
docs.deleted索引中已删除的记录数量Number

示例响应：

[
  {
    "dataset.size": "0b",
    "docs.count": "0",
    "docs.deleted": "0",
    "health": "green",
    "index": "otel-traces-v0_7",
    "pri": "1",
    "pri.store.size": "0b",
    "rep": "1",
    "status": "open",
    "store.size": "0b",
    "uuid": "otel-traces-v0_7:01HTJC6TQDGM07KBDQZ2KDHW53"
  },
  {
    "dataset.size": "387.5gb",
    "docs.count": "224453081",
    "docs.deleted": "0",
    "health": "green",
    "index": "otel-logs-v0_7",
    "pri": "1",
    "pri.store.size": "37.5gb",
    "rep": "1",
    "status": "open",
    "store.size": "37.5gb",
    "uuid": "otel-logs-v0_7:01HTJC6TME1JGXBFERHZ0FJ860"
  }
]

Query DSL​

Elasticsearch Query DSL 参考.

支持以下查询类型：

query_string​

Elasticsearch 参考文档

Example​

{
  "query": {
    "query_string": {
      "query": "bitpacking AND author.login:fulmicoton",
      "fields": [
        "payload.description"
      ]
    }
  }
}

支持的参数​

变量类型描述默认值
queryString需要解析的查询语句。-
fieldsString[]（可选）默认搜索目标字段。-
default_operator"AND" 或 "OR"在没有布尔运算符的情况下定义术语是否应作为连词（AND）或析取词（OR）组合。OR
boostNumber用于得分计算的乘数增强。1.0

bool​

Elasticsearch 参考文档

示例​

{
  "query": {
    "bool": {
      "must": [
        {
          "query_string": {
            "query": "bitpacking"
          }
        }
      ],
      "must_not": {
        "term": {
          "type": {
            "value": "CommitEvent"
          }
        }
      }
    }
  }
}

支持的参数​

变量类型描述默认值
mustJsonObject[]（可选）必须匹配文档的子查询。[]
must_notJsonObject[]（可选）不得匹配文档的子查询。[]
shouldJsonObject[]（可选）应该匹配文档的子查询。[]
filterJsonObject[]类似于 must 查询，但匹配结果不影响 _score。[]
boostNumber用于得分计算的乘数增强。1.0

range​

Elasticsearch 参考文档

示例​

{
  "query": {
    "range": {
      "my_date_field": {
        "lt": "2015-02-01T00:00:13Z",
        "gte": "2015-02-01T00:00:10Z"
      }
    }
  }
}

支持的参数​

变量类型描述默认值
gtbool, string, Number（可选）大于None
gtebool, string, Number（可选）大于等于None
ltbool, string, Number（可选）小于None
ltebool, string, Number（可选）小于等于None
boostNumber用于得分计算的乘数增强1.0

match​

Elasticsearch 参考文档

示例​

{
  "query": {
    "match": {
        "type": {
            "query": "CommitEvent",
            "zero_terms_query": "all"
        }
    }
  }
}

支持的参数​

变量类型描述默认值
queryString全文搜索查询。-
operator"AND" 或 "OR"定义所有术语是否都应存在（AND）或者至少一个术语足以匹配（OR）。OR
zero_terms_queryall 或 none定义如果查询在分词后不包含任何术语时，是否返回所有文档（all）或不返回任何文档（none）。none
boostNumber用于得分计算的乘数增强。1.0

match_phrase​

Elasticsearch 参考文档

示例​

{
  "query": {
    "match_phrase": {
      "title": "search keywords",
      "analyzer": "default"
    }
  }
}

match_phrase_prefix​

Elasticsearch 参考文档

示例​

{
  "query": {
    "match_phrase_prefix": {
      "payload.commits.message": {
        "query": "automated comm" // This will match "automated commit" for instance.
      }
    }
  }
}

支持的参数​

变量类型描述默认值
queryString全文搜索查询。最后一个标记将进行前缀匹配。-
zero_terms_queryall 或 none定义如果查询在分词后不包含任何术语时，是否返回所有文档（all）或不返回任何文档（none）。none
max_expansionsInteger前缀匹配时要匹配的术语数量。50
slopInteger允许查询标记之间有额外的标记。0
analyzerString用于将查询切分为术语的分析器。建议不要使用此参数。实际字段的分词器。

match_bool_prefix​

Elasticsearch 参考文档

示例​

{
  "query": {
    "match_bool_prefix": {
      "payload.commits.message": {
        "query": "automated comm" // This will match "automated commit" for instance.
      }
    }
  }
}

与 ES/Opensearch 不同，在 Quickwit 中，搜索查询的最后一个术语作为前缀 match_bool_prefix 时，最多只会考虑 50 个术语。

支持的参数​

变量类型描述默认值
queryString全文搜索查询。最后一个标记将进行前缀匹配。-
operator"AND" 或 "OR"定义所有术语是否都应存在（AND）或者至少一个术语足以匹配（OR）。OR
zero_terms_queryall 或 none定义如果查询在分词后不包含任何术语时，是否返回所有文档（all）或不返回任何文档（none）。none

Multi-match​

Elasticsearch 参考文档

Example​

{
  "query": {
    "multi_match": {
      "query": "search keywords",
      "fields": [
        "title",
        "body"
      ]
    }
  }
}
{
  "query": {
    "multi_match": {
      "query": "search keywords",
      "type": "most_fields",
      "fields": [
        "title",
        "body"
      ]
    }
  }
}
{
  "query": {
    "multi_match": {
      "query": "search keywords",
      "type": "phrase",
      "fields": [
        "title",
        "body"
      ]
    }
  }
}
{
  "query": {
    "multi_match" : {
      "query":      "search key",
      "type":       "phrase_prefix",
      "fields":     [ "title", "body" ]
    }
  }
}

支持的多字段匹配查询​

类型描述
most_fields查找匹配任何字段的文档并结合每个字段的 _score（默认）。
phrase在每个字段上运行 match_phrase 查询。
phrase_prefix在每个字段上运行 match_phrase_prefix 查询。
bool_prefix在每个字段上运行 match_bool_prefix 查询。
warning

在 phrase、phrase_prefix 和 bool_prefix 模式下，Quickwit 会累加不同字段的得分而不是返回它们的最大值。

此外，虽然 Quickwit 不支持 best_fields 或 cross_fields，但在遇到这些类型时不会返回错误。为了兼容性原因，Quickwit 会默默地接受这些参数，并将它们解释为 most_fields 类型。

term​

Elasticsearch 参考文档

示例​

{
  "query": {
    "term": {
      "payload.commits.message": {
        "value": "automated",
        "boost": 2.0
      }
    }
  }
}

支持的参数​

变量类型描述默认值
valueString术语值。这是分词后的标记的字符串表示。-
boostNumber用于得分计算的乘数增强。1.0

match_all / match_none​

Elasticsearch 参考文档

Example​

{"match_all": {}}
{"match_none": {}}

exists​

Elasticsearch 参考文档

仅匹配给定字段包含非空值的文档的查询。

示例​

{
  "query": {
    "exists": {
      "field": "author.login"
    }
  }
}

支持的参数​

变量类型描述默认值
fieldString仅返回具有字段值的文档。-

搜索多个索引​

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

多目标语法​

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

多目标表达式有以下约束：

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

示例​

GET api/v1/_elastic/stackoverflow-000001,stackoverflow-000002/_search
{
  "query": {
    "query_string": {
      "query": "search AND engine",
      "fields": [
        "title",
        "body"
      ]
    }
  }
}
GET api/v1/_elastic/stackoverflow*/_search
{
  "query": {
    "query_string": {
      "query": "search AND engine",
      "fields": [
        "title",
        "body"
      ]
    }
  }
}