查询配置

引入或更新：v1.2.901

本页介绍 databend-query.toml 配置文件中可用的 Query 节点配置。

• 下表中列出的某些参数可能未出现在 databend-query.toml 中。如需使用这些参数，可手动将其添加到文件。

• 您可在 GitHub 上找到示例配置文件，这些文件为不同部署环境配置了 Databend。它们仅用于内部测试，请勿直接修改。若您的部署场景类似，可参考这些文件编辑自己的配置。

[query] 部分

[query] 部分可用参数如下：

参数	描述
max_active_sessions	最大活跃会话数。
shutdown_wait_timeout_ms	等待超时时间（毫秒）。
flight_api_address	监听 Databend-Query 集群 shuffle 数据的 IP 地址与端口。
admin_api_address	Admin REST API 地址。
metric_api_address	Metrics REST API 地址。
mysql_handler_host	MySQL 查询处理器主机名。
mysql_handler_port	MySQL 查询处理器端口。
clickhouse_http_handler_host	ClickHouse HTTP 查询处理器主机名。
clickhouse_http_handler_port	ClickHouse HTTP 查询处理器端口。
http_handler_host	HTTP API 查询处理器主机名。
http_handler_port	HTTP API 查询处理器端口。
flight_sql_handler_host	实验性 Arrow Flight SQL API 查询处理器主机名。
flight_sql_handler_port	实验性 Arrow Flight SQL API 查询处理器端口。
tenant_id	默认租户 ID。
cluster_id	默认集群 ID。
table_engine_memory_enabled	是否启用 Memory 表引擎（Memory Table Engine）。
max_running_queries	可同时执行的最大查询数，默认为 8，0 表示无限制。
data_retention_time_in_days_max	设置 data_retention_time_in_days 的上限，默认为 90 天。

[query.users] 部分

[[query.users]] 部分可用参数如下。有关管理员用户配置的更多信息，请参见配置管理员用户。

参数	描述
name	用户名。
auth_type	认证类型（如 no_password、double_sha1_password、sha256_password）。
auth_string	认证字符串（如密码的 SHA-1 或 SHA-256 哈希）。

[query.settings] 部分

[query.settings] 部分可用参数如下：

参数	描述
aggregate_spilling_memory_ratio	聚合操作触发磁盘溢出的内存阈值百分比。当内存使用超过总可用内存的该百分比时，数据将溢出到对象存储以避免内存耗尽。例如设为 60，则内存使用超过 60% 时触发溢出。
join_spilling_memory_ratio	Join 操作触发磁盘溢出的内存阈值百分比。当内存使用超过总可用内存的该百分比时，数据将溢出到对象存储以避免内存耗尽。例如设为 60，则内存使用超过 60% 时触发溢出。

[log] 部分

该部分可包含以下子部分：[log.file]、[log.stderr]、[log.query] 和 [log.tracing]。

[log.file] 部分

[log.file] 部分可用参数如下：

参数	描述
on	是否启用文件日志，默认为 true。
dir	日志文件存储路径。
level	日志级别，遵循 env_logger 语法：error、warn、info、debug、trace、off。默认为 warn,databend_=info,openraft=info。
format	日志格式：json 或 text，默认为 json。
limit	保留的最大日志文件数，默认为 48。

[log.stderr] 部分

[log.stderr] 部分可用参数如下：

参数	描述
on	是否启用 stderr 日志，默认为 false。
level	日志级别，遵循 env_logger 语法：error、warn、info、debug、trace、off。默认为 warn,databend_=info,openraft=info。
format	日志格式：json 或 text，默认为 json。

[log.query] 部分

[log.query] 部分可用参数如下：

参数	描述
on	是否将查询执行详情记录到日志目录的 query-details 文件夹，默认为启用。存储空间有限时可考虑关闭。

[log.tracing] 部分

[log.tracing] 部分可用参数如下：

参数	描述
capture_log_level	执行期间捕获追踪的日志级别（DEBUG、TRACE、INFO、WARN 或 ERROR）。
on	是否启用追踪，默认为 false，设为 true 启用。
otlp_endpoint	用于追踪的 OpenTelemetry Protocol（OTLP）端点，默认为 http://127.0.0.1:4317，可替换为所需端点。

[log.history] 部分

[log.history] 部分可用参数如下：

参数	描述
on	是否启用历史日志功能，默认为 false，设为 true 启用历史表。
log_only	启用后，节点将转换任务委托给其他节点，减轻自身负载。
interval	历史日志刷新的间隔（秒），默认为 2。
stage_name	临时保存日志数据的暂存区名称，默认为唯一值以避免冲突。
level	历史日志的日志级别（DEBUG、TRACE、INFO、WARN 或 ERROR），默认为 WARN。
retention_interval	触发保留流程检查并清理旧数据的间隔（小时），默认为 24。
tables	指定要启用的历史表及其保留策略。该数组中的每个对象包含 table_name（历史表名）和 retention（该表的保留时长，单位小时）。
storage	指定历史表的存储位置。默认与 [storage] 部分配置相同，也可单独指定，格式与 [storage] 部分完全一致。

tables 为对象数组，每个对象包含两个参数：

参数	描述
table_name	历史表名（当前支持：log_history、profile_history、query_history、login_history）
retention	该表的保留时长（小时）。
注意：log_history 表默认启用。

若指定了 storage，原有默认历史表将被删除并以新存储配置重建。同一租户下所有节点必须使用相同的 storage 配置以保证一致性。

[meta] 部分

[meta] 部分可用参数如下：

参数	描述
username	连接 Meta 服务的用户名，默认为 "root"。
password	连接 Meta 服务的密码。建议使用环境变量 META_PASSWORD 提供，默认为 "root"。
endpoints	查询服务器可连接的 meta 服务器端点列表。为提升连接可靠性，建议列出集群内多个 meta 服务器作为备份。示例：["192.168.0.1:9191", "192.168.0.2:9191"]，默认为 ["0.0.0.0:9191"]。
client_timeout_in_second	连接 meta 服务器的超时时间（秒），默认为 60。
auto_sync_interval	查询服务器自动从集群 meta 服务器同步端点列表的间隔（秒）。启用后，Databend-query 会定期联系 Databend-meta 获取 grpc_api_advertise_host:grpc-api-port 列表。设为 0 禁用同步，默认为 60。
unhealth_endpoint_evict_time	内部不再向不健康 meta 节点端点查询的时间（秒），默认为 120。

[storage] 部分

[storage] 部分可用参数如下：

参数	描述
type	存储类型，可选值：fs、s3、azblob、gcs、oss、cos。
allow_insecure	默认为 false。在 MinIO 部署或通过 http:// 前缀 URL 加载数据时需设为 true，否则报错：“copy from insecure storage is not allowed. Please set allow_insecure=true”。
storage_retry_timeout	（秒） OpenDAL 读写操作超时后的重试阈值，默认为 10。
storage_retry_io_timeout	（秒） OpenDAL HTTP 请求超时后的重试阈值，默认为 60。
storage_pool_max_idle_per_host	每主机最大连接池大小，默认为无限制。
storage_connect_timeout	（秒） TCP 连接超时，默认为 30。
storage_tcp_keepalive	（秒） TCP keepalive 持续时间，默认为无。
storage_max_concurrent_io_requests	最大并发 I/O 请求数，默认为无限制。

[storage.fs] 部分

[storage.fs] 部分可用参数如下：

参数	描述
data_path	数据存储路径。

[storage.s3] 部分

[storage.s3] 部分可用参数如下：

参数	描述
bucket	类 Amazon S3 存储桶名称。
endpoint_url	类 S3 存储服务的 URL 端点，默认为 "https://s3.amazonaws.com"。
access_key_id	存储服务认证所需的 Access Key ID。
secret_access_key	存储服务认证所需的 Secret Access Key。
enable_virtual_host_style	是否启用虚拟主机风格寻址的布尔标志。
external_id	认证用的 External ID。
master_key	认证用的主密钥。
region	类 S3 存储服务的区域。
role_arn	认证用的 ARN（Amazon Resource Name）。
root	指定桶内 Databend 操作的目录。示例：若桶根目录有 myroot 文件夹，则 root = "myroot/"。
security_token	认证用的安全令牌。

[storage.azblob] 部分

[storage.azblob] 部分可用参数如下：

参数	描述
endpoint_url	Azure Blob Storage 的 URL 端点，如 https://<your-storage-account-name>.blob.core.windows.net。
container	Azure 存储容器名称。
account_name	Azure 存储账户名称。
account_key	Azure Blob Storage 认证用的账户密钥。
root	指定容器内 Databend 操作的目录。示例：若容器根目录有 myroot 文件夹，则 root = "myroot/"。

[storage.gcs] 部分

[storage.gcs] 部分可用参数如下：

参数	描述
bucket	Google Cloud Storage 桶名称。
credential	用于 GCS 认证的 base64 编码服务账户密钥文件。
root	指定桶内 Databend 操作的目录。示例：若桶根目录有 myroot 文件夹，则 root = "myroot/"。

获取 credential 的方法：按 Google 文档创建服务账户密钥生成并下载密钥文件，然后执行：

base64 -i -o ~/Desktop/base64-encoded-key.txt

将其转为 base64 字符串。

[storage.oss] 部分

[storage.oss] 部分可用参数如下：

参数	描述
bucket	阿里云 OSS 桶名称。
endpoint_url	阿里云 OSS 的 URL 端点。
access_key_id	阿里云 OSS 认证用的 Access Key ID。
access_key_secret	阿里云 OSS 认证用的 Access Key Secret。
presign_endpoint_url	阿里云 OSS 预签名操作的 URL 端点。
root	指定桶内 Databend 操作的目录。示例：若桶根目录有 myroot 文件夹，则 root = "myroot/"。

[storage.obs] 部分

以下是 [storage.obs] 部分中可用的参数列表：

参数	描述
bucket	您的华为云 OBS 桶名称。
endpoint_url	华为云 OBS 的 URL 端点。
access_key_id	用于华为云 OBS 认证的 Access Key ID。
secret_access_key	用于华为云 OBS 认证的 Secret Access Key。

[storage.cos] 部分

[storage.cos] 部分可用参数如下：

参数	描述
bucket	腾讯云 COS 桶名称。
endpoint_url	腾讯云 COS 的 URL 端点（可选）。
secret_id	腾讯云 COS 认证用的 Secret ID。
secret_key	腾讯云 COS 认证用的 Secret Key。
root	指定桶内 Databend 操作的目录。示例：若桶根目录有 myroot 文件夹，则 root = "myroot/"。

[cache] 部分

[cache] 部分可用参数如下：

参数	描述
data_cache_storage	表数据缓存的存储类型。可选："none"（禁用表数据缓存）、"disk"（启用磁盘缓存），默认为 "none"。
iceberg_table_meta_count	缓存的 Iceberg 表元数据条目数量，设为 0 禁用元数据缓存。

[cache.disk] 部分

[cache.disk] 部分可用参数如下：

参数	描述
path	磁盘缓存的存储路径。
max_bytes	磁盘缓存的最大数据量（字节），默认为 21474836480 字节（20 GB）。

[spill] 部分

Databend 支持溢出存储（Spill Storage）以处理超出可用内存的大型查询。统一配置格式为所有存储类型提供一致模式并支持自动检测。

[spill.storage] 部分

参数	描述
type	存储类型，可选：fs（文件系统）、s3、azblob、gcs、oss、cos 等。

[spill.storage.fs] 部分（文件系统存储）

参数	描述
data_path	溢出数据在本地文件系统的存储目录路径。
reserved_space_percentage	为系统保留、不用于溢出的磁盘空间百分比，防止磁盘被写满，确保系统稳定。默认值：30。
max_bytes	允许溢出到本地文件系统的最大字节数。达到限制后，新溢出操作自动回退到主数据存储（远程存储），保证查询不中断。默认值：无限制。

示例（文件系统存储）：

[spill.storage]
type = "fs"

[spill.storage.fs]
data_path = "/fast-ssd/spill"
reserved_space_percentage = 25.0
max_bytes = 107374182400  # 100GB

[spill.storage.s3] 部分（S3 远程存储）

S3 溢出存储使用与 storage.s3 部分 相同的参数。

示例（S3 存储）：

[spill.storage]
type = "s3"

[spill.storage.s3]
bucket = "my-spill-bucket"
region = "us-west-2"
access_key_id = "your-access-key"
secret_access_key = "your-secret-key"

旧格式（向后兼容）

备注

旧格式仅用于向后兼容。若 Databend 版本早于 v1.2.901，请使用此格式；新部署请使用上述统一格式。

参数	描述
spill_local_disk_path	溢出数据在本地磁盘的存储目录路径。
spill_local_disk_reserved_space_percentage	为系统保留、不用于溢出的磁盘空间百分比，防止磁盘被写满，确保系统稳定。默认值：30。
spill_local_disk_max_bytes	允许溢出到本地磁盘的最大字节数。达到限制后，新溢出操作自动回退到主数据存储（远程存储），保证查询不中断。默认值：无限制。

示例（旧格式）：

[spill]
spill_local_disk_path = "/data/spill"
spill_local_disk_reserved_space_percentage = 30.0
spill_local_disk_max_bytes = 53687091200