本文深入解析 FaunaDB 日期范围查询的核心方法：必须将日期字段配置为索引的 values（而非 terms），并采用 Range + Match 组合配合 Date 或 Time 类型值进行查询，否则将始终无法获取有效数据。

在 FaunaDB 中执行日期范围查询时，你是否也遇到过返回空数组的困扰？这并非个例，许多开发者都曾在此处受阻。问题的关键，通常不在于查询逻辑，而在于索引设计与查询语法之间那层必须精确匹配的关系。简而言之，如果日期字段在索引中的位置设置错误，任何查询尝试都将徒劳无功。

核心解决方案非常明确：要实现有效的日期范围查询，必须将日期字段置于索引的 values 部分，而非 terms 中。因为 terms 仅支持精确匹配，其设计初衷就不包含范围扫描功能。

✅ 正确方法：使用 values 定义支持排序与范围查询的字段

索引中的 values 字段决定了数据的排序方式，并且是 Range 操作能够生效的唯一目标。因此，针对日期范围查询，正确的做法是将时间字段（例如 data.created）放入 values：

CreateIndex({
  name: "entries_ordered_by_created",
  source: Collection("Entries"),
  values: [{ field: ["data", "created"] }] // ✅ 核心要点：使用 values，而非 terms
})

⚠️ 重要提示：values 中的字段值必须是标量类型，例如字符串、数字或时间戳。你示例中的 "created": "2023-08-22T10:23:06-05:00" 是 ISO 8601 字符串，FaunaDB 会依据字典序进行排序——这在时区统一、格式规范的情况下是可行且高效的。然而，更稳健的方案是直接存储为原生的 Time 类型，从而从根本上避免时区混淆问题（下文将详细说明）。

✅ 正确查询：结合 Range + Match 与标准化时间值

索引定义正确后，查询语句也需相应调整。你需要使用 Range 对索引进行区间筛选，并且传入的起始值与结束值必须与索引 values 中定义的数据类型严格一致：

const START_DATE = "2023-08-01T00:00:00Z"; // 建议采用 UTC 格式
const END_DATE = "2023-08-30T23:59:59Z";

const entriesQuery = q.Map(
  q.Paginate(
    q.Range(
      q.Match(q.Index("entries_ordered_by_created")),
      q.Time(START_DATE), // ✅ 使用 Time() 包装字符串，确保类型准确
      q.Time(END_DATE)
    )
  ),
  q.Lambda("ref", q.Get(q.Var("ref")))
);

const result = await client.query(entriesQuery);
console.log("ENTRIES:", result.data); // ✅ 此时将成功返回匹配的文档记录

? 实用技巧：q.Time() 函数会解析 ISO 字符串并将其标准化为内部时间对象。如果你的原始数据仅包含日期（不含时间部分），也可以使用 q.Date("2023-08-01")，但前提是索引 values 中存储的也必须是 Date 类型（即在数据写入时便使用 Date() 构造）。

❌ 常见错误与解决方案

掌握了正确方法后，识别并避免以下常见陷阱至关重要：

• 错误1：误将 terms 用于范围查询
  这是最典型的误区。terms 的定位是精确过滤条件（例如 Match(Index("by_status"), "active")），它只能用于查找特定时间点，完全无法支持“在某个时间段内”这类范围查询。如果你的索引定义中使用了 terms: [{ field: ["data", "created"] }]，那么无论怎样调用 Range，结果都将是空的。

• 错误2：字符串格式不一致导致排序异常
  即便使用了 values，如果数据格式混杂，排序结果也会出错。设想一下，部分记录为 "2023-08-01"，而另一部分为 "2023-08-01T12:00:00Z"，字典序比较将产生混乱。务必在数据写入阶段统一格式，强烈建议全部采用 ISO 8601 UTC 字符串，或直接使用原生的 Time 类型。

• 错误3：忽略时区影响，引发逻辑错误
  时区是一个隐蔽的隐患。"2023-08-22T10:23:06-05:00"（美国东部时间）与 "2023-08-22T10:23:06Z"（UTC时间）在字典序中是完全不同的值。解决方案有两种：
  1. 写入时统一转换为 UTC 时间，例如使用 new Date().toISOString()。
  2. 更推荐直接使用 Time 类型，让 FaunaDB 自动完成标准化处理：

  Create(Collection("Entries"), {
    data: {
      ...otherFields,
      created: Time("2023-08-22T15:23:06.000Z") // 自动进行归一化
    }
  })

✅ 进阶推荐：采用 FQL v10（Fauna Schema Language）

如果你的项目使用的是较新版本的 FaunaDB（v4.5+），强烈建议尝试 FQL v10。其语法更为简洁，语义也更加清晰，能帮助你从底层细节中解脱出来。

在 Schema 文件中定义索引变得非常直观：

// 在 Schema 文件中定义
collection Entries {
  index orderedByCreated {
    values: [ .data.created ] // 直接路径访问，类型自动推导
  }
}

执行查询时，调用方式也更为优雅：

Entries.orderedByCreated({
  from: Time("2023-08-01T00:00:00Z"),
  to: Time("2023-08-30T23:59:59Z")
})

总结

总而言之，在 FaunaDB 中成功实现日期范围查询，关键在于确保三个环节无缝衔接：索引定义、数据类型、查询构造。为了方便对比，请参考以下总结表格：

只要牢记这三点，确保索引的 values、存储的数据类型、查询时使用的 Time/Date 三者保持高度一致，日期范围查询就能稳定且高效地运行。