> For the complete documentation index, see [llms.txt](https://litedb.gitbook.io/litedb-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://litedb.gitbook.io/litedb-docs/architecture_and_design/scalar_index/keys_and_constraints.md).

# 键与约束

`ScalarIndexKey` 是标量索引的规范键类型。所有后端都通过它获得一致的类型检查、相等判断和排序规则。

## 支持的键类型

当前支持：

| 类型        | 说明                |
| --------- | ----------------- |
| `BOOLEAN` | `false` 小于 `true` |
| `INT32`   | 32 位整数            |
| `INT64`   | 64 位整数            |
| `FLOAT`   | 单精度浮点数            |
| `DOUBLE`  | 双精度浮点数            |
| `VARCHAR` | 按字符串字节序比较         |

以下值不能构造标量索引键：

* `NULL`；
* `VECTOR`；
* 浮点 `NaN`；
* 其他未支持的值类型。

`NULL` 由 `IndexEngine` 在构造键之前跳过，所以它不是一个特殊的“最小值”键，也不会出现在索引中。

## 类型是键的一部分

键比较会先比较物理类型，再比较值。因此：

```
INT32(1) != INT64(1)
FLOAT(1.0) != DOUBLE(1.0)
```

`IndexStore` 还会要求键类型与索引描述符完全一致。索引不会进行隐式数值提升，也不会把不同数值类型折叠为同一个键空间。

这一规则与记录模式相配合：一个索引对应一个具有固定类型的列。

## 排序语义

同类型值的排序遵循：

* 布尔值按 `false < true`；
* 整数按数值大小；
* 有限浮点数按数值大小；
* 正零和负零视为相等；
* 字符串按 `std::string` 的字节序；
* `NaN` 在进入比较器之前就被拒绝。

不同类型的全局次序由内部类型枚举决定。正常索引文件只包含描述符指定的一种键类型，因此跨类型次序主要用于保证通用比较器拥有严格弱序，而不是 SQL 层的混合类型排序承诺。

## 完整条目顺序

B+ 树中的实际条目是：

```
(ScalarIndexKey, RecordId)
```

树按键排序；键相同时再按 `RecordId` 排序。这让非唯一索引中的重复值仍然具有确定的全序，并允许精确删除某一条记录的索引入口。

## 唯一索引

`IndexStore` 是唯一性约束的执行位置。

单条插入时，它先用 `find_equal` 查询同键记录，只要已有入口就返回重复键错误。批量构建唯一索引时，输入会先排序，再检查相邻条目的标量键是否重复。

需要区分三件事：

* Catalog 的 `IndexEntry::unique` 会落实为运行时唯一索引检查；
* 普通非唯一索引允许相同键对应多个 `RecordId`；
* 列模式上的其他约束不会自动等价为一个已经创建的唯一索引。

唯一性检查发生在写入准备和 `IndexStore` 边界，但跨文件并发与持久化原子性仍需要事务层配合。

## 范围边界

`IndexRange` 可表达：

* 无界范围；
* 闭区间；
* 任意开闭组合的上下界；
* 只有下界；
* 只有上界。

上下界也是 `ScalarIndexKey`，必须服从同样的类型和比较规则。B+ 树游标在定位起点和判断终点时统一使用这些边界信息。

## 错误模型

索引层以结构化 `IndexError` 报告错误，常见代码包括：

* 不支持的键类型或键值；
* 键类型不匹配；
* 重复条目或重复唯一键；
* 索引不存在或已经存在；
* 索引列无效；
* 后端不支持范围扫描；
* 底层存储错误。

错误上下文可以携带操作名、索引 ID、页面 ID、文件路径和底层错误码，便于在不依赖异常的情况下定位失败边界。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://litedb.gitbook.io/litedb-docs/architecture_and_design/scalar_index/keys_and_constraints.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.