# Data Explorer presets

> Source: https://docs.clonepartner.com/reference/data-explorer-presets/

A Data Explorer preset is a server-stored team query. The record has a name, optional connector and resource scope, a definition, creator, and timestamps.

## Record shape

```json
{
  "name": "Failed records by migration job",
  "connector_id": 7,
  "resource": "migration_records",
  "definition": {
    "mode": "visual",
    "filters": [],
    "parameters": []
  }
}
```

Scope behavior:

- connector and resource set — visible for that exact Explorer context;
- connector set and resource null — visible for every resource on that connector;
- both null — global.

## Definition

```text
mode: visual | raw
action?: find | count | insert | update | delete
filters?: [{ field, operator, value, valueType? }]
rawQuery?: string
columns?: string[]
limit?: string
sort?: string
order?: asc | desc
resultView?: table | json
jsonata?: string
csvDelimiter?: string
parameters?: PresetParameter[]
```

Visual mode restores builder state. `find` is the default action. Raw mode restores connector-specific raw query text.

Presets can capture write actions. Applying a preset does not bypass the normal UI, role, or confirmation behavior for that action.

## Parameters

```json
{
  "name": "job",
  "label": "Migration job",
  "required": true,
  "type": "mongoRecord",
  "collection": "migration_jobs",
  "valueField": "_id",
  "labelField": "name",
  "descriptionFields": ["tenant_id"],
  "searchFields": ["name", "tenant_id"],
  "filter": {
    "status": "active"
  },
  "sort": {
    "updated_at": -1
  }
}
```

Parameter types:

- `string` — trimmed text;
- `objectId` — validated 24-character hexadecimal ID;
- `mongoRecord` — searchable record on the preset's MongoDB connector.

`mongoRecord.collection` is required. `valueField` defaults to `_id`; optional label, description, search, filter, and sort fields control the picker.

## Placeholders

In visual mode, place `{{name}}` in `filters[].value`. Set `valueType: objectId` when the target field stores an ObjectId.

In raw MongoDB JSON, keep the placeholder inside a JSON string:

```json
{
  "_id": {
    "$oid": "{{record}}"
  }
}
```

Raw parameter substitution is available only when the query parses as JSON. Parameterized SQL and OData raw queries are rejected.

## Validation

- `mode` must be `visual` or `raw`.
- Parameter names must be unique and match `^\w+$`.
- Names and labels cannot be empty.
- Every placeholder must have a declared parameter.
- Every declared parameter must be used.
- A `mongoRecord` must declare `collection`.
- Parameterized raw queries must be non-empty valid JSON.

## API

- `GET /api/explorer-presets?connector_id=&resource=&q=` lists matching presets.
- `POST /api/explorer-presets` creates a preset.
- `PUT /api/explorer-presets/{id}` updates an authorized preset.
- `DELETE /api/explorer-presets/{id}` deletes an authorized preset.

Presets do not grant connector access. A `mongoRecord` picker is searched and paged at the server.

See [Use presets in practice](/guides/data-explorer-presets-in-practice) and [Data Explorer](/ui/data-explorer).