Skip to content
Cruncher

Querying Data in Cruncher

Cruncher uses QQL (Quick Query Language) to let you query, filter, and transform your data efficiently. A QQL query is composed of several parts:

  • Datasource (optional, not yet implemented): An @name token that will scope the query to a specific adapter.
  • Controller parameters (controllerParams): Special key-value pairs at the start of the query that act as filters for the underlying data adapter, enabling more efficient data retrieval.
  • Search expression: A free-text or structured search to filter records.
  • Pipeline commands: A sequence of commands (like where, stats, table, etc.) to further process and shape your results.

Query Structure

Section titled “Query Structure”
1
🔌
Datasource
@name — scope the query to a specific adapter (not yet implemented)
2
🎛️
Controller Parameters
key="value" pairs pushed to the backend adapter for early server-side filtering
3
🔍
Search Expression
Free-text words or phrases matched against all fields in each record
4
⚙️
Pipeline Commands
| where … | stats … | table … — transform and shape the results

A typical QQL query looks like:

controllerParam1="value1" controllerParam2="42" search terms | where ... | stats ... | table ...

Datasource Selection

Section titled “Datasource Selection”

When multiple adapters are configured, you will be able to scope a query to a specific one by placing an @datasource-name token at the very start of the query:

@datasource-name <rest of query>
  • The name must match the adapter identifier as configured in your cruncher.config.yaml.
  • When omitted, the query runs against the currently selected adapter in the UI.

Controller Parameters (controllerParams)

Section titled “Controller Parameters (controllerParams)”

Controller parameters are written at the beginning of your query, before the main search or pipeline. They support equality, exclusion, and regex matching:

key="value" equality

Include only records where key equals value.

key!="value" exclusion

Exclude records where key equals value.

key=`pattern` regex match

Include records where key matches the regex pattern (backtick-wrapped).

key!=`pattern` regex exclusion

Exclude records where key matches the regex pattern (backtick-wrapped).

Controller parameters are sent directly to the adapter backend, allowing it to filter data as early as possible. This can greatly improve query performance, especially on large datasets, by reducing the amount of data that needs to be loaded and processed.

Tip: Always use controller parameters for fields that are indexed or supported by your data source for best performance.

Examples

Section titled “Examples”
user="alice" environment="prod" | where duration > 1000 | table timestamp, message

Include only records where user is alice and environment is prod.

environment!="dev" | stats count() by service

Exclude records from the dev environment.

namespace=`^prod-.*` | where level == "error"

Include records where namespace matches the regex ^prod-.*.

namespace!=`^test-.*` | stats count() by service

Exclude records where namespace matches ^test-.*.

Search Expressions

Section titled “Search Expressions”

After controller parameters, you can add a search expression. The search expression is a sequence of words or phrases that are matched against your data.

  • Each word is treated as a separate token. By default, there is an implicit AND between all tokens: all words must be present in a record for it to match.
  • To match a full sentence or exact phrase, wrap it in double quotes ("...").
  • You can use the OR and AND operators to build more complex search logic:
    • error OR warning matches records containing either “error” or “warning”.
    • error AND timeout (or just error timeout) matches records containing both “error” and “timeout”.
  • Parentheses can be used to group conditions: (error OR warning) AND timeout.

Examples

Section titled “Examples”
user="alice" error | table message

Matches records where the user is “alice” and the word “error” appears anywhere in the record.

error timeout

Matches records containing both “error” and “timeout” (implicit AND).

"disk full"

Matches records containing the exact phrase “disk full”.

error OR warning

Matches records containing either “error” or “warning”.

(error OR warning) timeout

Matches records containing either “error” or “warning”, and also “timeout”.

Regex and String Literals

Section titled “Regex and String Literals”

When writing QQL queries, it’s important to distinguish between string and regex types:

  • String values are usually wrapped in double quotes ("...").
  • Regex values must be wrapped in backticks (`...`).
  • Single quoted strings ('...') can be used for column names that contain special characters, spaces, or reserved words. For example, where 'user name' == "alice" matches a column literally named user name.

This distinction is important for functions and commands that accept either type. For example:

| where match(message, `^Error:.*`)

This matches records where the message field matches the regular expression ^Error:.*.

| where user == "alice"

This matches records where the user field is exactly “alice”.

| where 'user name' == "alice"

This matches records where the column named user name is exactly “alice”.

Always use double quotes for string values, single quotes for column names with special characters, and backticks for regex patterns in your QQL queries.

Comments

Section titled “Comments”

QQL supports single-line comments starting with //. Everything from // to the end of the line is ignored by the parser.

// Filter to recent errors only
@docker | where level == "error" // only errors
  | stats count() by service

Comments can appear anywhere in the query — at the start, inline after a command, or on their own line. They are useful for annotating complex queries.

Continue to the next sections to learn about search expressions and pipeline commands in QQL.