doytsujin / giraffe

A foundation for visualizations in the InfluxDB UI

Giraffe

A React-based visualization library powering the data visualizations in InfluxDB 2.0 UI.

This library is currently in pre-beta

🦒 Features

There exist plenty of terrific visualization libraries in the JavaScript ecosystem. Giraffe aims to distinguish itself with several features:

• Supports Flux
• Easy reactivity and extensibility via React
• Support for mapping groupings of columns to a single visual aesthetic
• A high-level Grammar of Graphics style API that can specify a wide variety of visualizations with a few simple concepts
• A columnar interface for input data that enables efficient interop with Web Workers and Apache Arrow
• Self-contained configs in the style of Vega-Lite

Getting Started

Installation

Install Giraffe with your package manager

yarn add @influxdata/giraffe or npm install @influxdata/giraffe

Example

1. In your React code, import the Plot component and the newTable utility function

  import {Plot, newTable} from '@influxdata/giraffe'
  

2. Build the config object.
   a. Required properties:

   • table is data built using the newTable utilty function (also built from Flux results, see Flux example)
   • layers is an array of objects that describe how to render the data.

   b. Optional properties include customizations for

   • gridlines: color and opacity
   • axes: appearance, color, opacity, and scaling
   • ticks: generation, formatting and labeling, font, and color
   • legend (tooltip): labeling and styling

   For details on all configuration properties, go to the configuration guide.

   Here is an example of building the config object while skipping optional properties:

  // Example table and layer

  const table = newTable(5)
    .addColumn('_time', 'time', [1589838401244, 1589838461244, 1589838521244, 1589838581244, 1589838641244])
    .addColumn('_value', 'number', [2.58, 7.11, 4.79, 8.89, 2.23])

  const lineLayer = {
    type: "line",
    x: "_time",
    y: "_value",
  }

  const config = {
    table: table,
    layers: [lineLayer],
  }
  

3. Render your component by passing the config object as the config prop to the <Plot> component. Be sure that the parent component around <Plot> has both a height and a width measured in positive values. If either is not a positive value, the graph will not be visible.

   For example, to make a <Plot> that adjusts to screen height and width, in your React rendering code return this element:

  // return this element in your React rendering code:

  <div
    style={{
      width: "calc(70vw - 20px)",
      height: "calc(70vh - 20px)",
      margin: "40px",
    }}
  >
    <Plot config={config} />
  </div>
  

Example Using Flux

When generating the table through a Flux result:

• call the fromFlux utility function on the csv that is generated by Flux
• get the table in the returned object from calling fromFlux

Here is an example of turning a result in comma separate values (CSV) from Flux into a table and rendering it without optional properties:

  import {Plot, fromFlux} from '@influxdata/giraffe'

  // ...

  const fluxResultCSV = `#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string
#group,false,false,true,true,false,false,true,true,true,true
#default,_result,,,,,,,,,
,result,table,_start,_stop,_time,_value,_field,_measurement,example,location
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T18:31:33.95Z,29.9,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T18:55:23.863Z,28.7,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T19:50:52.357Z,15,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T19:53:37.198Z,24.8,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T19:53:53.033Z,23,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-03T20:19:21.88Z,20.1,value,temperature,index.html,browser
,,0,2020-03-25T20:58:15.731129Z,2020-04-24T20:58:15.731129Z,2020-04-10T22:20:40.776Z,28.7,value,temperature,index.html,browser
`

  const dataFromFlux = fromFlux(fluxResultCSV)

  const lineLayer = {
    type: "line",
    x: "_time",
    y: "_value",
  }

  const config = {
    table: dataFromFlux.table,
    layers: [lineLayer],
  }

  // ...

  // return this element in your React rendering code:

  <div
    style={{
      width: "calc(70vw - 20px)",
      height: "calc(70vh - 20px)",
      margin: "40px",
    }}
  >
    <Plot config={config} />
  </div>
  

Development

To contribute to Giraffe, see the contributing guide.

Looking for details on the configuration? See the configuration guide.