Search Syntax

LogchefQL is Logchef’s search syntax. You use it to filter logs without writing SQL.

LogchefQL is the quick-filter language shared across supported datasources:

• ClickHouse sources compile LogchefQL to SQL
• VictoriaLogs sources compile LogchefQL to LogsQL

Basic Syntax

The basic syntax follows a simple key-value pattern:

key="value"

For example:

level="error"
service="payment-api"

Operators

LogchefQL supports these operators:

Equality Operators

Operator	Description	Example
=	Equals	status=200
!=	Not equals	level!="debug"

Pattern Matching Operators

Operator	Description	Example
~	Contains (case-insensitive)	message~"timeout"
!~	Does not contain	path!~"health"

Comparison Operators

Operator	Description	Example
>	Greater than	status>400
<	Less than	response_time<1000
>=	Greater than or equal to	severity_number>=3
<=	Less than or equal to	duration<=5000

Combining Conditions

You can combine multiple conditions using and and or operators (case-insensitive):

# Find errors in payment service
level="error" and service="payment-api"

# Find successful or redirected responses
status=200 or status=301

# Complex combinations with parentheses
(service="auth" or service="users") and level="error"

# Find slow requests with errors
response_time>1000 and status>=500

Nested Field Access

LogchefQL supports accessing nested fields using dot notation. This works with:

• Map columns (e.g., Map(String, String))
• JSON columns
• String columns containing JSON

Dot Notation

Access nested keys using dots:

# Access nested field in a Map column
log_attributes.user_id="12345"

# Multi-level nesting
log_attributes.request.method="POST"

# Pattern matching on nested fields
log_attributes.error.message~"connection refused"

Quoted Field Names

For field names containing special characters (like dots), use quotes:

# Field name contains a literal dot
log_attributes."user.name"="alice"

# Mixed notation
log_attributes."nested.key".subfield="value"

Pipe Operator (Custom SELECT)

The pipe operator (|) selects specific columns instead of the default SELECT *. Use it for:

• Reducing data transfer
• Focusing on relevant fields
• Extracting specific nested values

Syntax

<filter conditions> | <field1> <field2> ...

Examples

# Select only service_name from syslog namespace
namespace="syslog" | service_name

# Select multiple fields
namespace="prod" | namespace service_name body

# Select nested fields
level="error" | timestamp log_attributes.request_id body

# Extract specific nested values
service="api" | timestamp log_attributes.user_id log_attributes.endpoint

The selected fields appear as columns in the result set, making it easy to focus on the data you need.

Examples

Finding Errors

level="error"

HTTP Status Codes

# Server errors
status>=500

# Client errors
status>=400 and status<500

# Successful requests
status=200

Service-specific Logs

service="payment-api" and level="error"

Partial Text Search

# Find logs containing "timeout"
message~"timeout"

# Find paths not containing "internal"
path!~"internal"

Performance Analysis

# Slow requests (over 1 second)
response_time>1000

# Very fast requests (under 10ms)
response_time<10

Nested Field Queries

# Filter by nested attribute
log_attributes.user_id="user-123"

# Pattern match in nested JSON
body~"error" and log_attributes.request.method="POST"

Under the Hood

When you use LogchefQL, Logchef converts it to the selected datasource’s native query language before execution.

ClickHouse

For ClickHouse sources, LogchefQL converts to optimized SQL queries:

• The ~ and !~ operators use ClickHouse’s positionCaseInsensitive function for efficient partial matches
• Nested field access on Map columns uses subscript notation: column['key']
• Nested field access on JSON/String columns uses JSONExtractString
• A default time range and limit is automatically applied
• Results are ordered by timestamp in descending order

For example, this search:

level="error" and log_attributes.user_id="12345"

Gets converted to (for a table with log_attributes as a Map column):

SELECT *
FROM logs.app
WHERE (`level` = 'error') AND (`log_attributes`['user_id'] = '12345')
  AND timestamp BETWEEN toDateTime('2025-04-07 14:20:42', 'UTC') AND toDateTime('2025-04-07 14:25:42', 'UTC')
ORDER BY timestamp DESC
LIMIT 100

And with the pipe operator:

level="error" | timestamp level body

Generates:

SELECT `timestamp`, `level`, `body`
FROM logs.app
WHERE `level` = 'error'
  AND timestamp BETWEEN toDateTime('2025-04-07 14:20:42', 'UTC') AND toDateTime('2025-04-07 14:25:42', 'UTC')
ORDER BY timestamp DESC
LIMIT 100

VictoriaLogs

For VictoriaLogs sources, the same LogchefQL expression compiles to LogsQL.

For example:

level="error" and service="payments" | _msg service level

Compiles to:

(level:="error") AND (service:="payments") | fields _time, _msg, service, level

Logchef applies the selected time range separately when executing LogsQL queries.

Native Mode

For advanced queries that go beyond LogchefQL’s capabilities, you can switch to the datasource’s native mode in the query editor:

• SQL for ClickHouse
• LogsQL for VictoriaLogs

Native mode gives you direct access to backend-specific capabilities, including:

• ClickHouse aggregations (COUNT, SUM, AVG, etc.)
• VictoriaLogs-specific LogsQL pipes and processing operators
• Subqueries
• Joins
• Custom functions
• Complex expressions

In SQL mode, your query executes exactly as written. Time range and limit controls are disabled since you have full control over the SQL.

Tips for Effective Queries

1. Start specific, then broaden: Begin with specific conditions and remove filters to expand results
2. Use parentheses for complex logic: (a or b) and c is clearer than relying on operator precedence
3. Use nested field access: Don’t flatten your logs. Query them directly
4. Use the pipe operator: Select only the fields you need for faster queries
5. Switch to SQL mode: For aggregations and advanced analysis

Next steps

• See Query Examples for LogchefQL patterns applied to real scenarios
• Review the Query Interface for time controls and result views
• Try the Field Values Sidebar to build filters without typing