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

# Filter by storage entities

> Filters items based on whether a corresponding entity exists in storage. Can optionally save new entities to storage for tracking.

export const FormField = ({property, label, required = false, diType, uiPatterns, children}) => {
  const patterns = Array.isArray(uiPatterns) ? uiPatterns : uiPatterns ? [uiPatterns] : [];
  return <div style={{
    margin: '1.5rem 0'
  }}>
      <div style={{
    display: 'flex',
    alignItems: 'baseline',
    flexWrap: 'wrap',
    gap: '0.5rem',
    marginBottom: '0.25rem'
  }}>
        <strong>{label}</strong>
        <span style={{
    fontSize: '0.7rem',
    fontWeight: 600,
    textTransform: 'uppercase',
    letterSpacing: '0.04em',
    color: required ? '#6241f5' : '#6b7280'
  }}>
          {required ? 'Required' : 'Optional'}
        </span>
      </div>

      <div>{children}</div>

      {diType || patterns.length > 0 ? <p style={{
    fontSize: '0.85rem',
    color: '#6b7280',
    marginBottom: 0
  }}>
          {diType ? <>
              See the <a href={`/references/${diType}`}>{diType}</a> reference.{' '}
            </> : null}
          {patterns.length > 0 ? <>
              Accepts a <a href={`/documentation/placeholders-and-patterns/patterns#${patterns[0]}`}>pattern</a>.
            </> : null}
        </p> : null}
    </div>;
};

Compares each incoming item against a storage you choose, using an identifier you provide. It looks the item up in storage and then decides, based on a condition, whether to let the item through or drop it. By default the condition keeps only items that are **not yet** in storage, which makes this a simple way to skip records you have already seen and process only new ones. When an item is kept it can optionally be saved into storage at the same time, so the next run knows it has been handled.

Use this to avoid processing the same record twice, for example to import only the orders or products you have not imported before.

This documentation describes: [Schema](/schemas/filter/storage-entity-filter)

## Fields

<FormField property="storage" label="Storage" required diType="storage">
  The storage used to look items up and, optionally, to save new ones into. You pick a storage you have already set up.
</FormField>

<FormField property="storageKey" label="Storage entity identifier" required>
  The key used to find each item in storage. This usually comes from the item itself, so you can use `&{}` placeholders to build it from the data, for example `&{order_id}`. See [Placeholders](/references/placeholders).
</FormField>

<FormField property="condition" label="Condition" required diType="storage-condition">
  The rule that decides, after the lookup, whether an item passes the filter. Defaults to keeping items that do not already exist in storage. Other rules let you match the stored entity exactly, or only on certain fields.
</FormField>

<FormField property="store.addEntityToStorage" label="Save entity to storage">
  When on (the default), an item that passes the filter is automatically saved into storage under its identifier, so it will be recognised on later runs. Turn this off if you only want to read from storage without recording anything.
</FormField>

## Sample data

This filter answers yes or no for each item, so there is no before and after. It relies on a configured storage, which cannot be exercised from a standalone example, so the illustration below is based on the feature's behaviour rather than a recorded run.

With the default condition (keep items that do not already exist) and a storage that already contains an entry for order `10041`:

| Field                     | Value                                                 |
| ------------------------- | ----------------------------------------------------- |
| Storage entity identifier | `&{order_id}`                                         |
| Condition                 | keep items that do not exist in storage (the default) |
| Save entity to storage    | on                                                    |

| Incoming item                                       | Result                                                 |
| --------------------------------------------------- | ------------------------------------------------------ |
| `{ "order_id": "10041", "customer": "Jane Doe" }`   | does not match (already in storage, so it is dropped)  |
| `{ "order_id": "10042", "customer": "John Smith" }` | matches (new, so it passes and is saved for next time) |

```json Configuration theme={null}
{
  "prototype": "storage-entity-filter",
  "parameters": {
    "storage": "your-storage",
    "storageKey": "&{order_id}",
    "condition": { "prototype": "storage-entity-exists" },
    "store": { "addEntityToStorage": true }
  }
}
```