SQL 查询 #

Easysearch SQL 插件让熟悉关系型数据库的用户无需学习 Query DSL 即可查询数据。插件将 SQL 语句翻译为原生 Easysearch DSL 执行，支持丰富的 SQL 语法——包括聚合、JOIN、子查询、全文搜索函数、窗口函数等。

快速开始 #

POST /_sql
{
  "query": "SELECT firstname, lastname, balance FROM accounts WHERE balance > 10000 ORDER BY balance DESC LIMIT 10"
}

响应（JDBC 格式，默认）：

{
  "schema": [
    {"name": "firstname", "type": "text"},
    {"name": "lastname", "type": "text"},
    {"name": "balance", "type": "long"}
  ],
  "datarows": [
    ["Amber", "Duke", 39225],
    ["Nanette", "Bates", 32838]
  ],
  "total": 2,
  "size": 2,
  "status": 200
}

REST API #

查询端点 #

方法	路径	说明
POST	`/_sql`	执行 SQL 查询
POST	`/_sql/_explain`	将 SQL 翻译为 Easysearch DSL（不执行）
POST	`/_sql/_cursor/close`	关闭游标/Scroll 上下文

请求体 #

POST /_sql
{
  "query": "SELECT * FROM my_index WHERE age > 30",
  "fetch_size": 50
}

参数	类型	说明
`query`	String	SQL 查询语句
`fetch_size`	Integer	游标分页大小。为 0 或不传时返回全部结果；大于 0 时启用游标分页
`cursor`	String	游标 ID，用于获取后续分页结果
`parameters`	Array	预编译参数（预留）

查询参数 #

通过 URL 参数控制输出格式和行为：

参数	说明
`format`	输出格式：`jdbc`（默认）、`json`、`csv`、`raw`/`txt`
`pretty`	美化 JSON 输出
`flat`	控制字段展平方式
`separator`	CSV 分隔符
`_score`	是否在结果中包含相关性评分
`_id`	是否在结果中包含文档 ID
`_type`	是否在结果中包含文档类型

输出格式 #

JDBC 格式（默认）——结构化 JSON，含 schema 元信息：

POST /_sql
{
  "query": "SELECT firstname, age FROM accounts LIMIT 2"
}

{
  "schema": [
    {"name": "firstname", "type": "text"},
    {"name": "age", "type": "integer"}
  ],
  "datarows": [
    ["Amber", 32],
    ["Hattie", 36]
  ],
  "total": 2, "size": 2, "status": 200
}

CSV 格式：

POST /_sql?format=csv
{
  "query": "SELECT firstname, age FROM accounts LIMIT 2"
}

firstname,age
Amber,32
Hattie,36

纯文本表格（raw 或 txt）：

POST /_sql?format=raw
{
  "query": "SELECT firstname, age FROM accounts LIMIT 2"
}

firstname | age
----------+----
Amber     | 32
Hattie    | 36

查询执行计划 #

使用 _explain 端点查看 SQL 如何被翻译为 Easysearch DSL：

POST /_sql/_explain
{
  "query": "SELECT firstname FROM accounts WHERE age > 30"
}

{
  "from": 0,
  "size": 200,
  "query": {
    "bool": {
      "filter": [{
        "bool": {
          "must": [{
            "range": {
              "age": {"from": 30, "include_lower": false}
            }
          }]
        }
      }]
    }
  },
  "_source": {
    "includes": ["firstname"]
  }
}

游标分页 #

对于大结果集，使用 fetch_size 启用游标分页（基于 Scroll API 实现）：

POST /_sql
{
  "query": "SELECT * FROM my_index ORDER BY timestamp",
  "fetch_size": 100
}

响应中包含 cursor 字段：

{
  "schema": [...],
  "datarows": [...],
  "cursor": "d:eyJhIjp7fSwi..."
}

获取下一页：

POST /_sql
{
  "cursor": "d:eyJhIjp7fSwi..."
}

当所有数据返回完毕后，响应中不再包含 cursor 字段。也可以主动关闭游标释放服务端资源：

POST /_sql/_cursor/close
{
  "cursor": "d:eyJhIjp7fSwi..."
}

支持的 SQL 语句 #

语句	说明
`SELECT`	数据检索，完整语法支持（WHERE、GROUP BY、HAVING、ORDER BY、LIMIT、子查询、JOIN、窗口函数等）
`SHOW TABLES LIKE`	列出匹配模式的索引
`DESCRIBE TABLES LIKE ... COLUMNS LIKE`	查看索引字段映射
`DELETE`	按条件删除文档（默认禁用，需手动开启）

SHOW 语句 #

列出匹配模式的索引：

SHOW TABLES LIKE 'account%'

DESCRIBE 语句 #

查看索引字段映射，可用 COLUMNS LIKE 过滤字段名：

DESCRIBE TABLES LIKE 'accounts' COLUMNS LIKE '%name%'

DELETE 语句 #

⚠️ DELETE 默认禁用，需设置 easysearch.sql.delete.enabled: true 后方可使用。

DELETE FROM accounts WHERE age > 50

数据类型映射 #

SQL 类型	Easysearch 类型	说明
`BOOLEAN`	`boolean`	布尔值
`BYTE`	`byte`	8 位整数
`SHORT`	`short`	16 位整数
`INTEGER`	`integer`	32 位整数
`LONG`	`long`	64 位整数
`FLOAT`	`float`	单精度浮点数
`DOUBLE`	`double`	双精度浮点数
`STRING`	`keyword`	精确值字符串
`TEXT`	`text`	全文分析字符串
`DATE`	`date`	日期
`TIME`	—	时间
`DATETIME` / `TIMESTAMP`	`date`	日期时间
`OBJECT`	`object`	嵌套 JSON 对象
`NESTED`	`nested`	嵌套文档数组
`GEO_POINT`	`geo_point`	经纬度坐标
`IP`	`ip`	IP 地址
`BINARY`	`binary`	二进制数据

类型之间的隐式转换遵循层级关系：BYTE → SHORT → INTEGER → LONG → FLOAT → DOUBLE。可通过 CAST() 函数进行显式类型转换。

插件设置 #

设置项	类型	默认值	说明
`easysearch.sql.enabled`	Boolean	`true`	启用/禁用 SQL 插件
`easysearch.sql.slowlog`	Integer	`2`（秒）	慢查询日志阈值
`easysearch.sql.cursor.keep_alive`	TimeValue	`1m`	游标 Scroll 上下文保持时间
`easysearch.sql.delete.enabled`	Boolean	`false`	是否允许 DELETE 语句
`easysearch.sql.query.size_limit`	Integer	`200`	默认结果集大小上限
`easysearch.sql.query.response.format`	String	`jdbc`	默认响应格式
`easysearch.sql.metrics.rollingwindow`	Long	`3600`（秒）	指标统计滚动窗口
`easysearch.sql.metrics.rollinginterval`	Long	`60`（秒）	指标统计滚动间隔

以上设置均为动态设置，支持运行时更新：

PUT /_sql/settings
{
  "persistent": {
    "easysearch.sql.enabled": true,
    "easysearch.sql.slowlog": 5,
    "easysearch.sql.query.size_limit": 500
  }
}

文档导航 #

基础查询：SELECT、FROM、WHERE、ORDER BY、LIMIT 等基本语法
全文搜索：在 SQL 中使用 MATCH、SCORE 等全文搜索函数
复杂查询：子查询、JOIN、CASE WHEN 等高级语法
聚合查询：GROUP BY、HAVING、聚合函数、FILTER 子句
内置函数：数学、字符串、日期、条件、类型转换函数参考
SQL-JDBC：通过 JDBC 驱动连接 Easysearch