Kronuz/Xapiand 索引文档API详解

Kronuz/Xapiand 索引文档API详解

Xapiand Xapiand: A RESTful Search Engine 项目地址: https://gitcode.com/gh_mirrors/xa/Xapiand

概述

Kronuz/Xapiand 的索引文档API（Index Document API）是该搜索引擎的核心功能之一，它允许用户向特定索引中添加或更新JSON格式的文档数据，使其可以被搜索。本文将深入解析这一API的使用方法、特性及最佳实践。

基本用法

创建或更新文档

最基本的索引操作是使用PUT方法将文档添加到指定索引中。需要提供三个关键信息：

1. 索引名称
2. 文档类型
3. 文档ID

示例：

PUT /twitter/tweet/1

{
    "user": "Kronuz",
    "post_date": "2019-03-22T14:35:26",
    "message": "Trying out Xapiand"
}

响应结果会包含原始文档内容以及系统生成的元数据：

{
  "user": "Kronuz",
  "post_date": "2019-03-22T14:35:26",
  "message": "Trying out Xapiand",
  "_id": 1,
  "_version": 1,
  "#docid": 1,
  "#shard": 1
}

重要注意事项

路径中的斜杠(/)有特殊含义：

• PUT /twitter/tweet/1 表示在/twitter/tweet/索引中创建ID为1的文档
• PUT /twitter/tweet/1/ 表示创建名为/twitter/tweet/1/的索引本身

高级特性

自动索引创建

当执行索引操作时，如果目标索引不存在，Xapiand会自动创建该索引，并应用任何已配置的索引模板。同时，如果索引没有预定义的schema，系统会自动创建动态schema。

动态schema特性意味着：

• 新字段会自动添加到schema定义中
• 新对象也会被自动识别和处理
• 字段类型会根据输入值自动推断

自动ID生成

如果不指定文档ID，系统会自动生成一个。此时需要使用POST方法而非PUT：

POST /twitter/tweet/

{
    "user": "Yosef",
    "post_date": "2019-03-22T14:46:10",
    "message": "Also trying out Xapiand!"
}

响应中会包含系统分配的ID：

{
  "_id": 2,
  ...
}

脚本支持

索引API支持使用脚本进行文档操作，语法与更新API一致。可以通过脚本实现复杂的文档处理逻辑，如条件更新、字段计算等。

性能与一致性控制

提交控制

通过添加commit查询参数，可以确保操作在文档变更提交到主分片后才返回。虽然这提供了更强的数据一致性保证，但会显著影响性能，应谨慎使用。

乐观并发控制

通过version参数可以实现乐观锁机制：

• 只有当文档当前版本与指定版本匹配时，操作才会执行
• 版本不匹配会返回409 Conflict状态码
• 适用于需要防止并发修改的场景

底层原理

分片与复制

索引操作遵循以下流程：

1. 根据文档ID的哈希值确定主分片
2. 操作首先在包含该主分片的节点上执行
3. 成功后，变更会同步到所有相关的副本分片
4. 这种设计确保了数据的高可用性和一致性

最佳实践

1. 对于已知ID的文档使用PUT，未知ID使用POST
2. 避免在生产环境中频繁使用commit参数
3. 在高并发场景考虑使用乐观并发控制
4. 利用自动schema特性快速原型开发，但生产环境建议明确定义schema
5. 注意路径斜杠的使用，避免意外创建索引而非文档

通过合理运用Xapiand的索引API，开发者可以高效地构建强大的搜索功能，同时确保数据的可靠性和一致性。

Xapiand Xapiand: A RESTful Search Engine 项目地址: https://gitcode.com/gh_mirrors/xa/Xapiand