dev_docs/lens/config_api.mdx
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, LensApiConfig } from '@kbn/lens-embeddable-utils';
const config: LensApiConfig = {
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 />
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.
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.The build method is the primary method used to generate a Lens configuration. It accepts a LensApiConfig 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 LensApiConfig 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:
booleanLensConfigBuilder. 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.TimeRangeTimeRange 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.Filter[]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.QueryQuery 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.