索引机制 #

索引作用：
├── 加速查询
├── 支持排序
├── 实现唯一约束
├── 支持全文搜索
└── 提供查询入口

FaunaDB索引特点：
├── 自动维护更新
├── 支持复合索引
├── 支持部分索引
├── 支持唯一约束
└── 支持绑定值

// 创建基本索引
CreateIndex({
  name: "users_by_email",
  source: Collection("users"),
  terms: [
    { field: ["data", "email"] }
  ]
})

// 完整配置示例
CreateIndex({
  name: "orders_by_user_and_date",
  
  // 数据源
  source: Collection("orders"),
  
  // 查询条件字段
  terms: [
    { field: ["data", "userId"] }
  ],
  
  // 排序字段
  values: [
    { field: ["data", "createdAt"], order: "desc" },
    { field: ["ref"] }
  ],
  
  // 是否唯一
  unique: false,
  
  // 是否串行化
  serialized: true,
  
  // 权限
  permissions: {
    read: Role("user")
  },
  
  // 部分索引
  source: {
    collection: Collection("orders"),
    fields: {
      statusFilter: Query(
        Lambda("doc",
          Equals(Select(["data", "status"], Var("doc")), "active")
        )
      )
    }
  }
})

// 单字段索引
CreateIndex({
  name: "users_by_email",
  source: Collection("users"),
  terms: [
    { field: ["data", "email"] }
  ]
})

// 使用
Match(Index("users_by_email"), "tom@example.com")

// 多字段索引
CreateIndex({
  name: "orders_by_user_and_status",
  source: Collection("orders"),
  terms: [
    { field: ["data", "userId"] },
    { field: ["data", "status"] }
  ]
})

// 使用
Match(
  Index("orders_by_user_and_status"),
  "user_001",
  "pending"
)

// 带排序值的索引
CreateIndex({
  name: "products_by_price",
  source: Collection("products"),
  values: [
    { field: ["data", "price"], order: "asc" },
    { field: ["ref"] }
  ]
})

// 使用（返回按价格排序的结果）
Paginate(
  Match(Index("products_by_price_range")),
  { size: 10 }
)

// 唯一约束索引
CreateIndex({
  name: "users_by_email_unique",
  source: Collection("users"),
  terms: [
    { field: ["data", "email"] }
  ],
  unique: true
})

// 尝试创建重复email会失败
Create(Collection("users"), {
  data: { email: "existing@example.com" }
})
// Error: instance not unique

// 创建全文索引
CreateIndex({
  name: "products_by_name_search",
  source: Collection("products"),
  terms: [
    { field: ["data", "name"] }
  ],
  source: {
    collection: Collection("products"),
    fields: {
      nameTokens: Query(
        Lambda("doc",
          LowerCase(Select(["data", "name"], Var("doc")))
        )
      )
    }
  }
})

terms用途：
├── 定义查询条件字段
├── 用于Match查询
├── 支持多个字段
└── 顺序重要

// terms示例
CreateIndex({
  name: "orders_by_user_status_date",
  source: Collection("orders"),
  terms: [
    { field: ["data", "userId"] },      // 第一个参数
    { field: ["data", "status"] }       // 第二个参数
  ]
})

// 查询时按顺序传参
Match(
  Index("orders_by_user_status_date"),
  "user_001",     // userId
  "pending"       // status
)

values用途：
├── 定义返回值排序
├── 支持升序/降序
├── 可以包含ref
└── 影响分页顺序

// values示例
CreateIndex({
  name: "orders_sorted_by_date",
  source: Collection("orders"),
  terms: [
    { field: ["data", "userId"] }
  ],
  values: [
    { field: ["data", "createdAt"], order: "desc" },  // 按日期降序
    { field: ["data", "total"], order: "desc" },      // 再按金额降序
    { field: ["ref"] }                                 // 最后是ref
  ]
})

// 使用绑定字段
CreateIndex({
  name: "products_by_category_name",
  source: {
    collection: Collection("products"),
    fields: {
      // 绑定计算字段
      categoryLower: Query(
        Lambda("doc",
          LowerCase(Select(["data", "category"], Var("doc")))
        )
      )
    }
  },
  terms: [
    { binding: "categoryLower" }
  ],
  values: [
    { field: ["data", "name"] },
    { field: ["ref"] }
  ]
})

// 基本Match
Match(Index("users_by_email"), "tom@example.com")

// 获取匹配的文档
Get(Match(Index("users_by_email"), "tom@example.com"))

// 分页查询
Paginate(Match(Index("all_users")), { size: 10 })

// 使用复合索引
Match(
  Index("orders_by_user_status_date"),
  "user_001",
  "pending"
)

// 范围查询（需要values）
Paginate(
  Range(
    Match(Index("products_by_price")),
    [10],    // 最小值
    [100]    // 最大值
  )
)

// 并集
Union(
  Match(Index("users_by_role"), "admin"),
  Match(Index("users_by_role"), "moderator")
)

// 交集
Intersection(
  Match(Index("users_by_status"), "active"),
  Match(Index("users_by_department"), "engineering")
)

// 差集
Difference(
  Match(Index("all_users")),
  Match(Index("users_by_status"), "deleted")
)

// 获取索引信息
Get(Index("users_by_email"))

// 列出所有索引
Paginate(Indexes())

// 检查索引是否存在
Exists(Index("users_by_email"))

// 更新索引（有限支持）
Update(Index("users_by_email"), {
  permissions: {
    read: Role("user")
  }
})

// 注意：terms和values不能修改
// 需要修改时，需要删除重建

// 删除索引
Delete(Index("old_index"))

设计原则：
├── 根据查询模式设计
├── 避免过多索引
├── 合理使用复合索引
├── 考虑排序需求
└── 利用绑定字段

// 使用索引覆盖查询
// 索引定义
CreateIndex({
  name: "users_email_name",
  source: Collection("users"),
  terms: [
    { field: ["data", "email"] }
  ],
  values: [
    { field: ["data", "name"] },    // 包含name
    { field: ["ref"] }
  ]
})

// 查询时可以直接获取name，无需Get
Map(
  Paginate(Match(Index("users_email_name"), "tom@example.com")),
  Lambda(["name", "ref"], {
    name: Var("name"),
    ref: Var("ref")
  })
)

// 只索引特定条件的文档
CreateIndex({
  name: "active_users",
  source: {
    collection: Collection("users"),
    fields: {
      isActive: Query(
        Lambda("doc",
          Equals(Select(["data", "status"], Var("doc")), "active")
        )
      )
    }
  },
  terms: [
    { binding: "isActive" }
  ]
})

// 查询只返回active用户
Paginate(Match(Index("active_users"), true))

// 按email查询（唯一）
CreateIndex({
  name: "users_by_email",
  source: Collection("users"),
  terms: [
    { field: ["data", "email"] }
  ],
  unique: true
})

// 按状态查询
CreateIndex({
  name: "users_by_status",
  source: Collection("users"),
  terms: [
    { field: ["data", "status"] }
  ],
  values: [
    { field: ["data", "createdAt"], order: "desc" },
    { field: ["ref"] }
  ]
})

// 按部门查询
CreateIndex({
  name: "users_by_department",
  source: Collection("users"),
  terms: [
    { field: ["data", "departmentId"] }
  ]
})

// 按用户查询订单
CreateIndex({
  name: "orders_by_user",
  source: Collection("orders"),
  terms: [
    { field: ["data", "userId"] }
  ],
  values: [
    { field: ["data", "createdAt"], order: "desc" },
    { field: ["ref"] }
  ]
})

// 按状态和时间范围查询
CreateIndex({
  name: "orders_by_status_date",
  source: Collection("orders"),
  terms: [
    { field: ["data", "status"] }
  ],
  values: [
    { field: ["data", "createdAt"] },
    { field: ["ref"] }
  ]
})

// 按金额范围查询
CreateIndex({
  name: "orders_by_total",
  source: Collection("orders"),
  values: [
    { field: ["data", "total"] },
    { field: ["ref"] }
  ]
})

// 按分类查询
CreateIndex({
  name: "products_by_category",
  source: Collection("products"),
  terms: [
    { field: ["data", "categoryId"] }
  ],
  values: [
    { field: ["data", "name"] },
    { field: ["ref"] }
  ]
})

// 按价格范围查询
CreateIndex({
  name: "products_by_price",
  source: Collection("products"),
  values: [
    { field: ["data", "price"] },
    { field: ["data", "name"] },
    { field: ["ref"] }
  ]
})

// 按库存查询
CreateIndex({
  name: "products_in_stock",
  source: {
    collection: Collection("products"),
    fields: {
      inStock: Query(
        Lambda("doc",
          GT(Select(["data", "stock"], Var("doc")), 0)
        )
      )
    }
  },
  terms: [
    { binding: "inStock" }
  ]
})

索引限制：
├── 每个集合最多64个索引
├── 每个索引最多32个terms
├── 每个索引最多32个values
├── 绑定字段最多32个
└── 索引名称最长64字符

大小限制：
├── 单个索引条目：64KB
├── terms值：最大8KB
├── values值：最大8KB
└── 绑定字段值：最大8KB

命名建议：
├── 描述性名称
├── 包含查询字段
├── 使用下划线分隔
└── 示例：users_by_email, orders_by_user_status

性能优化：
├── 根据查询模式创建索引
├── 避免创建不必要的索引
├── 使用复合索引减少索引数量
├── 利用values实现排序
└── 使用部分索引减少索引大小

维护建议：
├── 定期审查索引使用情况
├── 删除未使用的索引
├── 监控索引大小
└── 优化复合索引顺序

// 安全检查索引
If(
  Exists(Index("users_by_email")),
  Match(Index("users_by_email"), "tom@example.com"),
  Abort("Index not found")
)

// 安全获取结果
Let(
  {
    result: Match(Index("users_by_email"), "tom@example.com")
  },
  If(
    Exists(Var("result")),
    Get(Var("result")),
    null
  )
)

// 处理唯一约束
Let(
  {
    existing: Match(Index("users_by_email_unique"), "tom@example.com")
  },
  If(
    Exists(Var("existing")),
    Update(Select(["ref"], Get(Var("existing"))), {
      data: { name: "Updated Tom" }
    }),
    Create(Collection("users"), {
      data: { email: "tom@example.com", name: "New Tom" }
    })
  )
)