mirror of
https://github.com/elastic/kibana.git
synced 2025-04-25 02:09:32 -04:00
10e34e4723
## Summary For ES|QL charts the formula api should be redundant. This is going to make the api lighter as there is no need to import the lens plugin if you want to use the builder to create ES|QL charts.
82 lines
4.7 KiB
Text
82 lines
4.7 KiB
Text
---
|
|
id: kibDevLensConfigAPI
|
|
slug: /kibana-dev-docs/lens/config-builder
|
|
title: Lens Config Builder API Documentation
|
|
description: Lens Config Builder API Documentation
|
|
date: 2024-03-04
|
|
tags: ['kibana', 'dev', 'lens', 'introduction']
|
|
---
|
|
|
|
## Introduction
|
|
|
|
The Lens Config Builder API provides a streamlined and flexible interface for developers to construct and integrate Lens configurations within their applications. Lens, as a powerful visualization tool in Kibana, enables users to create, visualize, and analyze data in diverse and complex ways. This API aims to simplify the process of generating these visualizations programmatically, allowing for dynamic and customizable integration points with Lens. By abstracting the complexities of Lens configuration details, developers can focus on delivering rich data visualization experiences tailored to their application's needs.
|
|
|
|
```
|
|
import LensConfigBuilder, LensConfig from '@kbn/lens-embeddable-utils/config_builder';
|
|
|
|
const config: LensConfig = {
|
|
chartType: 'metric',
|
|
title: 'my metric chart',
|
|
dataset: { esql: 'from my_index | stats sum=sum(my_field)'}
|
|
value: 'sum'
|
|
}
|
|
|
|
const configBuilder = new LensConfigBuilder(dataViewsAPI, lensFormulaAPI);
|
|
const lensConfig = configBuilder(config, {
|
|
timeRange: { from: 'now-30d', to: 'now', type: 'relative' },
|
|
embeddable: true,
|
|
}
|
|
|
|
<LensEmbeddable ...lensConfig />
|
|
|
|
```
|
|
|
|
## Main Interface
|
|
|
|
### LensConfigBuilder
|
|
|
|
The `LensConfigBuilder` class is the central interface of the API, facilitating the creation of various Lens chart types through a unified and simplified process. It leverages predefined chart configurations and integrates seamlessly with essential Kibana services, such as formula calculations and data view management, to produce either Lens attributes or embeddable inputs based on the developer's requirements.
|
|
|
|
#### Constructor
|
|
|
|
The constructor requires two parameters:
|
|
|
|
- `dataViewsAPI`: An instance of `DataViewsPublicPluginStart`, enabling the builder to access and manage data views within Kibana.
|
|
- `formulaAPI`: An instance of `FormulaPublicApi`, allowing the builder to perform formula calculations necessary for certain visualizations. You can omit this if you want to create an ES|QL visualization.
|
|
|
|
#### build Method
|
|
|
|
The `build` method is the primary method used to generate a Lens configuration. It accepts a `LensConfig` object, detailing the type of chart and its options, and an optional `LensConfigOptions` object for additional configuration options like filters, queries, and time ranges.
|
|
|
|
**Parameters:**
|
|
|
|
- `config`: A `LensConfig` object specifying the chart type and its configuration.
|
|
- `options` (optional): A `LensConfigOptions` object providing additional settings such as embeddable options, time range overrides, filters, and queries.
|
|
|
|
**Returns:** A Promise resolving to either `LensAttributes` or `LensEmbeddableInput`, depending on the options provided. This allows the generated configuration to be directly used within Kibana Lens visualizations.
|
|
|
|
Here's a detailed breakdown of each property within the `LensConfigOptions`:
|
|
|
|
### embeddable
|
|
|
|
- **Type:** `boolean`
|
|
- **Optional**
|
|
- **Description:** Determines the format of the output generated by the `LensConfigBuilder`. When set to `true`, the output will be in the form of `LensEmbeddableInput`, suitable for embedding directly into a Kibana dashboard as an embeddable object. If `false` or not set, the output will be `LensAttributes`, representing the configuration attributes for Lens visualizations without the embedding specifics.
|
|
|
|
### timeRange
|
|
|
|
- **Type:** `TimeRange`
|
|
- **Optional**
|
|
- **Description:** Allows for an optional override of the time range for the visualization. The `TimeRange` object includes `from` and `to` properties to specify the start and end times, and a `type` property indicating whether the range is `relative` or `absolute`. This is particularly useful for tailoring the visualization to specific time frames of interest, independent of the global time filters applied in Kibana.
|
|
|
|
### filters
|
|
|
|
- **Type:** `Filter[]`
|
|
- **Optional**
|
|
- **Description:** Provides an array of `Filter` objects that will be applied to the visualization, enabling developers to pre-define and apply specific filters to the data being visualized. This allows for the creation of more focused and relevant visualizations by pre-filtering the data based on specific criteria.
|
|
|
|
### query
|
|
|
|
- **Type:** `Query`
|
|
- **Optional**
|
|
- **Description:** Allows specifying a query to further refine the data displayed in the visualization. The `Query` object includes a `language` property (e.g., `kuery` or `lucene`) and a `query` string, which represents the actual query to be executed. This is useful for dynamically adjusting the data set based on user input or application context, providing a flexible way to interact with the data.
|