Fields
Endpoints for managing Dataset fields: creation, updates, deletion, source locking, and synchronization with the search index.
GET /api/datasets/{id}/fields
Get all fields for a Dataset, sorted by position then name.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Dataset UUID or ownerId:slug natural id |
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
sample | boolean | false | Include sample values for each field, pulled from the index |
List Dataset fieldsGET /api/datasets/admin:inventory-levels/fields
Items are sorted by position, then name.
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Ainventory-levels/fields?sample=false"
}
},
"start": 0,
"count": 4,
"total": 4,
"_embedded": {
"inf:field": [
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Ainventory-levels/fields/onHand"
}
},
"label": "On Hand",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000001",
"tenant": "acme",
"name": "onHand",
"datasetId": "00000000-0000-4000-8000-000000000002",
"position": 0,
"dataType": "float",
"script": null,
"typeMapping": {
"type": "float"
},
"formatOptions": null,
"lockFieldId": false,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Ainventory-levels/fields/product"
}
},
"label": "Product",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000003",
"tenant": "acme",
"name": "product",
"datasetId": "00000000-0000-4000-8000-000000000002",
"position": 1,
"dataType": "keyword_text",
"script": null,
"typeMapping": {
"type": "keyword",
"fields": {
"text": {
"type": "text"
}
},
"ignore_above": 256
},
"formatOptions": null,
"lockFieldId": false,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Ainventory-levels/fields/reorderAt"
}
},
"label": "Reorder At",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000004",
"tenant": "acme",
"name": "reorderAt",
"datasetId": "00000000-0000-4000-8000-000000000002",
"position": 2,
"dataType": "float",
"script": null,
"typeMapping": {
"type": "float"
},
"formatOptions": null,
"lockFieldId": false,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null
},
"… 1 more items (4 total) — omitted from docs"
]
}
}
List fields with sample valuesGET /api/datasets/admin:inventory-levels/fields?sample=true
sample=true pulls example values for each field from the index.
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Ainventory-levels/fields?sample=true"
}
},
"start": 0,
"count": 4,
"total": 4,
"_embedded": {
"inf:field": [
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Ainventory-levels/fields/onHand"
}
},
"label": "On Hand",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000001",
"tenant": "acme",
"name": "onHand",
"datasetId": "00000000-0000-4000-8000-000000000002",
"position": 0,
"dataType": "float",
"script": null,
"typeMapping": {
"type": "float"
},
"formatOptions": null,
"lockFieldId": false,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null,
"sample": [
13,
17,
39
]
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Ainventory-levels/fields/product"
}
},
"label": "Product",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000003",
"tenant": "acme",
"name": "product",
"datasetId": "00000000-0000-4000-8000-000000000002",
"position": 1,
"dataType": "keyword_text",
"script": null,
"typeMapping": {
"type": "keyword",
"fields": {
"text": {
"type": "text"
}
},
"ignore_above": 256
},
"formatOptions": null,
"lockFieldId": false,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null,
"sample": [
"Aniseed Syrup",
"Chai",
"Chang"
]
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Ainventory-levels/fields/reorderAt"
}
},
"label": "Reorder At",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000004",
"tenant": "acme",
"name": "reorderAt",
"datasetId": "00000000-0000-4000-8000-000000000002",
"position": 2,
"dataType": "float",
"script": null,
"typeMapping": {
"type": "float"
},
"formatOptions": null,
"lockFieldId": false,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null,
"sample": [
25,
40
]
},
"… 1 more items (4 total) — omitted from docs"
]
}
}
Field Properties:
| Property | Type | Description |
|---|---|---|
name | string | Field identifier (unique within the Dataset) |
label | string | Display name |
dataType | string | Index type (see Field Data Types) |
position | integer | Display order |
script | object | Present for calculated fields (see POST below); source is "Script" for them and "Indexed" otherwise |
fieldId | string | Linked Datasource field id, when known |
lockFieldId | boolean | Keep fieldId through refreshes instead of relinking from the query |
format / formatOptions | object | Display formatting rules |
typeMapping | object | Full index type mapping (used for nested fields) |
ETag Support: Based on dataset_field and field table changes.
POST /api/datasets/{id}/fields
Create a calculated (script) field.
Authentication: Required
Permission: dataset:write (Data Wizard or above on the owning team)
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Field identifier |
label | string | Yes | Display name |
dataType | string | Yes | Index type (see Field Data Types) |
script | object | No | Script definition keyed by painless driver id; the raw script driver takes { "script": { "source": "<painless>" } } |
fieldId | string | No | Link to a Datasource field |
lockFieldId | boolean | No | Protect the fieldId link from refreshes |
position is assigned automatically (appended after existing fields).
Response: 201 Created with a Location header. The created field embeds
its painless driver.
Create a calculated fieldPOST /api/datasets/00000000-0000-4000-8000-000000000001/fields
script is an object keyed by painless-builder driver id; the raw 'script' driver takes { script: { source } }. position is assigned automatically (appended last).
Request body
{
"name": "surplus",
"label": "Surplus Units",
"dataType": "integer",
"script": {
"script": {
"source": "doc['onHand'].value - doc['reorderAt'].value"
}
}
}
Response · 201
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/fields/surplus"
}
},
"label": "Surplus Units",
"source": "Script",
"id": "00000000-0000-4000-8000-000000000002",
"tenant": "acme",
"lockFieldId": false,
"name": "surplus",
"dataType": "integer",
"script": {
"script": {
"source": "doc['onHand'].value - doc['reorderAt'].value"
}
},
"datasetId": "00000000-0000-4000-8000-000000000001",
"position": 4,
"updatedAt": "2026-01-15T16:20:00.000Z",
"createdAt": "2026-01-15T16:20:00.000Z",
"formatOptions": null,
"fieldId": null,
"typeMapping": null,
"_altid": null,
"_embedded": {
"inf:painless-driver": {
"_links": {
"self": {
"href": "https://informer.example.com/api/painless-drivers/script"
},
"inf:test": {
"href": "https://informer.example.com/api/painless-drivers/script/_test"
}
},
"id": "script",
"name": "Elasticsearch Script",
"icon": "fas fa-scroll",
"color": "blue",
"description": "A custom Elasticsearch script, using a secure language similar to Java",
"editor": "painlessScriptEditor"
}
}
}
Calculated Fields
Painless scripts compute values at query time from the indexed document
(doc['fieldName'].value). Make sure the script's result type matches
dataType; mismatches surface as search-time errors.
GET /api/datasets/{datasetId}/fields/{name}
Get a single field by name.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
datasetId | string | Dataset UUID (this route matches the raw column, so the ownerId:slug natural id answers 404 here) |
name | string | Field name |
Get a fieldGET /api/datasets/00000000-0000-4000-8000-000000000001/fields/surplus
This route resolves by raw column match, so the Dataset id must be the UUID here, not the ownerId:slug natural id.
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/fields/surplus"
}
},
"label": "Surplus Units",
"source": "Script",
"id": "00000000-0000-4000-8000-000000000002",
"tenant": "acme",
"name": "surplus",
"datasetId": "00000000-0000-4000-8000-000000000001",
"position": 4,
"dataType": "integer",
"script": {
"script": {
"source": "doc['onHand'].value - doc['reorderAt'].value"
}
},
"typeMapping": null,
"formatOptions": null,
"lockFieldId": false,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"_embedded": {
"inf:painless-driver": {
"_links": {
"self": {
"href": "https://informer.example.com/api/painless-drivers/script"
},
"inf:test": {
"href": "https://informer.example.com/api/painless-drivers/script/_test"
}
},
"id": "script",
"name": "Elasticsearch Script",
"icon": "fas fa-scroll",
"color": "blue",
"description": "A custom Elasticsearch script, using a secure language similar to Java",
"editor": "painlessScriptEditor"
}
}
}
PUT /api/datasets/{datasetId}/fields/{name}
Update an existing field (label, position, format, script, …).
Authentication: Required
Permission: dataset:write (Data Wizard or above on the owning team)
Update a fieldPUT /api/datasets/00000000-0000-4000-8000-000000000001/fields/surplus
Request body
{
"label": "Units Above Reorder Point"
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/fields/surplus"
}
},
"label": "Units Above Reorder Point",
"source": "Script",
"id": "00000000-0000-4000-8000-000000000002",
"tenant": "acme",
"name": "surplus",
"datasetId": "00000000-0000-4000-8000-000000000001",
"position": 4,
"dataType": "integer",
"script": {
"script": {
"source": "doc['onHand'].value - doc['reorderAt'].value"
}
},
"typeMapping": null,
"formatOptions": null,
"lockFieldId": false,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"_embedded": {
"inf:painless-driver": {
"_links": {
"self": {
"href": "https://informer.example.com/api/painless-drivers/script"
},
"inf:test": {
"href": "https://informer.example.com/api/painless-drivers/script/_test"
}
},
"id": "script",
"name": "Elasticsearch Script",
"icon": "fas fa-scroll",
"color": "blue",
"description": "A custom Elasticsearch script, using a secure language similar to Java",
"editor": "painlessScriptEditor"
}
}
}
DELETE /api/datasets/{datasetId}/fields/{name}
Delete a field from the Dataset.
Authentication: Required
Permission: dataset:write (Data Wizard or above on the owning team)
Delete a fieldDELETE /api/datasets/00000000-0000-4000-8000-000000000001/fields/surplus
Responds 200 with an empty body. The reserved _snapshots field cannot be deleted (400).
Response · 200 · no body
Restrictions:
- The reserved
_snapshotsfield cannot be deleted (400)
Field Deletion
Deleting an indexed field removes its definition; the underlying data column remains in the index until the next refresh rebuilds it.
POST /api/datasets/{id}/fields-lock
Lock or unlock the Datasource-field link (fieldId) of multiple fields.
Locked fields keep their link through refreshes instead of having it
re-derived from the query.
Authentication: Required
Permission: dataset:write (Data Wizard or above on the owning team)
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
fieldIds | array | Yes | DatasetField UUIDs (from the fields list), not names |
lock | boolean | Yes | true to lock, false to unlock |
Lock fields to their sourcePOST /api/datasets/00000000-0000-4000-8000-000000000001/fields-lock
fieldIds are DatasetField UUIDs (from the fields list), not names. Locking sets lockFieldId so a refresh will not overwrite the field's datasource-field link. Responds 200 with an empty body.
Request body
{
"fieldIds": [
"00000000-0000-4000-8000-000000000002"
],
"lock": true
}
Response · 200 · no body
POST /api/datasets/{id}/_syncFields
Rebuild the Dataset's field definitions from the live index mapping.
Authentication: Required
Sync fields from the index mappingPOST /api/datasets/admin:inventory-levels/_syncFields
Response · 200
0
Behavior:
- Adds a field for every property in the index mapping
- Removes non-script fields that no longer exist in the mapping (calculated fields are kept)
- Preserves labels, positions, and formats of existing fields, and the
fieldIdlink of locked fields - The numeric response body is an internal artifact; treat
200as success
Use Case:
When the index mapping has been changed outside a normal refresh and the field list no longer matches it. Refresh operations sync fields automatically.
POST /api/datasets/{id}/_link-fields
Re-derive each field's Datasource field link from the Dataset's query.
Authentication: Required
Permission: dataset:write (Data Wizard or above on the owning team)
Link fields to Datasource fieldsPOST /api/datasets/admin:northwind-orders/_link-fields
Compiles and runs the Dataset query (zero rows) to discover each column’s source field, then stores the links. Responds 200 with an empty body.
Response · 200 · no body
Behavior:
- Compiles and executes the Dataset's query with zero rows to discover which Datasource field produces each column
- Stores the discovered
fieldIdon each matching Dataset field - Responds
200with an empty body
Use Case:
Field links power Datasource-level metadata (labels, formats, security) on Dataset fields. Run this after building a Dataset whose fields never got linked.
Field Data Types
dataType accepts the index-level types, not abstract ones. Valid values:
text, keyword, keyword_text, long, integer, short, byte,
double, float, date, date_tz, time, boolean, binary,
integer_range, float_range, long_range, double_range, date_range,
object, nested, geo_point, geo_shape, ip, completion,
token_count, murmur3, attachment
keyword_text is the common choice for strings: it indexes the value as a
sortable keyword with a full-text .text sub-field.