RESTful 与 Query DSL #

Easysearch 通过 RESTful API 提供所有功能，使用 JSON 格式的 Query DSL 描述查询逻辑。理解这两个基础概念，是使用 Easysearch 的第一步。

RESTful API 约定 #

Easysearch 的所有操作都通过 HTTP 请求完成，遵循 RESTful 风格：

HTTP 方法	含义	示例
`GET`	读取	`GET /my-index/_search`
`PUT`	创建或全量更新	`PUT /my-index`
`POST`	创建或部分更新	`POST /my-index/_doc`
`DELETE`	删除	`DELETE /my-index`

请求结构 #

一个典型的 Easysearch 请求由三部分组成：

<HTTP方法> /<索引>/<操作>
{
  <JSON请求体>
}

例如，在 products 索引中搜索 “手机”：

GET /products/_search
{
  "query": {
    "match": {
      "title": "手机"
    }
  }
}

常用端点 #

端点	说明
`/_cat/health`	集群健康状态（文本格式）
`/_cluster/health`	集群健康状态（JSON）
`/_cat/indices`	索引列表
`/<index>/_search`	搜索
`/<index>/_doc/<id>`	读写单条文档
`/_bulk`	批量操作
`/_analyze`	分词测试

响应结构 #

每个搜索响应都包含以下关键字段：

{
  "took": 5,                    // 耗时（毫秒）
  "timed_out": false,           // 是否超时
  "hits": {
    "total": { "value": 42 },   // 命中总数
    "max_score": 1.5,           // 最高评分
    "hits": [                   // 命中的文档列表
      {
        "_index": "products",
        "_id": "1",
        "_score": 1.5,
        "_source": { ... }      // 原始文档
      }
    ]
  }
}

Query DSL 概览 #

Query DSL（Domain Specific Language）是 Easysearch 的查询语言，使用 JSON 结构描述查询条件。所有查询都放在 query 字段中。

两类查询上下文 #

上下文	关键字	作用	是否计算评分
查询上下文	`query`	文档与查询的匹配程度	是
过滤上下文	`filter`	文档是否匹配（是/否）	否（可缓存）

能用 filter 的场景尽量用 filter，不计算评分 + 可缓存 = 更快。

基础查询类型 #

match — 全文搜索 #

对输入文本分词后查询，是最常用的全文查询：

{
  "query": {
    "match": {
      "content": "分布式搜索引擎"
    }
  }
}

term — 精确匹配 #

不分词，精确匹配 keyword 字段：

{
  "query": {
    "term": {
      "status": "published"
    }
  }
}

range — 范围查询 #

{
  "query": {
    "range": {
      "price": { "gte": 100, "lte": 500 }
    }
  }
}

bool — 组合查询 #

通过 must / should / must_not / filter 组合多个条件：

{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "手机" } }
      ],
      "filter": [
        { "range": { "price": { "lte": 3000 } } },
        { "term": { "brand": "xiaomi" } }
      ]
    }
  }
}

match 与 term 的区别 #

	match	term
分词	会对输入分词	不分词
适用字段	`text`	`keyword`、数值、日期
典型场景	全文搜索	过滤、精确查找

分页与排序 #

{
  "query": { "match_all": {} },
  "from": 0,
  "size": 10,
  "sort": [
    { "created_at": "desc" },
    "_score"
  ]
}

from + size：适合浅分页（前几百页）
search_after：适合深分页
scroll：适合批量导出

高亮 #

{
  "query": {
    "match": { "content": "搜索引擎" }
  },
  "highlight": {
    "fields": {
      "content": {}
    }
  }
}

响应中的高亮片段：

"highlight": {
  "content": ["分布式<em>搜索引擎</em>的核心原理"]
}

聚合（简介） #

聚合用于统计分析，可与查询组合：

{
  "size": 0,
  "aggs": {
    "brand_count": {
      "terms": { "field": "brand.keyword" }
    }
  }
}

详见聚合分析。