---
title: "SQL查询"
date: 2026-02-18
lastmod: 2026-02-18
description: "使用SQL语法查询索引数据"
tags: ["查询", "SQL", "数据分析"]
summary: "使用 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" } ] 支持的参数类型："
---


使用 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 参数结构

```json
"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 查询

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

### 使用准备语句

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

### 使用游标分页

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

### 获取执行计划

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

## 响应示例

### JDBC 格式响应（默认）

```json
{
  "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 格式响应

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

### 游标响应

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

### 执行计划响应

```json
{
  "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 状态码 |

## 错误响应

```json
{
  "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" 错误。

## 注意事项

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