> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Elastic Data Tools

> MCP tools for querying custom datasets with flexible schemas

# 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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"] }
    }
  ]
}
```

<Accordion title="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"}`) |
</Accordion>

## `query_dataset`

Query records from a dataset with pagination.

**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         |
| `size`            | integer | No       | 50          | Results per page    |

**Example response:**

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

<Note>
  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.
</Note>

**Example prompts:**

```
"What custom datasets do we have?"
"Show me the schema for our water quality dataset"
"Query the first 20 records from dataset ds-123"
"How many records are in our supplier emissions dataset?"
"What fields does the energy tracking dataset have?"
```

## Workflow

1. **Discover datasets** — `list_datasets` to see available custom datasets and their record counts
2. **Understand schema** — `get_dataset` to see field definitions, types, and options
3. **Query records** — `query_dataset` to retrieve the actual data
4. **Cross-reference** — If `entity_type` is set, use the corresponding tool (e.g. `list_facilities`) to link records to native entities

## Related

<CardGroup cols={2}>
  <Card title="Custom KPIs" icon="chart-bar" href="/mcp/custom-kpis">
    KPI definitions that can be built on elastic datasets
  </Card>

  <Card title="Files" icon="file" href="/mcp/files">
    File uploads that can populate elastic datasets
  </Card>
</CardGroup>