Link Search Menu Expand Document Documentation Menu
文档

响应格式

SQL 插件提供 `jdbc`、`csv`、`raw` 和 `json` 响应格式，这些格式可用于不同的目的。`jdbc` 格式被广泛使用，因为它提供了模式信息并增加了更多功能，例如分页。除了 JDBC 驱动程序，各种客户端都可以从详细且格式良好的响应中受益。

JDBC 格式

默认情况下，SQL 插件以标准 JDBC 格式返回响应。此格式适用于需要良好格式化模式和结果集的 JDBC 驱动程序和客户端。

请求示例

以下查询未指定响应格式，因此格式设置为 `jdbc`

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

示例响应

在响应中，`schema` 包含字段名称和类型，`datarows` 字段包含结果集

{
  "schema": [{
      "name": "firstname",
      "type": "text"
    },
    {
      "name": "lastname",
      "type": "text"
    },
    {
      "name": "age",
      "type": "long"
    }
  ],
  "total": 4,
  "datarows": [
    [
      "Nanette",
      "Bates",
      28
    ],
    [
      "Amber",
      "Duke",
      32
    ]
  ],
  "size": 2,
  "status": 200
}

如果发生任何类型的错误，OpenSearch 会返回错误消息。

以下查询搜索不存在的字段 `unknown`

POST /_plugins/_sql
{
  "query" : "SELECT unknown FROM accounts"
}

响应包含错误消息和错误原因

{
  "error": {
    "reason": "Invalid SQL query",
    "details": "Field [unknown] cannot be found or used here.",
    "type": "SemanticAnalysisException"
  },
  "status": 400
}

OpenSearch DSL JSON 格式

如果将格式设置为 `json`，原始 OpenSearch 响应将以 JSON 格式返回。由于这是 OpenSearch 的原生响应，因此需要额外的努力来解析和解释它。

请求示例

以下查询将响应格式设置为 `json`

POST _plugins/_sql?format=json
{
  "query" : "SELECT firstname, lastname, age FROM accounts ORDER BY age LIMIT 2"
}

示例响应

响应是 OpenSearch 的原始响应

{
  "_shards": {
    "total": 5,
    "failed": 0,
    "successful": 5,
    "skipped": 0
  },
  "hits": {
    "hits": [{
        "_index": "accounts",
        "_type": "account",
        "_source": {
          "firstname": "Nanette",
          "age": 28,
          "lastname": "Bates"
        },
        "_id": "13",
        "sort": [
          28
        ],
        "_score": null
      },
      {
        "_index": "accounts",
        "_type": "account",
        "_source": {
          "firstname": "Amber",
          "age": 32,
          "lastname": "Duke"
        },
        "_id": "1",
        "sort": [
          32
        ],
        "_score": null
      }
    ],
    "total": {
      "value": 4,
      "relation": "eq"
    },
    "max_score": null
  },
  "took": 100,
  "timed_out": false
}

CSV 格式

您还可以指定以 CSV 格式返回结果。

请求示例

POST /_plugins/_sql?format=csv
{
  "query" : "SELECT firstname, lastname, age FROM accounts ORDER BY age"
}

示例响应

firstname,lastname,age
Nanette,Bates,28
Amber,Duke,32
Dale,Adams,33
Hattie,Bond,36

清理 CSV 格式的结果

默认情况下，OpenSearch 根据以下规则清理标题单元格（字段名称）和数据单元格（字段内容）

  • 如果单元格以 `+`、`-`、`=` 或 `@` 开头，清理器会在单元格开头插入一个单引号 (`'`)。
  • 如果单元格包含一个或多个逗号 (`,`)，清理器会用双引号 (`"`) 将单元格括起来。

示例

以下查询索引的文档中的单元格以特殊字符开头或包含逗号

PUT /userdata/_doc/1?refresh=true
{
  "+firstname": "-Hattie",
  "=lastname": "@Bond",
  "address": "671 Bristol Street, Dente, TN"
}

您可以使用以下查询请求 CSV 格式的结果

POST /_plugins/_sql?format=csv
{
  "query" : "SELECT * FROM userdata"
}

在响应中，以特殊字符开头的单元格前缀为 `'`。包含逗号的单元格用引号括起来

'+firstname,'=lastname,address
'Hattie,'@Bond,"671 Bristol Street, Dente, TN"

要跳过清理，请将 `sanitize` 查询参数设置为 false

POST /_plugins/_sql?format=csvandsanitize=false
{
  "query" : "SELECT * FROM userdata"
}

响应包含原始 CSV 格式的结果

=lastname,address,+firstname
@Bond,"671 Bristol Street, Dente, TN",-Hattie

Raw 格式

您可以使用 raw 格式将结果通过管道传输到其他命令行工具进行后处理。

请求示例

POST /_plugins/_sql?format=raw
{
  "query" : "SELECT firstname, lastname, age FROM accounts ORDER BY age"
}

示例响应

Nanette|Bates|28
Amber|Duke|32
Dale|Adams|33
Hattie|Bond|36

默认情况下，OpenSearch 根据以下规则清理 `raw` 格式的结果

  • 如果数据单元格包含一个或多个管道字符 (`|`)，清理器会用双引号将其括起来。

示例

以下查询索引的文档在其字段中包含管道字符 (`|`)

PUT /userdata/_doc/1?refresh=true
{
  "+firstname": "|Hattie",
  "=lastname": "Bond|",
  "|address": "671 Bristol Street| Dente| TN"
}

您可以使用以下查询请求 `raw` 格式的结果

POST /_plugins/_sql?format=raw
{
  "query" : "SELECT * FROM userdata"
}

该查询返回的单元格中包含的 `|` 字符用引号括起来

"|address"|=lastname|+firstname
"671 Bristol Street| Dente| TN"|"Bond|"|"|Hattie"
剩余 350 字符

有问题？。

想贡献？ 或 。