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.).

`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?"

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

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

Elastic Data Tools

Elastic Data Tools

`list_datasets`

`get_dataset`

`query_dataset`

`get_dataset_record`

`list_dataset_groups`

`list_project_datasets`

Workflow

Custom KPIs

Files

​Elastic Data Tools

​list_datasets

​get_dataset

​query_dataset

​get_dataset_record

​list_dataset_groups

​list_project_datasets

​Workflow

​Related

Custom KPIs

Files

Elastic Data Tools

`list_datasets`

`get_dataset`

`query_dataset`

`get_dataset_record`

`list_dataset_groups`

`list_project_datasets`

Workflow

Related