Tổng quan BQL Server

BQL Server (bql-server) là gRPC server thực thi ngôn ngữ truy vấn BQL (BlackHole Query Language). Nó là thành phần data plane của hệ thống: nhận truy vấn BQL kèm metadata (khoảng thời gian, thông tin OpenSearch, phân quyền index) qua gRPC và trả về kết quả dạng streaming tăng dần — không chờ toàn bộ kết quả xong mới gửi.

Vai trò trong kiến trúc

BQL client (Search UI / Go control plane)
        │  gRPC (bidirectional stream)
        ▼
   bql-server :9090
        │
        ├──► OpenSearch (pushdown filter/projection/time range)
        └──► Rust engine (join, stats, rex, … streaming)

• Nhận truy vấn BQL qua RPC bql.v1.Bql/Execute (server-streaming).
• Push down phần có thể xuống OpenSearch (filter, projection, time range).
• Xử lý phần còn lại trong engine Rust theo từng chunk (256 dòng/batch).
• Luôn kết thúc bằng đúng một Completion (FULL / PARTIAL / FAILED) — không bao giờ EOF im lặng.

Các service gRPC

BQL Server expose hai service trên cùng một cổng 9090:

Service	RPC	Mô tả
bql.v1.Bql	Execute	Thực thi truy vấn BQL, trả kết quả streaming
transform.v1.TransformService	Transform	Chạy thử transform pipeline (filter, remap, route, throttle, reduce, dedupe) trên dữ liệu mẫu

gRPC Reflection (v1) được bật sẵn — các công cụ như grpcurl có thể tự khám phá service mà không cần file proto.

Đặc điểm chính

• Streaming kết quả: client nhận Chunk* rồi Completion — đúng một completion mỗi truy vấn.
• Phân quyền index: danh sách allowed_indexes được kiểm tra trước khi chạy; hỗ trợ glob pattern và tiền tố tenant ({prefix}_{index}).
• PIT cache: cache Point-in-Time ID (TTL 300s, dọn mỗi 60s) phục vụ phân trang cursor (search_after).
• Graceful shutdown: tắt mềm khi nhận Ctrl+C hoặc SIGTERM.
• Không lưu trạng thái người dùng: server không lưu session; mọi thông tin (URL/credential OpenSearch, time range, quyền) được gửi trong từng request.

Cổng mạng

Port	Thành phần
9090	gRPC (Bql + TransformService + reflection)

Yêu cầu

• OpenSearch 3.x — nguồn dữ liệu để truy vấn (server không chứa dữ liệu).
• Truy vấn bắt buộc có mệnh đề from để xác định index nguồn.

Tài liệu liên quan

• Triển khai BQL Server — cài đặt bằng Docker, Docker Compose, systemd, build từ source
• Cấu hình BQL Server — biến môi trường, port, tham chiếu request gRPC
• Vận hành BQL Server — kiểm tra bằng grpcurl, định dạng phản hồi, xử lý lỗi
• Khắc phục sự cố — các lỗi triển khai thường gặp
• Ngôn ngữ truy vấn BQL — cú pháp và lệnh BQL