Hướng dẫn gỡ lỗi truy vấn
Khi truy vấn BQL không hoạt động như mong đợi, hướng dẫn này sẽ giúp bạn tìm và sửa lỗi.
Truy vấn không hoạt động — Phải làm gì?
Làm theo các bước sau theo thứ tự:
Bước 1: Đọc thông báo lỗi
Nếu bạn thấy lỗi, hãy đọc kỹ. Thông thường lỗi sẽ nói chính xác vấn đề nằm ở đâu.
Mẫu lỗi thường gặp:
- "syntax error" → Kiểm tra dấu
|và cách viết lệnh - "unknown field" → Kiểm tra tên trường trong mô hình dữ liệu
- "type mismatch" → Kiểm tra xem bạn có đang so sánh String với Int không
Tham khảo đầy đủ: Xem Tham chiếu thông báo lỗi
Bước 2: Đơn giản hóa truy vấn
Bớt phức tạp cho đến khi chạy được, rồi từng bước thêm lại.
Ví dụ:
-- Bắt đầu đơn giản:
from events-* | head 10
-- Thêm một bộ lọc:
from events-* | search status=error | head 10
-- Thêm một bộ lọc nữa:
from events-* | search status=error and env=prod | head 10
-- Thêm tổng hợp:
from events-* | search status=error and env=prod | stats countBước 3: Kiểm tra tên trường
Tên trường phân biệt hoa/thường và phải khớp chính xác.
Cách kiểm tra:
- Chạy truy vấn đơn giản để xem các trường có sẵn:bql
from events-* | head 1 - Xem Tham chiếu mô hình dữ liệu cho mẫu index của bạn
- Kiểm tra cách viết và thứ tự chữ hoa/thường
Bước 4: Kiểm tra kiểu dữ liệu
BQL có hai kiểu: String và Int. Khi so sánh phải cùng kiểu.
Cách kiểm tra:
- String:
"error","42","true" - Int:
42,0,100 "42"(String) khác42(Int)
Sai lầm thường gặp: search port=443 trong khi port là String → dùng search port="443"
Bước 5: Kiểm tra hạn chế
Một số tính năng bạn mong đợi có thể chưa tồn tại trong BQL.
Hạn chế đã biết:
- Không có toán tử
NOT→ dùng!= - Không có toán tử
<><=>= - Không dùng regex trong
search→ dùngmatch()trongeval - Không có kiểu Float → dùng Int hoặc String
Danh sách đầy đủ: Xem Hạn chế đã biết
Bước 6: Kiểm tra thứ tự pipeline
BQL thực thi lệnh từ trái sang phải. Thứ tự rất quan trọng.
Sai lầm thường gặp:
- Sắp xếp trước khi lọc (lãng phí tài nguyên)
- Tổng hợp trước khi lọc (đếm sai hàng)
Thứ tự đúng:
from index-* | search ... | where ... | eval ... | stats ... | sort ... | headBước 7: Kiểm tra dữ liệu thiếu
Nếu truy vấn trả về kết quả rỗng:
- Xác nhận mẫu index tồn tại (
from events-*) - Kiểm tra khoảng thời gian (
timerange earliest=... latest=...) - Xác nhận trường có dữ liệu (kiểm tra mẫu với
head 10)
Sơ đồ quyết định
Có thông báo lỗi?
├── "syntax error" → Kiểm tra dấu | và cách viết lệnh
├── "unknown field" → Kiểm tra tham chiếu mô hình dữ liệu
├── "type mismatch" → Kiểm tra String vs Int
├── "function not found" → Kiểm tra tham chiếu hàm
├── "timeout" → Thêm head/limit, thu hẹp bộ lọc
└── Không lỗi, nhưng kết quả rỗng?
├── Kiểm tra mẫu index
├── Kiểm tra khoảng thời gian
├── Kiểm tra trường có tồn tại
└── Kiểm tra kiểu dữ liệuDanh sách kiểm tra khi gỡ lỗi
Sử dụng danh sách này khi gặp sự cố:
- [ ] Cú pháp đã đúng chưa? (dấu
|giữa các lệnh) - [ ] Tên lệnh viết đúng chưa?
- [ ] Tên trường khớp chính xác chưa? (phân biệt hoa/thường)
- [ ] Đang so sánh đúng kiểu chưa? (String vs Int)
- [ ] Thứ tự pipeline đúng chưa? (lọc → tổng hợp → sắp xếp)
- [ ] Chỉ dùng các tính năng được hỗ trợ chưa? (kiểm tra hạn chế)
- [ ] Mẫu index có tồn tại không?
- [ ] Khoảng thời gian đã đặt đúng chưa?
- [ ] Có dữ liệu cho các trường bạn đang truy vấn không?
Ví dụ thực tế khi gỡ lỗi
Tình huống 1: Lỗi cú pháp
Truy vấn:
search status=error | | head 5Lỗi: parse error: empty command in pipeline
Sửa: Xóa dấu | thừa:
search status=error | head 5Tình huống 2: Kết quả rỗng
Truy vấn:
from logs-* | search status=Error | head 10Không lỗi, nhưng không có kết quả.
Gỡ lỗi:
- Kiểm tra giá trị trường:
from logs-* | head 1→ thấystatus=error(chữ thường) - Sửa lỗi hoa/thường:
search status=error
Kết quả: Chạy được sau khi sửa chữ hoa/thường.
Tình huống 3: Sai kiểu dữ liệu
Truy vấn:
from logs-* | search port=443 | head 10Không lỗi, nhưng không có kết quả.
Gỡ lỗi:
- Kiểm tra kiểu trường:
portđược lưu dưới dạng String - Sửa kiểu:
search port="443"
Kết quả: Chạy được sau khi thêm dấu ngoặc kép.
Tình huống 4: Thiếu khoảng thời gian
Truy vấn:
from logs-* | search status=error | head 10Lỗi: scan without time range
Sửa: Thêm khoảng thời gian:
timerange earliest=2026-01-01T00:00:00Z latest=2026-01-02T00:00:00Z | from logs-* | search status=error | head 10Tình huống 5: Hàm không tồn tại
Truy vấn:
from logs-* | eval label=toLower("hello") | head 5Lỗi: semantic error: unknown function 'toLower'
Sửa: Dùng đúng tên hàm:
from logs-* | eval label=lower("hello") | head 5Cần giúp thêm
Nếu vẫn chưa giải quyết được:
- Xem Tham chiếu thông báo lỗi để biết chi tiết lỗi cụ thể
- Xem Sai lầm thường gặp để tìm vấn đề tương tự
- Xem Hạn chế đã biết để biết tính năng chưa có
- Xem Cookbook để tham khảo truy vấn mẫu
Chủ đề liên quan
- Bắt đầu — Mới sử dụng BQL? Bắt đầu từ đây
- Tham chiếu lệnh — Cú pháp đầy đủ của các lệnh
- Cookbook — Các truy vấn sẵn sàng sử dụng
- Hạn chế đã biết — Những gì BQL chưa làm được