折腾 Quickwit，Rust 编写的分布式搜索引擎-官方配置详解

Node configuration(节点配置)

节点配置允许您为集群中的各个节点自定义和优化设置。它被分为几个部分：

• 常规配置设置：共享的顶级属性
• Storage(存储)设置：在storage部分定义

• https://quickwit.io/docs/configuration/node-config#storage-configuration

• Metastore(元存储)设置：在metastore部分定义

• https://quickwit.io/docs/configuration/node-config#metastore-configuration

• Ingest 设置：在ingest_api部分定义

• https://quickwit.io/docs/configuration/node-config#ingest-api-configuration

• Indexer(索引器)设置：在indexer部分定义

• https://quickwit.io/docs/configuration/node-config#indexer-configuration

• Searcher(搜索器)设置：在Searcher部分定义

• https://quickwit.io/docs/configuration/node-config#searcher-configuration

• Jaeger 设置：在Jaeger部分定义

• https://quickwit.io/docs/configuration/node-config#jaeger-configuration

一个带注释的例子可在此处找到：quickwit.yaml。

• https://github.com/quickwit-oss/quickwit/blob/main/config/quickwit.yaml

Common configuration(常规配置)

• https://kubernetes.io/docs/concepts/services-networking/service/#headless-services
• https://quickwit.io/docs/configuration/metastore-config

REST configuration(REST 配置)

此部分包含 REST API 的配置选项。

• https://quickwit.io/docs/configuration/node-config#configuring-cors-cross-origin-resource-sharing

Configuring CORS (配置跨源资源共享）

CORS（跨源资源共享）描述了哪些地址或来源可以从浏览器访问 REST API。
默认情况下，不允许跨源共享资源。

可以在 cors_allow_origins 参数中指定通配符、单一来源或多个来源：

REST 配置示例：

rest:
  listen_port: 1789
  extra_headers:
    x-header-1: header-value-1
    x-header-2: header-value-2
  cors_allow_origins: '*'

#   cors_allow_origins: https://my-hdfs-logs.domain.com   # Optionally we can specify one domain
#   cors_allow_origins:                                   # Or allow multiple origins
#     - https://my-hdfs-logs.domain.com
#     - https://my-hdfs.other-domain.com

gRPC configuration(gRPC 配置)

此部分包含用于节点间内部通信的 gRPC 服务和客户端的配置选项。

gRPC 配置示例：

grpc:
  max_message_size: 30 MiB

我们建议只有在遇到以下错误时才更改 20 MiB 的默认值：
Error, message length too large: found 24732228 bytes, the limit is: 20971520 bytes.(错误，消息长度过大：找到 24732228 字节，限制是：20971520 字节。) 在这种情况下，请逐步增加 max_message_size，每次增加 10 MiB，直到问题消失。这是一个临时解决方案：Quickwit 的下一个版本 0.8 将完全依赖于 gRPC 流式传输端点，并能处理任意长度的消息。

Storage configuration(存储配置)

请参阅专门的 存储配置 页面，了解如何为各种存储提供商配置 Quickwit 的更多信息。

• https://quickwit.io/docs/configuration/storage-config

这里还有一些如何使用 Amazon S3 或 Alibaba OSS 配置 Quickwit 的最小示例：

AWS_ACCESS_KEY_ID=<your access key ID>
AWS_SECRET_ACCESS_KEY=<your secret access key>

Amazon S3

storage:
  s3:
    region: us-east-1

Alibaba

storage:
  s3:
    region: us-east-1
    endpoint: https://oss-us-east-1.aliyuncs.com

Metastore configuration(元存储配置)

此部分可能包含每个可用元存储实现的一个配置子部分。每个实现的具体配置参数可能会有所不同。目前可用的元存储实现包括：

• File-backed
• PostgreSQL

File-backed metastore configuration(文件型元存储配置)

文件支持型元存储没有节点级别的配置。您可以在 索引级别 配置轮询间隔。

• https://quickwit.io/docs/configuration/metastore-config#polling-configuration

PostgreSQL metastore configuration(PostgreSQL 元存储配置)

PostgreSQL 元存储配置的 YAML 格式示例：

metastore:
  postgres:
    min_connections: 10
    max_connections: 50
    acquire_connection_timeout: 30s
    idle_connection_timeout: 1h
    max_connection_lifetime: 1d

Indexer configuration(索引器配置)

此部分包含索引器的配置选项。分片存储在 索引文档 中有详细说明。

• https://quickwit.io/docs/overview/concepts/indexing#split-store

示例：

indexer:
  split_store_max_num_bytes: 100G
  split_store_max_num_splits: 1000
  max_concurrent_split_uploads: 12
  enable_otlp_endpoint: true

Ingest API configuration(Ingest API 配置)

示例：

ingest_api:
  max_queue_memory_usage: 2GiB
  max_queue_disk_usage: 4GiB

Searcher configuration(搜索器配置)

此部分包含搜索器的配置选项。

• https://quickwit.io/docs/reference/metrics

Searcher split cache configuration(搜索器分片缓存配置)

此部分包含磁盘上搜索器分片缓存的配置选项。

示例：

searcher:
  fast_field_cache_capacity: 1G
  split_footer_cache_capacity: 500M
  partial_request_cache_capacity: 64M
  split_cache:
    max_num_bytes: 1G
    max_num_splits: 10000
    num_concurrent_downloads: 1

Jaeger configuration(Jaeger 配置)

示例：

searcher:
  enable_endpoint: true

Using environment variables in the configuration(在配置中使用环境变量)

您可以在配置文件中使用环境变量引用，以设置在部署期间需要可配置的值。为此，请使用：

${VAR_NAME}

其中 VAR_NAME 是环境变量的名称。

每个变量引用在启动时都会被环境变量的值替换。替换过程区分大小写，并且在解析配置文件之前发生。除非您指定了默认值或自定义错误文本，否则引用未定义的变量会抛出错误。

为了指定默认值，请使用：

${VAR_NAME:-default_value}

其中 default_value 是如果环境变量未设置时要使用的值。

<config_field>: ${VAR_NAME}
or
<config_field>: ${VAR_NAME:-default value}

例如:

export QW_LISTEN_ADDRESS=0.0.0.0

# config.yaml
version: 0.7
cluster_id: quickwit-cluster
node_id: my-unique-node-id
listen_address: ${QW_LISTEN_ADDRESS}
rest:
  listen_port: ${QW_LISTEN_PORT:-1111}

将被 Quickwit 理解为:

version: 0.7
cluster_id: quickwit-cluster
node_id: my-unique-node-id
listen_address: 0.0.0.0
rest:
  listen_port: 1111

Storage configuration(存储配置)

Supported Storage Providers(支持的存储提供商)

Quickwit 目前支持四种类型的存储提供商：

• Amazon S3 和 S3 兼容（Garage、MinIO 等）
• Azure Blob 存储
• 本地文件存储*
• Google Cloud Storage（原生 API）

Storage URIs(存储 URI)

存储 URI 通过 URI “协议” 或 “方案” 来标识不同的存储提供商。Quickwit 支持以下存储 URI 协议：

• s3:// 用于 Amazon S3 和 S3 兼容
• azure:// 用于 Azure Blob 存储
• file:// 用于本地文件系统
• gs:// 用于 Google Cloud Storage

通常情况下，您可以在任何直观地期望文件路径的地方使用存储 URI 或文件路径。例如：

• 设置索引的 index_uri 以指定存储提供商和位置；
• 在节点配置中设置 metastore_uri 以建立基于文件的元数据存储；
• 作为命令行参数传递文件路径。

Local file storage URIs(本地文件存储 URI)

Quickwit 将常规文件路径解释为本地文件系统 URI。允许使用相对文件路径，并且它们相对于当前工作目录（CWD）进行解析。可以使用 ~ 作为快捷方式来引用用户的主目录。以下是有效的本地文件系统 URI：

- /var/quickwit
- file:///var/quickwit
- /home/quickwit/data
- ~/data
- ./quickwit

当使用 file:// 协议时，需要第三个 / 来表示绝对路径。例如，URI file://home/quickwit/ 被解释为 ./home/quickwit。

Storage configuration(存储配置)

此部分包含针对每个存储提供商的一个配置子部分。如果未显式设置存储配置参数，则 Quickwit 依赖于存储提供商 SDK（Azure SDK for Rust，AWS SDK for Rust）提供的默认值。

• https://github.com/Azure/azure-sdk-for-rust
• https://github.com/awslabs/aws-sdk-rust

S3 storage configuration(S3 存储配置)

• https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html
• https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html
• https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html

将凭证硬编码到配置文件中是不安全的，强烈不建议这样做。优先考虑您的存储后端可能提供的替代认证方法。

Environment variables(环境变量)

Storage flavors(存储风味)

Storage flavors 确保 Quickwit 通过自动配置适当的设置与偏离 S3 API 的存储提供商正确工作。可用的风味包括：

• digital_ocean
• garage
• gcs
• minio

Digital Ocean

Digital Ocean flavor (digital_ocean) 强制使用路径风格访问，并关闭多对象删除请求。

Garage flavor

Garage flavor (garage) 覆盖 region 参数为 garage 并强制使用路径风格访问。

Google Cloud Storage

Google Cloud Storage flavor (gcs) 关闭多对象删除请求和多部分上传。

MinIO flavor

MinIO flavor (minio) 强制使用路径风格访问。

Google Cloud Storage 的存储配置 YAML 格式示例：

storage:
  s3:
    flavor: gcs
    region: us-east1
    endpoint: https://storage.googleapis.com

Azure storage configuration(Azure 存储配置)

Environment variables(环境变量)

Azure 的存储配置 YAML 格式示例：

storage:
  azure:
    account: your-azure-account-name
    access_key: your-azure-access-key

Storage configuration examples for various object storage providers(各种对象存储提供商的存储配置示例)

Garage

Garage 是一个为自托管定制的开源分布式对象存储服务。

• https://garagehq.deuxfleurs.fr/

storage:
  s3:
    flavor: garage
    endpoint: http://127.0.0.1:3900

MinIO

MinIO 是一种高性能的对象存储。

• https://min.io/

storage:
  s3:
    flavor: minio
    endpoint: http://127.0.0.1:9000

注意：default_index_root_uri 或索引 URI 不包含端点，您应该将其设置为典型的 S3 路径，如 s3://indexes。

Index configuration(索引配置)

本页面描述了如何配置一个索引。

除了 index_id 外，索引配置还允许您定义五个项目：

• index-uri：它定义了索引文件应存储的位置。
• 文档映射：它定义了一个文档及其包含的字段如何为给定索引存储和索引。
• 索引设置：它定义了用于分片的时间戳字段，以及一些更高级的参数，如合并策略。
• 搜索设置：它定义了默认搜索字段 default_search_fields，即如果用户查询没有明确指定字段时 Quickwit 将搜索的字段列表。
• 保留策略：它定义了 Quickwit 应保留已索引数据的时间长度。如果不指定，则数据将永久存储。

配置是在创建索引时设置的，并且可以使用 更新端点 或 CLI 进行更改。

• https://quickwit.io/docs/reference/rest-api
• https://quickwit.io/docs/reference/cli

Config file format(配置文件格式)

索引配置格式为 YAML。当配置文件中缺少某个键时，将使用默认值。
下面是一个适用于 HDFS 日志数据集的完整示例：

version: 0.7 # File format version.

index_id: "hdfs"

index_uri: "s3://my-bucket/hdfs"

doc_mapping:
  mode: lenient
  field_mappings:
    - name: timestamp
      type: datetime
      input_formats:
        - unix_timestamp
      output_format: unix_timestamp_secs
      fast_precision: seconds
      fast: true
    - name: severity_text
      type: text
      tokenizer: raw
      fast:
        - tokenizer: lowercase
    - name: body
      type: text
      tokenizer: default
      record: position
    - name: resource
      type: object
      field_mappings:
        - name: service
          type: text
          tokenizer: raw
  tag_fields: ["resource.service"]
  timestamp_field: timestamp
  index_field_presence: true

search_settings:
  default_search_fields: [severity_text, body]

retention:
  period: 90 days
  schedule: daily

Index ID(索引 ID)

索引 ID 是一个字符串，用于在元存储中唯一标识索引。它只能包含大写或小写的 ASCII 字母、数字、破折号 (-) 和下划线 (_)。最后，它必须以字母开头，并且至少包含 3 个字符但不超过 255 个字符。

Index uri(索引 URI)

索引 URI 定义了索引文件（也称为切片）应存储的位置。
此参数期望一个 存储 URI。

• https://quickwit.io/docs/configuration/storage-config#storage-uris

index-uri 参数是可选的。
默认情况下，index-uri 会通过将 index-id 与 Quickwit 的配置 中定义的 default_index_root_uri 连接起来计算得出。

• https://quickwit.io/docs/configuration/node-config

在分布式模式下运行 Quickwit 时，文件存储将无法工作。相反，在运行多个搜索节点时，应使用 AWS S3、Azure Blob 存储、Google Cloud Storage（在 S3 互操作模式下）或其他 S3 兼容的存储系统，如 Scaleway Object Storage 和 Garage 作为存储。

Doc mapping(文档映射)

文档映射定义了如何为给定索引存储和索引文档及其包含的字段。文档是一组命名字段的集合，每个字段都有自己的数据类型（文本、字节、日期时间、布尔、i64、u64、f64、IP、JSON）。

*: 标签字段和时间戳字段表示为从 JSON 对象根到给定字段的路径。如果字段名称包含一个 . 字符，则需要用 \ 字符转义。

• https://quickwit.io/docs/configuration/index-config#mode
• https://quickwit.io/docs/overview/concepts/querying#tag-pruning
• https://quickwit.io/docs/overview/architecture
• https://quickwit.io/docs/overview/concepts/querying#partitioning

Field types(字段类型)

每个字段[^1]都有一个类型，指示它包含的数据种类，例如 64 位整数或文本。
Quickwit 支持以下原始类型：text、i64、u64、f64、datetime、bool、ip、bytes 和 json，同时也支持复合类型，如数组和对象。在幕后，Quickwit 使用 tantivy 字段类型，如果您想深入了解细节，请参阅 tantivy 文档。

• https://quickwit.io/docs/configuration/index-config#text-type
• https://quickwit.io/docs/configuration/index-config#numeric-types-i64-u64-and-f64-type
• https://quickwit.io/docs/configuration/index-config#numeric-types-i64-u64-and-f64-type
• https://quickwit.io/docs/configuration/index-config#numeric-types-i64-u64-and-f64-type
• https://quickwit.io/docs/configuration/index-config#datetime-type
• https://quickwit.io/docs/configuration/index-config#bool-type
• https://quickwit.io/docs/configuration/index-config#ip-type
• https://quickwit.io/docs/configuration/index-config#bytes-type
• https://quickwit.io/docs/configuration/index-config#json-type
• https://github.com/tantivy-search/tantivy

Raw types(原始类型)

Text type(文本类型)

此字段是一个文本字段，在索引之前会被分析并拆分成令牌。
这种类型的字段适合全文搜索。

文本字段映射示例：

文本字段参数

• https://quickwit.io/docs/configuration/index-config#description-of-available-tokenizers
• https://quickwit.io/docs/configuration/index-config#description-of-available-normalizers

可用分词器的描述

可用规范化器的描述

记录选项的描述

使用位置索引是执行短语查询所必需的。

Numeric types: i64, u64 and f64 type(数值类型：i64、u64 和 f64 类型)

Quickwit 支持三种数值类型：i64、u64 和 f64。

数值值可以存储在快速字段中（相当于 Lucene 的 DocValues），这是一种用于范围查询和聚合的列式存储。

在未指定字段的情况下查询负数（使用 default_search_fields），您应该单引号括起数字（例如 -5），否则它将被解释为匹配除了该数字以外的任何内容。

u64 字段映射示例：

name: rating
description: Score between 0 and 5
type: u64
stored: true
indexed: true
fast: true

数值类型字段 (i64, u64, 和 f64) 参数

datetime type(日期时间类型)

datetime 类型处理日期和日期时间。由于 JSON 没有日期类型，datetime 字段支持多种输入类型和格式。支持的输入类型包括：

• 表示 Unix 时间戳的浮点数或整数
• 包含格式化的日期、日期时间或 Unix 时间戳的字符串

input_formats 字段参数指定了接受的日期格式。以下输入格式得到原生支持：

• iso8601
• rfc2822
• rfc3339
• strptime
• unix_timestamp

输入格式

当指定多个输入格式时，相应的解析器会按照声明的顺序尝试。以下格式得到原生支持：

• iso8601, rfc2822, rfc3339：使用标准的 ISO 和 RFC 格式解析日期。
• strptime：使用 Unix strptime 格式解析日期，有一些变化：

• strptime 格式标识符：%C, %d, %D, %e, %F, %g, %G, %h, %H, %I, %j, %k, %l, %m, %M, %n, %R, %S, %t, %T, %u, %U, %V, %w, %W, %y, %Y, %%。
• %f 用于毫秒精度支持。
• %z 时区偏移可以指定为 (+|-)hhmm 或 (+|-)hh:mm。

目前不支持时区名称格式标识符 (%Z)。
https://man7.org/linux/man-pages/man3/strptime.3.html

• unix_timestamp：解析浮点数和整数为 Unix 时间戳。浮点值转换为以秒表示的时间戳。整数值转换为 Unix 时间戳，其精度（秒、毫秒、微秒或纳秒）根据输入数字位数推断。内部地，日期时间转换为 UTC（如果指定了时区），并存储为 i64 整数。因此，Quickwit 只支持从 Apr 13, 1972 23:59:55 到 Mar 16, 2242 12:56:31 的时间戳值。

从浮点数到整数值的转换可能会导致精度损失。

当 datetime 字段存储为快速字段时，fast_precision 参数指示在编码前用于截断值的精度，这有助于压缩（此处的截断意味着清零）。fast_precision 参数可以取以下值：seconds, milliseconds, microseconds, 或 nanoseconds。它只影响标记为“快速”的 datetime 字段在快速字段中存储的内容。最后，对 datetime 快速字段的操作，例如通过聚合，需要在纳秒级别进行。

内部地，`datetime` 在快速字段和文档存储中以 `nanoseconds` 存储，在术语字典中以 `seconds` 存储。

此外，Quickwit 支持 output_format 字段参数来指定以何种精度反序列化日期时间。此参数支持与输入格式相同的值，除了 unix_timestamp 被替换为以下格式：

• unix_timestamp_secs：以秒显示时间戳。
• unix_timestamp_millis：以毫秒显示时间戳。
• unix_timestamp_micros：以微秒显示时间戳。
• unix_timestamp_nanos：以纳秒显示时间戳。

datetime 字段映射示例：

name: timestamp
type: datetime
description: Time at which the event was emitted
input_formats:
  - rfc3339
  - unix_timestamp
  - "%Y %m %d %H:%M:%S.%f %z"
output_format: unix_timestamp_secs
stored: true
indexed: true
fast: true
fast_precision: milliseconds

日期时间字段参数

bool type(布尔类型)

bool 类型接受布尔值。

布尔字段映射示例：

name: is_active
description: Activation status
type: bool
stored: true
indexed: true
fast: true

布尔字段参数

ip type(IP 类型)

ip 类型接受 IP 地址值，同时支持 IPv4 和 IPv6。内部地，IPv4 地址会被转换为 IPv6。

IP 字段映射示例：

name: host_ip
description: Host IP address
type: ip
fast: true

IP 字段参数

bytes type(二进制类型)

bytes 类型接受一个以 Base64 编码的字符串形式的二进制值。

二进制字段映射示例：

name: binary
type: bytes
stored: true
indexed: true
fast: true
input_format: hex
output_format: hex

二进制字段参数

json type(JSON 类型)

json 类型接受一个 JSON 对象。

JSON 字段映射示例：

name: parameters
type: json
stored: true
indexed: true
tokenizer: raw
expand_dots: false
fast:
  normalizer: lowercase

JSON 字段参数

• https://quickwit.io/docs/configuration/index-config#description-of-available-normalizers

注意 tokenizer 和 record 与文本字段具有相同的定义和相同的效果。

要在 JSON 对象中搜索，则需要扩展字段名以指向目标值的路径。

例如，当索引以下对象时：

{
    "product_name": "droopy t-shirt",
    "attributes": {
        "color": ["red", "green", "white"],
        "size:": "L"
    }
}

假设 attributes 已经被定义为如下字段映射：

- type: json
  name: attributes

attributes.color:red 是一个有效的查询。

如果另外将 attributes 设置为默认搜索字段，那么 color:red 也是一个有效的查询。

Composite types(复合类型)

array(数组)

Quickwit 支持所有原始类型（除了 object 类型）的数组。

要在索引配置中声明一个 i64 类型的数组，只需将类型设置为 array<i64> 即可。

object(对象)

Quickwit 支持嵌套对象，只要它不包含对象数组即可。

name: resource
type: object
field_mappings:
  - name: service
    type: text

concatenate(拼接)

Quickwit 支持将多个字段的内容映射到单一字段上。这在查询时可能比遍历数十个 default_search_fields 更高效。它还允许在不知道要搜索字段的路径的情况下，在 JSON 字段内进行查询。

name: my_default_field
type: concatenate
concatenated_fields:
  - text # things inside text, tokenized with the `default` tokenizer
  - resource.author # all fields in resource.author, assuming resource is an `object` field.
include_dynamic_fields: true
tokenizer: default
record: basic

拼接字段不支持快速字段，并且永远不会存储。它们使用自己的分词器，独立于各个字段上配置的分词器。
在查询时，拼接字段不支持范围查询。
仅支持以下类型的拼接字段：text、bool、i64、u64、json。其他类型会在创建索引时被拒绝，或者如果在 JSON 字段中发现，则在索引化过程中被静默丢弃。
向拼接字段添加对象字段不会自动添加其子字段（目前还不支持）。
无法从 JSON 字段添加子字段到拼接字段。例如，如果 attributes 是一个 JSON 字段，则无法仅将 attributes.color 添加到拼接字段中。

对于 JSON 字段和动态字段，仅索引值而不索引路径。例如，给定以下文档：

{
  "421312": {
    "my-key": "my-value"
  }
}

可以搜索 my-value 而不必知道完整的路径，但无法搜索包含键 my-key 的所有文档。

Mode

mode 描述了当 Quickwit 接收到未在字段映射中定义的字段时的行为。

Quickwit 提供了三种不同的模式：

• dynamic（默认值）：未映射的字段会被 Quickwit 收集，并按照 dynamic_mapping 参数中定义的方式处理。
• lenient：未映射的字段会被 Quickwit 忽略。
• strict：如果文档包含未映射的字段，Quickwit 将会忽略该文档，并将其计为错误。

Dynamic Mapping(动态映射)

dynamic 模式使得可以在无模式或部分模式的情况下运行 Quickwit。
dynamic 模式的配置可通过 dynamic_mapping 参数设置。
dynamic_mapping 提供与配置 json 字段相同的配置选项，默认为：

version: 0.7
index_id: my-dynamic-index
doc_mapping:
  mode: dynamic
  dynamic_mapping:
    indexed: true
    stored: true
    tokenizer: default
    record: basic
    expand_dots: true
    fast: true

当 dynamic_mapping 设置为已索引（默认），通过动态模式映射的字段可以通过针对从 JSON 对象根部访问它们所需的路径来搜索。

例如，在完全无模式的设置下，最简单的索引配置可能是：

version: 0.7
index_id: my-dynamic-index
doc_mapping:
    # If you have a timestamp field, it is important to tell quickwit about it.
    timestamp_field: unix_timestamp
    # mode: dynamic #< Commented out, as dynamic is the default mode.

有了这样一个简单的配置，我们可以对一个复杂的文档进行索引，如下面所示：

{
  "endpoint": "/admin",
  "query_params": {
    "ctk": "e42bb897d",
    "page": "eeb"
  },
  "src": {
    "ip": "8.8.8.8",
    "port": 53,
  },
  //...
}

以下查询是有效的，并匹配上述文档。

// Fields can be searched simply.
endpoint:/admin

// Nested object can be queried by specifying a `.` separated
// path from the root of the json object to the given field.
query_params.ctk:e42bb897d

// numbers are searchable too
src.port:53

// and of course we can combine them with boolean operators.
src.port:53 AND query_params.ctk:e42bb897d

Field name validation rules(字段名称验证规则)

目前 Quickwit 只接受符合以下正则表达式的字段名称：
^[@$_\-a-zA-Z][@$_/\.\-a-zA-Z0-9]{0,254}$

用通俗的语言来说：

• 需要有至少一个字符。
• 只能包含大写和小写的 ASCII 字母 [a-zA-Z]、数字 [0-9]、.、破折号 -、下划线 _、斜杠 /、at 符号 @ 和美元符号 $。
• 不得以点号或数字开头。
• 必须与 Quickwit 的保留字段映射名称 _source、_dynamic、_field_presence 不同。

对于包含 . 字符的字段名称，在引用它们时需要对其进行转义。否则 . 字符将被视为 JSON 对象属性的访问。因此，建议避免使用包含 . 字符的字段名称。

Behavior with null values or missing fields(对空值或缺失字段的行为)

JSON 文档中的 null 值或缺失字段在索引时将被静默忽略。

Indexing settings(索引设置)

本节描述了给定索引的索引设置。

• https://quickwit.io/docs/configuration/index-config#merge-policies

Merge policies(合并策略)

Quickwit 使得可以定义用于决定哪些拆分应该合并以及何时合并的策略。

Quickwit 提供了三种不同的合并策略，每种都有自己的参数集。

"Stable log" merge policy(“稳定日志”合并策略)

稳定日志合并策略试图最小化写入放大效应，并尽可能保持较高的时间修剪能力，通过合并大小相似且时间跨度相近的拆分。

Quickwit 默认的合并策略是 stable_log 合并策略，参数如下：

version: 0.7
index_id: "hdfs"
# ...
indexing_settings:
  merge_policy:
    type: "stable_log"
    min_level_num_docs: 100000
    merge_factor: 10
    max_merge_factor: 12
    maturation_period: 48h

"Limit Merge" merge policy(“限制合并”合并策略)

“限制合并”合并策略被认为是高级功能。

限制合并策略通过设置拆分应经历的合并操作次数的上限来简单地限制写入放大效应。

version: 0.7
index_id: "hdfs"
# ...
indexing_settings:
  merge_policy:
    type: "limit_merge"
    max_merge_ops: 5
    merge_factor: 10
    max_merge_factor: 12
    maturation_period: 48h

No merge(不合并)

no_merge 合并策略完全禁用合并。

此设置不推荐使用。合并是必要的，因为它可以减少拆分的数量，从而提高搜索性能。

version: 0.7
index_id: "hdfs"
indexing_settings:
    merge_policy:
        type: "no_merge"

Indexer memory usage(索引器内存使用)

索引器默认使用 2 GiB 的堆内存。这并不直接反映总体内存使用情况，但将这个值加倍应该能得到一个合理的近似值。

Search settings(搜索设置)

本节描述了给定索引的搜索设置。

Retention policy(保留策略)

本节描述了 Quickwit 如何管理数据保留。在 Quickwit 中，保留策略管理器按拆分删除数据，而不是单独删除文档。拆分根据其 time_range 进行评估，该 time_range 来自索引时间戳字段（在 (doc_mapping.timestamp_field) 设置中指定）。使用此设置，当 now() - split.time_range.end >= retention_policy.period 时，保留策略将删除拆分。

version: 0.7
index_id: hdfs
# ...
retention:
  period: 90 days
  schedule: daily

period 被指定为一系列时间间隔。每个时间间隔是一个整数后跟一个单位后缀，如：2 days 3h 24min。支持的单位有：

• nsec, ns -- 纳秒
• usec, us -- 微秒
• msec, ms -- 毫秒
• seconds, second, sec, s
• minutes, minute, min, m
• hours, hour, hr, h
• days, day, d
• weeks, week, w
• months, month, M -- 一个月定义为 30.44 天
• years, year, y -- 一年定义为 365.25 天

Metastore configuration

Quickwit 需要一个地方来存储关于其索引的元信息。

例如：

• 索引配置。
• 关于其拆分的元信息。例如，它们的 ID、包含的文档数量、大小、最小/最大时间戳以及拆分中存在的标签集。
• 不同来源的检查点。
• 一些额外的信息，如索引创建时间。

元存储完全由一个 URI 定义。可以通过编辑 节点配置文件（通常命名为 quickwit.yaml）中的 metastore_uri 参数来设置它。

• https://quickwit.io/docs/configuration/node-config

目前，Quickwit 提供了两种实现：

• PostgreSQL：推荐用于分布式使用。
• File-backed implementation。

PostgreSQL Metastore(PostgreSQL 元存储)

对于任何分布式使用场景，我们推荐使用 PostgreSQL 元存储。

可以通过在 Quickwit 配置文件中的 metastore_uri 参数设置 PostgreSQL URI 来配置 PostgreSQL 元存储。URI 的格式如下：

postgres://[user]:[password]@[host]:[port]/[dbname]

一些参数可以省略。以下 PostgreSQL URI 是有效的示例：

postgres://localhost/mydb
postgres://user@localhost
postgres://user:secret@localhost
postgres://host1:123,host2:456/mydb

数据库需要提前创建。

在首次执行时，Quickwit 将透明地创建必要的表。

同样，如果你将 Quickwit 升级到包含 PostgreSQL 模式更改的版本，Quickwit 将在启动时透明地执行迁移。

File-backed metastore(基于文件的元存储)

为了方便起见，Quickwit 还允许使用基于文件的元存储来将其元数据存储在文件中。在这种情况下，Quickwit 将为每个索引写一个文件。

然后通过传递一个 存储 URI 来配置元存储，该 URI 将作为元存储的根目录。

• https://quickwit.io/docs/configuration/storage-config#storage-uris

与给定索引关联的元数据文件将存储在

[storage_uri]/[index_id]/metastore.json

目前，Quickwit 支持两种类型的存储：

• 本地文件系统 URI（例如，file:///opt/toto）。直接传递文件路径（不带 file://）也是有效的，例如 /var/quickwit。相对路径将相对于当前工作目录解析。
• S3 兼容的存储 URI（例如，s3://my-bucket/some-path）。参阅 存储配置 文档来配置 S3 或 S3 兼容的存储提供商。

• https://quickwit.io/docs/configuration/storage-config

Polling configuration(拉取配置)

默认情况下，基于文件的元存储仅在启动 Quickwit 进程（如搜索器、索引器等）时读取一次。

您还可以配置它定期拉取基于文件的元存储以保持最新视图。这对于需要了解由并行运行的索引器发布的新的拆分的搜索器实例很有用。

要配置拉取间隔（以秒为单位），请向存储 URI 添加 URI 片段，如下所示：s3://quickwit/my-indexes#polling_interval=30s

拉取间隔只能以秒为单位配置；其他单位，如分钟或小时，不受支持。 Amazon S3 对每 1000 次 GET 请求收取 $0.0004 的费用。每 30 秒拉取一次元存储每月和每个索引的成本为 $0.04。

Examples(示例)

以下基于文件的元存储 URI 是有效的：

s3://my-indexes
s3://quickwit/my-indexes
s3://quickwit/my-indexes#polling_interval=30s
file:///local/indices
file:///local/indices#polling_interval=30s
/local/indices
./quickwit-metastores

基于文件的元存储不支持同时运行多个实例，因为它没有实现任何锁定机制来防止并发写入相互覆盖。确保任何时候只运行一个基于文件的元存储实例。

Source configuration(数据来源配置)

Quickwit 可以从一个或多个来源将数据插入到索引中。
可以在创建索引后使用 CLI 命令 quickwit source create 添加来源。
也可以使用 quickwit source enable/disable 子命令启用或禁用来源。

• https://quickwit.io/docs/reference/cli#source

来源是通过一个称为来源配置的对象声明的，该对象定义了来源的设置。它由多个参数组成：

• 来源 ID
• 来源类型
• 来源参数
• 输入格式
• 每个索引器的最大管道数（可选）
• 期望的管道数（可选）
• 转换参数（可选）

Source ID(来源 ID)

来源 ID 是一个字符串，用于在索引内唯一标识来源。它只能包含大写或小写的 ASCII 字母、数字、连字符 (-) 和下划线 (_)。最后，它必须以字母开头，并且至少包含 3 个字符，但不超过 255 个。

Source type(来源类型)

来源类型指定了正在配置的来源种类。截至版本 0.5，可用的来源类型有 ingest-api、kafka、kinesis 和 pulsar。file 类型也受支持，但仅用于从 CLI 进行本地摄入。

• https://quickwit.io/docs/main-branch/reference/cli#tool-local-ingest

Source parameters(来源参数)

来源参数指示如何连接到数据存储，并且特定于来源类型。

File source(文件数据来源)

文件来源从包含由新行分隔的 JSON 对象（NDJSON）的文件中读取数据。如果文件名以 .gz 后缀结尾，则支持 Gzip 压缩。

Ingest a single file (摄入特定文件 CLI only)

要摄入特定文件，请直接在临时 CLI 进程中运行索引：

./quickwit tool local-ingest --index <index> --input-path <input-path>

本地文件和对象文件都受支持，前提是环境已使用适当的权限进行配置。有一个教程可供参考 这里。

• https://quickwit.io/docs/ingest-data/ingest-local-file

Notification based file ingestion (基于通知的文件摄入 beta)

Quickwit 可以自动摄入所有上传到 S3 存储桶的新文件。这需要创建并配置一个 SQS 通知队列。一个完整的示例可以在 这个教程 中找到。

• https://docs.aws.amazon.com/AmazonS3/latest/userguide/ways-to-add-notification-config-to-bucket.html
• https://quickwit.io/docs/ingest-data/sqs-files

notifications 参数接受一个通知设置数组。目前每个来源可以配置一个通知器，并且仅支持 SQS 通知 type。

SQS notifications 参数项所需的字段：

• type: sqs
• queue_url: SQS 队列的完整 URL（例如 https://sqs.us-east-1.amazonaws.com/123456789012/queue-name）
• message_type: 消息负载的格式，可以是

• s3_notification: 一个 S3 事件通知
• raw_uri: 包含文件对象 URI 的消息（例如 s3://mybucket/mykey）
• https://docs.aws.amazon.com/AmazonS3/latest/userguide/EventNotifications.html

使用 CLI 向索引添加带有 SQS 通知的文件来源

• https://quickwit.io/docs/reference/cli#source

cat << EOF > source-config.yaml
version: 0.8
source_id: my-sqs-file-source
source_type: file
num_pipelines: 2
params:
  notifications:
    - type: sqs
      queue_url: https://sqs.us-east-1.amazonaws.com/123456789012/queue-name
      message_type: s3_notification
EOF
./quickwit source create --index my-index --source-config source-config.yaml

• Quickwit 在成功摄入后不会自动删除来源文件。您可以使用 S3 对象过期 来配置它们应在存储桶中保留多久。
• 配置通知仅转发类型为 s3:ObjectCreated:* 的事件。其他事件会被来源确认，但不再进一步处理，并记录警告。
• 我们强烈建议使用 死信队列 来接收所有无法被文件来源处理的消息。maxReceiveCount 的值为 5 是一个不错的默认值。以下是一些常见情况，其中通知消息最终会进入死信队列：

• 通知消息无法解析（例如，它不是一个有效的 S3 通知）
• 文件未找到
• 文件损坏（例如，意外压缩）

https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-expire-general-considerations.htmlhttps://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html

Ingest API source(Ingest API 来源)

Ingest API 来源从 Ingest API 读取数据。此来源会在创建索引时自动生成，不能删除或禁用。

• https://quickwit.io/docs/main-branch/reference/rest-api#ingest-data-into-an-index

Kafka source(Kafka 来源)

Kafka 来源从 Kafka 流中读取数据。流中的每条消息必须包含一个 JSON 对象。

有一个教程可供参考 这里。

• https://quickwit.io/docs/main-branch/ingest-data/kafka

Kafka source parameters(Kafka 参数)

Kafka 来源使用客户端库 librdkafka 消费 topic，并将 client_params 参数携带的键值对转发给底层的 librdkafka 消费者。常见的 client_params 选项包括引导服务器 (bootstrap.servers) 或安全协议 (security.protocol)。请参阅 Kafka 和 librdkafka 文档页面获取更高级的选项。

• https://github.com/edenhill/librdkafka
• https://kafka.apache.org/documentation/#consumerconfigs
• https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md

Kafka 客户端参数

• bootstrap.servers 逗号分隔的主机和端口对列表，这些是 Kafka 集群中 Kafka 经纪人的地址子集。
• auto.offset.reset 定义了来源在消费一个分区时的行为，该分区在检查点中没有保存初始偏移量。earliest 从分区开始消费，而 latest（默认）从分区末尾消费。
• enable.auto.commit 此设置被忽略，因为 Kafka 来源使用 检查点 API 内部管理提交偏移量，并强制禁用自动提交。

• https://quickwit.io/docs/overview/concepts/indexing#checkpoint

• group.id 基于 Kafka 的分布式索引依赖于消费者组。除非在客户端参数中覆盖，默认分配给来源管理的每个消费者的组 ID 是 quickwit-{index_uid}-{source_id}。
• max.poll.interval.ms 短的最大轮询间隔持续时间可能会导致来源在索引器出现反压时崩溃。因此，Quickwit 建议使用默认值 300000（5 分钟）。

使用 CLI 向索引添加 Kafka 来源

• https://quickwit.io/docs/reference/cli#source

cat << EOF > source-config.yaml
version: 0.8
source_id: my-kafka-source
source_type: kafka
num_pipelines: 2
params:
  topic: my-topic
  client_params:
    bootstrap.servers: localhost:9092
    security.protocol: SSL
EOF
./quickwit source create --index my-index --source-config source-config.yaml

Kinesis source(Kinesis 来源)

Kinesis 来源从 Amazon Kinesis 流中读取数据。流中的每条消息必须包含一个 JSON 对象。

• https://aws.amazon.com/kinesis/

有一个教程可供参考 这里。

• https://quickwit.io/docs/main-branch/ingest-data/kinesis

Kinesis source parameters

Kinesis 来源通过 stream_name 和 region 消费一个流。

如果没有指定区域，Quickwit 将尝试在多个其他位置查找区域，并按照以下优先顺序：

1. 环境变量 (AWS_REGION 然后是 AWS_DEFAULT_REGION)
2. 配置文件，通常位于 ~/.aws/config 或者如果设置了 AWS_CONFIG_FILE 环境变量且不为空，则按其指定的位置。
3. Amazon EC2 实例元数据服务确定当前运行的 Amazon EC2 实例所在的区域。
4. 默认值：us-east-1

使用 CLI 向索引添加 Kinesis 来源

• https://quickwit.io/docs/reference/cli#source

cat << EOF > source-config.yaml
version: 0.7
source_id: my-kinesis-source
source_type: kinesis
params:
  stream_name: my-stream
EOF
quickwit source create --index my-index --source-config source-config.yaml

Pulsar source(Pulsar 来源)

Pulsar 来源从一个或多个 Pulsar 主题读取数据。每个主题中的消息必须包含一个 JSON 对象。

有一个教程可供参考 这里。

• https://quickwit.io/docs/main-branch/ingest-data/pulsar

Pulsar source parameters

Pulsar 来源使用客户端库 pulsar-rs 消费 topics。

• https://github.com/streamnative/pulsar-rs

使用 CLI 向索引添加 Pulsar 来源

• https://quickwit.io/docs/reference/cli#source

cat << EOF > source-config.yaml
version: 0.7
source_id: my-pulsar-source
source_type: pulsar
params:
  topics:
    - my-topic
  address: pulsar://localhost:6650
EOF
./quickwit source create --index my-index --source-config source-config.yaml

Number of pipelines(管道数量)

num_pipelines 参数仅适用于像 Kafka、GCP PubSub 和 Pulsar 这样的分布式来源。

它定义了要在集群上为来源运行的管道数量。这些管道在不同索引器上的实际放置将由控制平面决定。

请注意，对于像 Kafka 这样的分区来源，通过将不同的分区分配给不同的管道来分布索引负载。因此，重要的是确保分区的数量是 num_pipelines 的倍数。

此外，假设您只在 Quickwit 集群中索引单个 Kafka 来源，您应该将管道数量设置为索引器数量的倍数。最后，如果您的索引吞吐量很高，您应该为每个管道配置 2 到 4 个 vCPU。

例如，假设您想要索引一个 60 个分区的主题，每个分区接收 10 MB/s 的吞吐量。如果您测量到 Quickwit 可以以每管道 40 MB/s 的速度索引您的数据，那么可能的设置可以是：

• 5 个索引器，每个有 8 个 vCPU
• 15 个管道

这样，每个索引器将负责 3 个管道，每个管道将覆盖 4 个分区。

Transform parameters(转换参数)

除了 ingest-api 类型之外的所有来源类型，在索引之前可以使用 Vector Remap Language (VRL) 脚本转换摄取的文档。

• https://vector.dev/docs/reference/vrl/

• https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

# Your source config here
# ...
transform:
  script: |
    .message = downcase(string!(.message))
    .timestamp = now()
    del(.username)
  timezone: local

Input format(输入格式)

input_format 参数指定了来源预期的数据格式。目前支持两种格式：

• json: JSON，这是默认格式
• plain_text: 非结构化文本文档

内部而言，Quickwit 只能索引 JSON 数据。为了允许摄取纯文本文档，Quickwit 会将它们实时转换成如下形式的 JSON 对象：{"plain_text": "<original plain text document>"}。然后，可以使用 VRL 脚本将它们可选地转换为更复杂的文档。（参见 transform 特性）。

• https://quickwit.io/docs/configuration/source-config#transform-parameters

下面是一个如何解析并转换包含用户列表的 CSV 数据集的例子，其中用户由 3 个属性描述：名字、姓氏和年龄。

# Your source config here
# ...
input_format: plain_text
transform:
  script: |
    user = parse_csv!(.plain_text)
    .first_name = user[0]
    .last_name = user[1]
    .age = to_int!(user[2])
    del(.plain_text)

Enabling/Disabling a source from an index(启用/禁用索引中的来源)

可以通过 CLI 命令 quickwit source enable 或 quickwit source disable 启用或禁用索引中的来源：

• https://quickwit.io/docs/reference/cli

quickwit source disable --index my-index --source my-source

来源默认是启用的。当禁用一个来源时，相关的索引管道将在每个相关索引器上关闭，对该来源的索引也会暂停。

Deleting a source from an index(从索引中删除来源)

可以通过 CLI 命令 quickwit source delete 从索引中移除来源：

• https://quickwit.io/docs/reference/cli

quickwit source delete --index my-index --source my-source

删除来源时，与来源关联的检查点也会被移除。

Ports configuration(端口配置)

当启动 Quickwit 搜索服务器时，可以配置的一个重要参数是 rest.listen_port（默认值为 7280）。

内部而言，Quickwit 实际上会使用三个套接字。这三个套接字的端口目前无法独立配置。
使用的端口相对于 rest.listen_port 端口计算得出，具体如下。

目前无法独立配置这些端口。

为了形成集群，还需要定义一个 peer_seeds 参数。
以下地址是有效的对等种子地址：

如果在对等节点地址中没有指定端口，Quickwit 节点将假定该对等节点使用与自己相同的端口。

更多

1. Binance 如何使用 Quickwit 构建 100PB 日志服务(Quickwit 博客)