全文检索（或文本搜索）用于识别符合查询条件的自然语言文档。最常见的应用是查找包含指定查询词的所有文档。通过构建全文索引对文档进行预处理，可以实现高效的后续搜索。ByteHouse 企业版通过增强文本倒排索引能力，支持更快速的文本检索与过滤，并允许使用 SQL 语法执行全文检索。本文将介绍如何使用 SQL 命令创建全文索引并进行查询。

在倒排索引使用之前需要确保所选集群开启了全文检索高级特性。开启方式请参见开启服务。

倒排索引可以为 String、Array(String)、JSON 中 String 类型构建倒排索引，提供快速的文本检索和过滤的方式。后续将支持 Nullable 类型倒排，敬请期待。

倒排索引使用 ClickHouse 二级索引 API 进行管理，二级索引常用命令均适用于倒排索引，如：ADD INDEX / DROP INDEX / MATERIALIZE INDEX / CLEAR INDEX，操作详情请参见ALTER INDEX 更改索引常用命令。以下展示了创建倒排索引的基本语法。

• 创建表时定义索引。

  CREATE TABLE test_inverted_with_token
  (
      `key` UInt64,
      `doc` String,
      INDEX doc_idx doc TYPE inverted('standard', '{"version":"v3"}') GRANULARITY 8192
  )
  ENGINE = MergeTree()
  ORDER BY key;
  

• 对于已有表，可使用 ALTER ADD INDEX 添加索引。

  ALTER TABLE test_inverted_with_token ADD INDEX doc_idx doc TYPE inverted('standard', '{"version":"v3"}') GRANULARITY 8192;
  

• 为存量数据构建索引。

  ALTER TABLE test_inverted_with_token MATERIALIZE INDEX doc_idx;
  

常用 settings 参数说明如下：

• GRANULARITY：二级索引通常将其设置为 1 ， 倒排索引则支持将 GRANULARITY 设置为 8192 或更大。
• 查询时添加 settings 参数 filter_with_inverted_index_segment = 1，可启用性能更好的过滤方式。

ALTER INDEX 更改索引常用命令

倒排索引使用二级索引 API 进行管理，二级索引常用命令均适用于倒排索引。

ADD INDEX

添加索引，但不会为历史数据构建索引。

ALTER TABLE test_inverted_with_token ON CLUSTER {cluster} ADD INDEX doc_idx doc TYPE inverted('standard', '{"version":"v3"}') GRANULARITY 8192;

如需为存量数据构建索引，可执行以下命令：

ALTER TABLE test_inverted_with_token MATERIALIZE INDEX doc_idx;

DROP INDEX

删除索引，并清空索引文件。

ALTER TABLE test_inverted_with_token ON CLUSTER {cluster} DROP INDEX doc_idx;

MATERIALIZE INDEX

为存量数据构建索引。

ALTER TABLE test_inverted_with_token ON CLUSTER {cluster} MATERIALIZE INDEX doc_idx;

CLEAR INDEX

清空存量数据索引文件，但保留索引。

ALTER TABLE test_inverted_with_token ON CLUSTER {cluster} CLEAR INDEX doc_idx;

切换倒排索引版本

ByteHouse 倒排索引支持 3 个版本，您可通过指定 "version" 参数使用对应的版本，不同版本差异说明如下：

使用 Version 3

INDEX doc_idx doc TYPE inverted('standard', '{"version":"v3"}') GRANULARITY 8192

使用 Version 2

INDEX doc_idx doc TYPE inverted('standard', '{"version":"v2"}') GRANULARITY 8192

使用 Version 1

INDEX doc_idx doc TYPE inverted('standard', '{"version":"v1"}') GRANULARITY 8192

为 Array/JSON/MAP 列文本内容构建倒排

ByteHouse 支持通过配置 sub_column_filters.value 指定 Array/JSON/MAP 子列，并为其构建倒排索引。

Array 列

CREATE TABLE test_inverted_with_arry_str
(
    `id` UInt64,
    `doc` Array(String),
    INDEX doc_idx doc TYPE inverted('token', '{"sub_column_filters": {"doc": ["*"]}}') GRANULARITY 8192
)
ENGINE = MergeTree()
ORDER BY id

JSON 列

• 为指定 JSON 子列文本内容构建倒排。

  CREATE TABLE index_partial_subcols
  (
      `key` Int,
      `value` JSON,
      INDEX val_ivt value TYPE inverted('token', '{"sub_column_filters": {"value": ["k0", "k1"]}}') GRANULARITY 8192
  )
  ENGINE = MergeTree
  ORDER BY key
  

• 为 JSON 全子列文本内容构建倒排。

  CREATE TABLE index_partial_subcols
  (
      `key` Int,
      `value` JSON,
      INDEX val_ivt value TYPE inverted('token', '{"sub_column_filters": {"value": ["*"]}}') GRANULARITY 8192
  )
  ENGINE = MergeTree
  ORDER BY key
  

MAP(String,String) 列

CREATE TABLE map_test.test_map
(
    `id` UInt32,
    `m` Map(String, String) KV,
    -- 为指定对 key1，key2 构建倒排索引 
    INDEX m_inv m TYPE inverted('token', '{"version":"v3", "sub_column_filters": { "m" : ["key1","key2"] } }') GRNULARITY 8192
)
ENGINE = MergeTree
ORDER BY id
SETTINGS index_granularity = 8192

分词算法

不同的分词算法在特定查询情况下过滤效率不同，同时也影响召回率。基于规则分词的分词算法（standard/token/ngram/char_sep分词）在绝大多数情况下，写入速度大幅优于基于语义的分词算法（ICU/中文分词）。通常情况下，关键词检索和模糊匹配场景建议使用基于规则的分词算法，相似度检索场景建议按需使用语义分词算法。

Standard 分词

INDEX doc_idx doc TYPE inverted('standard', '{"version":"v3"}') GRANULARITY 8192

Token 分词

INDEX doc_idx doc TYPE inverted('token', '{"version":"v3"}') GRANULARITY 8192

ngram分词

"ngrams": 3是以三元组的方式切分文本。

INDEX doc_idx doc TYPE inverted('ngram','{"version":"v3", "ngrams": 3 }') GRANULARITY 8192

自定义分割符

示例中，系统将按照 , 和 ; 分割。

INDEX doc_idx doc TYPE inverted('char_sep','{"version":"v3","seperators": ",;"}') GRANULARITY 1

ICU 分词

使用 language 指定分词文本语种。如下示例中，"language":"zh" 为中文。

inverted('icu', '{"version": "v2", "language":"zh"}')

中文分词

绝大多数中文场景下推荐使用 JIEBA，使用时需要额外在服务器上传词典。

inverted('chinese', '{"version": "v2", "config":"default"}')

<chinese_tokenizer>
    <default>
        <dict_path>/home/cppjieba/dict/jieba.dict.utf8</dict_path>
        <hmm_model_path>/home/dict/hmm_model.utf8</hmm_model_path>
        <user_dict_path>/home/cppjieba/dict/user.dict.utf8</user_dict_path>
        <idf_path>/home/cppjieba/dict/idf.utf8</idf_path>
        <stop_words_path>/homecppjieba/dict/stop_words.utf8</stop_words_path>
    </default>
</chinese_tokenizer>

常用查询函数

String 类型

Array(String) 类型

相似度检索

如下示例使用 version 2 索引， 基于 BM25 算法，通过 textSearch 函数召回与搜索文本相似的文本内容。

select * from table where textSearch(doc, 'text for sim') order by _text_search_score desc limit n;

查询相关

建表相关

服务配置相关

倒排索引磁盘占用查询

SELECT
    name,
    formatReadableSize(sum(file_size)) as index_size
FROM system.checksums
WHERE (database = '{database}') AND (table = '{table}') AND active AND (file_name LIKE '%{index_name}%')
GROUP BY name

返回结果：

倒排索引内存（LRU替换策略）占用查询

SELECT
    *,
    formatReadableSize(value)
FROM system.asynchronous_metrics
WHERE (metric LIKE '%Cache%') AND (metric LIKE '%Unified%')
ORDER BY metric ASC

返回结果：

• UnifiedGINCacheBytes：倒排索引缓存占用，最大缓存占用量支持通过设置 ginindex_store_cache_size 参数配置。
• UnifiedSSTCacheBytes：字典缓存占用，该参数仅适用于 version 3 版本，最大字典缓存占用量支持通过 ginindex_store_cache_sst_block_cache_size参数配置。