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

# Lens Config Builder API - Table
Understanding `LensTableConfig` in detail

## Required Properties


### `chartType`

- **Type:** Fixed value `'table'`
- **Description:** Sets the chart type to table, allowing for the display of data in a tabular format. Tables are versatile for detailed data analysis, enabling the display of multiple dimensions and metrics side by side.


### `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.


## Optional Properties


### `splitBy`

- **Type:** `LensBreakdownConfig[]`
- **Optional**
- **Description:** An array of breakdown configurations to segment the data into different sections within the table. Each breakdown can create a new column or row based on the field specified, allowing for complex data organization and grouping. Check breakdown configuration details below.


### `breakdown`

- **Type:** `LensBreakdownConfig[]`
- **Optional**
- **Description:** Similar to `splitBy`, but specifically used for creating additional columns based on the breakdown of a particular field. It's useful for comparing metrics across different categories directly within the table. Check breakdown configuration details below.


### `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 tableConfig: LensConfig = {
  chartType: 'table',
  title: 'Table chart',
  dataset: {
    esql: 'from kibana_sample_data_logs | stats bytes=sum(bytes) by geo.dest, geo.src',
  },
  splitBy: [
    'geo.src'
  ],
  breakdown: [
    'geo.dest'
  ],
  value: 'bytes',
};
const configBuilder = new LensConfigBuilder(dataViewsAPI, lensFormulaAPI);
const lensConfig = configBuilder.build(tableConfig, {
  timeRange: { from: 'now-1y', to: 'now', type: 'relative' },
  embeddable: true,
});
```