Fields

Endpoints for managing dataset fields including creation, updates, deletion, locking, and synchronization.

GET /api/datasets/{id}/fields

Get all fields for a dataset, sorted by position and name.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Query Parameters:

Parameter	Type	Default	Description
`sample`	boolean	false	Include sample values for each field

Response:

{
  "_links": {
    "self": { "href": "/api/datasets/{id}/fields" }
  },
  "_embedded": {
    "inf:field": [
      {
        "name": "order_id",
        "label": "Order ID",
        "dataType": "string",
        "position": 0,
        "visible": true,
        "locked": false,
        "searchable": true,
        "sortable": true,
        "filterable": true
      },
      {
        "name": "amount",
        "label": "Sale Amount",
        "dataType": "number",
        "position": 1,
        "visible": true,
        "locked": false,
        "format": {
          "type": "currency",
          "decimals": 2,
          "currency": "USD"
        }
      },
      {
        "name": "profit_margin",
        "label": "Profit Margin %",
        "dataType": "number",
        "position": 2,
        "visible": true,
        "calculated": true,
        "script": "doc['revenue'].value - doc['cost'].value",
        "scriptLang": "painless"
      }
    ]
  },
  "start": 0,
  "count": 3,
  "total": 3
}

With Samples:

GET /api/datasets/sales-2024/fields?sample=true

Returns field objects with sample property containing example values:

{
  "_links": {
    "self": { "href": "/api/datasets/{id}/fields?sample=true" }
  },
  "_embedded": {
    "inf:field": [
      {
        "name": "customer_name",
        "label": "Customer Name",
        "dataType": "string",
        "sample": ["Acme Corp", "TechStart Inc", "Global Industries"]
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

Field Properties:

Property	Type	Description
`name`	string	Field identifier (unique within dataset)
`label`	string	Display name
`dataType`	string	Data type: `string`, `number`, `date`, `boolean`, `object`
`position`	integer	Display order
`visible`	boolean	Show in default view
`locked`	boolean	Prevent user modification
`calculated`	boolean	Computed field (not from source)
`script`	string	Calculation script (for calculated fields)
`scriptLang`	string	Script language (`painless`, `expression`)
`format`	object	Display formatting rules
`searchable`	boolean	Enable full-text search
`sortable`	boolean	Enable sorting
`filterable`	boolean	Enable filtering

POST /api/datasets/{id}/fields

Create a new calculated or custom field.

Authentication: Required

Permission: dataset:write

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Field identifier
`label`	string	Yes	Display name
`dataType`	string	Yes	Data type
`script`	string	No	Calculation script
`fieldId`	string	No	Source field ID (for linking)
`lockFieldId`	boolean	No	Lock the source field

Example Request (calculated field):

{
  "name": "profit",
  "label": "Profit",
  "dataType": "number",
  "script": "doc['revenue'].value - doc['cost'].value",
  "scriptLang": "painless"
}

Example Request (alias field):

{
  "name": "sale_date",
  "label": "Sale Date",
  "dataType": "date",
  "fieldId": "order_date",
  "lockFieldId": true
}

Response:

Returns the created field object.

Calculated Fields

Use Painless scripting to create derived fields. Common use cases: profit calculations, date transformations, string concatenations, conditional logic.

GET /api/datasets/{datasetId}/fields/{name}

Get a single field by name.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`datasetId`	string	Dataset ID or slug
`name`	string	Field name

Response:

{
  "name": "amount",
  "label": "Sale Amount",
  "dataType": "number",
  "position": 1,
  "visible": true,
  "locked": false,
  "format": {
    "type": "currency",
    "decimals": 2,
    "currency": "USD"
  }
}

PUT /api/datasets/{datasetId}/fields/{name}

Update an existing field.

Authentication: Required

Permission: dataset:write

Path Parameters:

Parameter	Type	Description
`datasetId`	string	Dataset ID or slug
`name`	string	Field name

Request Body:

Field	Type	Description
`label`	string	Display name
`dataType`	string	Data type
`position`	integer	Display order
`visible`	boolean	Show in default view
`format`	object	Display formatting
`script`	string	Calculation script
`locked`	boolean	Prevent user modification

Example Request:

{
  "label": "Total Sale Amount",
  "format": {
    "type": "currency",
    "decimals": 2,
    "currency": "EUR"
  },
  "position": 5
}

Response:

Returns the updated field object.

DELETE /api/datasets/{datasetId}/fields/{name}

Delete a field from the dataset.

Authentication: Required

Permission: dataset:write

Path Parameters:

Parameter	Type	Description
`datasetId`	string	Dataset ID or slug
`name`	string	Field name

Response:

204 No Content

Restrictions:

Cannot delete the _snapshots field (reserved for snapshot tracking)
Cannot delete locked fields
Cannot delete fields used in visuals or filters (returns 400)

Field Deletion

Deleting a field removes it from the dataset schema and makes its data inaccessible. This operation cannot be undone.

POST /api/datasets/{id}/fields-lock

Lock or unlock multiple fields to prevent user modification.

Authentication: Required

Permission: dataset:write

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Request Body:

Field	Type	Required	Description
`fieldIds`	array	Yes	Array of field names to lock/unlock
`lock`	boolean	Yes	`true` to lock, `false` to unlock

Example Request (lock fields):

{
  "fieldIds": ["order_id", "customer_id", "order_date"],
  "lock": true
}

Example Request (unlock fields):

{
  "fieldIds": ["region", "category"],
  "lock": false
}

Response:

{
  "locked": 3,
  "fields": ["order_id", "customer_id", "order_date"]
}

Use Case:

Lock critical fields (IDs, timestamps) to prevent accidental modification by users while allowing flexibility with other fields.

POST /api/datasets/{id}/_syncFields

Synchronize field definitions from the Elasticsearch mapping.

Authentication: Required

Permission: dataset:write

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Response:

{
  "added": 3,
  "updated": 5,
  "removed": 1,
  "fields": [...]
}

Behavior:

Compares dataset field definitions with Elasticsearch mapping
Adds fields that exist in ES but not in dataset
Updates field types that have changed
Optionally removes fields that no longer exist in ES
Preserves custom field properties (labels, formats, positions)

Use Case:

After modifying the dataset query or importing new data, sync fields to ensure the dataset schema matches the actual data structure.

Automatic Sync

Field sync is automatically performed during dataset refresh operations. Manual sync is useful when the Elasticsearch mapping has been modified externally.

POST /api/datasets/{id}/_link-fields

Link dataset fields to datasource fields for query building.

Authentication: Required

Permission: dataset:write

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Response:

{
  "linked": 12,
  "fields": [
    {
      "name": "order_id",
      "sourceField": "orders.id",
      "sourceTable": "orders"
    }
  ]
}

Behavior:

Matches dataset fields to datasource schema
Creates links for query building and joins
Enables intelligent query suggestions
Preserves manual field mappings

Use Case:

After creating a dataset from a datasource query, link fields to enable advanced query building features and field suggestions.

Field Data Types

Supported data types and their Elasticsearch mappings:

Data Type	Elasticsearch Type	Description
`string`	`text`, `keyword`	Text values
`number`	`long`, `double`	Numeric values
`date`	`date`	Date/time values
`boolean`	`boolean`	True/false values
`object`	`object`, `nested`	Structured data
`geo_point`	`geo_point`	Geographic coordinates

Field Formatting

Common format configurations:

Currency

{
  "type": "currency",
  "decimals": 2,
  "currency": "USD",
  "symbol": "$"
}

Percentage

{
  "type": "percentage",
  "decimals": 1,
  "multiply": true
}

Date

{
  "type": "date",
  "format": "YYYY-MM-DD",
  "timezone": "America/New_York"
}

Number

{
  "type": "number",
  "decimals": 2,
  "thousandsSeparator": true,
  "prefix": "#"
}

Calculated Field Examples

Profit Calculation

{
  "name": "profit",
  "label": "Profit",
  "dataType": "number",
  "script": "doc['revenue'].value - doc['cost'].value"
}

Profit Margin Percentage

{
  "name": "profit_margin",
  "label": "Profit Margin %",
  "dataType": "number",
  "script": "(doc['revenue'].value - doc['cost'].value) / doc['revenue'].value * 100"
}

Full Name Concatenation

{
  "name": "full_name",
  "label": "Full Name",
  "dataType": "string",
  "script": "doc['first_name'].value + ' ' + doc['last_name'].value"
}

Days Since Order

{
  "name": "days_since_order",
  "label": "Days Since Order",
  "dataType": "number",
  "script": "(System.currentTimeMillis() - doc['order_date'].value.toInstant().toEpochMilli()) / (1000 * 60 * 60 * 24)"
}

Conditional Logic

{
  "name": "priority",
  "label": "Priority",
  "dataType": "string",
  "script": "if (doc['amount'].value > 10000) { return 'High'; } else if (doc['amount'].value > 1000) { return 'Medium'; } else { return 'Low'; }"
}

Best Practices

Field Naming

Use lowercase with underscores: customer_name, order_date
Avoid spaces and special characters
Be descriptive but concise
Match datasource conventions when possible

Field Organization

Set logical positions for related fields
Group calculated fields together
Place IDs and timestamps first
Hide internal/technical fields from default view

Performance

Limit calculated field complexity
Use keyword type for sorting/filtering
Use text type for full-text search
Avoid calculated fields in aggregations when possible

Security

Lock critical fields (IDs, audit timestamps)
Validate scripts before saving
Test calculated fields with sample data
Document complex calculations

GET /api/datasets/{id}/fields​

POST /api/datasets/{id}/fields​

GET /api/datasets/{datasetId}/fields/{name}​

PUT /api/datasets/{datasetId}/fields/{name}​

DELETE /api/datasets/{datasetId}/fields/{name}​

POST /api/datasets/{id}/fields-lock​

POST /api/datasets/{id}/_syncFields​

POST /api/datasets/{id}/_link-fields​

Field Data Types​

Field Formatting​

Currency​

Percentage​

Date​

Number​

Calculated Field Examples​

Profit Calculation​

Profit Margin Percentage​

Full Name Concatenation​

Days Since Order​

Conditional Logic​

Best Practices​

Field Naming​

Field Organization​

Performance​

Security​

GET /api/datasets/{id}/fields

POST /api/datasets/{id}/fields

GET /api/datasets/{datasetId}/fields/{name}

PUT /api/datasets/{datasetId}/fields/{name}

DELETE /api/datasets/{datasetId}/fields/{name}

POST /api/datasets/{id}/fields-lock

POST /api/datasets/{id}/_syncFields

POST /api/datasets/{id}/_link-fields

Field Data Types

Field Formatting

Currency

Percentage

Date

Number

Calculated Field Examples

Profit Calculation

Profit Margin Percentage

Full Name Concatenation

Days Since Order

Conditional Logic

Best Practices

Field Naming

Field Organization

Performance

Security