Tham Chiếu Lệnh

Các lệnh BQL là những khối xây dựng cho truy vấn của bạn. Mỗi lệnh biến đổi một dòng dữ liệu, và bạn ghép nối chúng bằng ký hiệu pipe (|) để tạo nên các truy vấn mạnh mẽ.

Một truy vấn điển hình bắt đầu với nguồn dữ liệu (dùng from) hoặc bộ lọc (dùng search hoặc where), sau đó áp dụng các phép biến đổi như eval, stats, hoặc sort:

bql

from events-* | search status=error | sort ts desc | head 10

Các lệnh đọc từ bên trái pipe và ghi ra bên phải. Mỗi lệnh nhận đầu ra của lệnh trước đó.

Độ Ưu Tiên Toán Tử

Độ ưu tiên	Toán tử	Mô tả
1 (cao nhất)	`=`	So sánh bằng
2	`and`	AND logic
3 (thấp nhất)	`or`	OR logic

Các mệnh đề liền kề mà không có toán tử logic rõ ràng sẽ được tự động ghép với AND: search status=error host=web01 tương đương search status=error and host=web01.

search

Lọc dòng dựa trên giá trị trường dữ liệu.

Cú pháp:

bql

search field=value
search field=value field2=value2       # implicit AND
search field=value and field2=value2   # explicit AND
search field=value or field2=value2    # OR
search field                           # bare field existence check

Toán tử:

Toán tử	Hỗ trợ	Ví dụ
`=`	Có	`search status=200`
`!=`	Có	`search status!=200`
`and` / `or`	Có	`search status=error and env=prod`
AND ngầm	Có	`search status=error host=web01`

Ví dụ:

bql

from events-* | search status=error | head 10
from auth-* | search action=login_failure | head 5
from firewall-* | search action=deny and dst_port=22 | head 5
from events-* | search status=error or status=warning | head 10
from dns-* | search response_code=NXDOMAIN | head 5

Lưu ý:

So sánh chuỗi là chính xác (phân biệt hoa/thường): "hello" != "Hello"
Các trường bị thiếu luôn trả về false trong so sánh
field!=null khớp với các dòng mà trường tồn tại và không rỗng
Không hỗ trợ glob, regex, hoặc mẫu contains
Không hỗ trợ toán tử <, >, <=, >=

where

Lọc dòng dựa trên biểu thức. Về mặt ngữ nghĩa giống hệt search.

Cú pháp:

bql

where field=value
where field=value and field2=value2
where field=value or field2=value2
where status!=200

Ví dụ:

bql

from events-* | where env=prod and team=sec | head 10
from events-* | where env=prod or env=staging | head 10
from events-* | where status!=200 | head 10
from events-* | where host!=null and status=error | head 10
from process-* | where exit_code!=0 | head 5

Lưu ý:

where và search có thể thay thế lẫn nhau
Dùng lệnh nào đọc tự nhiên hơn trong truy vấn của bạn

eval

Tạo hoặc ghi đè một trường dữ liệu bằng kết quả của một biểu thức.

Cú pháp:

bql

eval target=expression

Các loại biểu thức:

Biểu thức	Ví dụ	Kết quả
Chuỗi hằng	`eval label="prefix"`	`label = "prefix"`
Số nguyên hằng	`eval count=42`	`count = 42`
Tham chiếu trường	`eval x=host`	`x = <giá trị host>`
Gọi hàm	`eval sev=lower("ERROR")`	`sev = "error"`
eval nối tiếp	`eval a=lower("x") \| eval b=upper("y")`	cả hai trường được thêm

Ví dụ:

bql

from events-* | eval sev=lower("ERROR") | head 1
from events-* | eval decoded=decode_url("hello%20world") | head 1
from events-* | eval label="prefix" | head 1
from events-* | eval a=lower("x") | eval b=upper("y") | head 10
from events-* | eval hex_val=decode_hex("48656c6c6f") | head 1
from events-* | eval decoded=base64_decode("SGVsbG8=") | head 1

Lưu ý:

Các trường bị thiếu trong eval sẽ được giải thành chuỗi rỗng ""
Bạn có thể nối nhiều lệnh eval trong một pipeline
Nếu trường đích đã tồn tại, eval sẽ ghi đè bằng giá trị mới

stats

Tổng hợp dòng thành các thống kê tóm tắt.

Cú pháp:

bql

stats count
stats count(field)
stats distinct_count(field)
stats min(field)
stats max(field)
stats sum(field)
stats avg(field)
stats count by field
stats sum(field) by group_field
stats count by field1, field2

Nhiều phép tổng hợp (Multi-Agg):

Bạn có thể thực hiện nhiều phép tổng hợp trong cùng một lệnh stats bằng cách sử dụng dấu phẩy để phân tách. Tất cả các phép tổng hợp sẽ chia sẻ chung một mệnh đề by.

bql

stats count, sum(bytes), avg(latency)
stats count, sum(bytes), avg(latency) by host
stats count(user), distinct_count(user) by action

Các hàm tổng hợp:

Hàm	Cách hoạt động	Kiểu trả về
`count`	Đếm tất cả dòng	Int
`count(field)`	Đếm dòng có trường tồn tại	Int
`distinct_count(field)`	Đếm giá trị duy nhất	Int
`min(field)`	Giá trị Int nhỏ nhất	Int
`max(field)`	Giá trị Int lớn nhất	Int
`sum(field)`	Tổng các giá trị Int	Int
`avg(field)`	Trung bình (trả về String)	String

Ví dụ:

bql

from events-* | search status=error | stats count
from auth-* | stats count(action)
from auth-* | stats distinct_count(user)
from firewall-* | stats max(bytes)
from firewall-* | stats sum(bytes)
from events-* | stats avg(latency)
from dns-* | stats count(response_code)
from events-* | stats count by host
from auth-* | stats count by action, user
from firewall-* | stats sum(bytes) by dst_port | sort total desc | head 10

Ví dụ multi-agg:

bql

# Đếm, tổng và trung bình bytes trên mỗi host
from firewall-* | stats count, sum(bytes), avg(bytes) by host | head 10

# Phân tích hiệu suất trên mỗi endpoint
from endpoint-* | stats count, min(latency), max(latency), avg(latency) by host | head 10

# Tổng hợp nhiều thống kê xác thực
from auth-* | stats count, distinct_count(user) by action | head 10

Lưu ý:

stats tạo một dòng đầu ra duy nhất cho mỗi nhóm
Dùng mệnh đề by để nhóm: stats count by field
Hỗ trợ nhiều trường by: stats count by field1, field2
Multi-agg: Tất cả phép tổng hợp trong một lệnh stats chia sẻ chung một mệnh đề by
min/max/sum chỉ hoạt động với giá trị Int; các giá trị khác bị bỏ qua im lặng
avg trả về kiểu String (ví dụ: "368")
sum trả về Int(0) khi không có giá trị nào khớp
count(field) bỏ qua các dòng mà trường bị thiếu
min/max/avg trả về chuỗi rỗng khi không có giá trị nào khớp

sort

Sắp xếp dòng theo giá trị trường.

Cú pháp:

bql

sort field_name
sort field_name asc
sort field_name desc

Ví dụ:

bql

from events-* | sort host
from auth-* | sort ts desc | head 5
from firewall-* | sort bytes desc | head 1

Lưu ý:

Thứ tự sắp xếp mặc định là tăng dần
asc là tùy chọn (tăng dần là mặc định); desc sắp xếp giảm dần
Sắp xếp ổn định (các khóa bằng nhau giữ nguyên thứ tự đầu vào)
Giá trị kiểu String sắp xếp theo thứ tự từ điển; giá trị Int sắp xếp theo số
Các trường bị thiếu được coi là bằng nhau
Các kiểu hỗn hợp (String vs Int) được coi là bằng nhau

dedup

Xóa các dòng trùng lặp dựa trên tổ hợp trường.

Cú pháp:

bql

dedup
dedup field
dedup field1, field2
dedup field1 field2          # space-delimited also works

Ví dụ:

bql

from events-* | dedup host | head 10
from auth-* | dedup user, action | head 10
from firewall-* | dedup src_ip, dst_ip, dst_port | head 10

Lưu ý:

Giữ lại lần xuất hiện đầu tiên của mỗi tổ hợp duy nhất
Các trường bị thiếu được coi là khóa giá trị riêng biệt
dedup không có trường sẽ dùng tất cả các trường sắp xếp theo thứ tự bảng chữ cái

limit / head

Trả về N dòng đầu tiên từ đầu vào. limit và head là bí danh của nhau.

Cú pháp:

bql

limit N
head N

Ví dụ:

bql

from events-* | head 10
from auth-* | search action=login_failure | limit 5
from firewall-* | sort bytes desc | head 1

Lưu ý:

Cả limit và head đều thực hiện cùng một chức năng
Dùng head để dễ đọc hơn: ... | head 10
Trả về trạng thái hoàn thành "Partial" khi xảy ra cắt bớt

tail

Trả về N dòng cuối cùng từ đầu vào.

Cú pháp:

bql

tail N

Ví dụ:

bql

from events-* | tail 3
from events-* | sort ts | tail 5

Lưu ý:

Trả về N dòng CUỐI CÙNG dựa trên thứ tự đầu vào
Không giống "sort desc | head N" - tail giữ nguyên thứ tự đầu vào
Dùng sau sort để lấy N dòng đã sắp xếp cuối cùng

rename

Đổi tên một trường. Trường cũ sẽ bị xóa.

Cú pháp:

bql

rename old_name as new_name

Ví dụ:

bql

from events-* | search method=GET | rename method as http_method
from auth-* | rename user as username | head 5
from firewall-* | rename action as firewall_action | head 5

Lưu ý:

Từ khóa as là bắt buộc
Trường cũ bị xóa sau khi đổi tên
Hữu ích để làm cho tên trường dễ đọc hơn trong đầu ra

top

Trả về các giá trị xuất hiện nhiều nhất cho một trường.

Cú pháp:

bql

top N field_name
top field_name              # default count

Định dạng đầu ra: Trả về các dòng với tên trường và cột count, sắp xếp theo count giảm dần.

Ví dụ:

bql

from auth-* | top 5 action
from firewall-* | top dst_port
from events-* | top 3 host

Lưu ý:

Mặc định trả về top 5 giá trị
Đầu ra bao gồm tên trường và cột count
Các giá trị bằng nhau được sắp xếp theo thứ tự bảng chữ cái

rare

Trả về các giá trị xuất hiện ít nhất cho một trường.

Cú pháp:

bql

rare N field_name
rare field_name              # default count

Định dạng đầu ra: Giống top nhưng sắp xếp theo count tăng dần.

Ví dụ:

bql

from auth-* | rare 5 action
from firewall-* | rare dst_port

Lưu ý:

Mặc định trả về 5 giá trị hiếm nhất
Hữu ích để tìm các sự kiện bất thường hoặc dị thường

addtotal

Thêm trường total chứa tổng của một trường số trên tất cả các dòng.

Cú pháp:

bql

addtotal field_name

Ví dụ:

bql

from firewall-* | search action=allow | addtotal bytes | head 10

Lưu ý:

Trường đầu ra luôn có tên total (không phải tên trường đầu vào)
Hữu ích để tính phần trăm sau khi tổng hợp

lookup

làm giàu dữ liệu dòng bằng cách tra cứu giá trị trong bảng tra cứu.

Cú pháp:

bql

lookup table_name match_field OUTPUT field1, field2

Ví dụ:

bql

from events-* | search method=GET | lookup threat_intel src_ip OUTPUT threat_type, confidence | head 10

Lưu ý:

Bảng tra cứu được cấu hình phía server (không phải người dùng tự tạo)
Chỉ hỗ trợ tra cứu bằng so sánh bằng chính xác
Bên phải (bảng tra cứu) ghi đè bên trái khi có xung đột tên trường

inputlookup

Tải tất cả các dòng từ một bảng tra cứu vào pipeline.

Cú pháp:

bql

inputlookup table_name

Ví dụ:

bql

inputlookup threat_intel | head 10

Lưu ý:

Tải toàn bộ bảng tra cứu như một tập dữ liệu
Hữu ích để so sánh dữ liệu của bạn với dữ liệu tham chiếu
Bảng tra cứu được cấu hình phía server

join

Kết hợp hai tập dữ liệu dựa trên trường khóa.

Cú pháp:

bql

inner join key=field right_table
left join key=field right_table
right join key=field right_table

Các loại join:

Loại	Cách hoạt động
`inner`	Chỉ lấy dòng mà cả hai bên đều khớp
`left`	Lấy tất cả dòng bên trái; các trường bên phải không khớp sẽ rỗng
`right`	Lấy tất cả dòng khớp + các dòng bên phải không khớp

Ví dụ:

bql

from events-* | search method=GET | join type=inner key=src_ip threat_logs | head 10
from auth-* | search action=login | join type=left key=user_id users | head 10

Lưu ý:

Bên trái wins khi có xung đột tên trường
Các trường bên phải chỉ được thêm nếu chưa tồn tại bên trái
Hiện tại bị giới hạn với bảng tra cứu hoặc subsearch cho bên phải

from

Chỉ định nguồn dữ liệu cho truy vấn.

Cú pháp:

bql

from index_name
from index1, index2
from pattern*
from alias:my_alias

Các loại nguồn:

Loại nguồn	Cú pháp	Ví dụ
Index cụ thể	`index_name`	`from auth-logs`
Mẫu wildcard	`pattern*`	`from events-*`
Nhiều nguồn	`source1, source2`	`from auth-, dns-`
Alias	`alias:name`	`from alias:events-live`

Ví dụ:

bql

from auth-* | head 10
from firewall-*, dns-* | head 10
from events-* | search status=error | head 10

Lưu ý:

Mệnh đề from là tùy chọn - bạn có thể bắt đầu bằng bất kỳ lệnh nào
Wildcard (*) khớp với bất kỳ ký tự nào
Dùng dấu phẩy để truy vấn nhiều mẫu index

timerange

Đặt khoảng thời gian cho truy vấn.

Cú pháp:

bql

timerange earliest=<timestamp> latest=<timestamp>

Định dạng timestamp: ISO-8601 (ví dụ: 2026-05-01T00:00:00Z)

Ví dụ:

bql

timerange earliest=2026-05-01T00:00:00Z latest=2026-05-07T00:00:00Z | search status=error | head 10
from auth-* | timerange earliest=2026-01-01T00:00:00Z latest=2026-01-31T23:59:59Z | head 10

Lưu ý:

Cả earliest và latest đều bắt buộc
Dùng định dạng ISO-8601 với múi giờ (Z = UTC)
Lọc sự kiện theo trường ts (timestamp)

timechart

Nhóm các sự kiện theo khoảng thời gian và áp dụng tổng hợp.

Cú pháp:

bql

timechart span=<interval> [agg_func[(<field>)]] [by <fields>]

Các đơn vị khoảng:

Đơn vị	Ý nghĩa	Ví dụ
`s`	Giây	`span=30s`
`m`	Phút	`span=5m`
`h`	Giờ	`span=1h`
`d`	Ngày	`span=1d`
`w`	Tuần	`span=1w`

Các hàm tổng hợp: count (mặc định), sum, avg, min, max, distinct_count

Các cột đầu ra:

_span: Epoch giây tại thời điểm bắt đầu bucket
Bất kỳ trường nhóm by nào
Cột kết quả tổng hợp

Ví dụ:

bql

from events-* | timechart span=1h count
from firewall-* | timechart span=5m sum(bytes)
from auth-* | timechart span=1d count by action

Lưu ý:

Tổng hợp mặc định là count
Đầu ra được sắp xếp theo _span tăng dần
Dùng by để nhóm theo trường (ví dụ: by host, by action)

Chủ Đề Liên Quan

Bắt Đầu — Mới dùng BQL? Bắt đầu ở đây
Tham Chiếu Lệnh — Cú pháp đầy đủ của các lệnh
Sổ Tay — Các truy vấn sẵn sàng sử dụng
Hạn Chế Đã Biết — Những gì BQL chưa thể làm

Tham Chiếu Lệnh ​

Độ Ưu Tiên Toán Tử ​

search ​

where ​

eval ​

stats ​

sort ​

dedup ​

limit / head ​

tail ​

rename ​

top ​

rare ​

addtotal ​

lookup ​

inputlookup ​

join ​

from ​

timerange ​

timechart ​

Chủ Đề Liên Quan ​

Tham Chiếu Lệnh

Độ Ưu Tiên Toán Tử

search

where

eval

stats

sort

dedup

limit / head

tail

rename

top

rare

addtotal

lookup

inputlookup

join

from

timerange

timechart

Chủ Đề Liên Quan