Elastic Data Tools

Query custom elastic datasets — user-defined data structures with flexible schemas for tracking any type of operational data beyond the standard emission categories. Each dataset has its own field definitions and records, and can optionally extend a native Dcycle entity (facilities, vehicles, etc.). In the app they appear as My categories. The tools below read datasets; the write tools create, edit and delete datasets, fields and records.

Elastic data lives on the internal /v2 API, which only accepts a user session. These tools work when the MCP server is connected over OAuth (remote mode), not with a plain DCYCLE_API_KEY.

`list_datasets`

List all elastic datasets for the organization. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID

Example response:

[
  {
    "id": "ds1a2b3c-...",
    "name": "Water Quality Monitoring",
    "slug": "water-quality-monitoring",
    "description": "Monthly water quality samples from all facilities",
    "entity_type": "facilities",
    "record_count": 342,
    "organization_id": "a1b2c3d4-...",
    "created_at": "2024-06-15T09:00:00"
  },
  {
    "id": "ds4e5f6a-...",
    "name": "Supplier Emissions Data",
    "slug": "supplier-emissions-data",
    "description": null,
    "entity_type": "suppliers",
    "record_count": 89,
    "organization_id": "a1b2c3d4-...",
    "created_at": "2025-01-20T14:30:00"
  }
]

Key response fields:

Field	Description
`name`	Human-readable dataset name
`slug`	URL-friendly identifier
`entity_type`	Native Dcycle entity this dataset extends (null for standalone)
`record_count`	Number of records in the dataset

`get_dataset`

Get a dataset by ID with its full field definitions (schema). Parameters:

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "id": "ds1a2b3c-...",
  "name": "Water Quality Monitoring",
  "slug": "water-quality-monitoring",
  "entity_type": "facilities",
  "fields": [
    {
      "id": "f1a2b3c4-...",
      "key": "sample_date",
      "name": "Sample Date",
      "data_type": "date",
      "required": true,
      "position": 0,
      "has_values": true
    },
    {
      "id": "f5e6f7a8-...",
      "key": "ph_level",
      "name": "pH Level",
      "data_type": "decimal",
      "required": false,
      "position": 1,
      "has_values": true,
      "classification": "metric"
    },
    {
      "id": "f9b0c1d2-...",
      "key": "status",
      "name": "Compliance Status",
      "data_type": "select",
      "required": true,
      "position": 2,
      "options": { "values": ["compliant", "non_compliant", "pending"] }
    }
  ]
}

Field data types

Type	Description
`text`	Free-form text
`integer`	Whole numbers
`decimal`	Decimal numbers
`boolean`	True/false
`date`	Date (YYYY-MM-DD)
`datetime`	Date and time
`select`	Single choice from predefined options
`reference`	UUID reference to another dataset’s record
`quantity_unit`	Composite value with unit (e.g. `{"value": "12.5", "unit": "kg"}`)

`query_dataset`

Query records from a dataset with pagination, optional sorting, and optional filtering. Parameters:

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`organization_id`	string	No	default org	Organization UUID
`page`	integer	No	1	Page number (≥ 1)
`size`	integer	No	50	Results per page (max 200)
`sort`	string	No	—	Field key to sort by; prefix `-` for descending (e.g. `-created_date`)
`filters`	string[]	No	—	`field_key:op:value` clauses, AND-combined (see below)

Filter syntax (field_key:op:value)

Each filters item is field_key:op:value. Operators allowed depend on the field’s data_type:

Field type	Operators
any	`eq`, `ne`, `in`, `ni`
integer / decimal / date / datetime / quantity_unit	+ `gt`, `ge`, `lt`, `le`, `bt` (between), `nb` (not-between)
text / select / reference	+ `il` (contains, case-insensitive), `lk` (contains), `nl` (not-contains)
boolean	`eq`, `ne`, `in`, `ni` only

Value encoding:

Scalar ops: amount:gt:100, status:eq:open
bt/nb: JSON 2-array → amount:bt:[100,200]
in/ni: JSON array → status:in:["open","closed"]
Shortcut field_key:value (no op) = contains for text, exact otherwise
*:value = free-text search across all fields

A clause referencing an unknown field, an operator not allowed for the field’s type, or an uncoercible value is silently ignored (no error). Call get_dataset first so you use real field keys and valid operators.

Example response:

{
  "items": [
    {
      "id": "r1a2b3c4-...",
      "data": {
        "sample_date": "2025-03-15",
        "ph_level": 7.2,
        "status": "compliant"
      }
    }
  ],
  "total": 342,
  "page": 1,
  "size": 50,
  "pages": 7
}

Records are stored as JSONB — the data object uses the field key values from the dataset schema. Call get_dataset first to understand what fields exist and their types. Reference-field cells hold the target record’s UUID (a refs map in the response resolves them to display text when present).

`get_dataset_record`

Get a single record from a dataset by its ID (use query_dataset to find record IDs first). Parameters:

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`record_id`	string	Yes	—	UUID of the record
`organization_id`	string	No	default org	Organization UUID

Example response:

{
  "id": "r1a2b3c4-...",
  "data": { "sample_date": "2025-03-15", "ph_level": 7.2, "status": "compliant" },
  "entity_id": null,
  "created_at": "2025-03-15T10:12:00"
}

`list_dataset_groups`

List the organization’s dataset groups (folders that organize datasets in the UI). Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID

Example response:

[
  { "id": "g1a2b3c4-...", "name": "Environmental", "description": null, "position": 0 },
  { "id": "g5e6f7a8-...", "name": "Social", "description": "People & governance", "position": 1 }
]

`list_project_datasets`

List the elastic datasets associated with a specific project. Parameters:

Parameter	Type	Required	Default	Description
`project_id`	string	Yes	—	UUID of the project
`organization_id`	string	No	default org	Organization UUID

Example response:

[
  {
    "id": "ds1a2b3c-...",
    "name": "Water Quality Monitoring",
    "entity_type": "facilities",
    "record_count": 342
  }
]

Example prompts:

"What custom datasets do we have?"
"Show me the schema for our water quality dataset"
"Query the water quality records where ph_level is above 8, newest first"
"Show non-compliant samples from 2025 in the water quality dataset"
"Get record r-123 from the supplier emissions dataset"
"How many records are in our supplier emissions dataset?"
"Which datasets belong to project p-456?"

Write tools

Write tools are annotated readOnlyHint: false. The delete tools are also annotated destructiveHint: true, so AI assistants ask you before calling them.

`create_dataset`

Create an empty dataset. Add its columns with add_dataset_fields, then load rows with create_dataset_records.

Parameter	Type	Required	Default	Description
`name`	string	Yes	—	Visible name (1-255 chars)
`description`	string	No	—	Dataset description
`organization_id`	string	No	default org	Organization UUID

`update_dataset`

Rename a dataset or change its description. Unset values are left untouched.

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`name`	string	No	—	New name (1-255 chars)
`description`	string	No	—	New description (max 2000 chars)
`organization_id`	string	No	default org	Organization UUID

`delete_dataset`

Permanently delete a dataset together with all its fields and records. This cannot be undone.

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`organization_id`	string	No	default org	Organization UUID

`add_dataset_fields`

Add up to 200 fields (columns) to a dataset. Returns the dataset with its full field list.

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`fields`	object[]	Yes	—	Field definitions (see below)
`organization_id`	string	No	default org	Organization UUID

Each field object takes:

Key	Required	Description
`key`	Yes	Stable internal key, lowercase snake_case (`^[a-z][a-z0-9_]*$`). Records are keyed by it and it cannot be changed later
`name`	Yes	Visible column label
`data_type`	Yes	`text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `select`, `reference`, `quantity_unit`, `user` or `formula`
`required`	No	Whether a value is mandatory (default `false`)
`description`	No	Field description
`default_value`	No	Default value (raw text)
`options`	No	`select`: `{"values": ["a", "b"]}` · `reference`: `{"target": "dataset:<dataset-uuid>"}` · `quantity_unit`: `{"unit": "kg"}`

`update_dataset_field`

Update one field. Only the arguments you pass change, and the field’s key never changes.

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`field_id`	string	Yes	—	UUID of the field (from `get_dataset`)
`name`	string	No	—	New visible label
`required`	boolean	No	—	Whether a value is mandatory
`description`	string	No	—	New description
`options`	object	No	—	New type-specific config
`default_value`	string	No	—	New default value
`data_type`	string	No	—	New type, only while no record has a value for the field
`organization_id`	string	No	default org	Organization UUID

For a select field, options.values must keep every value already in use. To rename a value, add the new one, update the records with update_dataset_record, then remove the old one.

`delete_dataset_field`

Permanently delete a field and its value in every record of the dataset.

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`field_id`	string	Yes	—	UUID of the field
`organization_id`	string	No	default org	Organization UUID

`create_dataset_records`

Create up to 100 records per call. Each record is an object keyed by field key (not display name), for example {"site": "Madrid", "amount": 120.5, "measured_on": "2026-01-31"}. Values are validated against each field’s type; a quantity_unit value is {"value": "12.5", "unit": "kg"}.

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`records`	object[]	Yes	—	Rows keyed by field key (max 100)
`organization_id`	string	No	default org	Organization UUID

Rows are created one by one, so a bad row doesn’t block the rest:

{
  "created": 2,
  "failed": 1,
  "results": [
    { "index": 0, "id": "r1a2b3c4-..." },
    { "index": 1, "error": "..." },
    { "index": 2, "id": "r5e6f7a8-..." }
  ]
}

`update_dataset_record`

Change values of one record. Only the given field keys change; a key set to null clears it.

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`record_id`	string	Yes	—	UUID of the record (from `query_dataset`)
`data`	object	Yes	—	New values keyed by field key
`organization_id`	string	No	default org	Organization UUID

`delete_dataset_record`

Permanently delete one record.

Parameter	Type	Required	Default	Description
`dataset_id`	string	Yes	—	UUID of the dataset
`record_id`	string	Yes	—	UUID of the record
`organization_id`	string	No	default org	Organization UUID

Example prompts:

"Create a dataset called Water meters with a site, a reading in m3 and a measurement date"
"Add these 40 rows from the spreadsheet to the Water meters dataset"
"In Customer Success Metrics, remove 'MRR' from every value of the Type column"
"Mark record r-123 as closed"
"Delete the empty test dataset we created yesterday"

Workflow

Discover datasets — list_datasets (or list_project_datasets for a project) to see available datasets and record counts; list_dataset_groups for how they’re organized
Understand schema — get_dataset to see field keys, data_types, and options (needed to build filters/sort)
Query records — query_dataset with filters/sort to retrieve and narrow the data; use get_dataset_record for a single record by ID
Cross-reference — If entity_type is set, use the corresponding tool (e.g. list_facilities) to link records to native entities
Build or change data — create_dataset → add_dataset_fields → create_dataset_records; update_* to edit; delete_* only after confirming with the user

CLI: My Categories

The same operations from the terminal with dcy elastic

Custom KPIs

KPI definitions that can be built on elastic datasets

Files

File uploads that can populate elastic datasets

Getting Started

Tools Reference

Reference Data

`list_datasets`

`get_dataset`

`query_dataset`

`get_dataset_record`

`list_dataset_groups`

`list_project_datasets`

Write tools

`create_dataset`

`update_dataset`

`delete_dataset`

`add_dataset_fields`

`update_dataset_field`

`delete_dataset_field`

`create_dataset_records`

`update_dataset_record`

`delete_dataset_record`

Workflow

CLI: My Categories

Custom KPIs

Files

​list_datasets

​get_dataset

​query_dataset

​get_dataset_record

​list_dataset_groups

​list_project_datasets

​Write tools

​create_dataset

​update_dataset

​delete_dataset

​add_dataset_fields

​update_dataset_field

​delete_dataset_field

​create_dataset_records

​update_dataset_record

​delete_dataset_record

​Workflow

​Related

CLI: My Categories

Custom KPIs

Files

`list_datasets`

`get_dataset`

`query_dataset`

`get_dataset_record`

`list_dataset_groups`

`list_project_datasets`

Write tools

`create_dataset`

`update_dataset`

`delete_dataset`

`add_dataset_fields`

`update_dataset_field`

`delete_dataset_field`

`create_dataset_records`

`update_dataset_record`

`delete_dataset_record`

Workflow

Related