> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/investigate/querying-your-groundcover-data/groundcover-query-language.md).

# groundcover Query Language

The groundcover Query Language is a powerful tool for querying and analyzing logs, traces, and events across your infrastructure.

### What is the groundcover Query Language?

The groundcover Query Language is inspired by LogsQL but designed specifically for groundcover's observability platform. It uses a pipeline-based syntax where operations flow from left to right using the pipe operator `|`.

You can use it to:

* [**Filter**](/investigate/querying-your-groundcover-data/groundcover-query-language/filters.md) logs, traces, and events with flexible search patterns
* [**Aggregate**](/investigate/querying-your-groundcover-data/groundcover-query-language/aggregations.md) data with statistical functions (count, avg, percentiles, etc.)
* [**Join**](/investigate/querying-your-groundcover-data/groundcover-query-language/join-operations.md) multiple queries
* [**Transform**](/investigate/querying-your-groundcover-data/groundcover-query-language/pipeline-operations.md) results with sorting, limiting, field selection, and more

### Where Can You Use It?

The query language is available in:

1. [**Data Explorer**](/investigate/querying-your-groundcover-data/explore-and-monitors-query-builder.md) - Query and visualize data interactively
2. [**Monitors**](/automate/monitors.md) - Create alerts based on query results
3. [**Dashboards**](/investigate/dashboards-and-alerts.md) - Build custom visualizations
4. [**APIs**](https://docs.groundcover.com/use-groundcover/remote-access-and-apis/api-examples/query-data-gcql) - Query data programmatically

#### Code Mode

Access the query language through **Code Mode** in the Data Explorer and Monitors query builder. Code Mode gives you full control over your queries with syntax highlighting and auto-completion.

### Basic Query Structure

All queries follow this general pattern:

```
<filters> | <operation1> | <operation2> | ...
```

**Example - Simple filter:**

```
level:error
```

*Find all error logs*

**Example - Filter with aggregation:**

```
level:error | stats by (workload) count()
```

*Count errors per workload*

**Example - Full pipeline:**

```
level:error namespace:production | stats by (workload) count() as errors | sort by (errors desc) | limit 10
```

*Top 10 workloads with errors in production*

### Core Components

#### Filters

Filters narrow down your data using field-value matching.

```
level:error
```

```
workload:auth-service status_code>=500
```

```
"*timeout*" namespace:prod
```

#### Aggregations

Compute metrics from filtered data using `stats`.

```
* | stats count()
```

```
* | stats by (workload) avg(duration_seconds)
```

#### Join Operations

Combine data from multiple queries.

```
* | stats by (user_id) count() | join by (user_id) (event:purchase | stats by (user_id) count())
```

#### Pipeline Operations

Transform results with sort, limit, fields, and more.

```
* | sort by (timestamp desc)
```

```
* | stats by (endpoint) count() | sort by (count desc) | limit 10
```

```
* | fields timestamp, level, message, workload
```

### Differences from Other Query Languages

#### vs. LogsQL

* **Case-insensitive** by default (LogsQL is case-sensitive)
* **Implicit OR** for same-field filters: `level:error level:warn` = `level:error OR level:warn`
* **Time bucketing** configured externally, not in `stats by (_time:5m)`
* **Both** `*value*` and `~"value"` syntax for substring matching

#### vs. SQL

* **Pipeline-based** - Left-to-right flow with `|` vs. declarative SELECT/FROM/WHERE
* **No tables** - Query logs/traces/events directly
* **Implicit AND** - Multiple filters are ANDed automatically
* **Function syntax** - `stats by (field) count()` vs. `SELECT field, COUNT(*) GROUP BY field`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/investigate/querying-your-groundcover-data/groundcover-query-language.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.