SQL查询

使用 SQL 语法执行查询操作，对 Easysearch 索引中的数据进行检索和分析。

API 格式 #

POST /_sql
POST /_sql/_explain

API 作用 #

该 API 允许用户使用 SQL 语法查询 Easysearch 索引，支持：

执行 SELECT 查询语句
获取查询执行计划（使用 /_explain 端点）
使用准备语句（Prepared Statements）和参数化查询
使用游标（Cursor）进行分页查询
多种响应格式（JSON、JDBC、CSV 等）

注意：该 API 仅支持 POST 方法，不支持 GET 方法。

API 参数 #

路径说明 #

路径	描述
`/_sql`	执行 SQL 查询
`/_sql/_explain`	获取 SQL 查询的执行计划
`/_sql/close`	关闭游标

请求体参数 #

参数	类型	是否必填	默认值	描述
`query`	String	是	-	SQL 查询语句，例如：`SELECT * FROM my_index WHERE field > 100`
`fetch_size`	Integer	否	`0`	每批获取的行数。设置为大于 0 的值时启用游标模式
`parameters`	Array	否	-	准备语句的参数数组

parameters 参数结构 #

"parameters": [
  {
    "type": "STRING",
    "value": "parameter_value"
  }
]

支持的参数类型：

STRING
KEYWORD
DATE
BOOLEAN
BYTE、SHORT、INTEGER、LONG
FLOAT、DOUBLE
NULL

查询参数 #

参数	类型	是否必填	默认值	描述
`format`	String	否	`jdbc`	响应格式。可选值：`jdbc`、`json`、`csv`、`raw`、`table`
`pretty`	Boolean	否	`false`	是否格式化 JSON 输出
`escape`	Boolean	否	`false`	是否转义特殊字符
`sanitize`	Boolean	否	`true`	是否清理输出内容

请求示例 #

基本 SQL 查询 #

POST /_sql
{
  "query": "SELECT * FROM my_index WHERE age > 25"
}

使用准备语句 #

POST /_sql
{
  "query": "SELECT * FROM my_index WHERE age > ? AND name = ?",
  "parameters": [
    {
      "type": "INTEGER",
      "value": "25"
    },
    {
      "type": "STRING",
      "value": "John"
    }
  ]
}

使用游标分页 #

POST /_sql
{
  "query": "SELECT * FROM large_index",
  "fetch_size": 1000
}

获取执行计划 #

POST /_sql/_explain
{
  "query": "SELECT count(*) FROM my_index WHERE status = 'active'"
}

响应示例 #

JDBC 格式响应（默认） #

{
  "schema": [
    {
      "name": "name",
      "alias": null,
      "type": "keyword"
    },
    {
      "name": "age",
      "alias": null,
      "type": "integer"
    }
  ],
  "datarows": [
    ["Alice", 30],
    ["Bob", 25],
    ["Charlie", 35]
  ],
  "total": 3,
  "size": 3,
  "status": 200
}

JSON 格式响应 #

{
  "hits": {
    "total": {
      "value": 3,
      "relation": "eq"
    },
    "hits": [
      {
        "_id": "1",
        "_source": {
          "name": "Alice",
          "age": 30
        }
      },
      {
        "_id": "2",
        "_source": {
          "name": "Bob",
          "age": 25
        }
      }
    ]
  }
}

游标响应 #

{
  "schema": [
    {
      "name": "id",
      "alias": null,
      "type": "long"
    }
  ],
  "datarows": [[1], [2], [3], [4], [5]],
  "cursor": "cursor_id_here",
  "total": 1000,
  "size": 5,
  "status": 200
}

执行计划响应 #

{
  "name": "ProjectOperator",
  "description": {
    "fields": "[count(*)]"
  },
  "children": [
    {
      "name": "TableScanOperator",
      "description": {
        "request": "GET my_index/_search"
      }
    }
  ]
}

响应字段说明 #

JDBC 格式响应字段 #

字段	类型	描述
`schema`	Array	结果集的列定义（字段名、类型）
`schema[].name`	String	字段名称
`schema[].type`	String	字段类型
`datarows`	Array	数据行数组，每行是一个值数组
`total`	Integer	总行数
`size`	Integer	当前返回的行数
`cursor`	String	游标 ID（用于获取下一页）
`status`	Integer	HTTP 状态码

错误响应 #

{
  "error": {
    "type": "SqlParseException",
    "reason": "Failed to parse SQL query",
    "details": "line 1:10: no viable alternative at input 'SELECT FRO'"
  },
  "status": 400
}

功能要求 #

SQL 功能需要在配置中启用：

plugins.sql.enabled = true
rest.action.multi.allow_explicit_index = true

如果任一设置为 false，API 将返回 “SQL feature disabled” 错误。

注意事项 #

仅支持 POST 方法：该 API 不支持 GET 方法，所有请求必须使用 POST
游标超时：游标有默认超时时间，超时后需要重新查询
性能考虑：复杂 SQL 查询可能消耗较多资源，建议添加适当的过滤条件
字段映射：SQL 查询中的表名对应 Easysearch 的索引名
类型转换：确保参数类型与字段类型匹配，否则可能导致查询失败

标签

查询 SQL 数据分析