4.1 索引文档 (Index API)

4.1 索引文档 (Index API)

Elasticsearch 核心操作：文档管理 - 4.1 索引文档 (Index API)

1. 索引文档的基本概念

• 文档 (Document): Elasticsearch中的最小存储单元，通常是一个JSON对象，包含多个字段和对应的值。

• 索引 (Index): 一个逻辑上的命名空间，用于组织和存储相关文档。可以把它类比成关系型数据库中的表。

• 类型 (Type): 在Elasticsearch版本之前，一个索引可以包含多个类型。但是，从Elasticsearch.x开始，已经移除了类型的概念，一个索引只包含一个默认类型 _doc。

• ID: 每个文档在索引中都有一个唯一的ID。你可以手动指定ID，也可以让Elasticsearch自动生成。

2. Index API的基本语法

Index API使用HTTP PUT请求，其基本语法如下：

PUT /{index}/_doc/{id}
{
  "field1": "value1",
  "field2": "value2",
  ...
}
​

• {index}: 要索引的索引名称。

• _doc: 文档类型。在Elasticsearch.x及更高版本中，这是唯一的文档类型。

• {id}: 文档的ID。如果指定了ID，Elasticsearch会尝试更新现有文档（如果存在）或创建新文档（如果不存在）。 如果不指定ID，Elasticsearch会自动生成一个唯一的ID。

• {JSON Document}: 要索引的JSON文档。

3. Index API的常用参数

除了基本的语法，Index API还支持一些常用的查询参数，可以控制索引操作的行为：

• op_type: 指定操作类型。可以是 create 或 index。

  • create: 如果具有指定ID的文档已经存在，则操作将失败。

  • index: (默认) 如果具有指定ID的文档已经存在，则操作将更新该文档。

• version: 指定文档的版本号。用于实现乐观并发控制。

• version_type: 指定版本控制的类型。

• if_seq_no: 用于乐观并发控制，与if_primary_term一起使用。

• if_primary_term: 用于乐观并发控制，与if_seq_no一起使用。

• routing: 指定文档的路由值。

• timeout: 操作超时时间。

• refresh: 控制索引刷新行为。

  • true: 立即刷新索引，使文档可见。

  • false: 不刷新索引。

  • wait_for: 等待索引刷新。

4. Index API的代码实践 (使用Python Elasticsearch Client)

以下代码示例展示了如何使用Python Elasticsearch Client来索引文档：

from elasticsearch import Elasticsearch
# 连接到Elasticsearch集群
es = Elasticsearch([{'host': 'localhost', 'port': 9200}])
# 1. 索引文档 (指定ID)
document = {
    'title': 'Elasticsearch: The Definitive Guide',
    'author': 'Clinton Gormley, Zachary Tong',
    'publication_date': '2015-01-23',
    'tags': ['elasticsearch', 'search', 'distributed']
}
index_name = 'books'
document_id = '1'
try:
    response = es.index(index=index_name, id=document_id, document=document)
    print("索引文档 (指定ID) 结果:", response)
except Exception as e:
    print(f"索引文档 (指定ID) 失败: {e}")
# 2. 索引文档 (自动生成ID)
document2 = {
    'title': 'Mastering Elasticsearch',
    'author': 'Rafał Kuć',
    'publication_date': '2015-03-25',
    'tags': ['elasticsearch', 'performance', 'tuning']
}
try:
    response = es.index(index=index_name, document=document2)
    print("索引文档 (自动生成ID) 结果:", response)
    auto_generated_id = response['_id']
    print(f"自动生成的 ID: {auto_generated_id}")
except Exception as e:
    print(f"索引文档 (自动生成ID) 失败: {e}")
# 3. 索引文档 (使用op_type='create', 防止重复创建)
document3 = {
    'title': 'Elasticsearch in Action',
    'author': 'Radu Gheorghe, Matthew Lee Hinman, Roy Russo',
    'publication_date': '2015-12-03',
    'tags': ['elasticsearch', 'java', 'development']
}
document_id3 = '3'
try:
    response = es.index(index=index_name, id=document_id3, document=document3, op_type='create')
    print("索引文档 (op_type='create') 结果:", response)
except Exception as e:
    print(f"索引文档 (op_type='create') 失败: {e}")  # 如果ID为3的文档已经存在，这里会抛出异常
# 4. 索引文档 (使用refresh=True，立即刷新索引)
document4 = {
    'title': 'Relevant Search',
    'author': 'Doug Turnbull, John Berryman',
    'publication_date': '2016-11-14',
    'tags': ['elasticsearch', 'relevance', 'search']
}
document_id4 = '4'
try:
    response = es.index(index=index_name, id=document_id4, document=document4, refresh=True)
    print("索引文档 (refresh=True) 结果:", response)
except Exception as e:
    print(f"索引文档 (refresh=True) 失败: {e}")
# 关闭连接
#es.close()  # Elasticsearch.x client 不需要手动关闭连接
​

代码解释:

• 连接到Elasticsearch: 首先，使用Elasticsearch()函数连接到Elasticsearch集群。你需要根据你的实际情况修改host和port。

• 索引文档 (指定ID): 使用es.index()方法，指定index、id和document参数。

• 索引文档 (自动生成ID): 不指定id参数，Elasticsearch会自动生成一个唯一的ID。可以通过response['_id']获取自动生成的ID。

• 索引文档 (使用op_type='create'): 指定op_type='create'参数，防止重复创建文档。如果具有相同ID的文档已经存在，则会抛出ConflictError异常。

• 索引文档 (使用refresh=True): 指定refresh=True参数，立即刷新索引，使文档立即可见。默认情况下，Elasticsearch会延迟刷新索引，以提高性能。

5. Index API的返回结果

Index API会返回一个JSON对象，包含操作的结果信息：

{
  "_index" : "books",
  "_id" : "1",
  "_version" : 1,
  "result" : "created",  // 或 "updated"
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}
​

• _index: 索引名称。

• _id: 文档ID。

• _version: 文档版本号。每次更新文档，版本号都会递增。

• result: 操作结果。可以是 created (创建新文档) 或 updated (更新现有文档)。

• _shards: 分片信息。

• _seq_no: 序列号，用于乐观并发控制。

• _primary_term: 主Term，用于乐观并发控制。

6. 错误处理

在索引文档时，可能会遇到一些错误，例如：

• ConflictError: 当使用 op_type='create' 且具有相同ID的文档已经存在时，会抛出此异常。

• NotFoundError: 当指定的索引不存在时，会抛出此异常。

• RequestError: 当请求格式不正确时，会抛出此异常。

在代码中，应该使用 try...except 块来捕获这些异常，并进行相应的处理。

7. Index API的流程图

流程图解释:

1. 客户端发起PUT请求，包含索引名称、文档ID和JSON文档。

2. Elasticsearch节点接收到请求。

3. 检查是否已经存在具有相同ID的文档。

4. 如果存在，则更新现有文档，并递增版本号。

5. 如果不存在，则创建新文档。

6. 将文档索引到主分片。

7. 将文档复制到副本分片。

8. 向客户端发送包含结果信息的响应。

8. 最佳实践

• 选择合适的ID: 如果你的数据源已经包含唯一的ID，建议使用这些ID作为Elasticsearch文档的ID。 否则，让Elasticsearch自动生成ID。

• 批量索引: 如果需要索引大量文档，建议使用Bulk API，以提高性能。

• 合理设置刷新间隔: 根据你的业务需求，合理设置索引刷新间隔。频繁刷新会影响性能，而延迟刷新可能会导致数据可见性延迟。

• 使用模板: 使用索引模板来定义索引的映射和设置。

9. 总结

Index API是Elasticsearch中用于索引文档的核心操作。 理解其基本语法、常用参数、返回结果和错误处理机制，可以帮助你更好地管理Elasticsearch中的数据。 通过结合代码实践和流程图，可以更深入地理解Index API的工作原理。 记住，在实际应用中，要根据你的业务需求选择合适的参数和策略，以获得最佳的性能和数据一致性。