lq query¶

Query log files or stored events using SQL.

Alias: blq q

Synopsis¶

blq query [OPTIONS] [FILE...]
blq q [OPTIONS] [FILE...]

Description¶

The query command provides SQL-like querying of log files or stored events. When a file is specified, it queries the file directly using duck_hunt. Without a file, it queries previously captured events from the BIRD database.

Options¶

Option	Description
`-s, --select COLS`	Columns to select (comma-separated)
`-f, --filter WHERE`	SQL WHERE clause
`-o, --order ORDER`	SQL ORDER BY clause
`-n, --limit N`	Maximum rows to return
`--json, -j`	Output as JSON
`--csv`	Output as CSV
`--markdown, --md`	Output as Markdown table

Examples¶

Basic Query¶

Query all events from a log file:

blq q build.log

Select Columns¶

blq q -s ref_file,ref_line,severity,message build.log

Output:

  ref_file  ref_line severity                  message
 src/main.c           15    error undefined variable 'foo'
 src/main.c           28  warning   unused variable 'temp'

Filter with WHERE Clause¶

blq q -f "severity='error'" build.log
blq q -f "severity='error' AND ref_file LIKE '%main%'" build.log
blq q -f "ref_line > 100" build.log

Order and Limit¶

blq q -o "ref_line DESC" -n 10 build.log
blq q -o "ref_file, ref_line" build.log

Output Formats¶

# JSON (great for scripts and agents)
blq q --json build.log

# CSV (for spreadsheets)
blq q --csv build.log > errors.csv

# Markdown (for documentation)
blq q --markdown build.log

Query Stored Events¶

Without a file argument, queries stored events:

# All stored errors
blq q -f "severity='error'"

# Errors from today
blq q -f "severity='error' AND date = current_date"

# Errors from a specific run
blq q -f "run_id = 5"

Specify Log Format¶

Use the global -F flag to hint the log format:

blq -F gcc q build.log
blq -F pytest q test_output.log

Available Columns¶

When querying log files, these columns are typically available:

Column	Description
`event_id`	Unique event ID within the log
`severity`	error, warning, info, etc.
`ref_file`	Source file path
`ref_line`	Line number in source
`ref_column`	Column number in source
`message`	Error/warning message
`fingerprint`	Unique fingerprint for deduplication
`tool_name`	Tool that produced the event
`category`	Event category

For stored events, additional columns include: - run_id - Run identifier - source_name - Name of the source - source_type - Type (run, import, capture)