# DatAInsights Composer Data Binding

The DatAInsights Composer works with one or more datasets, and each dataset can have its own fields. This article describes how to supply the data to the component.

## Dataset Structure

Pass the data through the [`datasets`](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api/datainsightscomposerprops#datasets) property, which holds one or more [`DatasetDescriptor`](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api/datasetdescriptor) objects. Each descriptor contains:

* A unique `id` and, optionally, a `label` and a `description`.
* The names and the types of the fields of the data items, as an array of [`FieldDescriptor`](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api/fielddescriptor) objects.
* The data items in the `data` array.

> The DatAInsights Composer never sends the data items to the AI service. It sends the prompt of the user and the metadata of the datasets. When the AI picks a dataset, the component sends the `id` and the `description`, if defined, of each dataset, and the `name` and `type` of its fields. When the AI builds a visualization, the component sends the `description` of the dataset, if defined, and the `name` and `type` of its fields, together with their `label` and `description`, if defined. When the user refines a visualization, the component also sends its current configurations, which can include filter values.

### Local Data

The following example binds an in-memory array of typed sales orders to the DatAInsights Composer.

[Demo Source](https://demos.telerik.com/kendo-react-ui/datainsights-composer/strongly-typed-data/source.txt)

### Remote Data

To bind remote data, load the rows from an HTTP endpoint and pass them through the dataset's `data` array. The AI receives the prompt and the dataset metadata, not the rows.

The following example loads 100 Northwind orders from the public OData service when the user submits the first prompt. If the user stops the generation, the example cancels the request, and it reuses the loaded rows for the later prompts. Filtering and aggregation run locally after the rows arrive.

[Demo Source](https://demos.telerik.com/kendo-react-ui/datainsights-composer/load-data-on-demand/source.txt)

### Multiple Datasets

The default AI client uses dataset descriptions and fields to route prompts. When several datasets are provided without an active [`datasetId`](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api/datainsightscomposerprops#datasetid), the AI selects one and the component fires [`onDatasetResolve`](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api/datainsightscomposerprops#ondatasetresolve) with its `id`. In the handler, set `datasetId` to that value and provide the rows of the dataset. Until you do, the component stays in the `generating` state, and the user can stop it. When the dataset is active, the component sends the prompt itself. The event fires only with an AI client that implements `selectDatasetAsync`, as the default client does. Without one, set `datasetId` yourself. A follow-up can switch to another dataset; [`onConfigChange`](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api/datainsightscomposerprops#onconfigchange) reports this with `datasetSwitched: true`. Custom clients can support routing through optional selection methods.

Datasets load independently, and the component waits for the selected dataset's rows before showing its visualization. The following example demonstrates routing and on-demand loading.

[Demo Source](https://demos.telerik.com/kendo-react-ui/datainsights-composer/dataset-switching/source.txt)

## Dataset Metadata

The AI relies on the metadata of the datasets to choose and configure the visualizations, so descriptive `description` values and field names improve the results. The component sends the `description` of a dataset and the `label` and `description` of its fields to the AI service only if you define them. It also sends the `name` and `type` of the fields. All of this is part of the system prompt when it builds a visualization. The `label` of the dataset itself is not sent, and the step that picks a dataset sends only the `id` and `description` of each dataset and the `name` and `type` of its fields.

> The component inserts the dataset and field descriptions directly into the system prompt. Provide them from trusted content of your app, and do not pass text that comes from the users or from other untrusted sources.

The DatAInsights Composer also [displays the datasets and their fields](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/user-interface#datasets) to the user.

The following example demonstrates how the `label` of a dataset and the `label` of its fields appear in the chips, in the **Data Source** popup, and in the Grid and Chart text that the AI generates from the prompt. To edit the labels, use the settings above the DatAInsights Composer. If you omit a label, the UI shows the `id` of the dataset or the `name` of the field.

[Demo Source](https://demos.telerik.com/kendo-react-ui/datainsights-composer/data-source-labels/source.txt)

## Server-Side Data Processing

By default, the DatAInsights Composer filters, sorts, and limits rows locally according to each visualization's configuration. When the dataset is too large for the browser or its rows must remain on a server, use [`onDataProcess`](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api/datainsightscomposerprops#ondataprocess) to run these operations yourself.

1. Define the dataset's metadata and set `data` to `[]`. The handler does not run while `data` is `undefined`.
2. Use `dataset.id` to choose the data source and translate `state` into a backend query. For Grid and Chart, `state` contains the configuration's filter, sort descriptors, and row limit in KendoReact Data Query format. The event also provides `config` and its `componentType`.
3. Return an array of rows or a promise that resolves to one. Pass the event's `signal` to `fetch` to cancel requests when the configuration is replaced or removed.

The component calls the handler again when the configuration or dataset rows change. It shows a loading indicator while waiting and ignores results for replaced or removed configurations.

### Processing Behavior

Returned rows bypass built-in dataset processing, but Grid paging, grouping, and interactive sorting and filtering remain local. Gauge filtering and aggregation also remain local; its `state` is `undefined`, so use `config` to prepare its rows.

An empty returned array does not display the Composer's `noDataMessage` text.

Return `undefined` to use built-in processing. If the handler fails, [`onError`](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api/datainsightscomposerprops#onerror) fires with `operation: 'processData'`, and the component processes `dataset.data` locally.

### Processing Data Before Binding

Alternatively, apply a visualization's filter, sort, and row limit before passing rows to the dataset. The `applyDataOperations` helper applies the `dataset` settings of a configuration to an array of rows. A filter that exceeds the supported limits matches no rows.

When a configuration does not come from the default AI client, check it with [`validateConfig`](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api/validateconfig) before applying it.

## Suggested Links

* [Getting Started with the KendoReact DatAInsights Composer](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/get-started)
* [API Reference of the DatAInsights Composer](https://www.telerik.com/kendo-react-ui-develop/components/datainsights-composer/api)