命令行选项

Quickwit 命令行工具让你能够启动 Quickwit 服务器并管理索引（创建、删除、导入数据）、分片和数据源（创建、删除、切换）。要启动一个服务器，quickwit 需要一个节点配置文件路径，你可以通过 QW_CONFIG 环境变量指定该路径：export QW_CONFIG=./config/quickwit.yaml。

此页面记录了所有可用的命令、相关选项和环境变量。

常见选项

为了在远程集群上管理索引、分片和数据源，你可能需要指定与 Quickwit 节点的连接。支持以下选项：

选项	描述	默认值
`--endpoint`	Quickwit 节点的 URL	`http://127.0.0.1:7280`
`--timeout`	命令超时时间	见下文
`--connect-timeout`	连接超时时间	`5s`

默认超时时间因命令而异：

search - 1 分钟
ingest（无 force 或 wait）- 1 分钟
ingest（有 force 或 wait）- 30 分钟
所有其他操作 - 10 秒

超时时间可以表示为秒、分钟、小时或天。例如：

10s - 10 秒超时
1m - 1 分钟超时
2h - 2 小时超时
1d - 1 天超时
none - 不设置超时

caution

在使用 Quickwit 与对象存储之前，请参阅我们关于在 AWS S3 上部署的指南，以避免账单上的意外费用。

命令

命令行概览语法

帮助

quickwit 或 quickwit --help 显示可用命令列表。

quickwit <command name> --help 显示命令的文档和使用示例。

版本

quickwit --version 显示版本信息。这对于报告错误很有帮助。

语法

CLI 结构化为带有子命令的高级命令。 quickwit [command] [subcommand] [args]。

command: run, index, split, source 和 tool。

run

启动一个默认启用了所有服务的 Quickwit 节点：indexer、searcher、metastore、control-plane 和 janitor。

Indexer 服务

Indexer 服务运行由控制面分配的索引管道。

Searcher 服务

在 rest_listing_address:rest_list_port 启动一个 Web 服务器，该服务器暴露 Quickwit REST API。其中 rest_listing_address 和 rest_list_port 在 Quickwit 配置文件（quickwit.yaml）中定义。节点可选地使用 peer_seeds 参数加入一个集群。这个节点地址列表用于通过流言协议发现集群中的其余对等节点，详见 chitchat。

Metastore 服务

Metastore 服务在网络中暴露 Quickwit Metastore。这是一个核心内部服务，对于操作 Quickwit 是必需的。因此，至少需要一个此服务的运行实例才能使其他服务正常工作。

控制面服务

控制面服务调度索引任务给 indexer。它监听 metastore 事件，如 source 创建、删除、切换或索引删除，并相应地更新索引计划。

Janitor 服务

Janitor 服务在索引上运行维护任务：垃圾收集、文档删除和保留策略任务。

note

Quickwit 需要打开以下端口以便进行集群形成和工作负载分配：

TCP 端口（默认为 7280）用于 REST API TCP 和 UDP 端口（默认为 7280）用于集群成员协议 TCP 端口 + 1（默认为 7281）用于分布式搜索的 gRPC 地址

如果端口已被占用，serve 命令将失败。

quickwit run [args]

概览

quickwit run
    [--config <config>]
    [--service <service>]

Options

选项	描述	默认值
`--config`	配置文件位置	`config/quickwit.yaml`
`--service`	要运行的服务（`indexer`、`searcher`、`metastore`、`control-plane` 或 `janitor`）。如果未指定，则启动所有支持的服务。

Examples

启动一个 indexer 和 metastore 服务

quickwit run --service indexer --service metastore --endpoint=http://127.0.0.1:7280

启动一个 control plane、metastore 和 janitor 服务

quickwit run --service control_plane --service metastore --service janitor --config=./config/quickwit.yaml

对 wikipedia 索引发起搜索请求

# To create wikipedia index and ingest data, go to our tutorials https://quickwit.io/docs/get-started/.
# Start a searcher.
quickwit run --service searcher --service metastore --config=./config/quickwit.yaml
# Make a request.
curl "http://127.0.0.1:7280/api/v1/wikipedia/search?query=barack+obama"

index

管理索引：创建、更新、删除、导入数据、搜索、描述等。

index create

根据位于 index-config 的 YAML 配置文件在 index-uri 创建一个 ID 为 index 的索引。索引配置允许你定义文档在索引上的映射以及每个字段如何存储和索引。如果省略了 index-uri，index-uri 将被设置为 {default_index_root_uri}/{index}，更多详细信息请参阅 Quickwit 配置文档。如果索引已存在，则命令会失败，除非指定了 overwrite。当启用 overwrite 时，命令会在创建新索引之前删除 index-uri 下存储的所有文件。

quickwit index create [args]

概览

quickwit index create
    --index-config <index-config>
    [--overwrite]

Options

选项	描述
`--index-config`	索引配置文件的位置。
`--overwrite`	覆盖已存在的索引。这将在创建新索引之前删除 `index-uri` 下存储的所有现有数据。

Examples

创建一个新的索引。

# Start a Quickwit server.
quickwit run --config=./config/quickwit.yaml
# Open a new terminal and run:
curl -o wikipedia_index_config.yaml https://raw.githubusercontent.com/quickwit-oss/quickwit/main/config/tutorials/wikipedia/index-config.yaml
quickwit index create --endpoint=http://127.0.0.1:7280 --index-config wikipedia_index_config.yaml

index update

使用索引配置文件更新索引。 quickwit index update [args]

概览

quickwit index update
    --index <index>
    --index-config <index-config>

选项

选项	描述
`--index`	目标索引的 ID
`--index-config`	索引配置文件的位置

清除索引

清除一个索引：删除所有分片并重置检查点。 quickwit index clear [args] quickwit index clr [args]

概要

quickwit index clear
    --index <index>

选项

选项	描述
`--index`	索引 ID

删除索引

删除一个索引。 quickwit index delete [args] quickwit index del [args]

概要

quickwit index delete
    --index <index>
    [--dry-run]

选项

选项	描述
`--index`	目标索引的 ID
`--dry-run`	以预演模式执行命令，仅显示待删除的分片列表。

示例

删除您的索引

# Start a Quickwit server.
quickwit run --service metastore --config=./config/quickwit.yaml
# Open a new terminal and run:
quickwit index delete --index wikipedia --endpoint=http://127.0.0.1:7280

索引描述

显示一个索引的描述性统计信息。 quickwit index describe [args]

概要

quickwit index describe
    --index <index>

选项

选项	描述
`--index`	目标索引的 ID

示例

显示您的索引的描述性统计信息

# Start a Quickwit server.
quickwit run --service metastore --config=./config/quickwit.yaml
# Open a new terminal and run:
quickwit index describe --endpoint=http://127.0.0.1:7280 --index wikipedia

1. General infos
===============================================================================
Index id:                           wikipedia
Index uri:                          file:///home/quickwit-indices/qwdata/indexes/wikipedia
Number of published splits:         1
Number of published documents:      300000
Size of published splits:           448 MB

2. Statistics on splits
===============================================================================
Document count stats:
Mean ± σ in [min … max]:            300000 ± 0 in [300000 … 300000]
Quantiles [1%, 25%, 50%, 75%, 99%]: [300000, 300000, 300000, 300000, 300000]

Size in MB stats:
Mean ± σ in [min … max]:            448 ± 0 in [448 … 448]
Quantiles [1%, 25%, 50%, 75%, 99%]: [448, 448, 448, 448, 448]

索引列表

列出所有索引。 quickwit index list [args] quickwit index ls [args]

示例

列出所有索引

# Start a Quickwit server.
quickwit run --config=./config/quickwit.yaml
# Open a new terminal and run:
quickwit index list --endpoint=http://127.0.0.1:7280
# Or with alias.
quickwit index ls --endpoint=http://127.0.0.1:7280

                                    Indexes                                     
+-----------+--------------------------------------------------------+
| Index ID  |                       Index URI                        |
+-----------+--------------------------------------------------------+
| hdfs-logs | file:///home/quickwit-indices/qwdata/indexes/hdfs-logs |
+-----------+--------------------------------------------------------+
| wikipedia | file:///home/quickwit-indices/qwdata/indexes/wikipedia |
+-----------+--------------------------------------------------------+

index ingest

索引位于 input-path 或从 stdin 读取的新行分隔的 JSON 对象数据集。数据将追加到目标索引 index，除非传递了 overwrite。input-path 可以是一个文件或其他命令输出到 stdin。目前仅支持本地数据集。默认情况下，Quickwit 的索引器将使用 2 GiB 的内存堆。了解如何在索引配置文档页面中更改 heap-size。

quickwit index ingest [args]

概要

quickwit index ingest
    --index <index>
    [--input-path <input-path>]
    [--batch-size-limit <batch-size-limit>]
    [--wait]
    [--force]
    [--commit-timeout <commit-timeout>]

选项

选项	描述
`--index`	目标索引的 ID
`--input-path`	输入文件的位置。
`--batch-size-limit`	每个提交的文档批次的大小限制。
`--wait`	在退出前等待所有文档被提交并可用于搜索。
`--force`	在发送最后一个文档后强制提交，并在退出前等待所有文档被提交并可用于搜索。
`--commit-timeout`	需要等待最终提交的导入操作的超时时间（`--wait` 或 `--force`）。这与 `commit_timeout_secs` 索引设置不同，后者设置了创建分片后的最大提交时间。

示例

从文件索引数据集

# Start a Quickwit server.
quickwit run --config=./config/quickwit.yaml
# Open a new terminal and run:
curl -o wiki-articles-10000.json https://quickwit-datasets-public.s3.amazonaws.com/wiki-articles-10000.json
quickwit index ingest --endpoint=http://127.0.0.1:7280 --index wikipedia --input-path wiki-articles-10000.json

从 stdin 索引数据集

# Start a Quickwit server.
quickwit run --config=./config/quickwit.yaml
# Open a new terminal and run:
cat wiki-articles-10000.json | quickwit index ingest --endpoint=http://127.0.0.1:7280 --index wikipedia

索引搜索

使用 ID --index 搜索索引，并返回与 --query 指定查询匹配的文档。更多关于查询语言的细节，请参阅查询语言页面。可以使用 start-offset 和 max-hits 选项设置返回的第一个命中结果的偏移量和返回的命中结果数量。可以通过 search-fields 选项覆盖默认的搜索字段，定义 Quickwit 在用户查询未明确指定字段时将搜索的字段列表。如果通过 snippet-fields 选项请求，Quickwit 将返回匹配内容的片段。还可以使用 start-timestamp 和 end-timestamp 选项限制搜索的时间范围。这些时间戳选项在使用时间序列数据集时有助于提高查询性能。

warning

start_timestamp 和 end_timestamp 应以秒为单位指定，无论时间戳字段的精度如何。时间戳字段的精度仅影响其作为快速字段的存储方式，而文档过滤始终以秒为单位进行。

quickwit index search [args]

概要

quickwit index search
    --index <index>
    --query <query>
    [--aggregation <aggregation>]
    [--max-hits <max-hits>]
    [--start-offset <start-offset>]
    [--search-fields <search-fields>]
    [--snippet-fields <snippet-fields>]
    [--start-timestamp <start-timestamp>]
    [--end-timestamp <end-timestamp>]
    [--sort-by-score]

选项

选项	描述	默认值
`--index`	目标索引的 ID
`--query`	使用自然查询语言表达的查询 ((barack AND obama) OR "president of united states")。了解更多：https://quickwit.io/docs/reference/search-language
`--aggregation`	以 tantivy/elasticsearch 格式序列化的聚合请求 JSON
`--max-hits`	返回的最大命中结果数	`20`
`--start-offset`	返回的第一个命中结果在全局结果集中的偏移量	`0`
`--search-fields`	如果用户查询未明确指定字段，则 Quickwit 将在此字段列表中进行搜索。它会覆盖索引配置中定义的默认搜索字段。例如："field1 field2"
`--snippet-fields`	Quickwit 将返回片段高亮的字段列表。例如："field1 field2"
`--start-timestamp`	过滤掉该时间戳之前的所有文档（仅适用于时间序列索引）
`--end-timestamp`	过滤掉该时间戳之后的所有文档（仅适用于时间序列索引）
`--sort-by-score`	按 BM25 分数对文档进行排序

示例

搜索一个索引

# Start a Quickwit server.
quickwit run --config=./config/quickwit.yaml
# Open a new terminal and run:
quickwit index search --endpoint=http://127.0.0.1:7280 --index wikipedia --query "Barack Obama"
# If you have jq installed.
quickwit index search --endpoint=http://127.0.0.1:7280 --index wikipedia --query "Barack Obama" | jq '.hits[].title'

按 BM25 分数对文档进行排序

# Start a Quickwit server.
quickwit run --config=./config/quickwit.yaml
# Open a new terminal and run:
quickwit index search --endpoint=http://127.0.0.1:7280 --index wikipedia --query "obama" --sort-by-score

将结果集限制为 50 条命中结果

# Start a Quickwit server.
quickwit run --config=./config/quickwit.yaml
# Open a new terminal and run:
quickwit index search --endpoint=http://127.0.0.1:7280 --index wikipedia --query "Barack Obama" --max-hits 50
# If you have jq installed.
quickwit index search --endpoint=http://127.0.0.1:7280 --index wikipedia --query "Barack Obama" --max-hits 50 | jq '.num_hits'

仅在标题中查找匹配项

# Start a Quickwit server.
quickwit run --config=./config/quickwit.yaml
# Open a new terminal and run:
quickwit index search --endpoint=http://127.0.0.1:7280 --index wikipedia --query "obama" --search-fields body
# If you have jq installed.
quickwit index search --endpoint=http://127.0.0.1:7280 --index wikipedia --query "obama" --search-fields body | jq '.hits[].title'

source

管理源：创建、更新、删除源等。

source create

向索引添加一个新的源。 quickwit source create [args]

概要

quickwit source create
    --index <index>
    --source-config <source-config>

选项

选项	描述
`--index`	目标索引的 ID
`--source-config`	源配置文件的路径。请参阅文档以获取更多详细信息。

source enable

为索引启用一个源。 quickwit source enable [args]

概要

quickwit source enable
    --index <index>
    --source <source>

选项

选项	描述
`--index`	目标索引的 ID
`--source`	源的 ID

source disable

为索引禁用一个源。 quickwit source disable [args]

概要

quickwit source disable
    --index <index>
    --source <source>

选项

选项	描述
`--index`	目标索引的 ID
`--source`	源的 ID

source ingest-api

启用或禁用索引的 Ingest API。
quickwit source ingest-api [args]

Synopsis

quickwit source ingest-api
    --index <index>
    [--enable]
    [--disable]

Options

Option	Description
`--index`	目标索引的 ID
`--enable`	启用 Ingest API。
`--disable`	禁用 Ingest API。

source delete

从索引中删除一个数据源。
quickwit source delete [args]
quickwit source del [args]

Synopsis

quickwit source delete
    --index <index>
    --source <source>

Options

Option	Description
`--index`	目标索引的 ID
`--source`	数据源的 ID。

Examples

删除名为 wikipedia-source 的数据源

# Start a Quickwit server.
quickwit run --service metastore --config=./config/quickwit.yaml
# Open a new terminal and run:
quickwit source delete --endpoint=http://127.0.0.1:7280 --index wikipedia --source wikipedia-source

source describe

描述一个数据源。
quickwit source describe [args]
quickwit source desc [args]

Synopsis

quickwit source describe
    --index <index>
    --source <source>

Options

Option	Description
`--index`	目标索引的 ID
`--source`	数据源的 ID。

source list

列出一个索引中的所有数据源。
quickwit source list [args]
quickwit source ls [args]

Synopsis

quickwit source list
    --index <index>

Options

Option	Description
`--index`	目标索引的 ID

Examples

列出 wikipedia 索引中的数据源

# Start a Quickwit server.
quickwit run --service metastore --config=./config/quickwit.yaml
# Open a new terminal and run:
quickwit source list --endpoint=http://127.0.0.1:7280 --index wikipedia

source reset-checkpoint

重置数据源的检查点。
quickwit source reset-checkpoint [args]
quickwit source reset [args]

Synopsis

quickwit source reset-checkpoint
    --index <index>
    --source <source>

Options

Option	Description
`--index`	索引 ID
`--source`	数据源 ID

split

管理分片：列出、描述、标记删除等。

split list

列出一个索引中的所有分片。
quickwit split list [args]
quickwit split ls [args]

Synopsis

quickwit split list
    --index <index>
    [--offset <offset>]
    [--limit <limit>]
    [--states <states>]
    [--create-date <create-date>]
    [--start-date <start-date>]
    [--end-date <end-date>]
    [--output-format <output-format>]

Options

Option	Description
`--index`	目标索引 ID
`--offset`	要跳过的分片数量。
`--limit`	最大检索分片数量。
`--states`	选择状态包含在此逗号分隔列表中的分片。可能的值为 `staged`、`published` 和 `marked`。
`--create-date`	选择创建日期在此日期之前的分片。
`--start-date`	选择包含此日期之后文档的分片（仅时间序列索引）。
`--end-date`	选择包含此日期之前文档的分片（仅时间序列索引）。
`--output-format`	输出格式。可能的值为 `table`、`json` 和 `pretty-json`。

split describe

显示分片的元数据。
quickwit split describe [args]
quickwit split desc [args]

Synopsis

quickwit split describe
    --index <index>
    --split <split>
    [--verbose]

Options

Option	Description
`--index`	目标索引的 ID
`--split`	目标分片的 ID
`--verbose`	显示关于 hotcache 的附加元数据。

split mark-for-deletion

标记一个或多个分片以供删除。
quickwit split mark-for-deletion [args]
quickwit split mark [args]

Synopsis

quickwit split mark-for-deletion
    --index <index>
    --splits <splits>
    [--yes]

Options

Option	Description
`--index`	目标索引的 ID
`--splits`	逗号分隔的分片 ID 列表
`--yes`	对所有提示默认回答 "yes" 并以非交互模式运行。

tool

执行实用操作。需要节点配置。

tool local-ingest

本地索引 NDJSON 文档。
quickwit tool local-ingest [args]

Synopsis

quickwit tool local-ingest
    --index <index>
    [--input-path <input-path>]
    [--input-format <input-format>]
    [--overwrite]
    [--transform-script <transform-script>]
    [--keep-cache]

Options

Option	Description	Default
`--index`	目标索引的 ID
`--input-path`	输入文件的位置。
`--input-format`	输入数据的格式。	`json`
`--overwrite`	覆盖已存在的索引。
`--transform-script`	在索引前转换文档的 VRL 脚本。
`--keep-cache`	完成后不清除本地缓存目录。

tool extract-split

下载并提取一个分片到指定目录。
quickwit tool extract-split [args]

Synopsis

quickwit tool extract-split
    --index <index>
    --split <split>
    [--target-dir <target-dir>]

Options

Option	Description
`--index`	目标索引的 ID
`--split`	目标分片的 ID
`--target-dir`	提取分片的目标目录。

tool gc

垃圾回收过期的暂存分片和被标记为删除的分片。

note

在执行 Quickwit 命令时会创建中间文件。这些中间文件总是在每个成功执行的命令结束时被清理。然而，失败或中断的命令可能会留下需要移除的中间文件。此外，需要注意的是，使用非常短的宽限期（如几秒）可能会导致正在操作的中间文件被删除，特别是在同一索引上并发使用 Quickwit 时。实际上，默认值（1 小时）通常是足够的，只有在真正了解情况时才需要指定更低的值。

quickwit tool gc [args]

Synopsis

quickwit tool gc
    --index <index>
    [--grace-period <grace-period>]
    [--dry-run]

Options

Option	Description	Default
`--index`	目标索引的 ID
`--grace-period`	过期暂存分片被垃圾回收的阈值周期。	`1h`
`--dry-run`	以预演模式执行命令，仅显示候选垃圾回收的分片列表。

环境变量

QW_CLUSTER_ENDPOINT

指定要连接的集群地址。管理命令 index、split 和 source 需要 cluster_endpoint，你可以通过环境变量 QW_CLUSTER_ENDPOINT 一次性设置。

QW_CONFIG

指定 quickwit 配置文件的路径。命令 run 和 tools 需要 config，你可以通过环境变量 QW_CONFIG 一次性设置。

Example

export QW_CONFIG=config/quickwit.yaml

QW_DISABLE_TELEMETRY

当设置为任何非空值时，禁用 telemetry。

Example

QW_DISABLE_TELEMETRY=1 quickwit help

RUST_LOG

配置 quickwit 日志级别。

Examples

# run with higher verbosity
RUST_LOG=debug quickwit run
# run with log level info, except for indexing related logs
RUST_LOG=info,quickwit_indexing=debug quickwit run

常见选项​

命令​

帮助​

版本​

语法​

run​

Indexer 服务​

Searcher 服务​

Metastore 服务​

控制面服务​

Janitor 服务​

index​

index create​

index update​

清除索引​

删除索引​

索引描述​

索引列表​

index ingest​

索引搜索​

source​

source create​

source enable​

source disable​

source ingest-api​

source delete​

source describe​

source list​

source reset-checkpoint​

split​

split list​

split describe​

split mark-for-deletion​

tool​

tool local-ingest​

tool extract-split​

tool gc​

环境变量​

QW_CLUSTER_ENDPOINT​

QW_CONFIG​

QW_DISABLE_TELEMETRY​

RUST_LOG​

常见选项

命令

帮助

版本

语法

run

Indexer 服务

Searcher 服务

Metastore 服务

控制面服务

Janitor 服务

index

index create

index update

清除索引

删除索引

索引描述

索引列表

index ingest

索引搜索

source

source create

source enable

source disable

source ingest-api

source delete

source describe

source list

source reset-checkpoint

split

split list

split describe

split mark-for-deletion

tool

tool local-ingest

tool extract-split

tool gc

环境变量

QW_CLUSTER_ENDPOINT

QW_CONFIG

QW_DISABLE_TELEMETRY

RUST_LOG