# 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. ``` | | | ... ``` You can use gcQL in the Data Explorer, Monitors, Dashboards, and the groundcover API. {% hint style="info" %} gcQL was inspired by [LogsQL](https://docs.victoriametrics.com/victorialogs/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. {% endhint %} *** ### 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 duration ``` | Argument | Type | Description | | -------------- | --------------- | ----------------------------------------------------------- | | `duration` | 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** ``` _time:5m ``` *All records from the last 5 minutes* ``` _time:1h | stats by (workload) count() as cnt ``` *Count records per workload in the last hour* ``` _time:[2026-01-01, 2026-01-18] | stats by (level) count() as cnt ``` *Count records per level in a specific date range* ``` _time:5m offset 1h | stats by (workload) count() as cnt ``` *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** ``` field:in(value1, value2, ...) ``` **Examples** ``` level:in(error, fatal, critical) | fields timestamp, level, content | limit 20 ``` *Logs with level error, fatal, or critical* ``` workload:in(api, gateway, auth) | stats by (workload) count() as cnt ``` *Count logs for specific workloads* ``` workload:in(level:error | fields workload) | stats by (workload) count() as cnt ``` *Logs from workloads that have at least one error — uses a subquery to dynamically build the value list* **Notes** * The `in` filter 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** ``` field1:eq_field(field2) ``` **Examples** ``` container_name:eq_field(workload) | fields timestamp, container_name, workload | limit 10 ``` *Records where the container name matches the workload name* ``` namespace:eq_field(workload) | stats by (namespace) count() as cnt ``` *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** ``` field1:le_field(field2) ``` **Examples** ``` request.size_bytes:le_field(response.size_bytes) | fields start_timestamp, resource, request.size_bytes, response.size_bytes | limit 10 ``` *Traces where the request was smaller than or equal to the response* ``` min_latency:le_field(max_latency) | fields timestamp, workload, min_latency, max_latency | limit 10 ``` *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** ``` field1:lt_field(field2) ``` **Examples** ``` request.size_bytes:lt_field(response.size_bytes) | fields start_timestamp, resource, request.size_bytes, response.size_bytes | limit 10 ``` *Traces where the response was strictly larger than the request* ``` p50:lt_field(p99) | fields timestamp, workload, p50, p99 | limit 10 ``` *Records where p50 latency is strictly below p99 latency* **Notes** * `eq_field`, `le_field`, and `lt_field` compare 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** ``` is_ipv4(client_ip) | fields timestamp, client_ip, content | limit 10 ``` *Records where client\_ip contains a valid IPv4 address* ``` is_ipv4(source_address) | stats by (source_address) count() as cnt ``` *Count records grouped by IPv4 source address* *** ### is\_ipv6 Filter for records containing valid IPv6 addresses in a field. **Examples** ``` is_ipv6(client_ip) | fields timestamp, client_ip, content | limit 10 ``` *Records where client\_ip contains a valid IPv6 address* ``` is_ipv6(source_address) | stats by (source_address) count() as cnt ``` *Count records grouped by IPv6 source address* *** ### range Match numeric field values within a range. Use `[]` for inclusive bounds and `()` for exclusive bounds. **Syntax** ``` field:range[min, max] field:range(min, max) ``` **Examples** ``` latency:range[100, 500] | fields timestamp, workload, latency | limit 20 ``` *Records where latency is between 100 and 500 (inclusive)* ``` duration_seconds:range(0.1, 1.0) | stats by (workload) count() as cnt ``` *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** ``` field:~"pattern" field:!~"pattern" ``` **Examples** ``` workload:~"gc-.*" | stats by (workload) count() as cnt ``` *All workloads starting with "gc-"* ``` workload:~"(?i)GROUNDCOVER.*" | fields timestamp, workload, content | limit 10 ``` *Case-insensitive match for workloads starting with "groundcover"* ``` level:!~"debug|trace" | stats by (level) count() as cnt ``` *Exclude debug and trace logs* **Notes** * Uses [RE2 regex syntax](https://github.com/google/re2/wiki/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** ``` datetime_extract(field, 'part') as alias ``` | Argument | Type | Description | | -------- | --------------- | ----------------------------------------------------------------------------------------------------- | | `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** ``` * | datetime_extract(_time, 'hour') as hour | stats by (hour) count() ``` *Distribution of logs by hour of day* ``` * | datetime_extract(_time, 'weekday') as weekday | stats by (weekday) count() ``` *Distribution of logs by day of week* {% hint style="warning" %} `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()` {% endhint %} *** ### extract\_regexp Extract fields from a string using regex with named capture groups. {% hint style="warning" %} `extract_regexp` is not currently usable via the HTTP API. The `<>` characters in the `(?P...)` capture-group syntax are stripped by the server-side input sanitizer, causing parse errors. Use `grok` as an alternative for text extraction. {% endhint %} **Syntax** ``` extract_regexp 'pattern' from field ``` **Examples** ``` * | extract_regexp '(?P\d+\.\d+\.\d+\.\d+):(?P\d+)' from message | limit 10 ``` *Extract IP address and port from message field* ``` * | extract_regexp '(?P\w+) (?P/\S+)' from request | limit 10 ``` *Extract HTTP method and path from request field* **Notes** * Uses `(?P...)` syntax for named capture groups. * Due to the HTTP API limitation above, prefer `grok` for field extraction. *** ### field\_names Discover which fields are available in your data. Useful for exploring unfamiliar data sources. **Examples** ``` field_names ``` *List all field names across all records* ``` field_names limit 50 ``` *List up to 50 field names* ``` level:error | 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** ``` field_names_with_hits limit 20 ``` *Top 20 field names with occurrence counts* ``` workload:api | field_names_with_hits ``` *Field names and counts for the "api" workload* *** ### field\_values Get the unique values for a specific field, similar to SQL `SELECT DISTINCT`. **Examples** ``` field_values workload limit 100 ``` *List up to 100 unique workload names* ``` field_values level ``` *List all log levels present in the data* ``` level:error | field_values workload ``` *Which workloads have error logs?* *** ### field\_values\_with\_hits Like `field_values`, but also shows the occurrence count for each value. **Examples** ``` field_values_with_hits workload limit 20 ``` *Top 20 workloads with their log counts* ``` level:error | field_values_with_hits workload limit 10 ``` *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** ``` * | fields timestamp, level, content, workload | limit 10 ``` *Show only timestamp, level, content, and workload columns* ``` level:error | fields timestamp, instance, workload, content | limit 50 ``` *Inspect the last 50 errors with key context fields* ``` * | fields start_timestamp, resource, duration_seconds, status_code, trace_id | limit 10 ``` *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** ``` * | stats by (workload) count() as total | filter total>1000 ``` *Workloads with more than 1,000 records* ``` * | stats by (workload) avg(duration_seconds) as avg_dur | filter avg_dur>0.5 ``` *Workloads where average latency exceeds 500ms* **Notes** * An implicit syntax without the `filter` keyword is also supported: `| total>1000`. *** ### format Create formatted strings using a template with field placeholders. Useful for building human-readable summaries. **Syntax** ``` format "template with placeholders" as alias ``` Use `` to insert field values into the template. **Examples** ``` * | stats by (workload) count() as cnt | format ": " as summary | limit 10 ``` *Build "workload: count" summary strings* ``` * | format " returned " as request_summary | limit 10 ``` *Create request summary lines from trace fields* {% hint style="info" %} On logs, `format` works most reliably after a `stats` aggregation. On traces, it works on both raw and aggregated results. {% endhint %} *** ### grok Parse unstructured text using Logstash-style grok patterns. This is the recommended way to extract structured fields from log messages. **Syntax** ``` grok [field=source_field] "pattern" ``` If `field` is not specified, grok parses the default message field (`content`/`_msg`). **Examples** ``` * | grok "%{IP:client_ip} - - \[%{HTTPDATE:timestamp}\] \"%{WORD:method} %{URIPATHPARAM:request}\"" | limit 10 ``` *Parse Apache/Nginx access log lines* ``` * | grok field=content "%{TIMESTAMP_ISO8601:ts} %{LOGLEVEL:level} \[%{DATA:logger}\] %{GREEDYDATA:message}" | limit 10 ``` *Parse structured application logs* ``` level:error | grok "Exception: %{GREEDYDATA:exception_type}: %{GREEDYDATA:error_msg}" | limit 10 ``` *Extract exception type and message from error logs* ``` * | grok "user=%{USERNAME:user} action=%{WORD:action} status=%{WORD:status}" | stats by (user, action) count() ``` *Parse key=value pairs and aggregate by user and action* **Common grok patterns** | Pattern | Matches | | ---------------------- | ----------------------------- | | `%{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_regexp` supports arbitrary named capture groups (see `extract_regexp` for current limitations). *** ### join Join your query results with results from another query based on matching field values. **Syntax** ``` join [by (field1, field2)] (subquery) [prefix "prefix_"] ``` | Argument | Type | Description | | ----------- | ---------------------- | -------------------------------------------------------- | | `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** ``` * | join by (trace_id) (span_type:http | fields trace_id, status_code) ``` *Enrich results with HTTP status codes from related spans* *** ### len Calculate the byte length of a string field. **Examples** ``` * | len(content) as content_length | fields timestamp, content_length | limit 10 ``` *Show the byte length of each log message* ``` * | len(content) as content_length | stats avg(content_length) as avg_log_size ``` *Average log message size in bytes* **Notes** * Returns length in bytes, not characters. *** ### limit Limit the number of results returned. **Examples** ``` * | fields timestamp, level, content | limit 10 ``` *First 10 log records* ``` level:error | fields timestamp, workload, content | limit 50 ``` *First 50 error records* ``` * | stats by (workload) count() as cnt | sort by (cnt desc) | limit 10 ``` *Top 10 workloads by record count* {% hint style="info" %} 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. {% endhint %} *** ### math Perform arithmetic calculations on fields. Use this to derive new values from existing fields. **Syntax** ``` math expression as alias ``` **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** ``` * | stats by (workload) count() as total | math total * 2 as doubled | limit 10 ``` *Double the count for each workload* ``` * | stats by (workload) avg(duration_seconds) as avg_dur | math round(avg_dur * 1000) as avg_ms | limit 10 ``` *Convert average latency from seconds to milliseconds* ``` * | stats by (workload) sum(bytes_sent) as sent, sum(bytes_received) as received | math sent + received as total_bytes | limit 10 ``` *Total bytes transferred per workload* *** ### offset Skip a number of results for pagination. Typically used with `limit`. **Examples** ``` * | fields timestamp, level, content | offset 20 | limit 10 ``` *Records 21–30 (skip the first 20)* ``` * | stats by (workload) count() as cnt | sort by (cnt desc) | offset 10 | limit 10 ``` *Workloads ranked 11th–20th by count* *** ### rename Rename fields in the output. **Syntax** ``` rename old_name as new_name [, old_name2 as new_name2, ...] ``` **Examples** ``` * | rename duration_seconds as latency | fields timestamp, latency, workload | limit 10 ``` *Rename duration\_seconds to latency for readability* ``` * | stats by (workload) count() as cnt | rename cnt as total_count | limit 10 ``` *Rename the count alias* *** ### sort Sort results by one or more fields. Default order is ascending. **Syntax** ``` sort by (field1 [asc|desc], field2 [asc|desc], ...) ``` **Examples** ``` * | stats by (workload) count() as cnt | sort by (cnt desc) | limit 10 ``` *Top 10 workloads by log count* ``` * | stats by (level) count() as cnt | sort by (cnt asc) | limit 10 ``` *Levels sorted from least to most frequent* ``` * | stats by (workload) avg(duration_seconds) as avg_dur | sort by (avg_dur desc) | limit 10 ``` *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** ``` split 'separator' from field [as alias] ``` **Examples** ``` * | split ',' from tags as tag_array | limit 10 ``` *Split comma-separated tags into an array* ``` * | split ':' from key_value as parts | limit 10 ``` *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** ``` stats [by (field1, field2, ...)] func1() [as alias1], func2() [as alias2], ... ``` **Examples** ``` * | stats count() ``` *Total record count* ``` * | stats by (workload) count() as total ``` *Record count per workload* ``` * | stats by (env, cluster, namespace, workload) avg(duration_seconds) as avg_latency ``` *Average latency broken down by environment, cluster, namespace, and workload* ``` * | stats by (resource) quantile(0.99, duration_seconds) as p99 ``` *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 the `quantile` section below. *** ### total\_stats Compute running totals across the result set. Each output row includes the cumulative aggregate up to that point. **Syntax** ``` total_stats func1() as alias1 [, func2() as alias2] ``` **Examples** ``` * | stats by (workload) count() as cnt | total_stats count() as running | limit 10 ``` *Running count across workload groups* ``` * | total_stats count() as running_total | limit 5 ``` *Cumulative record count* {% hint style="info" %} On logs, `total_stats` works most reliably after a `stats` aggregation. On traces, it works on both raw and aggregated results. {% endhint %} *** ### uniq Get unique combinations of field values, similar to SQL `SELECT DISTINCT`. **Examples** ``` * | uniq by (workload) ``` *List all unique workload names* ``` * | uniq by (namespace, workload) ``` *All unique namespace + workload combinations* ``` * | uniq by (workload) limit 100 ``` *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** ``` unpack_json from field as prefix ``` **Examples** ``` * | unpack_json from payload as payload | limit 10 ``` *Parse the payload field as JSON* ``` * | unpack_json from request_body as req | fields req.user_id, req.action | limit 10 ``` *Extract user\_id and action from a JSON request body* ``` * | unpack_json from metadata as meta | stats by (meta.action) count() ``` *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** ``` unroll field [as alias] ``` **Examples** ``` * | split ',' from content as arr | unroll arr as item | limit 10 ``` *Split content by comma, then create one row per item* ``` * | split '/' from resource as parts | unroll parts as part | stats by (part) count() ``` *Split URL paths by "/" and count occurrences of each path segment* **Notes** * The target field must be an array. Use `split` first to create an array from a string field. * Use a different alias for the `unroll` output than the `split` output 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** ``` * | stats by (workload) avg(duration_seconds) as avg_latency ``` *Average latency per workload* ``` * | stats avg(duration_seconds) as overall_avg ``` *Overall average latency* *** ### count Count the number of records. The only stats function that takes no arguments. **Examples** ``` * | stats count() ``` *Total record count* ``` * | stats by (workload) count() as total ``` *Records per workload* ``` * | stats by (level) count() as log_count ``` *Records per log level* *** ### count\_empty Count records where a field is empty or missing. **Examples** ``` * | stats by (workload) count_empty(error_message) as missing_errors ``` *How many records per workload have no error message?* ``` * | stats count_empty(trace_id) as logs_without_trace ``` *Logs that are not associated with a trace* *** ### count\_uniq Count the number of unique (distinct) values for a field. **Examples** ``` * | stats by (workload) count_uniq(user_id) as unique_users ``` *Unique users per workload* ``` * | stats by (namespace) count_uniq(pod) as pod_count ``` *Number of distinct pods per namespace* **Notes** * To see the actual unique values (not just the count), use `uniq_values` instead. *** ### max Maximum value of a numeric field. **Examples** ``` * | stats by (workload) max(duration_seconds) as max_latency ``` *Slowest request per workload* ``` * | stats by (resource) max(response_time) as slowest ``` *Slowest response time per resource* *** ### median Median (50th percentile) of a numeric field. Equivalent to `quantile(0.50, field)`. **Examples** ``` * | stats by (workload) median(duration_seconds) as median_latency ``` *Median latency per workload* ``` * | stats median(duration_seconds) as overall_median ``` *Overall median latency* *** ### min Minimum value of a numeric field. **Examples** ``` * | stats by (workload) min(duration_seconds) as min_latency ``` *Fastest request per workload* ``` * | stats by (resource) min(response_time) as fastest ``` *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** ``` quantile(phi, field) ``` **Examples** ``` * | stats by (workload) quantile(0.50, duration_seconds) as p50 ``` *p50 latency per workload* ``` * | stats by (workload) quantile(0.95, duration_seconds) as p95 ``` *p95 latency per workload* ``` * | stats by (resource) quantile(0.99, duration_seconds) as p99 ``` *p99 latency per resource* {% hint style="warning" %} Do **not** use `p50()`, `p95()`, or `p99()` — these functions do not exist in gcQL. Always use `quantile()`. {% endhint %} *** ### row\_any Return any single (sample) value from a field within each group. Useful for grabbing an example value alongside an aggregation. **Examples** ``` * | stats by (workload) row_any(content) as sample_log, count() as cnt ``` *One sample log line per workload, plus the count* ``` * | stats by (level) row_any(workload) as example_workload, count() as cnt ``` *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** ``` * | stats by (workload) sum(bytes_sent) as total_bytes ``` *Total bytes sent per workload* ``` * | stats by (namespace) sum(request_count) as total_requests ``` *Total requests per namespace* *** ### sum\_len Sum the byte lengths of all values in a string field. **Examples** ``` * | stats by (workload) sum_len(content) as total_log_bytes ``` *Total log volume in bytes per workload* ``` * | stats sum_len(content) as total_bytes ``` *Total log volume across all records* *** ### uniq\_values Collect unique values from a field into an array. **Examples** ``` * | stats by (workload) uniq_values(level) as log_levels ``` *Which log levels does each workload produce?* ``` * | stats by (namespace) uniq_values(pod) limit 10 as sample_pods ``` *Up to 10 unique pod names per namespace* **Notes** * Returns an array of distinct values. Use `limit` inside the function to cap the array size. *** ### values Collect all values from a field into an array, including duplicates. **Examples** ``` * | stats by (workload) values(status_code) as all_status_codes ``` *All status codes seen per workload (with duplicates)* ``` * | stats by (workload) values(level) as all_levels ``` *All log levels per workload (with duplicates)* **Notes** * For distinct values only, use `uniq_values` instead. * The `limit N` modifier is accepted syntactically but may not reliably cap the number of values in the returned array. Use `uniq_values(field) limit N` for bounded results. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.groundcover.com/use-groundcover/querying-your-groundcover-data/groundcover-query-language/groundcover-query-language-gcql-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.