> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allium.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Use datasets to look up whether record fields match a managed list of values inside Beam JavaScript transforms.

A dataset is a named list of string values, such as wallet addresses, contract addresses, or token IDs, that your JavaScript transforms query with `beam.contains()`. Changes made through the [Datasets API](/beam/api-reference/datasets/list-datasets) apply to deployed pipelines **immediately**, with no redeploy.

Use a dataset when a list is large, changes often, or is shared across pipelines. For a list used by a single filter, a [set filter](/beam/api-reference/configuration) is simpler.

## Use `beam.contains()` in a transform

In a JavaScript (v8) transform, call `beam.contains()` with a dataset name and an array of values from the current record. It returns `true` if **any** value is in the dataset.

```javascript theme={null}
function transform(input) {
  if (beam.contains("DATASET_NAME", [input.field1, input.field2])) {
    return input;
  }
  return null; // drop records that don't match
}
```

| Argument | Type | Description |
| :- | :- | :- |
| `DATASET_NAME` | `string` | Name given in [Create dataset](/beam/api-reference/datasets/create-dataset). Must belong to the authenticated API key. |
| `[input.field1, input.field2]` | `string[]` | Values from the current record to check. Evaluation stops at the first match. |

<Note>
  Lookups are exact and case-sensitive: `0xAbC` and `0xabc` are different values. Store values in the same case as your records, or normalize both sides in your transform.
</Note>

### Example: keep transfers that involve a watchlisted wallet

```javascript theme={null}
function transform(input) {
  if (beam.contains("watchlist-wallets", [input.from_address, input.to_address])) {
    return input;
  }
  return null;
}
```

### Example: tag records sent to a known contract

```javascript theme={null}
function transform(input) {
  if (beam.contains("known-defi-contracts", [input.to_address])) {
    input.is_defi = true;
  }
  return input;
}
```

## Typical workflow

<Steps>
  <Step title="Create the dataset">
    Call [Create dataset](/beam/api-reference/datasets/create-dataset) with a unique name. The response includes the `id` used by ID-based endpoints.
  </Step>

  <Step title="Populate it">
    Load values with [Add entries](/beam/api-reference/datasets/add-entries) or [Add entries by name](/beam/api-reference/datasets/add-entries-by-name). Each request accepts up to 250,000 values. Split larger uploads into chunks and send at most 5 requests concurrently.
  </Step>

  <Step title="Reference it from a transform">
    Call `beam.contains("DATASET_NAME", [...])` in a JavaScript transform, then [deploy](/beam/api-reference/deployment/deploy) the pipeline.
  </Step>

  <Step title="Update membership live">
    Add or remove values with [Add entries](/beam/api-reference/datasets/add-entries) and [Remove entries](/beam/api-reference/datasets/remove-entries) at any time. Running pipelines see changes immediately, with no redeploy.
  </Step>
</Steps>

## Endpoints

<CardGroup cols={2}>
  <Card title="Create dataset" icon="plus" href="/beam/api-reference/datasets/create-dataset">
    Create a dataset.
  </Card>

  <Card title="List datasets" icon="list" href="/beam/api-reference/datasets/list-datasets">
    List your datasets.
  </Card>

  <Card title="Delete dataset" icon="trash" href="/beam/api-reference/datasets/delete-dataset">
    Delete a dataset and all of its entries.
  </Card>

  <Card title="Add entries" icon="upload" href="/beam/api-reference/datasets/add-entries">
    Add values to a dataset by ID.
  </Card>

  <Card title="Add entries by name" icon="upload" href="/beam/api-reference/datasets/add-entries-by-name">
    Add values to a dataset by name.
  </Card>

  <Card title="List entries" icon="table-list" href="/beam/api-reference/datasets/list-entries">
    Paginate through a dataset's values.
  </Card>

  <Card title="Remove entries" icon="minus" href="/beam/api-reference/datasets/remove-entries">
    Remove specific values from a dataset.
  </Card>

  <Card title="Check entry" icon="magnifying-glass" href="/beam/api-reference/datasets/check-entry">
    Check whether a value exists in a dataset.
  </Card>
</CardGroup>

## Datasets vs. filter values

Both provide fast membership lookups. They differ in where you use them:

| | **Datasets** | **Filter values** |
| :- | :- | :- |
| Used in | JavaScript transforms, via `beam.contains()` | Set filter transforms |
| Scope | Shared across pipelines and transforms | One set filter transform |
| Lookup | Several record fields against one list | One record field against the set |
| Best for | Shared allowlists and denylists, enrichment logic | Keeping records whose field matches a list |

See [Filter values](/beam/api-reference/filter-values/list-filter-values) for set filters.