IBM Cloudant 查询性能指南

如何识别大型扫描

使用 _explain 端点检查查询将使用哪个索引：

POST /orders/_explain
{
  "selector": {
    "username": "bob@email.com",
    "status": "cancelled",
    "date": {"$gte": "2018-01-01", "$lt": "2019-01-01"}
  }
}

如果答复显示了特定指数，则评估该指数是_高_选择性还是_低_选择性。 在本例中，status 字段上的索引可能是低选择性索引，因此需要对该查询进行处理：

{
  "index": {
    "ddoc": "_design/status-index",
    "def": {
      "fields": [
        {
          "status": "asc"
        }
      ]
    },
    "name": "d479bdddf50865e520a0193704c8b93a3bd48f77",
    "type": "json"
  }
}

如果响应显示 "name": "_all_docs"，则查询将扫描整个数据库：

{
  "index": {
    "ddoc": null,
    "name": "_all_docs",
    "type": "special"
  }
}

解决方案：创建适当的索引

对于上述查询，最佳索引是涵盖查询字段的复合（多字段）JSON 索引：

POST /orders/_index
{
  "index": {
    "fields": ["username", "status", "date"]
  },
  "name": "username-status-date-index",
  "type": "json"
}

性能影响：在 100,000 个文档数据库中，这一变化可将查询时间从 20 多秒缩短到 10 毫秒以下。

生产安全：防止意外大扫描

如果知道某个索引对查询有很高的选择性，可将 use_index 与 allow_fallback: false 结合使用，以强制使用该索引：

{
  "selector": {"username": "bob@email.com", "status": "cancelled"},
  "use_index": ["my_design_doc", "username-index"],
  "allow_fallback": false
}

如果 my_design_doc/username-index 无法用于查询，则会返回错误，而不是默默地执行昂贵的扫描。 allow_fallback 的默认值是 true，这意味着 IBM Cloudant 将使用不同的索引来响应查询，可能会导致大量扫描。

如果不提供 use_index，那么 allow_fallback: false 仍将阻止使用 _all_docs 索引进行查询：

{
  "selector": {"username": "bob@email.com"},
  "allow_fallback": false
}

如果不存在合适的用户定义索引，将返回错误，从而避免昂贵的扫描。

有关这些查询参数的更多详情，请参阅查询 API 文档。

对于关键查询，建议的做法是始终将 use_index 与 allow_fallback 相结合。

关键规则 1：化合物指数选择性

按选择性排列您的相等字段（非范围字段） - 选择性最强的优先：

• user 字段：每个用户 50 份文档（高选择性）--将其放在首位。
• status 字段：每个状态 10,000 份文档（中等选择性）。

最佳索引排序：["username", "status", "date"]，其中 date 是范围字段。

关键规则 2：范围字段必须放在最后

创建复合索引时，任何与范围运算符一起使用的字段 ($gt, $gte, $lt, $lte) 必须在字段列表中最后出现。

错误 - 导致部分数据库扫描：

{
  "index": {
    "fields": ["date", "username", "status"]  // Bad - range field first
  }
}

正确--实现高效搜索：

{
  "index": {
    "fields": ["username", "status", "date"]  // Good - range field last
  }
}

关键规则 3：排序字段必须放在最后

索引还可用于对查询结果进行排序。 当您的查询对 username 和 status 等字段进行筛选，并对 date 等字段进行排序时，索引必须包括所有三个字段，排序字段放在最后。

例如，支持以下查询：

{
  "selector": { "username": "bob@email.com", "status": "cancelled" },
  "sort": [ { "date": "asc" } ]
}

您需要 ["username", "status", "date"] 上的索引。 在这种结构中，排序字段 (date) 必须放在最后。 这种排序方式可确保 IBM Cloudant 能够有效地使用索引进行筛选和排序。

为什么实地排序很重要

IBM Cloudant 索引的工作原理与排序表类似。 ["username", "status", "date"] 上的索引创建的条目首先按用户排序，然后按每个用户中的状态排序，最后按每个用户-状态组合中的日期排序：

["alice", "paid", "2018-01-15"]
["alice", "paid", "2018-02-20"]
["bob", "cancelled", "2018-01-10"]
["bob", "cancelled", "2018-01-15"]
["bob", "paid", "2018-01-12"]

当对 user: "bob", status: "cancelled", date: {$gte: "2018-01-01"} 这样的查询使用高效索引时，IBM Cloudant：

1. 直接跳转到鲍勃的记录。
2. 在鲍勃的记录中查找已取消的订单。
3. 有效扫描日期范围。

如果把日期放在首位，IBM Cloudant 就需要检查所有用户和状态的日期范围内的每份文档。

索引类型选择指南

在以下情况下选择 JSON 索引

• 查询模式具有可预测性和一致性。
• 您需要最大限度地提高精确匹配的性能。
• 文件结构一致。
• 您主要使用 $and、$eq 和范围运算符。

在下列情况下选择文本索引

• 您需要 $or 跨多个字段进行操作。
• 文件的结构各不相同。
• 您需要全文搜索功能。
• 查询模式是临时的或用户驱动的。
• 您正在使用 $ne、$exists 或复杂运算符。

决策矩阵示例：

// Predictable e-commerce queries → JSON index
{
  "selector": {
    "username": "bob@email.com",
    "status": "paid",
    "date": {"$gte": "2018-01-01"}
  }
}

// Flexible search interface → Text index  
{
  "selector": {
    "$or": [
      "status": {"$in": ["paid", "in-progress"]}
      "category": "electronics"
    ]
  }
}

问题

如果在 ["username", "status", "date"] 上创建索引，任何缺少其中一个字段的文档都会被完全排除在索引之外。 这意味着：

// This document WON'T be indexed
{
  "_id": "order123",
  "username": "bob@email.com",
  "status": "paid"
  // Missing "date" field
}

解决方案

方案 1：确保文件结构一致

// Always include all indexed fields
{
  "_id": "order123",
  "username": "bob@email.com",
  "status": "paid",
  "date": null  // Use null for missing values
}

方案 2：为不同的文档结构创建多个 JSON 索引

// Index for documents with all fields
{"fields": ["username", "status", "date"]}

// Index for documents without date
{"fields": ["username", "status"]}

方案 3：使用文本索引满足灵活的字段要求

{
  "index": {
    "fields": [
      {"name": "username", "type": "string"},
      {"name": "status", "type": "string"},
      {"name": "date", "type": "string"}
    ]
  },
  "type": "text"
}

文本索引将对缺少 date （或其他）字段的文件进行索引。

何时使用部分索引

在下列情况下，部分索引是理想的选择

• 您可以持续查询文档子集（例如，只查询活动记录）。
• 您的数据库包含大量与大多数查询无关的数据。
• 您希望降低 IBM Cloudant 存储成本（按 GB 计费）。

创建部分索引

使用 partial_filter_selector 指定要包含的文件：

{
  "index": {
    "fields": ["date", "category"]
  },
  "partial_filter_selector": {
    "status": "published"
  },
  "name": "published-articles-index"
}

该索引只包含 status: "published" 的文档，因此在查询已发布内容时，索引更小，速度更快。

partial_filter_selector 可以包含任何有效的选择器，而不仅仅是示例中简单的单字段选择器。

真实案例：博客系统

情景：一个拥有 100,000 篇文章的博客数据库，其中 80,000 篇为草稿，20,000 篇为已发表文章。

传统索引 （涵盖所有文件）：

{"fields": ["category", "publishDate"]}

部分索引 （仅发表文章）：

{
  "index": {"fields": ["category", "publishDate"]},
  "partial_filter_selector": {"status": "published"}
}

优点：

• 索引大小：缩小 80
• 查询速度：2-3x
• 存储成本：大幅降低
• 缓存效率：更多相关数据留在内存中

确保查询与部分索引兼容

要使用该索引，您的查询选择器必须与部分过滤器兼容。

这招管用：

// Compatible - query includes the partial filter condition
{
  "selector": {
    "status": "published",    // Matches partial filter
    "category": "technology"
  }
}

这行不通：

// Incompatible - query doesn't match partial filter
{
  "selector": {
    "status": "draft",        // Contradicts partial filter
    "category": "technology"
  }
}

了解覆盖索引

当您的索引包含满足查询选择器和返回字段所需的所有字段时，就产生了覆盖索引：

// Index covers these fields
{
  "index": {
    "fields": ["username", "status", "date", "amount"]
  }
}

// Query only needs indexed fields
{
  "selector": {"username": "bob@email.com", "status": "paid"},
  "fields": ["username", "date", "amount"]  // All fields in index
}

IBM Cloudant 可以直接从索引中返回结果，而无需读取原始文档，从而大大提高了性能。

设计覆盖范围

围绕常见查询模式规划索引：

// Analyze your query patterns
const commonQueries = [
  {selector: {username: "...", status: "..."}, fields: ["date", "amount"]},
  {selector: {status: "...", date: {...}}, fields: ["username", "amount"]},
  {selector: {username: "..."}, fields: ["status", "date", "total"]}
];

// Design covering index
{
  "index": {
    "fields": ["username", "status", "date", "amount", "total"]
  }
}

当找到能覆盖查询的索引时，_explain 端点 将包含 "covering": true。

指数战略审查

• 所有生产查询都有适当的索引
• 复合索引遵循“范围-前置-后置”规则
• 字段排序反映数据的实际选择性
• 查询不会意外返回到 _all_docs

性能验证

• 使用生产规模的数据量测试查询
• 监测效率比率（目标是 >50）
• 验证执行时间是否符合 SLA 要求
• 考虑部分索引以优化成本

监视设置

• 启用 execution_stats 日志记录
• 设置不良效率比率警报
• 监控索引使用模式
• 查询性能回归测试计划

错误处理

• 使用 allow_fallback: false 防止代价高昂的事故
• 优雅地处理索引选择错误
• 规划部署期间的索引构建时间