在列上创建标量索引。

标量索引与向量索引类似，可用于加速扫描。当扫描包含对已索引列的过滤表达式时，标量索引能显著提升查询速度。例如，若my_col列建有标量索引，以下扫描操作将执行得更快：

import lance

dataset = lance.dataset("/tmp/images.lance")
my_table = dataset.scanner(filter="my_col != 7").to_table()

带有预过滤器的向量搜索也可以从标量索引中受益。例如，

import lance

dataset = lance.dataset("/tmp/images.lance")
my_table = dataset.scanner(
    nearest=dict(
       column="vector",
       q=[1, 2, 3, 4],
       k=10,
    )
    filter="my_col != 7",
    prefilter=True
)

目前有5种标量索引类型可供选择。

• BTREE。最常见的类型是BTREE。该索引的灵感来源于btree数据结构，尽管只有btree的前几层会被缓存在内存中。它将在具有大量唯一值且每个值对应行数较少的列上表现良好。

• BITMAP。该索引为列中的每个唯一值存储一个位图。这种索引适用于具有少量唯一值且每个值对应多行数据的列。

• LABEL_LIST. 一种特殊索引，用于对值基数较小的列表列进行索引。例如，包含标签列表的列（如 ["tag1", "tag2", "tag3"]）可以使用 LABEL_LIST 索引。该索引只能加速带有 array_has_any 或 array_has_all 过滤器的查询。

• NGRAM. 一种用于索引字符串列的特殊索引。该索引会为字符串中的每个n元语法创建位图，默认使用三元语法。当前该索引可以加速在过滤器中使用contains函数的查询。

• FTS/INVERTED. 该索引用于文档列。这种索引可以进行全文搜索。例如，一个包含查询字符串"hello world"中任意单词的列。结果将按BM25排序。

请注意，可以使用环境变量LANCE_BYPASS_SPILLING来绕过磁盘溢出。将其设置为true可以避免内存耗尽问题（更多信息请参阅https://github.com/apache/datafusion/issues/10073）。

实验性API

Parameters:

column : str¶

要建立索引的列。必须是布尔型、整型、浮点型或字符串类型的列。

index_type : str¶

索引的类型。可选值为 "BTREE", "BITMAP", "LABEL_LIST", "NGRAM", "FTS" 或 "INVERTED"。

name : str, optional¶

索引名称。如果未提供，将根据列名自动生成。

replace : bool, default True¶

如果索引已存在，则替换现有索引。

with_position : bool, default True

这是针对INVERTED索引的。如果设为True，索引将存储文档中单词的位置信息，以便支持短语查询。这将显著增加索引大小。即使设置为True，也不会影响非短语查询的性能。

base_tokenizer : str, default "simple"

这是针对INVERTED索引的配置。指定使用的基础分词器，可选值包括： * "simple"：根据空白字符和标点符号进行分词。 * "whitespace"：仅根据空白字符进行分词。 * "raw"：不进行分词处理。

language : str, default "English"

这是针对INVERTED索引的。用于词干提取和停用词处理的语言。仅当stem或remove_stop_words为true时使用

max_token_length : Optional[int], default 40

这是针对INVERTED索引的设置。表示最大令牌长度。任何超过此长度的令牌将被移除。

lower_case : bool, default True

这是针对INVERTED索引的。如果设为True，索引会将所有文本转换为小写。

stem : bool, default False

这是针对INVERTED索引的。如果为True，索引将对词干进行提取。

remove_stop_words : bool, default False

这是针对INVERTED索引的。如果为True，该索引将移除停用词。

ascii_folding : bool, default False

这是针对INVERTED索引的。如果设为True，索引会尽可能将非ASCII字符转换为ASCII字符。例如会将带重音符号的字母如"é"转换为"e"。

示例

import lance

dataset = lance.dataset("/tmp/images.lance")
dataset.create_index(
    "category",
    "BTREE",
)

标量索引只能加速使用等值、比较、范围（例如my_col BETWEEN 0 AND 100）和集合成员（例如my_col IN (0, 1, 2)）等基础过滤条件的扫描

当筛选条件包含多个索引列且这些条件通过AND或OR逻辑连接时，可以使用标量索引 (例如 my_col < 0 AND other_col> 100)

如果过滤条件包含未建立索引的列，虽然可以使用标量索引，但根据过滤条件的结构，可能无法实际使用。例如，若列not_indexed没有标量索引，那么过滤条件my_col = 0 OR not_indexed = 1将无法利用my_col上的任何标量索引。

要判断扫描是否使用了标量索引，可以使用explain_plan查看lancedb生成的查询计划。使用标量索引的查询将包含ScalarIndexQuery关系或MaterializeIndex操作符。