mammoth-cli 2.4.1__tar.gz → 2.4.2__tar.gz

{mammoth_cli-2.4.1 → mammoth_cli-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.4.1
+Version: 2.4.2
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk

{mammoth_cli-2.4.1 → mammoth_cli-2.4.2}/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.4.1"
+__version__ = "2.4.2"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.4.1 → mammoth_cli-2.4.2}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.4.1
+version: 2.4.2
 description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines (join, merge, pivot, filter, clean), dashboards, exports, and handoffs."
 ---
 

{mammoth_cli-2.4.1 → mammoth_cli-2.4.2}/mammoth_cli/commands/view/aggregate.py

@@ -35,7 +35,7 @@ from mammoth_cli.runtime.session import (
     open_service,
     require_project,
 )
-from mammoth_cli.services import read_queries
+from mammoth_cli.services import medians, read_queries
 from mammoth_cli.services.conditions import CONDITION_KWARG, compile_condition
 from mammoth_cli.services.read_queries import ReadContext
 
@@ -198,6 +198,10 @@ def _run_aggregate(
         )
         kwargs[CONDITION_KWARG] = condition
     _forward_optional(document, kwargs, ("sequence",))
+    if medians.requested(document):
+        result = medians.aggregate(reads, fields, condition)
+        rows = read_queries.sort_locally(result["data"], sort)
+        return {**result, "data": rows[:limit] if limit else rows}
     if levels:
         response = read_queries.pivot_with_text_dates(
             reads,
@@ -222,7 +226,9 @@ def view_data_aggregate(invocation: Invocation) -> HandlerResult:
     Read-only: computes and returns the aggregated result without adding a
     task to the view's pipeline or otherwise changing it. Pass exactly one of
     ``aggregations`` (a PIVOT; ``group_by`` is optional) or ``metric`` (a
-    METRIC). ``function`` is one of SUM, COUNT, AVG, MIN, MAX, STDDEV, DISTINCT_COUNT. An optional
+    METRIC). ``function`` is one of SUM, COUNT, AVG, MIN, MAX, STDDEV, DISTINCT_COUNT, MEDIAN.
+    MEDIAN is exact, over a NUMERIC column's non-blank values (``median_note`` says how many
+    blank rows it left out), and goes in a read of its own. An optional
     ``condition`` filters rows before aggregating, and ``sequence`` pins the
     read to a pipeline step (default: latest). ``order_by`` (result labels,
     ``"Total desc"``) with ``top`` ranks the groups on the backend (and adds
@@ -308,9 +314,13 @@ def aggregate_on(
     reads = source.reads
     column_types = reads.column_types
     display_to_internal = reads.display_to_internal
-    levels: dict[int, str] = {}
-    if "aggregations" in document or "group_by" in document:
-        levels = read_queries.text_date_group_levels(document.get("group_by"), column_types)
+    pivot = "aggregations" in document or "group_by" in document
+    levels: dict[int, str] = (
+        read_queries.text_date_group_levels(document.get("group_by"), column_types) if pivot else {}
+    )
+    if medians.requested(document):
+        medians.check(document, column_types, bool(levels))
+    if pivot:
         fields, as_map = _build_pivot_fields(
             _plain_text_date_groups(document, levels, column_types), display_to_internal
         )

{mammoth_cli-2.4.1 → mammoth_cli-2.4.2}/mammoth_cli/runtime/trace.py

@@ -5,7 +5,7 @@ The server already logs every request it serves, with its path, status, latency,
 ``mammoth-cli/<version>``; this module adds a comment naming the command, so the log can
 answer which commands run, from which surface, by which agent, and how they end:
 
-    mammoth-cli/2.4.1 (cmd=view.data.get; inv=3f9c2a1b7d4e; surface=run; agent=claude-code)
+    mammoth-cli/2.4.2 (cmd=view.data.get; inv=3f9c2a1b7d4e; surface=run; agent=claude-code)
 
 ``inv`` is the invocation id: every request one command makes carries the same one, and the
 local run log (:mod:`mammoth_cli.runtime.runlog`) records it as its ``run_id``, so a local

mammoth_cli-2.4.2/mammoth_cli/services/medians.py

@@ -0,0 +1,145 @@
+"""MEDIAN for ``view data aggregate``, computed exactly in the CLI.
+
+The backend's volatile aggregate has no MEDIAN. Paging sorted rows to find the
+middle one is slow and goes wrong on blanks, which sort last but still count. So
+the CLI asks for one COUNT per stored value of the column (per group), drops the
+blank values, and takes the middle of what is left. The result says how many
+blank rows were skipped.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from mammoth_cli.errors.envelope import CODE_INVALID_ARGUMENTS, EXIT_USAGE, CliError
+from mammoth_cli.services.conditions import CONDITION_KWARG
+from mammoth_cli.services.read_queries import ReadContext
+
+MEDIAN = "MEDIAN"
+#: The backend returns at most this many grouped rows.
+BACKEND_ROW_CAP = 40000
+
+
+def _fail(message: str, hint: str = "") -> CliError:
+    return CliError(code=CODE_INVALID_ARGUMENTS, message=message, exit_status=EXIT_USAGE, hint=hint)
+
+
+def _items(document: dict[str, Any]) -> list[dict[str, Any]]:
+    if isinstance(document.get("metric"), dict):
+        return [document["metric"]]
+    aggregations = document.get("aggregations")
+    return (
+        [a for a in aggregations if isinstance(a, dict)] if isinstance(aggregations, list) else []
+    )
+
+
+def requested(document: dict[str, Any]) -> bool:
+    """Whether the read asks for a MEDIAN."""
+    return any(str(item.get("function") or "").upper() == MEDIAN for item in _items(document))
+
+
+def check(document: dict[str, Any], column_types: dict[str, str], text_date_groups: bool) -> None:
+    """Refuse a MEDIAN read this path cannot answer exactly, before any query."""
+    items = _items(document)
+    if any(str(item.get("function") or "").upper() != MEDIAN for item in items):
+        raise _fail(
+            "MEDIAN cannot be mixed with other functions in one read.",
+            "Run the MEDIAN aggregations in their own 'view data aggregate' call.",
+        )
+    if text_date_groups:
+        raise _fail(
+            "MEDIAN cannot be grouped by a date 'part', or by a 'truncate' of a TEXT date.",
+            "Group by a DATE column with 'truncate', or convert the TEXT date with "
+            "'view transform convert-type'.",
+        )
+    for item in items:
+        column = item.get("column")
+        if not column:
+            raise _fail("MEDIAN needs a 'column'.")
+        kind = column_types.get(str(column), "")
+        if kind not in ("", "NUMERIC"):
+            raise _fail(f"MEDIAN needs a NUMERIC column; '{column}' is {kind}.")
+
+
+def _number(value: Any) -> float | None:
+    try:
+        return None if value is None or isinstance(value, bool) else float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def weighted_median(counts: list[tuple[float, int]]) -> float | None:
+    """The median of values given as (value, how many rows hold it); None when empty."""
+    ordered = sorted(counts)
+    total = sum(n for _, n in ordered)
+    if total == 0:
+        return None
+    wanted = [(total - 1) // 2, total // 2]
+    found: list[float] = []
+    seen = 0
+    for value, n in ordered:
+        found.extend(value for position in wanted if seen <= position < seen + n)
+        seen += n
+    return (found[0] + found[1]) / 2
+
+
+def _counts_by_group(
+    reads: ReadContext, column: str, group_by: list[Any], condition: Any
+) -> tuple[dict[tuple[Any, ...], list[tuple[float, int]]], int]:
+    """(value, rows) per group for one column, and how many blank rows were left out."""
+    fields: dict[str, Any] = {
+        "aggregations": [{"function": "COUNT", "as_name": "n"}],
+        "group_by": [*group_by, column],
+        "limit": BACKEND_ROW_CAP,
+    }
+    if condition is not None:
+        fields[CONDITION_KWARG] = condition
+    rows = reads.query(**fields).get("data") or []
+    if len(rows) >= BACKEND_ROW_CAP:
+        raise _fail(
+            "Too many distinct values to take an exact median "
+            f"(the backend returns at most {BACKEND_ROW_CAP} groups).",
+            "Narrow the read with a condition.",
+        )
+    width = len(group_by)
+    counts: dict[tuple[Any, ...], list[tuple[float, int]]] = defaultdict(list)
+    blank = 0
+    for row in rows:
+        key = tuple(row.get(f"group_{i}") for i in range(width))
+        value, n = _number(row.get(f"group_{width}")), int(row.get("agg_0") or 0)
+        bucket = counts[key]  # a group whose values are all blank still gets a row
+        if value is None:
+            blank += n
+        else:
+            bucket.append((value, n))
+    return counts, blank
+
+
+def aggregate(reads: ReadContext, fields: dict[str, Any], condition: Any) -> dict[str, Any]:
+    """Answer a MEDIAN read with rows shaped like the backend's (``group_N``, ``agg_N``/``metric``).
+
+    ``fields`` holds the resolved SDK kwargs (internal column names).
+    """
+    group_by = list(fields.get("group_by") or [])
+    items = [fields["metric"]] if "metric" in fields else list(fields["aggregations"])
+    keys = ["metric"] if "metric" in fields else [f"agg_{i}" for i in range(len(items))]
+    merged: dict[tuple[Any, ...], dict[str, Any]] = {}
+    skipped: dict[str, int] = {}
+    for key, item in zip(keys, items, strict=True):
+        counts, blank = _counts_by_group(reads, item["column"], group_by, condition)
+        if not group_by:
+            counts.setdefault((), [])
+        for group, values in counts.items():
+            row = merged.setdefault(group, {f"group_{i}": v for i, v in enumerate(group)})
+            row[key] = weighted_median(values)
+        if blank:
+            skipped[item["as_name"]] = blank
+    rows = list(merged.values())
+    result: dict[str, Any] = {"data": rows, "row_count": len(rows)}
+    if skipped:
+        named = ", ".join(f"{label}: {n}" for label, n in skipped.items())
+        result["median_note"] = (
+            f"MEDIAN is over non-blank values only; blank rows left out ({named})."
+        )
+    return result

{mammoth_cli-2.4.1 → mammoth_cli-2.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.4.1"
+version = "2.4.2"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"

{mammoth_cli-2.4.1 → mammoth_cli-2.4.2}/spec/manifests/commands/view.yaml

@@ -291,7 +291,8 @@ commands:
   known_restrictions: 'Read-only: computes and returns an aggregated result without adding a task to the
     view''s pipeline or otherwise changing it. Pass exactly one of ''aggregations'' (a PIVOT group-by;
     ''group_by'' is optional) or ''metric'' (a single METRIC value). ''function'' is one of SUM, COUNT,
-    AVG, MIN, MAX, STDDEV, DISTINCT_COUNT. A group_by item is a column name, or {"column": C, "truncate":
+    AVG, MIN, MAX, STDDEV, DISTINCT_COUNT, MEDIAN. MEDIAN is exact over a NUMERIC column''s non-blank
+    values (median_note counts the blank rows left out) and goes in a read of its own. A group_by item is a column name, or {"column": C, "truncate":
     DAY|WEEK|MONTH|QUARTER|YEAR} to bucket a DATE (a trend over time), or {"column": C, "resolution":
     N} to bucket a NUMERIC; grouping by a raw date gives one row per day. A metric is a number: only COUNT
     and DISTINCT_COUNT work on a DATE or TEXT column. For one column''s trend, top values or spread, view

{mammoth_cli-2.4.1 → mammoth_cli-2.4.2}/spec/manifests/compiled/commands.json

@@ -682,7 +682,7 @@
 {"command_id":"view.data-check.get","command_path":"view data-check get","disposition":"command","alias_of":null,"operation_ids":["GetPipelineDataCheck"],"positionals":[{"name":"view_id","type":"int","required":true,"metavar":"VIEW_ID","falls_back_to_field":null,"help":"ID of the view to act on."},{"name":"data_check_id","type":"int","required":true,"metavar":"DATA_CHECK_ID","falls_back_to_field":null,"help":"ID of the data check."},{"name":"dataset_id","type":"int","required":false,"metavar":"DATASET_ID","falls_back_to_field":"dataset_id","help":"ID of the dataset the view belongs to; resolved from the view when omitted."}],"options":[],"sdk_symbol":"mammoth.api.data_checks.DataChecksAPI.get","sdk_conversion":"Call mammoth.api.data_checks.DataChecksAPI.get with validated request fields.","request_model":"ViewDataCheckGetRequest","result_model":"ViewDataCheckGetResult","mutation_class":"read","confirmation":"none","wait_policy":"not_async","pagination_policy":"none","acceptance_evidence":"live_read_only","live_test":"LT-VIEW-DATA-CHECK-GET","live_exemption_reason":null,"contract_fixture":null,"required_fixture_guard":null,"secret_fields":[],"human_example":"mammoth view data-check get VIEW_ID DATA_CHECK_ID --help","agent_example":"mammoth view data-check get 123 456 789","unit_tests":["UT-VIEW-DATA-CHECK-GET"],"contract_tests":["CT-VIEW-DATA-CHECK-GET-HUMAN","CT-VIEW-DATA-CHECK-GET-JSON","CT-VIEW-DATA-CHECK-GET-ERROR"],"draft_test":null,"undo_test":null,"known_restrictions":null,"reviewed_by":"primary","output_schema":"openapi"},
 {"command_id":"view.data-check.list","command_path":"view data-check list","disposition":"command","alias_of":null,"operation_ids":["GetPipelineDataChecks"],"positionals":[{"name":"view_id","type":"int","required":true,"metavar":"VIEW_ID","falls_back_to_field":null,"help":"ID of the view to act on."},{"name":"dataset_id","type":"int","required":false,"metavar":"DATASET_ID","falls_back_to_field":"dataset_id","help":"ID of the dataset the view belongs to; resolved from the view when omitted."}],"options":[],"sdk_symbol":"mammoth.api.data_checks.DataChecksAPI.list","sdk_conversion":"Call mammoth.api.data_checks.DataChecksAPI.list with validated request fields.","request_model":"ViewDataCheckListRequest","result_model":"ViewDataCheckListResult","mutation_class":"read","confirmation":"none","wait_policy":"not_async","pagination_policy":"single_page","acceptance_evidence":"live_read_only","live_test":"LT-VIEW-DATA-CHECK-LIST","live_exemption_reason":null,"contract_fixture":null,"required_fixture_guard":null,"secret_fields":[],"human_example":"mammoth view data-check list VIEW_ID --help","agent_example":"mammoth view data-check list 123 456","unit_tests":["UT-VIEW-DATA-CHECK-LIST"],"contract_tests":["CT-VIEW-DATA-CHECK-LIST-HUMAN","CT-VIEW-DATA-CHECK-LIST-JSON","CT-VIEW-DATA-CHECK-LIST-ERROR"],"draft_test":null,"undo_test":null,"known_restrictions":null,"reviewed_by":"primary","output_schema":"openapi"},
 {"command_id":"view.data-check.update","command_path":"view data-check update","disposition":"command","alias_of":null,"operation_ids":["EditDatacheck"],"positionals":[{"name":"view_id","type":"int","required":true,"metavar":"VIEW_ID","falls_back_to_field":null,"help":"ID of the view to act on."},{"name":"data_check_id","type":"int","required":true,"metavar":"DATA_CHECK_ID","falls_back_to_field":null,"help":"ID of the data check."},{"name":"dataset_id","type":"int","required":false,"metavar":"DATASET_ID","falls_back_to_field":"dataset_id","help":"Exact parent dataset ID. Required for this command: pass it here or as the 'dataset_id' input field; only read commands may omit it and discover the parent."}],"options":[],"sdk_symbol":"mammoth.api.data_checks.DataChecksAPI.update","sdk_conversion":"Call mammoth.api.data_checks.DataChecksAPI.update with validated request fields.","request_model":"ViewDataCheckUpdateRequest","result_model":"ViewDataCheckUpdateResult","mutation_class":"benign_mutation","edits_target":true,"undo":{"strategy":"irreversible","reason":"Overwrites the view data check; the earlier value is not kept, so it cannot be restored."},"confirmation":"none","wait_policy":"not_async","pagination_policy":"none","acceptance_evidence":"live_disposable_project","live_test":"LT-VIEW-DATA-CHECK-UPDATE","live_exemption_reason":null,"contract_fixture":null,"required_fixture_guard":null,"secret_fields":[],"human_example":"mammoth view data-check update VIEW_ID DATA_CHECK_ID --help","agent_example":"mammoth view data-check update 123 456 789 --input '{\"body\": {\"patches\": [{\"op\": \"command\", \"path\": \"disable\", \"value\": null}]}}'","unit_tests":["UT-VIEW-DATA-CHECK-UPDATE"],"contract_tests":["CT-VIEW-DATA-CHECK-UPDATE-HUMAN","CT-VIEW-DATA-CHECK-UPDATE-JSON","CT-VIEW-DATA-CHECK-UPDATE-ERROR"],"draft_test":null,"undo_test":null,"known_restrictions":"patches are {op: command, path: enable|disable, value: null} or {op: replace, path: spec, value: AddDataCheckSpec}, the same body the web app sends. On release the PATCH returns HTTP 500 (outcome_unknown) from backend validation that runs after the change is committed; read the check back with view data-check get before retrying.","reviewed_by":"primary","output_schema":{"ref":"WriteResult"},"readback":{"command":"view.data-check.get","ids":{"view_id":"positional.0","data_check_id":"positional.1"},"kind":"object"}},
-{"command_id":"view.data.aggregate","command_path":"view data aggregate","disposition":"command","alias_of":null,"operation_ids":["ExecuteVolatileQuery"],"positionals":[{"name":"view_id","type":"int","required":true,"metavar":"VIEW_ID","falls_back_to_field":null,"help":"ID of the view to act on."},{"name":"dataset_id","type":"int","required":false,"metavar":"DATASET_ID","falls_back_to_field":"dataset_id","help":"ID of the dataset the view belongs to; resolved from the view when omitted."}],"options":[],"sdk_symbol":"mammoth.api.dataviews.DataviewsAPI.aggregate","sdk_conversion":"Call mammoth.api.dataviews.DataviewsAPI.aggregate with validated request fields.","request_model":"ViewDataAggregateRequest","result_model":"ViewDataAggregateResult","mutation_class":"read","confirmation":"none","wait_policy":"always_wait","pagination_policy":"none","acceptance_evidence":"contract_only_no_disposable_fixture","live_test":null,"live_exemption_reason":"No automated disposable-view fixture wired into tests/live yet for this command.","contract_fixture":null,"required_fixture_guard":null,"secret_fields":[],"human_example":"mammoth view data aggregate VIEW_ID --help","agent_example":"mammoth view data aggregate 123 456 --input '{\"group_by\": [\"Channel\"], \"aggregations\": [{\"column\": \"Spend\", \"function\": \"SUM\", \"as_name\": \"Total Spend\"}]}'","unit_tests":["UT-VIEW-DATA-AGGREGATE"],"contract_tests":["CT-VIEW-DATA-AGGREGATE-HUMAN","CT-VIEW-DATA-AGGREGATE-JSON","CT-VIEW-DATA-AGGREGATE-ERROR"],"draft_test":null,"undo_test":null,"known_restrictions":"Read-only: computes and returns an aggregated result without adding a task to the view's pipeline or otherwise changing it. Pass exactly one of 'aggregations' (a PIVOT group-by; 'group_by' is optional) or 'metric' (a single METRIC value). 'function' is one of SUM, COUNT, AVG, MIN, MAX, STDDEV, DISTINCT_COUNT. A group_by item is a column name, or {\"column\": C, \"truncate\": DAY|WEEK|MONTH|QUARTER|YEAR} to bucket a DATE (a trend over time), or {\"column\": C, \"resolution\": N} to bucket a NUMERIC; grouping by a raw date gives one row per day. A metric is a number: only COUNT and DISTINCT_COUNT work on a DATE or TEXT column. For one column's trend, top values or spread, view data explore is the shorter call. order_by (result labels; a string like 'Total desc' or {column, direction}) with top ranks the groups on the backend; a limit without order_by keeps arbitrary rows and the result says ordered false. A group_by truncate on a TEXT column of dates is bucketed by the CLI: the stored format is detected from the data and stated in text_dates, an ambiguous day/month order (settle it with text_date_format) or an unreadable value fails loud, and a range condition (GT, GTE, LT, LTE, IN_RANGE with a YYYY-MM-DD value) on such a column works the same way. A truncate on a NUMERIC column, or a resolution on a non-NUMERIC one, is refused. To group by the part of a date, give {\"column\": C, \"part\": weekday|day|month|quarter|year} on a DATE or TEXT-date column: the groups are named (Monday, January, Q1) and in calendar order. This is the read-only way to answer by-weekday and by-month questions. An empty result carries observed_range: the min and max of the filtered or date column.","reviewed_by":"primary","output_schema":{"ref":"OpenObject"}},
+{"command_id":"view.data.aggregate","command_path":"view data aggregate","disposition":"command","alias_of":null,"operation_ids":["ExecuteVolatileQuery"],"positionals":[{"name":"view_id","type":"int","required":true,"metavar":"VIEW_ID","falls_back_to_field":null,"help":"ID of the view to act on."},{"name":"dataset_id","type":"int","required":false,"metavar":"DATASET_ID","falls_back_to_field":"dataset_id","help":"ID of the dataset the view belongs to; resolved from the view when omitted."}],"options":[],"sdk_symbol":"mammoth.api.dataviews.DataviewsAPI.aggregate","sdk_conversion":"Call mammoth.api.dataviews.DataviewsAPI.aggregate with validated request fields.","request_model":"ViewDataAggregateRequest","result_model":"ViewDataAggregateResult","mutation_class":"read","confirmation":"none","wait_policy":"always_wait","pagination_policy":"none","acceptance_evidence":"contract_only_no_disposable_fixture","live_test":null,"live_exemption_reason":"No automated disposable-view fixture wired into tests/live yet for this command.","contract_fixture":null,"required_fixture_guard":null,"secret_fields":[],"human_example":"mammoth view data aggregate VIEW_ID --help","agent_example":"mammoth view data aggregate 123 456 --input '{\"group_by\": [\"Channel\"], \"aggregations\": [{\"column\": \"Spend\", \"function\": \"SUM\", \"as_name\": \"Total Spend\"}]}'","unit_tests":["UT-VIEW-DATA-AGGREGATE"],"contract_tests":["CT-VIEW-DATA-AGGREGATE-HUMAN","CT-VIEW-DATA-AGGREGATE-JSON","CT-VIEW-DATA-AGGREGATE-ERROR"],"draft_test":null,"undo_test":null,"known_restrictions":"Read-only: computes and returns an aggregated result without adding a task to the view's pipeline or otherwise changing it. Pass exactly one of 'aggregations' (a PIVOT group-by; 'group_by' is optional) or 'metric' (a single METRIC value). 'function' is one of SUM, COUNT, AVG, MIN, MAX, STDDEV, DISTINCT_COUNT, MEDIAN. MEDIAN is exact over a NUMERIC column's non-blank values (median_note counts the blank rows left out) and goes in a read of its own. A group_by item is a column name, or {\"column\": C, \"truncate\": DAY|WEEK|MONTH|QUARTER|YEAR} to bucket a DATE (a trend over time), or {\"column\": C, \"resolution\": N} to bucket a NUMERIC; grouping by a raw date gives one row per day. A metric is a number: only COUNT and DISTINCT_COUNT work on a DATE or TEXT column. For one column's trend, top values or spread, view data explore is the shorter call. order_by (result labels; a string like 'Total desc' or {column, direction}) with top ranks the groups on the backend; a limit without order_by keeps arbitrary rows and the result says ordered false. A group_by truncate on a TEXT column of dates is bucketed by the CLI: the stored format is detected from the data and stated in text_dates, an ambiguous day/month order (settle it with text_date_format) or an unreadable value fails loud, and a range condition (GT, GTE, LT, LTE, IN_RANGE with a YYYY-MM-DD value) on such a column works the same way. A truncate on a NUMERIC column, or a resolution on a non-NUMERIC one, is refused. To group by the part of a date, give {\"column\": C, \"part\": weekday|day|month|quarter|year} on a DATE or TEXT-date column: the groups are named (Monday, January, Q1) and in calendar order. This is the read-only way to answer by-weekday and by-month questions. An empty result carries observed_range: the min and max of the filtered or date column.","reviewed_by":"primary","output_schema":{"ref":"OpenObject"}},
 {"command_id":"view.data.compare","output_schema":{"ref":"ViewDataCompare"},"command_path":"view data compare","disposition":"command","alias_of":null,"operation_ids":["ExecuteVolatileQuery"],"positionals":[{"name":"view_id_a","type":"int","required":true,"metavar":"VIEW_ID_A","falls_back_to_field":null,"help":"ID of the first view to compare."},{"name":"view_id_b","type":"int","required":true,"metavar":"VIEW_ID_B","falls_back_to_field":null,"help":"ID of the second view to compare."}],"options":[],"sdk_symbol":"mammoth.api.dataviews.DataviewsAPI.aggregate","sdk_conversion":"Runs view.data.aggregate's own handler once per view (which calls mammoth.api.dataviews.DataviewsAPI.aggregate), then joins client-side; recorded here so discovery advertises the same accepted document fields view.data.aggregate does, not this command's own dispatch (see _VIEW_DATA_COMPARE_FIELDS in command_contract.py).","request_model":"ViewDataCompareRequest","result_model":"ViewDataCompareResult","mutation_class":"read","confirmation":"none","wait_policy":"not_async","pagination_policy":"none","acceptance_evidence":"live_read_only","live_test":null,"live_exemption_reason":"Delegates to view.data.aggregate's own live coverage for the actual SDK call; the join/compare step itself is local and deterministic.","contract_fixture":null,"required_fixture_guard":null,"secret_fields":[],"human_example":"mammoth view data compare VIEW_ID_A VIEW_ID_B --help","agent_example":"mammoth view data compare 111 222 --input '{\"group_by\": [\"Campaign\"], \"aggregations\": [{\"column\": \"Spend\", \"function\": \"SUM\", \"as_name\": \"Spend\"}]}'","unit_tests":["UT-VIEW-DATA-COMPARE"],"contract_tests":["CT-VIEW-DATA-COMPARE"],"draft_test":null,"undo_test":null,"known_restrictions":"Every number reported to the user comes from a tool result: use this to compare the same PIVOT/METRIC aggregate across two views (e.g. two platforms' totals per campaign) instead of subtracting two 'view data aggregate' reads by hand -- calc is the tool for a single expression. Takes the exact same --input shape as view data aggregate (aggregations/group_by, or metric); rows are joined on the group-by key (or compared as a single row for a bare metric) using exact Decimal arithmetic. A key present in only one view's result is not an error: 'only_in_first' and 'only_in_second' give its exact count and the first 25 rows, and 'rows' holds the keys both views have.","reviewed_by":"primary"},
 {"command_id":"view.data.drivers","output_schema":{"ref":"OpenObject"},"command_path":"view data drivers","disposition":"command","alias_of":null,"operation_ids":[],"positionals":[{"name":"view_id","type":"int","required":true,"metavar":"VIEW_ID","falls_back_to_field":null,"help":"ID of the view whose figures rose or dropped: the change to explain."},{"name":"dataset_id","type":"int","required":false,"metavar":"DATASET_ID","falls_back_to_field":null,"help":"ID of the dataset the view belongs to; resolved from the view when omitted."}],"options":[],"sdk_symbol":"mammoth_cli.commands.view_drivers.view_data_drivers","sdk_conversion":"Runs view data aggregate's own helpers (mammoth.api.dataviews.DataviewsAPI.aggregate) once per 'by' column, grouped by that column and a date bucket over both periods, then splits the buckets into the two periods client-side; the accepted document fields are the view.data.drivers entry of _LOCAL_CONTRACT_FIELDS in command_contract.py.","request_model":"ViewDataDriversRequest","result_model":"ViewDataDriversResult","mutation_class":"read","confirmation":"none","wait_policy":"not_async","pagination_policy":"none","acceptance_evidence":"live_read_only","live_test":null,"live_exemption_reason":"Read-only composite over view.data.aggregate's live-covered SDK call; the period split and ranking are local and unit-tested.","contract_fixture":null,"required_fixture_guard":null,"secret_fields":[],"human_example":"mammoth view data drivers VIEW_ID --help","agent_example":"mammoth view data drivers 123 --input '{\"measure\": {\"column\": \"revenue\", \"function\": \"SUM\"}, \"date_column\": \"sale_date\", \"compare\": [\"2026-07\", \"2026-08\"], \"by\": [\"store\", \"category\"]}'","unit_tests":["UT-VIEW-DATA-DRIVERS"],"contract_tests":["CT-VIEW-DATA-DRIVERS-HUMAN","CT-VIEW-DATA-DRIVERS-JSON","CT-VIEW-DATA-DRIVERS-ERROR"],"draft_test":null,"undo_test":null,"known_restrictions":"Read-only. Use this, not a series of view data aggregate reads, for \"why did X drop/rise\", \"what drove the change between July and August\", \"explain the decline\": one call returns the total for each period, the change and its percentage, whether it came from volume (the row count) or value (value per row), and per 'by' column the groups that moved most with their signed share_of_change. --input: \"measure\" {\"column\", \"function\": SUM or COUNT}; \"date_column\"; \"compare\" [A, B], each 'YYYY-MM', 'YYYY-Qn', 'YYYY' or {\"from\": \"YYYY-MM-DD\", \"to\": \"YYYY-MM-DD\"} (the change is read from A to B; any other form is refused); \"by\" 1 to 3 columns; optional \"conditions\" in view data aggregate's condition shape. partial_period names a period the data does not cover to its end (or from its start): say it is incomplete, never compare it as a whole period. Answer with the total change first, then the top contributors with their share, then volume vs value. Amounts carry the currency in 'currency'; when it is null give plain numbers and never invent a currency.","reviewed_by":"primary"},
 {"command_id":"view.data.explore","output_schema":{"ref":"OpenObject"},"command_path":"view data explore","disposition":"command","alias_of":null,"operation_ids":["ExecuteVolatileQuery"],"positionals":[{"name":"view_id","type":"int","required":true,"metavar":"VIEW_ID","falls_back_to_field":null,"help":"ID of the view to act on."},{"name":"column","type":"str","required":true,"metavar":"COLUMN","falls_back_to_field":null,"help":"Display name of the column to explore."},{"name":"dataset_id","type":"int","required":false,"metavar":"DATASET_ID","falls_back_to_field":"dataset_id","help":"ID of the dataset the view belongs to; resolved from the view when omitted."}],"options":[],"sdk_symbol":"mammoth.api.dataviews.DataviewsAPI.explore","sdk_conversion":"Call mammoth.api.dataviews.DataviewsAPI.explore with validated request fields.","request_model":"ViewDataExploreRequest","result_model":"ViewDataExploreResult","mutation_class":"read","confirmation":"none","wait_policy":"always_wait","pagination_policy":"none","acceptance_evidence":"contract_only_no_disposable_fixture","live_test":null,"live_exemption_reason":"No automated disposable-view fixture wired into tests/live yet for this command.","contract_fixture":null,"required_fixture_guard":null,"secret_fields":[],"human_example":"mammoth view data explore VIEW_ID COLUMN --help","agent_example":"mammoth view data explore 123 Status 456","unit_tests":["UT-VIEW-DATA-EXPLORE"],"contract_tests":["CT-VIEW-DATA-EXPLORE-HUMAN","CT-VIEW-DATA-EXPLORE-JSON","CT-VIEW-DATA-EXPLORE-ERROR"],"draft_test":null,"undo_test":null,"known_restrictions":"Read-only: reads one column's value distribution -- trend, distribution, histogram, or top values. It does not open or change any card in the UI; to open Explore cards use 'view explore-panel set'. It reads without adding a task to the view's pipeline (never use 'view transform pivot' just to explore). DATE column: counts per 'level' bucket (AUTO default; SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR, DECADE, CENTURY, MILLENNIUM) for \"what's trending\", \"over time\", \"by month\", \"by year\". NUMERIC column: counts per 'level' resolution (AUTO default; a power of 10) for a distribution or histogram. TEXT column: top values by count, 'limit' default 20 -- \"what's in this column\". Every bucket has 'count' and 'percentage' of the total. 'row_count' is the number of unique values (buckets). Options (--input): 'metric' {\"column\",\"function\"} adds a per-bucket SUM, COUNT, AVG, MIN, MAX, STDDEV or DISTINCT_COUNT over another column (the custom card); 'condition' filters rows first -- include/exclude values, blanks, a date or number range, text contains -- and several cards' selections combine as one AND condition (cross-filter); drill down by re-running at a finer 'level' with a 'condition' on the chosen bucket's range; 'percentage_of' \"metric\" makes 'percentage' the share of the 'metric' total (default: of the count); 'sort' count_desc, count_asc, value_asc, value_desc, metric_desc or metric_asc (blanks last; the card puts them first); 'limit' and 'offset' page the buckets (\"load more\"); 'range' true adds the exact earliest and latest value of a DATE or NUMERIC column under the same condition; '-o csv' prints the buckets as CSV; 'sequence' explores at a pipeline step. To exclude a value the way the card does (blank rows stay), use or(NE value, IS_EMPTY on that column): a plain NE, NOT_IN_LIST or not drops blank rows. To put the card on a dashboard, say it in words: 'dashboard chat edit DASHBOARD_ID' (prompt) or 'dashboard v3 generate'. Search several columns for text: or of CONTAINS per text column. Replace all values like this: 'view transform replace'. Related: distinct raw values of a DATE/NUMERIC column, a summary (min/max/sum/avg) or a matching-row count -> 'view data aggregate'; keep the filter as a pipeline step -> 'view transform filter'; save it as a new view -> 'view create' then 'view transform filter' on it; download all rows -> 'view export csv'. A TEXT column of dates takes a level (or column_type DATE): the format is detected from the data and stated in text_dates; ambiguous or unreadable dates fail loud. A column_type that disagrees with the stored type is refused, never dropped. Example: --input '{\"level\": \"MONTH\", \"condition\": {\"column\": \"Results\", \"operator\": \"EQ\", \"value\": \"Fail\"}}'. A figure for a period (year, quarter, month) is one explore of the DATE column with level YEAR, QUARTER or MONTH and a metric {\"column\": AMOUNT, \"function\": \"SUM\"}: it returns one figure per period and the date range the data covers, so no rows need paging. cumulative true adds a running total; keep one year or range with condition, for a year {\"column\": DATE_COLUMN, \"operator\": \"=\", \"value\": 2017, \"component\": \"year\"}. Figures come back rounded to two decimals: quote them as returned.","reviewed_by":"primary"},