perses-query-builder

Build and validate Perses panel queries across PromQL, LogQL, and TraceQL.

415|44|Updated Mar 18, 2026
One-click install
npx skills add https://github.com/notque/claude-code-toolkit --skill perses-query-builder
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: perses-query-builder
Source: https://github.com/notque/claude-code-toolkit/tree/main/skills/perses-query-builder
Command: npx skills add https://github.com/notque/claude-code-toolkit --skill perses-query-builder

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Perses query building and optimization for Perses dashboards is error-prone; this skill provides a structured approach to craft, validate, and optimize PromQL, LogQL, and TraceQL queries for Perses panels, ensuring correctness and efficient execution.

Core Features & Use Cases

  • Build PromQL, LogQL, and TraceQL queries for Perses panel definitions with correct variable interpolation.
  • Validate syntax, suggest optimizations, and ensure datasource binding with both kind and name.
  • Use cases include creating panel queries for dashboards, debugging slow queries, and preparing queries for variable-driven dashboards.

Quick Start

Provide a ready-to-run Perses panel query by building and validating a PromQL, LogQL, or TraceQL query with proper variable interpolation and a correct datasource binding.

Frequently Asked Questions about perses-query-builder

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I build a PromQL query for a Perses dashboard panel?

To build a PromQL query for a Perses panel, you construct the query with correct variable interpolation and bind it to a datasource using both its kind and name. This ensures the query executes correctly within the dashboard environment.

Can I use LogQL and TraceQL queries in Perses panels?

Yes, you can use LogQL and TraceQL queries in Perses panels. The query builder validates syntax and optimizes execution across all three query languages, ensuring correct datasource binding and variable interpolation for each.

What is the correct way to interpolate variables in Perses panel queries?

Interpolating variables in Perses panel queries requires using Perses-specific interpolation formats. The query builder enforces these best practices, structuring variable references correctly so they resolve dynamically within your PromQL, LogQL, or TraceQL queries.

Why does my Perses panel query fail to execute correctly?

Perses panel queries often fail due to incorrect datasource binding or syntax errors in PromQL, LogQL, or TraceQL. The query builder validates syntax, flags common mistakes, and ensures the datasource is bound with both kind and name.

What's the best way to optimize slow PromQL or LogQL queries in Perses?

The best way to optimize slow PromQL or LogQL queries in Perses is to validate them for syntax correctness and apply best practices during construction. The query builder suggests optimizations and flags common mistakes to ensure efficient execution.

Do I need to specify both kind and name when binding a datasource in Perses?

Yes, you need to specify both the datasource kind and name when binding it in Perses. Correct datasource binding is enforced during query validation to ensure the panel retrieves data from the intended source accurately.