or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-transformations.mddataframe-operations.mddatetime-operations.mdevent-system.mdfield-processing.mdindex.mdplugin-system.mdtheme-system.mdutility-functions.mdvalue-formatting.md
tile.json

tessl/npm-grafana--data

Core data manipulation and type system library for Grafana, providing DataFrame operations, field processing, transformations, and visualization utilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@grafana/data@12.1.x

To install, run

npx @tessl/cli install tessl/npm-grafana--data@12.1.0

index.mddocs/

Grafana Data Library

Grafana Data Library is the core data manipulation and type system library for Grafana, providing comprehensive functionality for working with time series data, data frames, field types, transformations, and visualization utilities. It enables developers to build data visualization applications, monitoring dashboards, and analytics tools with structured data processing capabilities.

Package Information

  • Package Name: @grafana/data
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @grafana/data

Core Imports

import { 
  DataFrame, 
  Field, 
  FieldType,
  createDataFrame,
  MutableDataFrame,
  dateTime,
  getValueFormat
} from "@grafana/data";

For CommonJS:

const { 
  DataFrame, 
  Field, 
  FieldType,
  createDataFrame,
  MutableDataFrame,
  dateTime,
  getValueFormat
} = require("@grafana/data");

Basic Usage

import { 
  createDataFrame, 
  FieldType, 
  dateTime, 
  getValueFormat 
} from "@grafana/data";

// Create a DataFrame with time series data
const frame = createDataFrame({
  name: "Temperature Data",
  fields: [
    {
      name: "time",
      type: FieldType.time,
      values: [
        dateTime('2023-01-01T00:00:00Z').valueOf(),
        dateTime('2023-01-01T01:00:00Z').valueOf(),
        dateTime('2023-01-01T02:00:00Z').valueOf(),
      ]
    },
    {
      name: "temperature",
      type: FieldType.number,
      values: [20.5, 21.2, 19.8],
      config: {
        unit: "celsius"
      }
    }
  ]
});

// Format values for display
const formatter = getValueFormat("celsius");
const formatted = formatter(21.2, 1);
console.log(formatted.text); // "21.2°C"

// Process the data
console.log(`DataFrame has ${frame.length} rows and ${frame.fields.length} fields`);

Architecture

Grafana Data Library is built around several key components:

  • DataFrame System: Core data structure (DataFrame, Field) with type-safe operations for tabular data
  • Field Processing: Comprehensive field configuration, display processing, and override system
  • Type System: Rich type definitions covering all data visualization concepts and plugin architectures
  • DateTime Handling: Timezone-aware date/time operations with moment.js compatibility
  • Transformation Pipeline: Pluggable data transformation system with built-in transformers
  • Value Formatting: Extensive value formatting system with units, localization, and custom formatters
  • Theme System: Complete theming infrastructure for colors, typography, spacing, and visualization
  • Event System: Type-safe event bus for application-wide communication
  • Plugin Context: Context system for panel plugins, data source plugins, and app plugins

Capabilities

DataFrame Operations

Core data structure operations including creation, manipulation, transformation, and serialization of tabular data with full type safety.

interface DataFrame {
  name?: string;
  fields: Field[];
  length: number;
  refId?: string;
  meta?: QueryResultMeta;
}

function createDataFrame(data: PartialDataFrame): DataFrame;

DataFrame Operations

Field Processing

Field configuration, display processing, color management, thresholds, and override system for customizing field appearance and behavior.

interface Field<T = any, V = Vector<T>> {
  name: string;
  type: FieldType;
  config: FieldConfig<T>;
  values: V;
  labels?: Labels;
  state?: FieldState;
}

function getFieldDisplayValues(options: GetFieldDisplayValuesOptions): FieldDisplay[];
function applyFieldOverrides(options: ApplyFieldOverrideOptions): DataFrame[];

Field Processing

DateTime Operations

Comprehensive date and time handling with timezone support, formatting, parsing, and duration calculations.

function dateTime(input?: DateTimeInput, formatInput?: FormatInput, zone?: TimeZone): DateTime;
function dateTimeFormat(dateTime: DateTime, options?: DateTimeOptionsWithFormat): string;
function parseDuration(duration: string): number;

DateTime Operations

Data Transformations

Pluggable transformation system for filtering, aggregating, joining, and modifying data frames with built-in transformers and custom transformation support.

function transformDataFrame(options: DataTransformContext): Observable<DataFrame[]>;
function fieldReducers.get(id: ReducerID): FieldReducerInfo;
function reduceField(field: Field, id: ReducerID, nullValueMode?: NullValueMode): ReduceDataOptions;

Data Transformations

Value Formatting

Extensive value formatting system supporting units, localization, custom formatters, and display processing.

function getValueFormat(id: string): ValueFormatter;
function formattedValueToString(value: FormattedValue): string;

interface FormattedValue {
  text: string;
  numeric: number;
  prefix?: string;
  suffix?: string;
}

Value Formatting

Theme System

Complete theming infrastructure including colors, typography, spacing, shadows, and visualization-specific color schemes.

function createTheme(options?: NewThemeOptions): GrafanaTheme2;
function getThemeById(id: string): GrafanaTheme2;

interface GrafanaTheme2 {
  colors: ThemeColors;
  typography: ThemeTypography;
  spacing: ThemeSpacing;
  shadows: ThemeShadows;
  shape: ThemeShape;
  visualization: ThemeVisualizationColors;
}

Theme System

Event System

Type-safe event bus system for application-wide communication with built-in events and custom event support.

class EventBusSrv implements EventBus {
  publish<T extends BusEvent>(event: T): void;
  subscribe<T extends BusEvent>(typeInfo: BusEventType<T>, handler: BusEventHandler<T>): Unsubscribable;
}

function eventFactory<TPayload = undefined>(name: string): BusEventType<BusEventWithPayload<TPayload>>;

Event System

Plugin System

Comprehensive plugin architecture supporting panel plugins, data source plugins, and app plugins with configuration, context, and extension systems.

class PanelPlugin<TOptions = any, TFieldOptions = any> extends GrafanaPlugin<PanelPluginMeta> {
  setFieldConfigOptions(builder: FieldConfigEditorBuilder<TFieldOptions>): this;
  setPanelOptions(builder: PanelOptionsEditorBuilder<TOptions>): this;
}

class DataSourcePlugin<TOptions extends DataSourceJsonData = DataSourceJsonData, TQuery extends DataQuery = DataQuery> extends GrafanaPlugin<DataSourcePluginMeta<TOptions>> {
  components: DataSourcePluginComponents<TOptions, TQuery>;
}

Plugin System

Table Operations

Time series table manipulation functions for amending and trimming table data structures.

type Table = [times: number[], ...values: any[][]];

function amendTable(prevTable: Table, nextTable: Table): Table;
function trimTable(table: Table, fromTime: number, toTime: number): Table;

Utility Functions

Collection of utility functions for data processing, URL handling, CSV operations, label processing, and various data manipulation tasks.

function anyToNumber(value: any): number;  
function parseLabels(labels: string): Labels;
function readCSV(text: string, options?: CSVOptions): DataFrame[];
function objRemoveUndefined<T>(obj: T): T;

Utility Functions