折腾 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(常规配置)

属性	描述	环境变量	默认值
version	配置文件版本。0.7 是唯一可用的值，并且与 0.5 和 0.4 版本向后兼容。
cluster_id	节点将加入的集群的唯一标识符。共享同一网络的集群应使用不同的集群ID。	QW_CLUSTER_ID	quickwit-default-cluster
node_id	节点的唯一标识符。它必须与集群中其他节点的标识符不同。如果未设置，则默认为实例的短主机名。	QW_NODE_ID	短主机名
enabled_services	已启用的服务(控制平面、索引器、清理程序、元存储、搜索器)	QW_ENABLED_SERVICES	所有服务
listen_address	Quickwit 服务绑定的 IP 地址或主机名，用于启动 REST 和 gRPC 服务器以及连接此节点到其他节点。默认情况下，Quickwit 绑定到 127.0.0.1(本地主机)。当尝试形成集群时，此默认值无效。	QW_LISTEN_ADDRESS	127.0.0.1
advertise_address	节点广播的 IP 地址，即对等节点用于连接到该节点进行远程过程调用的 IP 地址。	QW_ADVERTISE_ADDRESS	listen_address
gossip_listen_port	监听 Gossip 集群成员服务(UDP)的端口。	QW_GOSSIP_LISTEN_PORT	rest.listen_port
grpc_listen_port	gRPC 服务监听流量的端口。	QW_GRPC_LISTEN_PORT	rest.listen_port + 1
peer_seeds	用于引导集群并发现完整节点集的 IP 地址或主机名列表。此列表可以包含当前节点的地址，并不需要详尽无遗。如果 peer_seeds 列表中包含主机名，Quickwit 将通过每分钟查询 DNS 来解析它。例如，在 Kubernetes 中，最好将其设置为 无头服务。	QW_PEER_SEEDS
data_dir	用于持久化数据(临时数据、用于缓存目的的切片)的目录路径。这主要用于索引操作。	QW_DATA_DIR	./qwdata
metastore_uri	元存储 URI。可以是本地目录或 s3://my-bucket/indexes 或 postgres://username:password@localhost:5432/metastore。了解更多关于元存储配置的信息。	QW_METASTORE_URI	{data_dir}/indexes
default_index_root_uri	定义存储索引数据(切片)位置的默认索引根 URI。索引 URI 的构建遵循以下模式：{default_index_root_uri}/{index-id}	QW_DEFAULT_INDEX_ROOT_URI	{data_dir}/indexes
仅环境变量	Quickwit 的日志级别。可以是直接的日志级别，或者是由逗号分隔的 module_name=level 列表。	RUST_LOG	info

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

REST configuration(REST 配置)

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

属性	描述	环境变量	默认值
listen_port	REST API 监听 HTTP 流量的端口。	QW_REST_LISTEN_PORT	7280
cors_allow_origins	配置允许访问 API 的 CORS 来源。了解更多
extra_headers	头名称和值的列表

• 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 服务和客户端的配置选项。

属性	描述	环境变量	默认值
max_message_size	内部 gRPC 客户端和服务之间交换的消息的最大大小(字节)。		20 MiB

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=
AWS_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 元存储配置)

属性	描述	默认值
min_connections	池中始终维护的最小连接数。	0
max_connections	池中维护的最大连接数。	10
acquire_connection_timeout	在放弃查询之前等待可用连接的最大时间。	10s
idle_connection_timeout	关闭单个连接前的最大空闲持续时间。	10min
max_connection_lifetime	单个连接的最大生命周期。	30min

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

属性	描述	默认值
split_store_max_num_bytes	分片存储中允许的最大字节数。	100G
split_store_max_num_splits	分片存储中允许的最大文件数。	1000
max_concurrent_split_uploads	节点上允许的最大并发分片上传数。	12
merge_concurrency	节点上可以同时执行的最大合并操作数。	(2 x 可用线程数) / 3
enable_otlp_endpoint	如果为真，则启用通过 OpenTelemetry 协议 (OTLP) 接收日志和跟踪的 OpenTelemetry 导出端点。	false
cpu_capacity	控制平面使用的咨询参数。值可以用线程表示(例如 2)，也可以用 millicpus 表示(例如 2000m)。控制平面将尝试根据索引器声明的 CPU 容量，在不同节点上按比例调度索引管道。它不是作为限制使用。无论集群是否有足够的容量，所有管道都将被调度。当负载远低于 cpu_capacity 时，控制平面不会试图平均分配工作。需要在所有索引器节点上均衡负载的用户可以将 cpu_capacity 设置为一个任意低的值，只要它与可用线程数成比例即可。	可用线程数

示例：

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 配置)

属性	描述	默认值
max_queue_memory_usage	Ingest 队列在内存中的最大大小(字节)。	2GiB
max_queue_disk_usage	Ingest 队列占用的最大磁盘空间(字节)。最小大小至少为 256M 并且至少为 max_queue_memory_usage。	4GiB

示例：

ingest_api:
  max_queue_memory_usage: 2GiB
  max_queue_disk_usage: 4GiB

Searcher configuration(搜索器配置)

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

属性	描述	默认值
aggregation_memory_limit	控制聚合阶段前可以使用的最大内存量。此限制适用于每个请求和单个叶查询(叶查询是指并发查询一个或多个分片)。它用于防止聚合阶段中过度使用内存，这可能导致性能下降或崩溃。由于它是针对每个请求的，因此并发请求可能会超过此限制。	500M
aggregation_bucket_limit	确定返回给客户端的最大桶数。	65000
fast_field_cache_capacity	搜索器上的快速字段内存缓存容量。如果您按日期过滤、运行聚合、范围查询，或者使用搜索流 API，甚至进行追踪，可能值得增加此参数。以 quickwit_cache_fastfields_cache 开头的 指标 可帮助您在设置此值时做出明智的选择。	1G
split_footer_cache_capacity	搜索器上的分片尾部内存缓存容量(本质上是热缓存)。	500M
partial_request_cache_capacity	搜索器上的部分请求内存缓存容量。为请求缓存中间状态，可能使后续请求更快。可以通过将其大小设置为 0 来禁用它。	64M
max_num_concurrent_split_searches	在搜索器上运行的最大并发分片搜索请求数。	100
max_num_concurrent_split_streams	在搜索器上运行的最大并发分片流请求数。	100
split_cache	下面定义的搜索器分片缓存配置选项。如果未指定，则禁用缓存。

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

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

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

属性	描述	默认值
max_num_bytes	分片缓存中允许的最大磁盘大小(字节)。可能会被单个分片的大小超过。
max_num_splits	分片缓存中允许的最大分片数。	10000
num_concurrent_downloads	最大并发下载分片数。	1

示例：

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 配置)

属性	描述	默认值
enable_endpoint	如果为真，则启用允许 Jaeger 查询服务连接并检索跟踪的 gRPC 端点。	false

示例：

searcher:
  enable_endpoint: true

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

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

${VAR_NAME}

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

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

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

${VAR_NAME:-default_value}

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

: ${VAR_NAME}
or
: ${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 存储配置)

属性	描述	默认值
flavor	可选的存储风味。可用的风味包括 digital_ocean、garage、gcs 和 minio。
access_key_id	AWS 访问密钥 ID。
secret_access_key	AWS 密钥访问密钥。
region	发送请求的 AWS 区域。	us-east-1(SDK 默认值)
endpoint	与 S3 兼容提供商一起使用的自定义端点。	SDK 默认值
force_path_style_access	禁用 虚拟主机风格请求。某些 S3 兼容提供商(Ceph、MinIO)要求使用。	false
disable_multi_object_delete	禁用 多对象删除请求。某些 S3 兼容提供商(GCS)要求使用。	false
disable_multipart_upload	禁用 多部分上传对象。某些 S3 兼容提供商(GCS)要求使用。	false

• 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(环境变量)

环境变量	描述
QW_S3_ENDPOINT	自定义 S3 端点。
QW_S3_MAX_CONCURRENCY	限制对 S3 的并发请求数量。

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 存储配置)

属性	描述	默认值
account	Azure 存储账户名称。
access_key	Azure 存储账户访问密钥。

Environment variables(环境变量)

环境变量	描述
QW_AZURE_STORAGE_ACCOUNT	Azure Blob 存储账户名称。
QW_AZURE_STORAGE_ACCESS_KEY	Azure Blob 存储账户访问密钥。

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)。

变量	描述	默认值
field_mappings	字段映射的集合，每个映射都有其自己的数据类型(文本、二进制、日期时间、布尔、i64、u64、f64、IP、JSON)。	[]
mode	定义了 Quickwit 如何处理不在 field_mappings 中的文档字段。特别是，“动态”模式使得可以在无模式的方式下使用 Quickwit。(参见 mode)	dynamic
dynamic_mapping	当 mode 设置为 dynamic 时才允许此参数。然后它定义了是否应该对动态映射的字段进行索引、存储等。	(参见 mode)
tag_fields	已经在 field_mappings 中定义的字段集合*，这些字段的值将作为 tags 元数据的一部分存储。了解更多关于标签的信息。	[]
store_source	原始 JSON 文档是否存储在索引中。	false
timestamp_field	用于将文档分片的日期时间字段*。该字段必须是 datetime 类型。了解更多关于时间分片的信息。	None
partition_key	如果设置，Quickwit 将根据声明为 partition_key 的字段名称将文档路由到不同的切片中。	null
max_num_partitions	限制通过分区创建的切片数量。(参见 分区)	200
index_field_presence	对快速字段自动启用 exists 查询。为了对所有其他字段启用它，请将此参数设置为 true。启用它可能会在索引时产生显著的 CPU 开销。	false

*: 标签字段和时间戳字段表示为从 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(文本类型)

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

文本字段映射示例：

文本字段参数

变量	描述	默认值
description	字段的可选描述。	None
stored	值是否存储在文档存储中。	true
indexed	值是否应该被索引以便能够进行搜索。	true
tokenizer	Tokenizer 的名称。(查看分词器)以获取可用分词器的列表。	default
record	描述索引的信息量，可以选择 basic、freq 和 position。	basic
fieldnorms	是否为字段存储字段规范。字段规范用于计算文档的 BM25 分数。	false
fast	值是否存储在快速字段中。快速字段将包含术语 ID 和字典。对于 true 的默认行为是不变地存储原始文本。快速字段上的规范化器单独配置。可以通过 normalizer: lowercase 来配置。(查看规范化器)以获取可用规范化器的列表。	false

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

可用分词器的描述

分词器	描述
raw	不处理也不分词文本。过滤掉大于 255 字节的令牌。
raw_lowercase	不分词文本，但将其转换为小写。过滤掉大于 255 字节的令牌。
default	根据空白字符和标点符号分割文本，移除过长的令牌，并转换为小写。过滤掉大于 255 字节的令牌。
en_stem	类似于 default，但在结果令牌上还应用了词干提取。过滤掉大于 255 字节的令牌。
whitespace	仅根据空白字符分割文本。不移除长令牌也不转换为小写。
chinese_compatible	除了 default 执行的操作之外，还在每个 CJK 字符之间进行分割。应与 record: position 一起使用以正确地进行搜索。
lowercase	对文本应用小写转换。它不分词文本。

可用规范化器的描述

规范化器	描述
raw	不处理也不分词文本。过滤掉大于 255 字节的令牌。
lowercase	对文本应用小写转换。过滤掉大于 255 字节的令牌。

记录选项的描述

记录选项	描述
basic	仅记录 DocId
freq	记录文档 ID 以及术语频率
position	记录文档 ID、术语频率以及出现位置。

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

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) 参数

变量	描述	默认值
description	字段的可选描述。	None
stored	字段值是否存储在文档存储中。	true
indexed	字段值是否被索引。	true
fast	字段值是否存储在快速字段中。	false
coerce	是否将作为字符串传递的数字转换为整数或浮点数。	true
output_format	用于返回搜索结果中数字的 JSON 类型。可能的值为 number 或 string。	number

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

日期时间字段参数

变量	描述	默认值
input_formats	用于解析输入日期的格式	[rfc3339, unix_timestamp]
output_format	用于在搜索结果中显示日期的格式	rfc3339
stored	字段值是否存储在文档存储中	true
indexed	字段值是否被索引	true
fast	字段值是否存储在快速字段中	false
fast_precision	用于存储快速值的精度 (seconds, milliseconds, microseconds, 或 nanoseconds)	seconds

bool type(布尔类型)

bool 类型接受布尔值。

布尔字段映射示例：

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

布尔字段参数

变量	描述	默认值
description	字段的可选描述。	None
stored	值是否存储在文档存储中	true
indexed	值是否被索引	true
fast	值是否存储在快速字段中	false

ip type(IP 类型)

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

IP 字段映射示例：

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

IP 字段参数

变量	描述	默认值
description	字段的可选描述。	None
stored	值是否存储在文档存储中	true
indexed	值是否被索引	true
fast	值是否存储在快速字段中	false

bytes type(二进制类型)

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

二进制字段映射示例：

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

二进制字段参数

变量	描述	默认值
description	字段的可选描述。	None
stored	值是否存储在文档存储中	true
indexed	值是否被索引	true
fast	值是否存储在快速字段中。仅支持一对一基数，不支持 array 字段	false
input_format	用于表示输入二进制数据的编码，可以是 hex 或 base64	base64
output_format	用于在搜索结果中表示二进制数据的编码，可以是 hex 或 base64	base64

json type(JSON 类型)

json 类型接受一个 JSON 对象。

JSON 字段映射示例：

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

JSON 字段参数

变量	描述	默认值
description	字段的可选描述。	None
stored	值是否存储在文档存储中	true
indexed	值是否被索引	true
fast	值是否存储在快速字段中。JSON 中文本的默认行为是不变地存储文本。可以通过 normalizer: lowercase 配置一个标准化器。(查看可用的标准化器) 以获取可用标准化器列表。	true
tokenizer	仅影响 JSON 对象中的字符串。Tokenizer 的名称，可以选择 raw, default, en_stem 和 chinese_compatible	raw
record	仅影响 JSON 对象中的字符串。描述索引的信息量，可以选择 basic, freq 和 position	basic
expand_dots	如果为真，则包含 . 的 JSON 键将被展开。例如，如果 expand_dots 设置为真，则 {"k8s.node.id": "node-2"} 将像 {"k8s": {"node": {"id": "node2"}}} 一样被索引。这样做的好处是在查询时不需要转义 .。换句话说，k8s.node.id:node2 将匹配文档。这不会影响文档的存储方式。	true

• 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 即可。

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(索引设置)

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

变量	描述	默认值
commit_timeout_secs	自创建以来提交拆分的最大秒数。	60
split_num_docs_target	每个拆分的目标文档数。	10000000
merge_policy	描述触发拆分合并操作所采用的策略(参见下方的 合并策略 部分)。
resources.heap_size	每个来源每个索引的索引器堆大小。	2000000000
docstore_compression_level	docstore 中使用的 zstd 压缩级别。较低的值可能会提高摄取速度，但代价是索引大小	8
docstore_blocksize	docstore 中块的大小，以字节为单位。较小的值可能会提高文档检索速度，但代价是索引大小	1000000

• 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

变量	描述	默认值
merge_factor	(高级) 在单次合并操作中一起合并的拆分数目。	10
max_merge_factor	(高级) 在单次合并操作中可以一起合并的最大拆分数目。	12
min_level_num_docs	(高级) 文档数目低于此值的所有拆分被视为属于同一层级。	100000
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

变量	描述	默认值
max_merge_ops	给定拆分应经历的最大合并次数。	4
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(搜索设置)

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

变量	描述	默认值
default_search_fields	用于搜索的默认字段列表。此列表中的字段名称可以在模式中显式声明，也可以引用由动态模式捕获的字段。	None

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	以人类可读方式表示的拆分被删除后的持续时间(如 1 day、2 hours、a week 等)。	必需
schedule	以 cron 表达式 (0 0 * * * *) 或人类可读形式 (hourly、daily、weekly、monthly、yearly) 表示的保留策略评估和应用的频率。	hourly

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  --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

属性	描述	默认值
topic	要消费的主题名称。	必需
client_log_level	librdkafka 客户端日志级别。可能的值是：debug、info、warn、error。	info
client_params	librdkafka 客户端配置参数。	{}
enable_backfill_mode	回填模式在到达主题末尾后停止来源。	false

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 消费一个流。

属性	描述	默认值
stream_name	要消费的流名称。	必需
region	流所在的 AWS 区域。与 endpoint 互斥。	us-east-1
endpoint	用于与 AWS 兼容的 Kinesis 服务一起使用的自定义端点。与 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

属性	描述	默认值
topics	要消费的主题列表。	必需
address	Pulsar URL(pulsar:// 和 pulsar+ssl://)。	必需
consumer_name	要与 Pulsar 来源注册的消费者名称。	quickwit

使用 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/

属性	描述	默认值
script	执行以转换文档的 VRL 程序的源代码。	必需
timezone	VRL 程序中用于日期和时间操作的时区。它必须是 TZ 数据库 中的有效名称。	UTC

• 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": ""}。然后，可以使用 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 端口计算得出，具体如下。

服务	使用的端口	协议	默认值
带 REST API 的 HTTP 服务器	${rest.listen_port}	TCP	7280
集群成员资格	${rest.listen_port}	UDP	7280
GRPC 服务	${rest.listen_port} + 1	TCP	7281

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

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

类型	不带端口的示例	带端口的示例
IPv4	172.1.0.12	172.1.0.12:7180
IPv6	2001:0db8:85a3:0000:0000:8a2e:0370:7334	[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:7280
主机名	node3	node3:7180

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

更多

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