mammoth-cli 2.2.12__tar.gz → 2.2.14__tar.gz

{mammoth_cli-2.2.12 → mammoth_cli-2.2.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.12
+Version: 2.2.14
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.9,>=0.8.12
+Requires-Dist: mammoth-io<0.9,>=0.8.14
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.2.12 → mammoth_cli-2.2.14}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.2.12"
+__version__ = "2.2.14"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.12 → mammoth_cli-2.2.14}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -878,11 +878,11 @@ Status on release: ran once on CLI 2.0.14 — write sweep 2026-09-18: exit 0 on
 
 Run: `mammoth view update`. Exact input fields: `mammoth schema get view.update`.
 
-Example: `mammoth view update 123 123 --input '{"patch_data": [{"sample_key": "Status"}]}'`. Discovery only: this command is fail-closed and must not dispatch a request.
+Example: `mammoth view update 123 123 --input '{"name": "Revenue report"}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
-Execution is unavailable for the current contract and returns `unsupported_contract`. Do not infer request fields or retry it; use only a separately typed alternative.
+Result: `ViewUpdateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 
-Known restriction: BLOCKED[B09 DATAVIEW_INPUT_UNTYPED]: patch_data is an arbitrary dictionary; reserved, not registered.
+Status on release: untried; no live run recorded.
 
 ### `view.version.apply`
 

{mammoth_cli-2.2.12 → mammoth_cli-2.2.14}/mammoth_cli/commands/browse.py

@@ -86,6 +86,26 @@ def _forward_optional(
             kwargs[field] = document[field]
 
 
+#: The id a dataset or a view is known by elsewhere in the CLI; a hit's ``id`` is its tree id.
+_OBJECT_ID_KEYS = {"datasource": "dataset_id", "dataview": "view_id"}
+
+
+def _with_object_ids(data: Any) -> Any:
+    """Name the id a command takes: ``dataset_id`` / ``view_id`` beside the tree ``id``."""
+    rows = data.get("resources") if isinstance(data, dict) else None
+    if not isinstance(rows, list):
+        return data
+    named = [
+        (
+            {**row, key: row.get("object_id")}
+            if isinstance(row, dict) and (key := _OBJECT_ID_KEYS.get(str(row.get("resource_type"))))
+            else row
+        )
+        for row in rows
+    ]
+    return {**data, "resources": named}
+
+
 def browse_folder(invocation: Invocation) -> HandlerResult:
     """Browse resources inside one folder of the active project.
 
@@ -173,7 +193,7 @@ def browse_resources(invocation: Invocation) -> HandlerResult:
     )
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
-    return data, _meta(invocation, auth.workspace_id, project_id)
+    return _with_object_ids(data), _meta(invocation, auth.workspace_id, project_id)
 
 
 def browse_resource(invocation: Invocation) -> HandlerResult:
@@ -208,7 +228,11 @@ def browse_ancestors(invocation: Invocation) -> HandlerResult:
 
 
 def browse_search(invocation: Invocation) -> HandlerResult:
-    """Search resources across every project of the workspace (resources v2)."""
+    """Search resources across every project of the workspace (resources v2).
+
+    ``resource_type`` ``dataset`` means the route's ``datasource``. Each dataset hit
+    carries ``dataset_id`` and each view hit ``view_id``: pass those, never the tree ``id``.
+    """
     document = invocation.load_input() or {}
     kwargs: dict[str, Any] = {}
     _forward_optional(
@@ -216,7 +240,7 @@ def browse_search(invocation: Invocation) -> HandlerResult:
     )
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
-    return data, _meta(invocation, auth.workspace_id, None)
+    return _with_object_ids(data), _meta(invocation, auth.workspace_id, None)
 
 
 def browse_resources_bulk(invocation: Invocation) -> HandlerResult:

{mammoth_cli-2.2.12 → mammoth_cli-2.2.14}/mammoth_cli/commands/dataset.py

@@ -33,6 +33,7 @@ from mammoth_cli.runtime.session import open_service, require_project
 from mammoth_cli.services.listing import (
     DATASET_ROW_FIELDS,
     ambiguity_note,
+    compact_columns,
     dataset_summary,
     fit_budget,
     name_hit,
@@ -202,7 +203,11 @@ _SEARCH_PAGE_SIZE = 100
 
 
 def search_hits(
-    service: Any, resource_type: str, needle: str, project_id: int | None = None
+    service: Any,
+    resource_type: str,
+    needle: str,
+    project_id: int | None = None,
+    fields: str = "minimal",
 ) -> tuple[list[dict[str, Any]], bool]:
     """Resources of ``resource_type`` whose name contains ``needle``, from the search route.
 
@@ -222,11 +227,11 @@ def search_hits(
     for _ in range(_SEARCH_PAGES):
         page = service.call(
             symbol,
-            search=needle,
+            search=needle or None,
             resource_type=resource_type,
             limit=_SEARCH_PAGE_SIZE,
             cursor=cursor,
-            fields="minimal",
+            fields=fields,
             **scope,
         )
         rows += [r for r in page.get("resources", []) if isinstance(r, dict)]
@@ -274,6 +279,61 @@ def named_project(service: Any, project_id: int, visible: list[dict[str, Any]])
     return {"id": project_id, "name": record.get("name")}
 
 
+def _requested_columns(document: dict[str, Any]) -> list[str]:
+    """The ``columns`` input as a list of names (a comma-separated string is split)."""
+    raw = document.get("columns")
+    if raw is None:
+        return []
+    names = raw.split(",") if isinstance(raw, str) else raw
+    if not isinstance(names, list) or not all(isinstance(n, str) for n in names):
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message="'columns' must be a list of column names (or one comma-separated string).",
+            exit_status=EXIT_USAGE,
+        )
+    return [n.strip() for n in names if n.strip()]
+
+
+def _column_names(hit: dict[str, Any]) -> list[str]:
+    """Display names of the columns a full-field search hit carries."""
+    properties = hit.get("object_properties")
+    metadata = properties.get("metadata") if isinstance(properties, dict) else None
+    return [
+        str(c["display_name"])
+        for c in metadata or []
+        if isinstance(c, dict) and c.get("display_name")
+    ]
+
+
+def _find_by_columns(
+    service: Any,
+    needle: str,
+    columns: list[str],
+    visible: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], bool]:
+    """Datasets (named like ``needle``, when given) that have every one of ``columns``."""
+    hits, cut = search_hits(service, "datasource", needle, fields="full")
+    names = {p.get("id"): p.get("name") for p in visible}
+    wanted = [c.lower() for c in columns]
+    matches: list[dict[str, Any]] = []
+    for hit in hits:
+        have = _column_names(hit)
+        if not set(wanted) <= {c.lower() for c in have}:
+            continue
+        matches.append(
+            {
+                "project_id": hit.get("project_id"),
+                "project_name": names.get(hit.get("project_id")),
+                "id": hit.get("object_id"),
+                "name": hit.get("name"),
+                "rows": hit.get("row_count"),
+                "cols": len(have),
+                "columns": compact_columns([(c, None) for c in have], limit=None),
+            }
+        )
+    return matches, cut
+
+
 def dataset_find(invocation: Invocation) -> HandlerResult:
     """Search dataset names for a substring across every visible project.
 
@@ -326,9 +386,11 @@ def dataset_find(invocation: Invocation) -> HandlerResult:
 def dataset_list(invocation: Invocation) -> HandlerResult:
     """List datasets in the active project, newest first, each with what tells them apart.
 
-    Every item carries its size, created/updated time, how its data arrived, and
-    its column names and types (from the list route's stored ``stats``,
-    ``sources`` and ``data_schema``), cut to fit the agent tool output cap.
+    Every item carries its created/updated time and how its data arrived (from the
+    list route's ``sources``), cut to fit the agent tool output cap. The list asks
+    only the cheap fields, so it holds no row counts or column names: ``view list
+    DATASET_ID`` shows a dataset's columns, and ``dataset find --input '{"columns":
+    [...]}'`` finds the dataset that has given columns.
     ``full: true`` returns the raw ``{id, name}`` list instead. ``name`` keeps only datasets
     whose name contains it (case-insensitive) across every page, as short rows without
     column lists; ``limit``/``offset`` then page over the matches.
@@ -347,7 +409,9 @@ def dataset_list(invocation: Invocation) -> HandlerResult:
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
     if compact:
-        data = _compact_dataset_list(data, kwargs.get("offset", 0), kwargs.get("sort"))
+        data = _compact_dataset_list(
+            data, kwargs.get("offset", 0), kwargs.get("sort"), kwargs.get("limit", 100)
+        )
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
@@ -388,7 +452,7 @@ def _dataset_name_search(
     return page, _meta(invocation, auth.workspace_id, project_id)
 
 
-def _compact_dataset_list(data: Any, offset: int, sort: str | None) -> Any:
+def _compact_dataset_list(data: Any, offset: int, sort: str | None, limit: int) -> Any:
     """Summarise a dataset-list page and fit it to the tool output cap."""
     datasets = data.get("datasets") if isinstance(data, dict) else None
     if not isinstance(datasets, list):
@@ -404,7 +468,8 @@ def _compact_dataset_list(data: Any, offset: int, sort: str | None) -> Any:
             "stored sample_values per view (all_columns: true lists every column)."
         ),
     }
-    if omitted or data.get("next"):
+    # The list route sends no ``next``: a page of ``limit`` rows may have a successor.
+    if omitted or data.get("next") or len(datasets) >= limit:
         result["more"] = True
         result["next_offset"] = int(offset) + len(kept)
     return result

{mammoth_cli-2.2.12 → mammoth_cli-2.2.14}/mammoth_cli/commands/registry.py

@@ -718,7 +718,7 @@ HANDLERS: dict[str, Handler] = {
     "view.update": view_cmd.view_update,
     "view.data.get": view_cmd.view_data_get,
     "view.data.query": view_cmd.view_data_query,
-    "view.data.aggregate": view_cmd.view_data_aggregate,
+    "view.data.aggregate": view_cmd.view_data_aggregate_rounded,
     "view.data.compare": view_cmd.view_data_compare,
     "view.data.explore": view_cmd.view_data_explore,
     "view.data.profile": view_profile_cmd.view_data_profile,

{mammoth_cli-2.2.12 → mammoth_cli-2.2.14}/mammoth_cli/commands/schedule.py

@@ -22,6 +22,7 @@ from mammoth_cli.errors.envelope import (
     CODE_SDK_SYMBOL_UNRESOLVED,
     EXIT_USAGE,
     CliError,
+    not_available_error,
 )
 from mammoth_cli.manifest.loader import command_by_id
 from mammoth_cli.runtime.confirm import (
@@ -154,14 +155,17 @@ def _meta(invocation: Invocation, workspace_id: int, project_id: int) -> dict[st
 
 
 def schedule_list(invocation: Invocation) -> HandlerResult:
-    """List schedules in the active project. ``limit``/``offset`` are optional."""
-    project_id = require_project(invocation)
-    document = _bound_document(invocation)
-    kwargs: dict[str, Any] = {"project_id": project_id}
-    _forward_optional(document, kwargs, ("limit", "offset"))
-    with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), **kwargs)
-    return data, _meta(invocation, auth.workspace_id, project_id)
+    """Retired: the server does not implement listing a project's schedules.
+
+    ``GET /workspaces/{id}/projects/{id}/schedules`` always answers ``5GENR011
+    NOT_IMPLEMENTED`` (the server raises it on purpose). The command stays so a
+    caller gets a clear answer instead of a bare backend error.
+    """
+    raise not_available_error(
+        "schedule list",
+        web_path="the web app, which opens a schedule from the dataset or automation that owns it",
+        instead="`schedule get SCHEDULE_ID` reads one schedule by an id you already have.",
+    )
 
 
 def schedule_get(invocation: Invocation) -> HandlerResult:

{mammoth_cli-2.2.12 → mammoth_cli-2.2.14}/mammoth_cli/commands/schema.py

@@ -74,6 +74,7 @@ _GROUP_DISCOVERY_PURPOSES = {
 }
 
 _COMMAND_DISCOVERY_PURPOSES = {
+    "view.update": "rename change name to a new name title relabel",
     "file.upload": (
         "upload import CSV spreadsheet XLSX source data append add rows union stack "
         "a file into an existing dataset excel workbook tabs sheets drop in"
@@ -305,7 +306,8 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "view.data.explore": (
         "explore trend trends trending over time per day week month quarter year by date "
         "distribution spread histogram top most common frequent values breakdown share "
-        "percentage profile"
+        "percentage profile period year quarter month date range coverage figure "
+        "cumulative"
     ),
     # "Give the West team their own copy they can change" / "duplicate this
     # dataset as an independent copy" / "clone it without changing the
@@ -323,7 +325,10 @@ _COMMAND_DISCOVERY_PURPOSES = {
     # value -- and neither can be dropped as a data word anyway, since
     # view.data.explore's own purpose text already uses both for its trend
     # feature.
-    "view.data.aggregate": "group and sum totals by month week without changing the pipeline",
+    "view.data.aggregate": (
+        "group and sum totals by month week without changing the pipeline "
+        "sum total figure answer a question, read only"
+    ),
     # Goals stated as "what is in this data" / "why do customers churn": one
     # whole-view profile answers both, so the phrasing must reach it.
     "view.data.profile": (
@@ -1740,6 +1745,21 @@ def _inline_call_detail(entries: list[dict[str, Any]]) -> None:
             entry["agent_example"] = record["agent_example"]
 
 
+def _inline_picks(page: list[dict[str, Any]], offset: int) -> list[dict[str, Any]]:
+    """The entries to inline: the top ones, plus read commands ranked below a write.
+
+    A read that answers the question is worth its fields even when a write such as
+    ``view.transform.pivot`` outranks it; otherwise the caller needs a ``schema get``.
+    """
+    head = page[: max(0, _INLINE_DETAIL_COUNT - offset)]
+    reads = [
+        entry
+        for entry in page[len(head) :]
+        if (command_by_id(entry["command_id"]) or {}).get("mutation_class") == "read"
+    ]
+    return head + reads[:_INLINE_DETAIL_COUNT]
+
+
 #: How to drill down from a find: a family's full command list, or every family.
 _BROWSE_NEXT = (
     "mammoth schema list FAMILY lists every command in a family; mammoth schema list "
@@ -1902,7 +1922,7 @@ def find_schemas(
     )
     total_matches = len(ranked_matches)
     page = [match for _, match in ranked_matches[offset : offset + bounded_limit]]
-    _inline_call_detail(page[: max(0, _INLINE_DETAIL_COUNT - offset)])
+    _inline_call_detail(_inline_picks(page, offset))
     has_more = offset + len(page) < total_matches
     continuation = (
         {

{mammoth_cli-2.2.12 → mammoth_cli-2.2.14}/mammoth_cli/commands/view.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 
 import dataclasses
 import inspect
+import shlex
 from datetime import UTC, datetime
 from decimal import Decimal, InvalidOperation
 from typing import Any
@@ -899,19 +900,45 @@ def view_impact(invocation: Invocation) -> HandlerResult:
 
 
 def view_update(invocation: Invocation) -> HandlerResult:
-    """Reject free-form dataview patches until the API supplies typed variants."""
-    raise CliError(
+    """Rename a view from the name input field; any other patch is refused.
+
+    The dataview patch route leaves op, path and value unconstrained, so the only
+    typed change offered is the rename (``replace`` on ``name``).
+    """
+    project_id = require_project(invocation)
+    dataview_id = _require_int_positional_at(invocation, 0, "view id")
+    document = invocation.load_input() or {}
+    name = document.get("name")
+    # ``dataview_id`` is the VIEW_ID positional, bound into the document by the contract.
+    allowed = {"name", _DATASET_ID_FIELD, "dataview_id"}
+    if set(document) - allowed or not isinstance(name, str) or not name.strip():
+        raise _untyped_patch_error(invocation)
+    with open_service(invocation) as (service, auth):
+        dataset_id = _resolve_dataset_id(service, invocation, dataview_id, document)
+        data = service.call(
+            _symbol(invocation),
+            dataset_id=dataset_id,
+            dataview_id=dataview_id,
+            patch_data=[{"op": "replace", "path": "name", "value": name.strip()}],
+            project_id=project_id,
+        )
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+def _untyped_patch_error(invocation: Invocation) -> CliError:
+    """The refusal for a view patch that is not the typed rename."""
+    return CliError(
         code=CODE_UNSUPPORTED_CONTRACT,
         message="Raw dataview patch operations are not available through the CLI.",
         exit_status=EXIT_USAGE,
         hint=(
-            "The OpenAPI operation leaves op, path, and value unconstrained. "
-            "Use a separately typed view command when its schema covers the intended change."
+            "The OpenAPI operation leaves op, path, and value unconstrained. The typed "
+            'change is the rename: view update VIEW_ID --input \'{"name": "New name"}\'.'
         ),
         details={
             "command_id": invocation.command_id,
             "blocker": "B09 DATAVIEW_INPUT_UNTYPED",
-            "typed_alternatives": [],
+            "typed_alternatives": ['view update VIEW_ID --input \'{"name": "New name"}\''],
         },
         recovery_commands=[
             "mammoth schema find view",
@@ -1288,17 +1315,19 @@ def _relabel_and_check(
 ) -> Any:
     """Relabel a data page to display names and add ``column_warnings`` and ``duplicates``.
 
+    Only read-only data reads call this, so a dates-as-text finding carries no convert fix.
+
     The metadata read happens only when the page has rows and the caller has
     not read it already (one read serves both the names and the types).
     """
     rows = data.get(_ROWS_KEY) if isinstance(data, dict) else None
     if not isinstance(rows, list) or not rows:
         data = _relabel_columns(service, dataset_id, view_id, project_id, data, mapping)
-        return _with_column_warnings(data, types or {}, view_id, dataset_id)
+        return _with_column_warnings(data, types or {}, view_id, dataset_id, read_only=True)
     if mapping is None or types is None:
         mapping, types = _column_profile(service, dataset_id, view_id, project_id)
     data = _relabel_columns(service, dataset_id, view_id, project_id, data, mapping)
-    data = _with_column_warnings(data, types, view_id, dataset_id)
+    data = _with_column_warnings(data, types, view_id, dataset_id, read_only=True)
     return _with_duplicates_fact(data, view_id, dataset_id, whole_view)
 
 
@@ -1322,7 +1351,11 @@ COLUMN_CHECK_ISSUES = (
 
 
 def _with_column_warnings(
-    data: Any, types: dict[str, str], view_id: int, dataset_id: int | None = None
+    data: Any,
+    types: dict[str, str],
+    view_id: int,
+    dataset_id: int | None = None,
+    read_only: bool = False,
 ) -> Any:
     """Add ``column_checks`` (always) and ``column_warnings`` (when found).
 
@@ -1332,13 +1365,19 @@ def _with_column_warnings(
     """
     if not isinstance(data, dict) or not isinstance(data.get(_ROWS_KEY, []), list):
         return data
-    checks, warnings = _check_columns(data.get(_ROWS_KEY) or [], types, view_id, dataset_id)
+    checks, warnings = _check_columns(
+        data.get(_ROWS_KEY) or [], types, view_id, dataset_id, read_only
+    )
     out = {**data, "column_checks": checks}
     return {**out, "column_warnings": warnings} if warnings else out
 
 
 def _check_columns(
-    rows: list[Any], types: dict[str, str], view_id: int, dataset_id: int | None
+    rows: list[Any],
+    types: dict[str, str],
+    view_id: int,
+    dataset_id: int | None,
+    read_only: bool = False,
 ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
     """Run ``column_warnings`` and describe what was checked (never raises)."""
     checks: dict[str, Any] = {
@@ -1350,7 +1389,7 @@ def _check_columns(
     warnings: list[dict[str, Any]] = []
     if rows and types:
         try:
-            warnings = column_warnings(rows, types, view_id, dataset_id)
+            warnings = column_warnings(rows, types, view_id, dataset_id, read_only)
         except Exception as exc:  # noqa: BLE001 -- a presentation aid must not fail the read
             checks["checked"] = []
             checks["error"] = f"{type(exc).__name__}: {exc}"
@@ -1652,6 +1691,7 @@ def view_data_aggregate(invocation: Invocation) -> HandlerResult:
     TEXT-date) column groups by the named part of the date -- ``Monday``..``Sunday``,
     ``January``..``December``, ``Q1``..``Q4``, the year -- in calendar order: the
     read-only way to answer by-weekday and by-month questions.
+    Figures are rounded for display (2 decimals; 4 below 1).
     Never use ``view transform pivot`` just to read a number -- it mutates the
     view's pipeline.
     """
@@ -1707,6 +1747,15 @@ def view_data_aggregate(invocation: Invocation) -> HandlerResult:
     return data, meta
 
 
+def view_data_aggregate_rounded(invocation: Invocation) -> HandlerResult:
+    """``view data aggregate`` as the user reads it: floats rounded (2 decimals; 4 below 1).
+
+    ``view data compare`` calls :func:`view_data_aggregate` itself, at full precision.
+    """
+    data, meta = view_data_aggregate(invocation)
+    return read_queries.round_result_rows(data), meta
+
+
 def _compare_key_and_value_columns(document: dict[str, Any]) -> tuple[list[str], list[str]]:
     """Return the (key, value) display-column names an aggregate call over
     ``document`` will produce, without making the call -- mirrors the label
@@ -1728,7 +1777,7 @@ def _run_aggregate_for_compare(
 ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
     """Run ``view data aggregate``'s own handler against one view, for compare."""
     sub_invocation = dataclasses.replace(
-        invocation, command_id="view.data.aggregate", extra_args=[str(view_id)]
+        invocation, command_id="view.data.aggregate", extra_args=[str(view_id)], positionals={}
     )
     data, meta = view_data_aggregate(sub_invocation)
     rows = data.get(_ROWS_KEY, [])
@@ -1892,7 +1941,9 @@ def _explore_text_dates(
         condition=condition,
     )
     page = (document.get("offset"), document.get("limit"))
-    rows = read_queries.apply_explore_order(response["data"], document.get("sort"), page)
+    rows = read_queries.apply_explore_order(
+        response["data"], document.get("sort"), page, bool(document.get("cumulative"))
+    )
     return {**response, "data": rows}
 
 
@@ -1915,7 +1966,13 @@ def view_data_explore(invocation: Invocation) -> HandlerResult:
     An optional ``metric`` ``{"column": ..., "function": ...}`` (SUM, COUNT,
     AVG, MIN, MAX, STDDEV or DISTINCT_COUNT) adds a second aggregate per bucket over another column,
     and an optional ``condition`` filters rows first -- same as ``view data
-    aggregate``, which this command wraps for the raw PIVOT shape. Never use
+    aggregate``, which this command wraps for the raw PIVOT shape. A date range
+    is one ``and`` condition (``>=`` a start, ``<=`` an end); one year is
+    ``{"column": ..., "operator": "=", "value": 2017, "component": "year"}``.
+    ``cumulative: true`` adds a running total of the metric (of ``count`` without
+    one) over the buckets in date order, whatever ``sort`` or ``limit`` shows:
+    the answer to "cumulative / running total through X". Figures are rounded for
+    display (2 decimals; 4 below 1). Never use
     ``view transform pivot`` just to explore a column; it mutates the
     pipeline.
     """
@@ -1951,6 +2008,8 @@ def view_data_explore(invocation: Invocation) -> HandlerResult:
         if isinstance(metric, dict):
             resolved_metric = _resolved_aggregate_item(metric, display_to_internal)
             as_map["agg_1"] = resolved_metric["as_name"]
+        if document.get("cumulative"):
+            as_map["cumulative"] = f"{as_map.get('agg_1', 'count')} (running total)"
         if bucket_dates:
             data = _explore_text_dates(reads, document, internal_column, resolved_metric)
         else:
@@ -1965,7 +2024,7 @@ def view_data_explore(invocation: Invocation) -> HandlerResult:
         data = read_queries.with_assumptions(reads, data)
         if not bucket_dates:
             data = read_queries.with_variant_hint(reads, data, column_arg)
-    return data, meta
+    return read_queries.round_result_rows(data), meta
 
 
 def _explore_on_backend(
@@ -1990,7 +2049,9 @@ def _explore_on_backend(
         kwargs[CONDITION_KWARG] = compile_condition(spec).build(
             reads.display_to_internal or None, reads.column_types or None
         )
-    _forward_optional(document, kwargs, ("level", "sequence", "limit", "offset", "sort"))
+    _forward_optional(
+        document, kwargs, ("level", "sequence", "limit", "offset", "sort", "cumulative")
+    )
     return reads.service.call(_symbol(invocation), **kwargs)
 
 
@@ -3436,7 +3497,14 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
                     int(target_ds_id),
                     kwargs.get("column_mapping"),
                 )
-        data = service.call_view(dataview_id, method, dataset_id=dataset_id, **kwargs)
+        try:
+            data = service.call_view(dataview_id, method, dataset_id=dataset_id, **kwargs)
+        except CliError as error:
+            if not (is_dataset_route and error.details.get("export_pending")):
+                raise
+            return _pending_dataset_export(error, dataview_id, result_project_id), _meta(
+                invocation, auth.workspace_id, project_id
+            )
         if is_dataset_route and isinstance(data, int):
             # The SDK returns the bare id of the dataset written to; name it, and
             # say which project it landed in, so the agent's next read is obvious.
@@ -3497,6 +3565,33 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
+def _pending_dataset_export(error: CliError, view_id: int, project_id: int) -> dict[str, Any]:
+    """A dataset export that was accepted but whose dataset id is not known yet.
+
+    The export was submitted and the server is writing it (or has written it); only
+    the lookup of its id ran out of time. That is not a failure, so say what is known
+    and how to read the dataset when it lands, never an error.
+    """
+    name = error.details.get("dataset_name")
+    pending: dict[str, Any] = {
+        "status": "pending",
+        "source_view_id": view_id,
+        "project_id": project_id,
+        "refreshes_on_pipeline_run": True,
+        "note": (
+            "The export was submitted and is still being written, so its dataset id is not "
+            "known yet. Do not export again: that would create a second dataset. Look it up "
+            f"in a moment with the next command (its source reads 'export of view {view_id}')."
+        ),
+    }
+    if name is not None:
+        pending["dataset_name"] = name
+        pending["next"] = f"mammoth dataset find {shlex.quote(str(name))} --project {project_id}"
+    if error.details.get("dataset_id") is not None:
+        pending["dataset_id"] = error.details["dataset_id"]
+    return pending
+
+
 _EXPORTS_LIST_SYMBOL = "mammoth.api.exports.ExportsAPI.list"
 _INTERNAL_DATASET_HANDLER_TYPE = "internal_dataset"