# Datasets

Datasets provide lookup data from the KASKO Data Service. They enable autocomplete inputs, field mapping, and dynamic data integration.

## How Datasets Work

1. A field is configured with the `in_dataset:DATASET_ID` validation rule
2. The user selects/enters a value using a dataset component
3. The selected item's ID (prefixed with `dai_`) is stored in the field
4. The framework fetches the full dataset item
5. The dataset item is exposed under the `dataset` namespace

## Dataset Item Structure

When a dataset item is loaded, it looks like this:

```typescript
{
  id: string;           // Dataset item ID (e.g., "dai_abc123...")
  dataset_id: string;   // Dataset ID (e.g., "dat_xyz789...")
  [key: string]: any;   // Arbitrary data fields from the dataset
}
```

## Dataset Components

### `form-data-input`

Typeahead/autocomplete input:

```json
{
  "type": "form-data-input",
  "config": {
    "field_name": "data.company",
    "data_field_name": "name",
    "content_key": {
      "label": "form.company.label",
      "placeholder": "form.company.placeholder"
    },
    "field_map": {
      "data.company_code": "code",
      "data.company_name": "name"
    },
    "sort": "asc",
    "wait_ms": 300,
    "min_length": 2,
    "clear_fields_on_change": ["data.company_code"]
  }
}
```

| Config                   | Description                                                 |
| ------------------------ | ----------------------------------------------------------- |
| `field_name`             | Field that stores the dataset item ID                       |
| `data_field_name`        | Dataset field used for search/display                       |
| `field_map`              | Maps form fields to dataset fields (auto-fill on selection) |
| `filter_by`              | Filter dataset results by criteria                          |
| `sort`                   | Sort results: `"asc"` or `"desc"`                           |
| `wait_ms`                | Debounce time in milliseconds                               |
| `min_length`             | Minimum characters before search triggers                   |
| `clear_fields_on_change` | Fields to clear when selection changes                      |

### `form-data-lookup`

Dropdown lookup:

```json
{
  "type": "form-data-lookup",
  "config": {
    "field_name": "data.location",
    "data_field_name": "city",
    "source_field_name": "region",
    "content_key": {
      "placeholder": "form.location.placeholder"
    }
  }
}
```

### `dataset-map`

Invisible mapper that fills additional fields when a dataset item loads:

```json
{
  "type": "dataset-map",
  "config": {
    "field_name": "data.company",
    "field_map": {
      "data.company_address": "address",
      "data.company_phone": "phone"
    }
  }
}
```

## Validation

Fields using datasets must include the `in_dataset` rule:

```json
{
  "name": "company",
  "path": "data",
  "validation": "required|string|in_dataset:dat_XXXXXXXXXXXXXXXXXXXX"
}
```

* First argument is the dataset ID (starts with `dat_`)
* Backend validates the value exists in the dataset
* Frontend ignores validation for `in_dataset`, but dataset lookup still requires it

## Accessing Datasets in JsonLogic

Dataset items are available under the `dataset` namespace:

```json
{ "var": "dataset.data.company" }
```

Access fields:

```json
{ "var": "dataset.data.company.name" }
{ "var": "dataset.data.company.code" }
{ "var": "dataset.data.company.address.city" }
```

## Accessing Datasets in Content

Use dataset tokens in translations:

```
"Company: {dataset.data.company.name}"
"Code: {dataset.data.company.code}"
"Address: {dataset.data.company.address}"
```

## Repeaters

Datasets work with repeater fields:

```json
{
  "name": "agents.*.location",
  "path": "data",
  "validation": "in_dataset:dat_locations"
}
```

Each repeater item has its own dataset entry:

* `dataset.data.agents.0.location`
* `dataset.data.agents.1.location`

## Filtering Results

Basic filters:

```json
{
  "filter_by": {
    "type": "fruit",
    "active": true
  }
}
```

Advanced filters:

```json
{
  "filter_by": {
    "price": {
      "type": "operator",
      "operator": ">=",
      "search": 100
    },
    "region": {
      "type": "operator",
      "operator": "IN",
      "search": ["US", "UK", "DE"]
    }
  }
}
```

## Automatic Cleanup

When a dataset field is cleared or changed:

* The old dataset item is removed from state
* Prevents stale data from accumulating

## Tips

* Use `field_map` or `dataset-map` to auto-fill related fields
* Keep `field_name` aligned with the form field path (e.g., `data.company`)
* Use `clear_fields_on_change` to reset dependent fields when selection changes


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kasko.io/kasko-frontend-documentation/core-concepts/datasets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.