响应格式

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": "integer"
    }
  ],
  "datarows": [
    [
      "Nanette",
      "Bates",
      28
    ],
    [
      "Amber",
      "Duke",
      32
    ]
  ],
  "total": 2,
  "size": 2,
  "status": 200
}

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

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

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

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

{
  "error":{
    "reason":"Invalid SQL query",
    "details":"can't resolve Symbol(namespace=FIELD_NAME, name=unknown) in type env",
    "type":"SemanticCheckException"
    },
    "status": 400
}

UDB-SX DSL JSON 格式

如果将格式设置为 json，则返回原始的 UDB-SX 响应（JSON 格式）。因为这是 UDB-SX 的原生响应，所以需要额外的努力来解析和解释它。

示例请求

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

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

示例响应

响应是来自 UDB-SX 的原始响应：

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

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 格式中清理结果

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

如果单元格以 +、-、= 或 @ 开头，清理程序会在单元格开头插入一个单引号 (')。
如果单元格包含一个或多个逗号 (,)，清理程序会用双引号 (") 包围该单元格。

示例

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

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"
}

在响应中，以特殊字符开头的单元格前缀为 '。包含逗号的单元格被引号包围：

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

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

POST /_plugins/_sql?format=csv&sanitize=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"
}

示例响应

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

默认情况下，UDB-SX 根据以下规则清理 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|address|+firstname
"671 Bristol Street| Dente| TN"|"Bond|"  |       |"|Hattie" 