Cấu hình BQL Server

BQL Server không dùng file cấu hình (không giống BlackHole Core/Search với blackhole.yml). Toàn bộ cấu hình server gồm:

1. Biến môi trường — log level, port (qua port mapping Docker/systemd).
2. Request gRPC — mọi thông tin truy vấn (OpenSearch, time range, quyền index) được client gửi trong từng request Execute.

Biến môi trường

Biến	Mô tả	Mặc định
RUST_LOG	Log level của tracing (error, warn, info, debug, trace)	info
APP_IMAGE	Chỉ dùng trong docker-compose.deploy.yml để chọn image GHCR	—

📝

Port gRPC mặc định là **9090** (hardcode trong binary: `0.0.0.0:9090`). Để đổi port, dùng port mapping của Docker (`-p 19090:9090`) hoặc `systemd` socket proxy — binary hiện không đọc biến môi trường cho port.

Cấu hình log

# Chạy trực tiếp
RUST_LOG=debug cargo run -p bql-server

# Docker
docker run -d -p 9090:9090 -e RUST_LOG=debug ghcr.io/gcsclabs/bql-server:latest

Log output ở mức info bao gồm request đến, metadata injected, và shutdown. Ở mức debug, chi tiết hơn (index overrides, PIT cache, chunk).

Tham chiếu request gRPC

Service chính: bql.v1.Bql/Execute (server-streaming). Message ExecuteRequest:

Trường	Kiểu	Mô tả
bql	string	Nội dung truy vấn BQL (bắt buộc có from <index>)
earliest_unix	int64	Bắt đầu khoảng thời gian (Unix giây). 0 = không áp dụng
latest_unix	int64	Kết thúc khoảng thời gian (Unix giây). 0 = không áp dụng
time_field	string	Tên trường thời gian (mặc định ts nếu để trống)
opensearch_url	string	Base URL OpenSearch, vd http://opensearch:9200
opensearch_user	string	Username OpenSearch (bỏ trống nếu không có auth)
opensearch_pass	string	Password OpenSearch
row_limit	uint32	Giới hạn số dòng trả về (0 = mặc định engine)
byte_limit	uint32	Giới hạn dung lượng phản hồi
timeout_ms	uint32	Timeout truy vấn (milli giây)
lookup_tables	map<string,string>	Dữ liệu lookup CSV theo tên bảng
pushdown_enabled	bool	Bật pushdown filter/projection xuống OpenSearch
filter	repeated FilterClause	Bộ lọc proto (range/term/bool/match) ép trực tiếp xuống OpenSearch
aggs	map<string, AggregationSpec>	Aggregation proto (date_histogram, terms, histogram, min/max/sum/avg/count)
size	int32	Số dòng mỗi page (giống head)
from	int32	Offset phân trang (0 = từ đầu)
allowed_indexes	repeated IndexInfo	Danh sách index được phép truy vấn (phân quyền)
sort	repeated SortClause	Sắp xếp theo trường (ASC/DESC)
source_includes	repeated string	Chỉ trả về các trường này
source_excludes	repeated string	Loại trừ các trường này
track_total_hits	int32	Bật đếm tổng số hit chính xác
search_after	string	Cursor phân trang (JSON từ Completion.search_after của page trước)

IndexInfo — phân quyền index

message IndexInfo {
  string name   = 1;  // Tên index hoặc glob pattern, vd "logs-*"
  string prefix = 2;  // Tiền tố tenant, vd "tenant_a" → truy vấn "tenant_a_logs-*"
}

Quy tắc:

• Index trong from phải khớp (exact hoặc glob) với một IndexInfo.name trong allowed_indexes, nếu không request bị từ chối.
• Nếu prefix khác rỗng, index thực tế truy vấn là {prefix}_{name}.
• allowed_indexes rỗng → từ chối toàn bộ truy vấn.

Phản hồi gRPC

ExecuteResponse là một oneof:

Trường	Mô tả
chunk	Chunk dữ liệu: columns + rows (mỗi row là map<string,string>)
completion	Kết thúc truy vấn: FULL / PARTIAL / FAILED
aggregation_response	Kết quả aggregation (buckets)

Completion chứa ExecutionReport (query_id, rows_emitted, source_rows_read, operator_steps, telemetry_json) và search_after (cursor cho page kế tiếp, rỗng khi hết).

ℹ️

Mỗi truy vấn luôn kết thúc bằng **đúng một** `Completion`. Nếu stream dừng mà không có `Completion` là lỗi giao thức — hãy báo lỗi phía client.

Đặc điểm hành vi cần biết

• Bắt buộc from: request không có mệnh đề from bị từ chối (INVALID_ARGUMENT).
• Time range tự inject: nếu earliest_unix/latest_unix khác 0 và truy vấn chưa có timerange, server tự chèn timerange field=<time_field> earliest=... latest=... vào pipeline.
• Không time range → từ chối: nếu query thiếu cả timerange lẫn earliest/latest, engine từ chối (tránh full scan) với FAILED_PRECONDITION.
• PIT cache: server cache Point-in-Time ID (TTL 300s) theo fingerprint của query để phân trang search_after hiệu quả; cache nằm trong bộ nhớ server, mất khi restart.

Liên kết liên quan

• Triển khai BQL Server
• Vận hành BQL Server
• Khắc phục sự cố