@groundcover/metricsql

A headless MetricsQL query builder library that provides a programmatic way to build, parse, and manipulate MetricsQL queries. This library is framework-agnostic and can be used with any UI framework or editor.

Installation

npm install @groundcover/metricsql
# or
yarn add @groundcover/metricsql

Usage

The library provides a programmatic way to build and manipulate MetricsQL queries:

import { Editor, QueryEditor } from '@groundcover/metricsql';

// Create a new query editor
const queryEditor = new QueryEditor();

// Build a query programmatically
const query = queryEditor
  .setMetric('http_requests_total')
  .setFilters([{ label: 'status', operator: '!~', value: '4..' }])
  .setDerivativeFunction({ functionName: 'rate', window: '5m' })
  .getQuery();

// Convert to MetricsQL string
const metricsql = queryEditor.toMetricsql();
// Result: rate(http_requests_total{status!~"4.."}[5m])

// Parse existing MetricsQL
const editor = Editor.fromMQL('sum(rate(http_requests_total[5m])) by (job)');
if (editor) {
  const state = editor.getState();
  // Manipulate the query state...
  const newMetricsql = editor.toMetricsql();
}

Features

• Parse MetricsQL queries into a structured format
• Build queries programmatically with a fluent API
• Convert between MetricsQL strings and structured query objects
• Support for all MetricsQL operations:
  • Metric selection with label filters
  • Rate and increase functions
  • Aggregation functions (sum, avg, etc.)
  • Math functions
  • Rollup functions
  • And more...

API

The library exports several main components:

• Editor: Main class for working with MetricsQL queries
• QueryEditor: Class for building individual queries
• EditorState: Type definitions for the query state
• Various utility functions for query manipulation

See the API documentation for more details.

License

MIT