MARGINNOOK / DEVELOPER PREVIEW

CSV / JSON aggregation

Count and sum rows by a field with exact decimal strings.

Developer preview. Hosted API is not live yet. Explore fixed synthetic samples; anonymous uploads, hosted execution and payments remain closed.

Inputs and results

Input: CSV or JSON rows. Returns: Grouped counts, decimal sums, input scope and pagination.

HTTP business ID data.aggregate maps to MCP aggregate.

Arguments

{
  "group_by": "category",
  "value_field": "amount",
  "limit": 100,
  "offset": 0
}

group_by and value_field are required simple ASCII field names; limit 1–1,000 (default 100). Sum values are decimal strings, not floating-point estimates. Pass decimal strings to preserve source precision. Missing fields or malformed CSV fail.

Reproducible sample

{
  "format": "json_rows",
  "content": [
    {
      "category": "books",
      "amount": "12.50"
    },
    {
      "category": "books",
      "amount": "7.25"
    },
    {
      "category": "tools",
      "amount": "3.00"
    }
  ]
}

{
  "tool": "data.aggregate",
  "resource_id": "<private-resource-handle>",
  "arguments": {
    "group_by": "category",
    "value_field": "amount",
    "limit": 100,
    "offset": 0
  }
}

{
  "operation": "data.aggregate",
  "scope": {
    "input_rows": 3,
    "group_by": "category",
    "value_field": "amount",
    "all_rows_computed": true
  },
  "sum_encoding": "decimal-string; decimal-text-inputs-exact; floats-use-received-value",
  "source_refs": [
    "input:rows"
  ],
  "offset": 0,
  "next_offset": null,
  "total_items": 2,
  "omitted_items": 0,
  "incomplete": false,
  "source_read_required": false,
  "oversized_item_refs": [],
  "groups": [
    {
      "group_id": "group-00001",
      "group": "books",
      "count": 2,
      "sum": "19.75"
    },
    {
      "group_id": "group-00002",
      "group": "tools",
      "count": 1,
      "sum": "3.00"
    }
  ]
}

Result fields and evidence

scope declares what was processed. incomplete, next_offset, omitted_items and source_read_required describe the bounded page. The core result is at most 128 KiB; whole items are omitted instead of clipped. A download is the complete returned page, not an unlimited result.

source_refs point back to the uploaded input; the HTTP job supplies source_resource_id and result_resource. groups contain group_id, group, count and sum; scope.all_rows_computed describes computation, separately from pagination.

Use GET /v1/resources/<private-resource-handle> for stored original/result bytes, or MCP read_evidence(resource_id, offset=0, length=4000). Never publish real handles. Resource-family expiry and management deletion apply to all derived evidence.

Errors and recovery

Quote checks arguments and metadata, not parsing. Preserve input and job ID on failure. Retry keyed submission with the original key; do not repeat uncertain uploads automatically. Invalid input needs correction; quota and platform capacity use distinct machine codes. Successfully extracting failing tests is a completed tool job.

HTTP contract · MCP · Limits · Switch samples