Data frames

A data frame is a collection of fields, where each field corresponds to a column. Each field, in turn, consists of a collection of values and metadata, such as the data type of those values.

For example:

export interface Field<T = any, V = Vector<T>> {
  /**
   * Name of the field (column)
   */
  name: string;
  /**
   *  Field value type (string, number, and so on)
   */
  type: FieldType;
  /**
   *  Meta info about how field and how to display it
   */
  config: FieldConfig;

  /**
   * The raw field values
   * In Grafana 10, this accepts both simple arrays and the Vector interface
   * In Grafana 11, the Vector interface has been removed
   */
  values: V | T[];

  /**
   * When type === FieldType.Time, this can optionally store
   * the nanosecond-precison fractions as integers between
   * 0 and 999999.
   */
  nanos?: number[];

  labels?: Labels;

  /**
   * Cached values with appropriate display and id values
   */
  state?: FieldState | null;

  /**
   * Convert a value for display
   */
  display?: DisplayProcessor;

  /**
   * Get value data links with variables interpolated
   */
  getLinks?: (config: ValueLinkConfig) => Array<LinkModel<Field>>;
}

Available data frame types

A data frame type consists of a kind of data (for example, time series or numeric) and the data format (for example, wide).

The following data frame types are available:

• Time series
  • Wide
  • Long
  • Multi
• Numeric
  • Wide
  • Multi
  • Long
• Heatmap
  • Rows
  • Cells
• Logs
  • LogLines

Work with data frames

Refer to Data frames in the Plugins developer documentation for an overview of data frames.

For a guide to plugin development with data frames, refer to Create data frames.

Technical references

Data frames were introduced in Grafana 7.0, replacing the Time series and Table structures with a more generic data structure that can support a wider range of data types. The concept of data frame is borrowed from data analysis tools like the R programming language and Pandas. Other technical references are provided below.

Apache Arrow

The data frame structure is inspired by and uses the Apache Arrow Project. JavaScript data frames use Arrow Tables as the underlying structure, and the backend Go code serializes its frames in Arrow Tables for transmission.

JavaScript

You can find the JavaScript implementation of data frames in the /src/dataframe folder and /src/types/dataframe.ts of the @grafana/data package.

Go

For documentation on the Go implementation of data frames, refer to the Grafana SDK Go data package.