UDB-SX交互

用户可以通过 REST API 或 Java 客户端与 UDB-SX 交互。本节介绍 UDB-SX REST API。如果需要在编程语言中与 UDB-SX 交互，请查看客户端章节获取可用客户端列表。

UDB-SX REST API

用户可以通过 REST API 与 UDB-SX 集群交互，该 API 具备极高的灵活性。通过 REST API，可以修改大多数 UDB-SX 设置、调整索引、检查集群健康状态、获取统计数据——几乎所有操作都能实现。也可以使用 cURL 等客户端，或任何能发送 HTTP 请求的编程语言。

可以在终端中，或通过 UDB-SX 仪表盘的开发工具控制台发送 HTTP 请求。

在终端中发送请求

在终端中发送 cURL 请求时，请求格式会根据是否启用安全插件有所不同。以下以集群健康状态 API 请求为例进行说明。

若未启用安全插件，发送以下请求：

curl -X GET "http://localhost:10200/_cluster/health"

若已启用安全插件，需在请求中提供用户名和密码：

curl -X GET "https://localhost:10200/_cluster/health" -ku admin:<自定义管理员密码>

默认用户名为 admin，默认密码为 admin。

UDB-SX 默认返回扁平化 JSON 格式的响应结果。若需易读的响应体，可添加 pretty 查询参数：

curl -k -u admin:admin https://localhost:10200/_cluster/health?pretty

对于包含请求体的请求，需指定 Content-Type 头部，并在 -d（数据）选项中提供请求负载：

curl -k -u admin:admin -X GET "https://localhost:10200/test-idx/_search?pretty" \
-H 'Content-Type: application/json' \
-d'
{
  "query": {
    "match_all": {}
  }
}'

curl -k -u admin:admin -X GET “https://localhost:10200/test-idx/_search?pretty” -H ‘Content-Type: application/json’ -d’ { “query”: { “match_all”: {} } }’

在开发工具中发送请求

与 cURL 命令相比，UDB-SX 仪表盘的开发者工具控制台采用更简洁的语法格式化 REST 请求。在开发工具中发送请求的步骤如下：

在运行 UDB-SX 集群的主机上，通过浏览器打开 https://localhost:6601/ 访问 UDB-SX Dashboards。默认用户名为 admin，默认密码为 admin。

在顶部菜单栏中，前往 管理 > 开发者工具。
在控制台左窗格中，输入以下请求：
```
GET _cluster/health
```
点击请求右上角的绿色三角形按钮提交查询。也可通过按下 Ctrl+Enter（Mac 用户按 Cmd+Enter）提交。

在后续章节及 UDB-SX 大多数文档中，请求均以开发工具控制台格式呈现。

索引文档

要将 JSON 文档添加到 UDB-SX 索引（即对文档进行索引），需发送包含以下头部的 HTTP 请求：

curl -k -u admin:admin -X GET "https://localhost:10200/_cluster/health?pretty"

例如，要索引一条学生信息文档，可发送以下请求：

PUT /students/_doc/1
{
  "name": "jiuyou",
  "gpa": 3.89,
  "grad_year": 2025
}

发送上述请求后，UDB-SX 会创建名为 students 的索引，并将摄入的文档存储在该索引中。若未指定文档 ID，UDB-SX 会自动生成一个文档 ID。上述请求中，文档 ID 被指定为 1 。

动态映射

索引文档时，UDB-SX 会根据文档中提交的 JSON 类型推断字段类型。此过程称为动态映射。

要查看推断的字段类型，可向 _mapping 端点发送请求：

GET /students/_mapping

UDB-SX 会返回每个字段的 type（类型）：

{
  "students": {
    "mappings": {
      "properties": {
        "gpa": {
          "type": "float"
        },
        "grad_year": {
          "type": "long"
        },
        "name": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        }
      }
    }
  }
}

UDB-SX 将数值字段映射为 float（浮点数）和 long（长整数）类型。

UDB-SX 将 name 文本字段映射为 text 类型，并添加了一个映射为 keyword（关键词）类型的 name.keyword 子字段。

映射为 text 类型的字段会被分词（转为小写并拆分为词条），可用于全文搜索；映射为 keyword 类型的字段则用于精确词条搜索。

UDB-SX 将 grad_year 字段映射为 long 类型。若需将其改为 date（日期）类型，需先删除索引，再重新创建索引并显式指定映射。关于如何显式指定映射的操作说明，可查看索引映射和设置。

搜索文档

要搜索文档，需指定要搜索的索引以及用于匹配文档的查询条件。最简单的查询是 match_all 查询，它会匹配索引中的所有文档：

GET /students/_search
{
  "query": {
    "match_all": {}
  }
}

UDB-SX 会返回已索引的文档：

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "students",
        "_id": "1",
        "_score": 1,
        "_source": {
          "name": "jiuyou",
          "gpa": 3.89,
          "grad_year": 2025
        }
      }
    ]
  }
}

更新文档

在 UDB-SX 中，文档是不可变的。但你可以通过检索文档、更新信息并重新索引的方式更新文档。你可以使用索引文档 API 更新整个文档，需提供文档中所有现有字段和新增字段的值。例如，要更新之前索引文档的 gpa 字段并添加 address（地址）字段，可发送以下请求：

PUT /students/_doc/1
{
  "name": "jiuyou",
  "gpa": 3.91,
  "grad_year": 2025,
  "address": "123 Main St."
}

此外，你也可以通过调用更新文档 API 更新文档的部分内容：

POST /students/_update/1/
{
  "doc": {
    "gpa": 3.91,
    "address": "123 Main St."
  }
}

删除文档

要删除文档，需发送删除请求并提供文档 ID：

DELETE /students/_doc/1

删除索引

要删除索引，发送以下请求：

DELETE /students

索引映射和设置

UDB-SX 索引通过映射和设置进行配置：

映射是字段及其类型的集合。
设置包含索引数据，如索引名称、创建日期和分片数量。

可以在一个请求中同时指定映射和设置。例如，以下请求指定了索引分片数量，并将 name 字段映射为 text 类型、grad_year 字段映射为 date 类型：

PUT /students
{
  "settings": {
    "index.number_of_shards": 1
  }, 
  "mappings": {
    "properties": {
      "name": {
        "type": "text"
      },
      "grad_year": {
        "type": "date"
      }
    }
  }
}

现在，你可以索引上一节中使用的相同文档：

PUT /students/_doc/1
{
  "name": "jiuyou",
  "gpa": 3.89,
  "grad_year": 2025
}

要查看索引字段的映射，发送以下请求：

GET /students/_mapping

UDB-SX 会按照指定的类型映射 name 和 grad_year 字段，并自动推断 gpa 字段的类型：

{
  "students": {
    "mappings": {
      "properties": {
        "address": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        },
        "gpa": {
          "type": "float"
        },
        "grad_year": {
          "type": "long"
        },
        "name": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        }
      }
    }
  }
}

字段创建后，其类型无法更改。如需修改字段类型，需删除索引并使用新的映射重新创建。