groundcover Query Language (gcQL) Reference
Overview
gcQL is a pipeline-based query language for searching, filtering, aggregating, and transforming your logs, traces, and events in groundcover. Queries flow left to right using the pipe operator |, where each stage processes the output of the previous stage.
<filters> | <pipe> | <pipe> | ...You can use gcQL in the Data Explorer, Monitors, Dashboards, and the groundcover API.
gcQL was inspired by LogsQL from VictoriaMetrics VictoriaLogs. If you are familiar with LogsQL, many gcQL concepts will feel familiar. See the Filters page for key differences between gcQL and LogsQL.
Filters
Filters narrow down which records your query returns. They appear at the beginning of a query, before any pipe operations. Use * to match all records when you don't need filtering.
time
Narrow your query to a specific time window. By default, the time range is controlled by the UI time picker, but you can override it directly in the query.
Syntax
_time:duration
_time:[start, end]
_time:YYYY-MM-DD
_time:duration offset durationduration
duration string
Time window relative to now. Units: s, m, h, d, w
start, end
date string
Absolute range in YYYY-MM-DD format
offset
duration string
Shifts the window backwards by the specified duration
Examples
All records from the last 5 minutes
Count records per workload in the last hour
Count records per level in a specific date range
Records from 65–60 minutes ago (5-minute window, shifted back 1 hour)
in
Match any of multiple values for a field, similar to SQL IN.
Syntax
Examples
Logs with level error, fatal, or critical
Count logs for specific workloads
Logs from workloads that have at least one error — uses a subquery to dynamically build the value list
Notes
The
infilter accepts both static value lists and subqueries.When using a subquery, it must return a single field.
eq_field
Match records where two fields have equal values. Useful for finding records where related fields match (e.g., container name equals workload name).
Syntax
Examples
Records where the container name matches the workload name
Records where namespace and workload have the same value
le_field
Match records where the value of one field is less than or equal to the value of another field.
Syntax
Examples
Traces where the request was smaller than or equal to the response
Records where min_latency does not exceed max_latency
lt_field
Match records where the value of one field is strictly less than the value of another field.
Syntax
Examples
Traces where the response was strictly larger than the request
Records where p50 latency is strictly below p99 latency
Notes
eq_field,le_field, andlt_fieldcompare field values within the same record.For numeric fields, the comparison is numeric. For string fields, the comparison is lexicographic.
is_ipv4
Filter for records containing valid IPv4 addresses in a field.
Examples
Records where client_ip contains a valid IPv4 address
Count records grouped by IPv4 source address
is_ipv6
Filter for records containing valid IPv6 addresses in a field.
Examples
Records where client_ip contains a valid IPv6 address
Count records grouped by IPv6 source address
range
Match numeric field values within a range. Use [] for inclusive bounds and () for exclusive bounds.
Syntax
Examples
Records where latency is between 100 and 500 (inclusive)
Count records per workload where duration is between 0.1 and 1.0 (exclusive)
Notes
Mixed brackets are supported:
[min, max)or(min, max].
regexp
Match field values using regular expressions (RE2 syntax). Use ~ for positive match and !~ for negation.
Syntax
Examples
All workloads starting with "gc-"
Case-insensitive match for workloads starting with "groundcover"
Exclude debug and trace logs
Notes
Uses RE2 regex syntax.
Prefix the pattern with
(?i)for case-insensitive matching.The field must be a string-type column.
Pipe Operations
Pipe operations transform, reshape, or aggregate your query results. They appear after filters, separated by the | operator. You can chain multiple pipes together — each one processes the output of the previous stage.
datetime_extract
Extract date/time components (hour, day, weekday, etc.) from a timestamp field. Useful for time-based grouping and analysis.
Syntax
field
timestamp field
The timestamp to extract from (typically _time)
part
string
One of: year, month, day, hour, minute, second, weekday, dayofyear, quarter, week
Examples
Distribution of logs by hour of day
Distribution of logs by day of week
datetime_extract is a pipe operation — it must appear after a filter or *. Use it before stats, not inside stats by().
Correct: * | datetime_extract(_time, 'hour') as hour | stats by (hour) count()
Incorrect: stats by (datetime_extract(_time, 'hour')) count()
extract_regexp
Extract fields from a string using regex with named capture groups.
extract_regexp is not currently usable via the HTTP API. The <> characters in the (?P<name>...) capture-group syntax are stripped by the server-side input sanitizer, causing parse errors. Use grok as an alternative for text extraction.
Syntax
Examples
Extract IP address and port from message field
Extract HTTP method and path from request field
Notes
Uses
(?P<name>...)syntax for named capture groups.Due to the HTTP API limitation above, prefer
grokfor field extraction.
field_names
Discover which fields are available in your data. Useful for exploring unfamiliar data sources.
Examples
List all field names across all records
List up to 50 field names
List field names that appear in error logs
field_names_with_hits
Like field_names, but also shows how many records contain each field.
Examples
Top 20 field names with occurrence counts
Field names and counts for the "api" workload
field_values
Get the unique values for a specific field, similar to SQL SELECT DISTINCT.
Examples
List up to 100 unique workload names
List all log levels present in the data
Which workloads have error logs?
field_values_with_hits
Like field_values, but also shows the occurrence count for each value.
Examples
Top 20 workloads with their log counts
Top 10 workloads by error count
fields
Select specific columns to include in the output. Use this to narrow down results or inspect specific data.
Examples
Show only timestamp, level, content, and workload columns
Inspect the last 50 errors with key context fields
Select trace-specific fields
filter
Apply a filter after aggregation. Use this when you need to filter on computed values like counts or averages.
Examples
Workloads with more than 1,000 records
Workloads where average latency exceeds 500ms
Notes
An implicit syntax without the
filterkeyword is also supported:| total>1000.
format
Create formatted strings using a template with field placeholders. Useful for building human-readable summaries.
Syntax
Use <field_name> to insert field values into the template.
Examples
Build "workload: count" summary strings
Create request summary lines from trace fields
On logs, format works most reliably after a stats aggregation. On traces, it works on both raw and aggregated results.
grok
Parse unstructured text using Logstash-style grok patterns. This is the recommended way to extract structured fields from log messages.
Syntax
If field is not specified, grok parses the default message field (content/_msg).
Examples
Parse Apache/Nginx access log lines
Parse structured application logs
Extract exception type and message from error logs
Parse key=value pairs and aggregate by user and action
Common grok patterns
%{IP}
IPv4 or IPv6 address
%{WORD}
Single word
%{NUMBER}
Integer or float
%{GREEDYDATA}
Rest of line
%{DATA}
Non-greedy match
%{TIMESTAMP_ISO8601}
ISO 8601 timestamp
%{HTTPDATE}
Apache-style date
%{LOGLEVEL}
Log level (INFO, ERROR, etc.)
%{POSINT}
Positive integer
%{URIPATHPARAM}
URI path with params
Notes
Use
%{PATTERN:field_name}to extract into a named field. Unnamed%{PATTERN}matches but does not extract.For custom regex patterns,
extract_regexpsupports arbitrary named capture groups (seeextract_regexpfor current limitations).
join
Join your query results with results from another query based on matching field values.
Syntax
by fields
field names (optional)
Fields to join on. Performs a FULL JOIN when specified
subquery
gcQL query
The right-side query to join with
prefix
string (optional)
Prefix for subquery fields to avoid name conflicts
Examples
Enrich results with HTTP status codes from related spans
len
Calculate the byte length of a string field.
Examples
Show the byte length of each log message
Average log message size in bytes
Notes
Returns length in bytes, not characters.
limit
Limit the number of results returned.
Examples
First 10 log records
First 50 error records
Top 10 workloads by record count
When querying raw log records, use the fields pipe before limit to select columns first (e.g., * | fields timestamp, level, content | limit 10). After stats and on traces, limit works directly.
math
Perform arithmetic calculations on fields. Use this to derive new values from existing fields.
Syntax
Operators: +, -, *, /, % (modulo), ^ (power)
Functions: max(a, b), min(a, b), abs(x), round(x), ceil(x), floor(x), ln(x), exp(x), now(), rand()
Examples
Double the count for each workload
Convert average latency from seconds to milliseconds
Total bytes transferred per workload
offset
Skip a number of results for pagination. Typically used with limit.
Examples
Records 21–30 (skip the first 20)
Workloads ranked 11th–20th by count
rename
Rename fields in the output.
Syntax
Examples
Rename duration_seconds to latency for readability
Rename the count alias
sort
Sort results by one or more fields. Default order is ascending.
Syntax
Examples
Top 10 workloads by log count
Levels sorted from least to most frequent
Slowest workloads by average latency
split
Split a string field by a separator into an array. Often used with unroll to expand the array into separate rows.
Syntax
Examples
Split comma-separated tags into an array
Split a key:value string on the colon
stats
Aggregate data using statistical functions, optionally grouped by one or more fields. This is the primary aggregation pipe in gcQL.
Syntax
Examples
Total record count
Record count per workload
Average latency broken down by environment, cluster, namespace, and workload
p99 latency per resource
Notes
Only
count()takes no arguments. All other stats functions require a field name.Use
quantile(phi, field)for percentiles — see thequantilesection below.
total_stats
Compute running totals across the result set. Each output row includes the cumulative aggregate up to that point.
Syntax
Examples
Running count across workload groups
Cumulative record count
On logs, total_stats works most reliably after a stats aggregation. On traces, it works on both raw and aggregated results.
uniq
Get unique combinations of field values, similar to SQL SELECT DISTINCT.
Examples
List all unique workload names
All unique namespace + workload combinations
Up to 100 unique workloads
unpack_json
Parse a JSON string field into queryable subfields. After unpacking, access fields with dot notation (prefix.field_name).
Syntax
Examples
Parse the payload field as JSON
Extract user_id and action from a JSON request body
Count records grouped by the action field inside a JSON metadata column
unroll
Expand an array field so each element becomes a separate row. Use after split to flatten delimited strings.
Syntax
Examples
Split content by comma, then create one row per item
Split URL paths by "/" and count occurrences of each path segment
Notes
The target field must be an array. Use
splitfirst to create an array from a string field.Use a different alias for the
unrolloutput than thesplitoutput to avoid column name conflicts.
Stats Functions
Stats functions are used inside the stats pipe (and related pipes like total_stats) to compute aggregate values. You can use multiple stats functions in a single stats call.
avg
Average (mean) of a numeric field.
Examples
Average latency per workload
Overall average latency
count
Count the number of records. The only stats function that takes no arguments.
Examples
Total record count
Records per workload
Records per log level
count_empty
Count records where a field is empty or missing.
Examples
How many records per workload have no error message?
Logs that are not associated with a trace
count_uniq
Count the number of unique (distinct) values for a field.
Examples
Unique users per workload
Number of distinct pods per namespace
Notes
To see the actual unique values (not just the count), use
uniq_valuesinstead.
max
Maximum value of a numeric field.
Examples
Slowest request per workload
Slowest response time per resource
median
Median (50th percentile) of a numeric field. Equivalent to quantile(0.50, field).
Examples
Median latency per workload
Overall median latency
min
Minimum value of a numeric field.
Examples
Fastest request per workload
Fastest response time per resource
quantile
Calculate percentile values. Use phi between 0 and 1 (e.g., 0.50 = p50, 0.95 = p95, 0.99 = p99).
Syntax
Examples
p50 latency per workload
p95 latency per workload
p99 latency per resource
Do not use p50(), p95(), or p99() — these functions do not exist in gcQL. Always use quantile().
row_any
Return any single (sample) value from a field within each group. Useful for grabbing an example value alongside an aggregation.
Examples
One sample log line per workload, plus the count
An example workload for each log level
Notes
The returned value is arbitrary and non-deterministic.
sum
Sum of values for a numeric field.
Examples
Total bytes sent per workload
Total requests per namespace
sum_len
Sum the byte lengths of all values in a string field.
Examples
Total log volume in bytes per workload
Total log volume across all records
uniq_values
Collect unique values from a field into an array.
Examples
Which log levels does each workload produce?
Up to 10 unique pod names per namespace
Notes
Returns an array of distinct values. Use
limitinside the function to cap the array size.
values
Collect all values from a field into an array, including duplicates.
Examples
All status codes seen per workload (with duplicates)
All log levels per workload (with duplicates)
Notes
For distinct values only, use
uniq_valuesinstead.The
limit Nmodifier is accepted syntactically but may not reliably cap the number of values in the returned array. Useuniq_values(field) limit Nfor bounded results.
Last updated