Building Queries

1. Using Query Editor

Example: Basic Query Construction

SELECT
  "timestamp",
  "value"
FROM
  "metrics"
WHERE
  "instance" = 'server-01'
ORDER BY
  "timestamp" ASC

Feature	Description	Usage
Query Editor	Interface for writing and executing queries	Used to build queries for data sources
Query History	Stores previously executed queries	Accessed via the history dropdown in the query editor
Variables	Dynamic placeholders in queries	Defined using `$variable` syntax

Note: The Query Editor supports syntax highlighting and auto-completion for various query languages like SQL, PromQL, and InfluxQL.

Warning: Complex queries may impact dashboard performance. Use query caching where possible.

Key Features of Query Editor

Real-time syntax validation
Query history and favorites
Variable substitution support
Result preview with tabular view

2. Adding Multiple Queries

Example: Adding Multiple Queries in Grafana

{
  "targets": [
    {
      "refId": "A",
      "expr": "up"
    },
    {
      "refId": "B",
      "expr": "node_cpu_seconds_total"
    }
  ]
}

Property	Description	Values
refId	Unique identifier for the query	`A`, `B`, etc.
expr	Query expression (PromQL, Loki, etc.)	`up`, `node_cpu_seconds_total`

Note: Each query must have a unique refId to distinguish it in the results.

Multiple Query Use Cases

Comparing metrics from different sources
Combining data from multiple series
Applying transformations to query results

3. Setting Query Alias

Property	Description	Example
alias	Defines the alias for the query result	`"alias": "CPU Usage"`
format	Specifies the output format of the query result	`"format": "time_series"`

Example: Setting Query Alias in JSON

{
  "refId": "A",
  "alias": "CPU Usage",
  "format": "time_series"
}

4. Configuring Min Interval

Property	Value	Description
minInterval	`1s`	Minimum interval for query execution. Prevents queries from running too frequently.

Example: Setting minInterval in a query

{
  "refId": "A",
  "minInterval": "5s",
  "expr": "rate(http_requests_total[5m])"
}

Note: Setting minInterval helps prevent overwhelming the data source with too many rapid queries, which can lead to performance issues or rate limiting.

5. Setting Max Data Points

Property	Value	Description
maxDataPoints	`1000`	Maximum number of data points to return from a query

Example: Configuring maxDataPoints in a query

{
  "refId": "A",
  "maxDataPoints": 500,
  "expr": "rate(http_requests_total[5m])"
}

Note: Setting maxDataPoints helps optimize performance by limiting the number of data points returned, especially useful for long-running queries or when visualizing large datasets.

6. Using Query Variables (${variable} syntax)

Variable	Type	Description	Example
${variable}	String	Reference to a query variable in Grafana	`${job}`

Example: Using Variables in PromQL

up{job="${job}"}

Example: Variable in a Panel Query

rate(http_requests_total{job="${job}",instance="${instance}"}[5m])

Note: Variables can be defined in the dashboard's Variables section and used in queries to make dashboards dynamic.

7. Using Mixed Data Sources

Data Source	Query Type	Notes
Prometheus	`promql`	Used for time-series data queries
InfluxDB	`flux`	Used for time-series data queries with Flux language
MySQL	`SQL`	Used for relational data queries
Elasticsearch	`Lucene`	Used for log and event data queries

Example: Mixed Data Source Query

SELECT * FROM "prometheus".metrics WHERE metric_name = 'cpu_usage'

Note: When using mixed data sources, ensure that the query syntax matches the specific data source's requirements.

8. Hiding Queries

Option	Values	Notes
hide	`true` \| `false`	When set to `true`, the query is hidden from the UI in the query editor.

Example: Hiding a Query in Grafana

{
  "datasource": {
    "type": "prometheus",
    "uid": "prometheus-datasource-uid"
  },
  "hide": true,
  "refId": "A",
  "expr": "up"
}

9. Running Query Inspection

Example: Inspecting a Query in Grafana

// Example query inspection in Grafana
const query = 'SELECT * FROM logs WHERE level = \'ERROR\' AND timestamp > now() - 1h';

// In Grafana UI:
// 1. Navigate to the dashboard
// 2. Open the panel editor
// 3. Go to the "Query" tab
// 4. Enter the query in the query editor
// 5. Click "Run Query" to inspect results

// Sample result structure:
{
  "data": [
    {
      "refId": "A",
      "meta": {
        "stats": {
          "queryCount": 1,
          "duration": "250ms"
        }
      },
      "rows": [
        [1634567890000, "ERROR", "Database connection failed"],
        [1634567900000, "ERROR", "Timeout in API call"]
      ]
    }
  ]
}

Property	Description	Values
query	The SQL or PromQL query to inspect	`SELECT * FROM logs WHERE level = 'ERROR'`
refId	Reference ID for the query in the dashboard	`A`
meta.stats.queryCount	Number of queries executed	`1`
meta.stats.duration	Time taken to execute the query	`250ms`

Note: Query inspection helps identify performance bottlenecks and ensures accurate data retrieval.

Warning: Large datasets can cause slow query execution. Use LIMIT clauses to optimize performance.

Query Inspection Best Practices

Use EXPLAIN for SQL queries to understand query plans
Monitor query execution time and optimize accordingly
Limit result sets to prevent memory issues
Validate query syntax before running in production

10. Caching Query Results

Option	Values	Notes
cacheTimeout	`300`	Cache timeout in seconds (default 5 minutes)
maxDataPoints	`1000`	Maximum number of data points to cache per query
minInterval	`1m`	Minimum interval between cache refreshes

Example: Configuring Cache Timeout

{
  "cacheTimeout": 600,
  "maxDataPoints": 2000
}

Note: Caching improves performance but may cause stale data. Adjust timeout based on data freshness requirements.