DDQB — DataDog Query Builder

DDQB is a Go library for constructing and parsing DataDog metric queries with a chainable API and type safety.

• 🧱 Chainable builder for metrics, filters, functions, rollups, and groups
• 🔍 Parse existing queries and modify them programmatically
• 🧪 Type-safe composition without string concatenation
• 🧭 Clear primitives for constructing complex queries

Quick links

• Examples → examples.md
• API Reference → api.md (generated by CI)

Install

go get github.com/jonwinton/ddqb

Minimal example

import (
  "fmt"
  "github.com/jonwinton/ddqb"
)

func main() {
  q, err := ddqb.Metric().
    Metric("system.cpu.idle").
    Build()
  if err != nil { panic(err) }
  fmt.Println(q)
}

Common patterns

Aggregation + window

q, _ := ddqb.Metric().
  Aggregator("avg").
  TimeWindow("5m").
  Metric("system.cpu.idle").
  Build()

Filters, groups, functions

q, _ := ddqb.Metric().
  Metric("system.cpu.idle").
  Filter(ddqb.Filter("host").Equal("web-1")).
  Filter(ddqb.Filter("env").Equal("prod")).
  GroupBy("host").
  ApplyFunction(ddqb.Function("rollup").WithArgs("60", "sum")).
  Build()

Parse and modify an existing query

import (
  "fmt"
  "github.com/jonwinton/ddqb"
)

func main() {
  b, err := ddqb.FromQuery("avg(5m):system.cpu.idle{host:web-1}")
  if err != nil { panic(err) }
  q, err := b.
    TimeWindow("10m").
    Filter(ddqb.Filter("env").Equal("prod")).
    Build()
  if err != nil { panic(err) }
  fmt.Println(q)
}