# [[LogQL]]
[docs](https://grafana.com/docs/loki/latest/query/)
LogQL is a [[Query language]] for the [[Logs|log]] aggregation tool [[Grafana Loki|Loki]].
![[LogQL.svg]]
Here's a video I created about getting started with LogQL:
[^nvdh]
The results of a LogQL query can be one of the following data types:
- A [[Log stream]] is a a sequence of [[Logs|log]] entries that share the same label set. It's sort of like a [[Time Series]], but for logs instead of numbers. Only [[Log queries in Loki|log queries]] can return raw log streams.
- A [[LogQL queries don't return scalar values|scalar]] is a single simple numeric floating point value, such as `42`. Scalars can only be returned using [[Metric queries in Loki|metric queries]].
- An [[Instant vectors in LogQL|instant vector]] is a single sample (comprised of potentially multiple data points or log records) taken at a given timestamp. Instant vectors can only be returned by [[Metric queries in Loki|metric queries]].
## History of LogQL
[[Tom Wilkie]] asked [[Cyril Tovena]] to create a query language for Loki that was compatible with [[Prometheus]]'s [[PromQL]], so that people can flexibly query both metrics and logs using a similar syntax. Cyril created it along with outside help from [[Frederic Branczyk]], founder of [[Polar Signals]], and since Loki was being marketed as "Like Prometheus, but for logs", they decided that the premise for LogQL was "Like PromQL, but for logs".
## Features of LogQL
### Enables "Schema at query"
One of the defining charateristics of Loki is that it does very well with unstructured logs and does not require a strict schema up front. Instead of maintaining a large index, LogQL lets users create a "schema at query" in that the logs are parsed and a schema or structure is inferred at the time of querying, rather than when the log line was [[Ingesting logs into Loki|ingested]].
LogQL accomplishes this by requiring users to start every query with a *log stream selector*: `{job="nginx", status="500"}` that contains labels that Loki can use to filter out data. A unique combination of labels is called a *stream*.
The advantages of the "Schema at query" approach are:
- *Flexibility* in terms of what can be sent to Loki. No strict structure is necessary. Loki can also adapt to new log formats easily, with only the LogQL queries needing to be changed.
- *Performance* on ingestion: Loki doesn't need to spend time creating an index from logs when it receives them.
However, this approach also has some disadvantages:
- *Performance* on read: dynamic queries cost more to run in the absence of a large index.
- *Complexity* of LogQL since it has to define the schema at the beginning of the query
### Pipe-based
LogQL uses the pipe character (`|`) similarly to [[Bash]]: the output of the query to the left of the pipe is used as input for the query to the right of the pipe. In this way, LogQL queries are progressively narrowed down.
LogQL is always executed from the left to the right.
### Scalar vector support
LogQL can create [[Scalar]] [[Vector|Vectors]] out of logs: it can take a string and turn it into a collection of time-series data points that are numbers. LogQL supports metric queries that can then be used for [[Alerting]] or [[Data Visualization|Visualization]].
### Filtering and parsing
LogQL supports both filtering (searching lines and labels for a specific string) and parsing (interpreting the line based on a given format and returning elements based on that).
### Results formatting
LogQL can also reformat how the results are displayed, using either `label_format()` or `line_format()`.
### Go templating language
LogQL supports the [[Go templating language]] in queries, particularly for `label_format()` and `line_format()`.
## [[Structure of LogQL]]
## Execution
LogQL queries can be executed in two places:
- On [[Grafana]]: Most people will execute log queries here.
- On [[LogCLI]]: Used for getting stats on queries or running them against a Loki instance without needing Grafana to be installed
- By using the [[Loki API]]: You can sent [[HTTP]] requests to Loki via endpoints
Of these, executing queries in Grafana is what I'd recommend for ease and simplicity.
## Types of queries
### Data type
There are two types of LogQL queries according to the data type they return:
- [[Log queries in Loki]]
- [[Metric queries in Loki]]
Log queries are queries whose output remains strings, structured or otherwise. They use the log stream selector and log pipeline construction and can be chained together to create longer log queries.
Metric queries return results that are numbers or vectors of numbers.
### Evaluation type
You can also differentiate between LogQL queries based on their evaluation type. All LogQL queries can be run as:
- an [[Instant queries in LogQL|instant query]]: evaluated at a single point in time
- a [[Range queries in LogQL|range query]]: evaluated across a time range
Both log and metric queries can be evaluated as instant or range queries.
### Intersection of data and evaluation type queries
The log/metric and range/instant types can be mixed and matched, and they show slightly different things.
- *log + instant*: "Show me the last log"
- *log + range*: "Show me logs over time"
- *metric + instant*: "Show me the current error rate"
- *metric + range*: "Graph error rate over time"
## [[Recommended practices for using LogQL]]
## Comparison to other query languages
- [[Elasticsearch]] [[Elasticsearch Query DSL|Query DSL]]: Elasticsearch can do full text searches, which you can't do in LogQL.
- [[Splunk]] [[Splunk Search Processing Language (SPL)|Search Processing Language (SPL)]]: Also pipe-based, arguably better for custom processing
Here's a comparison table, generated by AI. ==Needs to be verified.==
![[logql-comparison-table.png]]
## Related
- [[Grafana Loki Query Best Practices with LogQL - Loki Community Call December 2024]]
- [[GOH 27 - Grafana Loki design basics with Ed Welch]]
- New [[Loki Query Engine]]
%%
### [My learning session at Dev Advocacy Weekly about LogQL](https://youtu.be/u5JANb13ZVA)
<iframe width="560" height="315" src="https://www.youtube.com/embed/u5JANb13ZVA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
00:00:00 Introduction and marketing
00:01:28 Features of LogQL
00:05:20 Querying demo on Grafana Play
00:09:20 Query expressions: 1. Filter expressions
00:11:10 Q: What does it mean when we say a query is "expensive?"
00:12:23 Q: What's the difference between searching on labels in the log stream selector and filter expressions?
00:14:36 Query expressions: 2. Parser expressions
00:16:05 Query expressions: 3. Format expressions
00:17:11 Metric queries
00:23:37 Recommended practices for LogQL
00:26:43 Discarding results that match a filter
00:27:21 Testing LogQL queries
%%
[^ward]: Bekker, W. Query retrieved from [this Grafana Play dashboard](https://play.grafana.org/d/T512JVH7z/loki-nginx-service-mesh-json-version?orgId=1&from=now-6h&to=now&timezone=utc&var-datasource=ac4000ca-1959-45f5-aa45-2bd0898f7026&var-label_name=filename&var-label_value=/var/log/nginx/json_access.log&var-job=$__all&var-instance=$__all)
[^docs]: Grafana Labs. Unwrap examples. Retrieved from https://grafana.com/docs/loki/latest/query/query_examples/#unwrap-examples
[^nvdh]: van der Hoeven, N. (2025). *How to query Grafana Loki with LogQL*. Retrieved from https://youtu.be/57dQwcmqkpQ. ([[How to query Grafana Loki with LogQL|Video working note]])
%%
# Excalidraw Data
## Text Elements
## Embedded Files
0339e811a5e008a0f18086287a56fc9cf97a6d19: [[logql-logqueryquicksheet.svg]]
## Drawing
```compressed-json
N4KAkARALgngDgUwgLgAQQQDwMYEMA2AlgCYBOuA7hADTgQBuCpAzoQPYB2KqATLZMzYBXUtiRoIACyhQ4zZAHoFAc0JRJQgEYA6bGwC2CgF7N6hbEcK4OCtptbErHALRY8RMpWdx8Q1TdIEfARcZgRmBShcZQUebQBGOIAWGjoghH0EDihmbgBtcDBQMBKIEm4IAGkOAEEjGABOAAkAcVSSyFhECsJ9aKR+UsxuHgAOJO0AdlHphoA2JIXE+MnB
yBhuZwBmeIbtAAYtpK39/fj9gFZR+PGttYgKEnVuJIb47TnRnl2Gw7PFi73SQIQjKaTcOYXC7aC6TOY8SFbSZbC5jOb3azKYLcd4XeGLGanaaLfZJQGFARQUhsADWCAAwmx8GxSBUqdZmHBcIFsu1SppcNgacpqUIOMRGczWRJ2RxOdyslA+ZAAGaEfD4ADKsGxEkkgo0gWVEGYVNpCAA6k9JDj7qbqXTtTBdehBB5jaKwRxwrk0PF7mwudg1Bs/
ad7qLxd7mL7UBwhBq7QgEMRuDNjg17owWOwuH6oVmmKxOAA5ThiHGjT5QrYNSZ8CkQIRwYi4KApnHIo4NBonJL7BrkjplZgAEXS7dTaBVBDC9xFwjgAEliLG8gBde6aYTigCiwUy2TXm8bRA4NO48cTp7YQo709nCHuauCK4qh1rCGu8VwFwQp1GXB9hVG59irMZJl/OYVWwBpsBVOtcDmYhdmNZh3HEVACg6MB/QpXCKRPYdCHFLAKiA40VXITI
3zQK98DtKIoCEWMIEQcUSOUY1sGpOBLwTfBCgAX3AIiIFwOA4G1NtMOKTpgUyCpW1IC9BgYQgEAoAAhQVhUjCUmRZCoAGIVTM8y+QgbARB5KAl3bfRtQdBlDOldBjPiBBPM8yzrNIWz7IyHShQXMUDKlNlyDlLlbN8mzFUC/QADF1S1HVMJNJlyjUvyAocpzzStYhnjQBtSlyhL8rNR10oqN1ssKKz4uyRKACVhC9H1bUaiqWocgB5IMQxxcMeua
uyHKSzgoCS3B9HVUNUCSHLxsSqbsk1QgjEwnh9hW/zKoyAAVLAoBqIhlDzdBghVJV9ryjJpNIM7/LYChgVwKc4wE+7Dv0XdxRqV73pCL7xOBuKDr6jIgepCgjvgDL9Ms9DqQ1AANTY5i2bQjjmSZJjOSFJgueY8NKVGmXwABNEZUW0UZflJ0YjguXYyTKyAjDYAxuDkyB6AIIRMPeBFRguAdhN+6H9HasLo1Y5G1JFEhNu2kY9salXiG1BA+LQId
IG1gBZNhiAQAHcE0YIvpnfA5y10gSElIy0H5iAtKZMHSGUAUAApvlWXgVmoYOg/2GEAEpjVahBlATbkKh9/2eBOUPU723g09QCOLmjqWxqhqACrpQaoFzWN6LUqi5oQWPSKdjguLdxssitm3uCpYX7mwIh9dQLun0bDha870hu8bYQoDPTDB4L0o7AAKwQbAck1Ee4FN83Let+9UDth3SkFcvGCOnn8D5xsugysJglX3NuJYqADAR7o6J+m871tx
9n2pRz0nvpwbgB8h7DnwKEM699T7n34hqYS4AhL8AgC+cIfMRJCSAA==
```
%%