---
title: Lens Config Builder API - Gauge
description: Lens Config Builder API - Gauge
url: https://docs-v3-preview.elastic.dev/elastic/kibana/tree/main/extend/key-concepts/ui/lens-config-api/lens-config-builder-api-gauge
products:
  - Kibana
---

# Lens Config Builder API - Gauge
Understanding `LensGaugeConfig` in detail

## Required Properties


### `chartType`

- **Type:** Fixed value `'gauge'`
- **Description:** Sets the chart type to gauge.


### `title`

- **Type:** `string`
- **Description:** The title of the visualization.


### `dataset`

The `dataset` configuration within the Lens Config Builder API defines the source of data for a visualization.

#### Types of Dataset Configurations

1. **LensESQLDataset (`LensESQLDataset`):**

- Utilizes the Elasticsearch Query Language (ES|QL) for retrieving data.
- Attributes include:
- `esql`: A string containing the ES|QL query. ES|QL is a powerful query language that allows for complex search and aggregation operations, making this dataset type particularly flexible and powerful for advanced data retrieval scenarios.

1. **LensDatatableDataset (`LensDatatableDataset`):**

- Represents data in a tabular format, suitable for direct visualization or further processing.
- This dataset type is typically used when data is already aggregated or processed and just needs to be displayed.

1. **LensDataviewDataset (`LensDataviewDataset`):**

- Targets data within a specific Elasticsearch index or data view.
- Attributes include:
- `index`: The ID of the data view or the name of the Elasticsearch index pattern.
- `timeFieldName` (optional): The name of the field used for time-based operations, providing context for time range queries and aggregations.


### `value`

- **Type:** `LensLayerQuery`
- **Description:** Specifies the field or formula used to determine the main value displayed by the gauge. This is critical for representing the core metric around which the gauge visualization is centered.


## Optional Properties


### `label`

- **Type:** `string`
- **Description:** Offers a descriptive label for the gauge's main value, providing additional context and helping to clarify what the gauge measures.


### `queryMinValue`

- **Type:** `LensLayerQuery`
- **Description:** Defines a query for calculating the minimum value of the gauge's scale. This is particularly useful for gauges that measure a metric's performance against predefined ranges.


### `queryMaxValue`

- **Type:** `LensLayerQuery`
- **Description:** Determines a query for establishing the maximum value of the gauge's scale, setting the upper boundary for what the gauge can display.


### `queryGoalValue`

- **Type:** `LensLayerQuery`
- **Description:** Allows specifying a goal or target value for the gauge, enabling users to visually assess how the current value compares to a set objective.


### `shape`

- **Type:** `'arc' | 'circle' | 'horizontalBullet' | 'verticalBullet'`
- **Description:** Controls the appearance of the gauge by defining its shape. Each shape can convey the data differently, offering various stylistic and functional approaches to data presentation.


### `breakdown`

The `breakdown` configuration within the Lens Config Builder API allows developers to define how data should be segmented or aggregated in their visualizations.

#### Types of Breakdown Configurations

The `breakdown` configuration in case of using ES|QL or Datatable as a datasource just takes in the field name to use as a breakdown.
When using index as a datasource, breakdown can still be a field name, in which case lens will try to choose the most appropriate option, or it could be one of the following:
1. **Top Values (`LensBreakdownTopValuesConfig`):**

- Breaks down data based on the top occurring values for a specified field.
- Attributes include `field` (the field to break down by) and `size` (the number of top values to display).
- Ideal for pie charts, tag clouds, or any visualization where highlighting the most common or significant categories is beneficial.

1. **Date Histogram (`LensBreakdownDateHistogramConfig`):**

- Segments data over time using a specified date field.
- Attributes include `field` (the date field for the histogram), and `minimumInterval` (the smallest interval to use, e.g., `1M` for monthly).
- Useful for time series data, showing trends over time in line charts, area charts, etc.

1. **Intervals (`LensBreakdownIntervalsConfig`):**

- Divides data into intervals based on a numeric field.
- Attributes include `field` (the numeric field to create intervals from) and `granularity` (the interval size).
- Applicable for histograms or any visualization that benefits from numeric range segmentation.

1. **Filters (`LensBreakdownFiltersConfig`):**

- Allows for custom segmentation of data based on a collection of Elasticsearch filters.
- Attributes include an array of `filters`, each with a `label` (optional) and a `filter` string defining the filter query.
- Offers maximum flexibility in data segmentation, suitable for creating comparative visualizations across custom-defined segments.


## Example

```
const gaugeConfig: LensConfig = {
  chartType: 'gauge',
  title: 'CPU Utilization',
  dataset: {
    esql: 'from myindex | stats avgCpuUtilization = avg(cpu_utilization) | eval max=100 ',
  },
  value: 'avgCpuUtilization',
  label: 'Average CPU Utilization',
  queryMaxValue: 'max',
  shape: 'arc',
};
const configBuilder = new LensConfigBuilder(dataViewsAPI, lensFormulaAPI);
const lensConfig = configBuilder.build(gaugeConfig, { 
  timeRange: { from: 'now-1h', to: 'now', type: 'relative' },
  embeddable: true,
});
```

This example demonstrates how to create a gauge visualization using the `LensGaugeConfig`. It sets up a gauge to display the average CPU utilization.