mammoth-cli 2.0.37__tar.gz → 2.0.39__tar.gz

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.37
+Version: 2.0.39
 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.8,>=0.7.16
+Requires-Dist: mammoth-io<0.8,>=0.7.17
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.37
+version: 2.0.39
 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."
 ---
 
@@ -76,17 +76,49 @@ mammoth view transform --help              # every data transformation
 | Blanks to a constant, or to the previous row's value | `view transform set-values` (`IS_EMPTY`), `view transform fill-missing` |
 | Clean text | `view transform text`, `replace`, `bulk-replace` |
 | Change a column's type | `view transform convert-type` |
+| Rename a column, sort the rows (view settings, not tasks) | `view transform rename-columns`, `view transform sort` |
 | Rank, running total, previous row | `view transform window` |
 | A dashboard | `dashboard create-blank` ([dashboards](references/recipes/dashboards.md)) |
 | Deliver the rows | `view export csv`, `view export postgres` (and other destinations), `view export dataset` |
 
 A search with no full match returns `suggestions` and a `hint`. Before you
 conclude the CLI cannot do something the web app does, check
-`view transform --help` and "Not a pipeline step" in
+`view transform --help` and "View settings, and what has no command" in
 [about Mammoth](references/about-mammoth.md). Do not switch to the web app
 in a browser, or compute the result locally, for work the CLI covers;
 report a real gap with the command you tried.
 
+## Several files, one deliverable
+
+Users often upload related files without saying how they relate ("make a
+dashboard from t_a and t_b"). Work it out from the data before you build:
+
+1. Upload every file, then read every view in Mammoth (not the local
+   files): `view get VIEW_ID` (columns, types, row count) and `view data get
+   VIEW_ID`. The data read lists `column_warnings`: numbers or dates stored
+   as text, and blanks, each with the fix.
+2. Find the keys. A column in one view whose values appear in a column of
+   the other (`customer_id` and `id`, `order_ref` and `order_no`) is a
+   foreign key; the view with many rows per key is the main one.
+3. Make the keys match before the join: same type (`convert-type`), same
+   case and padding (`text`), no blanks (`set-values`, `filter`).
+4. Act on every `column_warnings` entry for a column the deliverable uses:
+   run its `fix` (`convert-type` to `NUMERIC` or `DATE`; the values that are
+   not numbers become empty), then decide on blanks (fill, filter, or keep and
+   say so). A text `price` cannot be summed on a dashboard.
+5. `view transform join` the lookup view into the main view (`LEFT`). The
+   result's `join_check` gives `match_rate`, `unmatched_rows` and
+   `unmatched_keys`; put them in your report, and stop to compare the keys
+   if more than a few rows found no match.
+6. Build the dashboard from the joined view
+   ([dashboards](references/recipes/dashboards.md)).
+
+For the defaults that most pipelines use (new column or overwrite, `LEFT`
+joins, date steps), see
+[transforms](references/recipes/transforms.md#what-most-pipelines-look-like).
+Say what you inferred (which columns you joined on, what you converted) in
+your report. If no column links the files, ask before you combine them.
+
 ## Calling a command
 
 - Ids are positionals; request fields are one `--input '{...}'` document;
@@ -125,6 +157,10 @@ report a real gap with the command you tried.
   target column *before* the change so the after-read has a comparison.
 - A uniform result (every amount 0, every region "Unknown", most join rows
   unmatched) means the previous step went wrong; stop and re-inspect it.
+- `column_warnings` on a data read and `join_check` on a join are findings,
+  not decoration: fix each one the deliverable depends on, or say in the
+  report why you kept it. `view data get` pages with `{"offset": 51,
+  "limit": 50}`.
 - A timeout, exit 7 or interruption does not prove failure; reconcile an
   `outcome_unknown` (`job get`, `view task list`) before replaying.
 - Run the [report checklist](references/report-checklist.md) before stating

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/about-mammoth.md

@@ -100,6 +100,8 @@ Checkpoint Alert are the `view data-check` and `view checkpoint` families.
 | Shift a date by an interval | Add / Subtract Date Values | `increment-date` |
 | Add an empty column | Add Column | `add-column` |
 | Copy a column under a new name | Copy Columns | `copy-columns` |
+| Rename a column | Rename (column header) | `rename-columns` (a view setting, not a task) |
+| Sort the rows | Sort (grid) | `sort` (a view setting, not a task) |
 | Remove columns | Remove Column | `delete-columns` |
 | Add columns from another view by matching keys | Join | `join` (`INNER`, `LEFT`, `RIGHT`, `OUTER`) |
 | Bring one value per key from another view | Lookup | `lookup` |
@@ -117,15 +119,24 @@ value per key into one new column. Before either, confirm the key columns
 in both views have the same type and values; recipes/transforms.md has the
 read-back.
 
-## Not a pipeline step, and the nearest route
+## View settings, and what has no command
+
+Two commands change how the view shows its rows, not the rows. They add no
+pipeline task, like their web counterparts (a column-header rename, a grid
+sort):
+
+- **Rename a column:** `view transform rename-columns` with `{"renames":
+  {"cust_id": "Customer ID"}}`. The column keeps its internal name, so
+  earlier tasks keep working; later commands, data reads, exports and
+  dashboards use the new name. To name a column you create, use its
+  `new_column` or `as_name` field instead.
+- **Sort the rows:** `view transform sort` with `{"order_by": [["Revenue",
+  "DESC"]]}` (up to three columns; `[]` clears it). Data reads and exports
+  return rows in this order. To keep only the top N rows, use `limit-rows`
+  with `order_by`; for a rank column, `window` (`RANK`, `ROW_NUMBER`).
+
+No command:
 
-- **Rename a column.** The web app's rename is a display change, not a
-  task; the CLI has no rename command. Name new columns when you create them
-  (`new_column`, `as_name`); for an existing column, `copy-columns` under
-  the new name.
-- **Sort.** There is no sort task, and the CLI has no sort command. For
-  "top N by X" use `limit-rows` with `order_by`; for a rank column use
-  `window` (`RANK`, `ROW_NUMBER`).
 - **Union or append two views.** There is no union task. Upload a file into
   an existing dataset with `append_to_ds_id`, or send a view's rows into an
   existing dataset with `view export dataset` (`target_ds_id` and
@@ -139,6 +150,6 @@ Both call the same API. Do not switch to the web app in a browser for a
 task the CLI covers. Before you conclude that the CLI cannot do something,
 run `mammoth view transform --help`, search in plain words (`mammoth schema
 find "merge two datasets"` finds `join`; a search with no full match lists
-`suggestions`), and read the section above. If it is still missing, report
-the gap with the command you tried; do not work around it in the browser or
-by computing the result locally.
+`suggestions`), and read "View settings, and what has no command" above.
+If it is still missing, report the gap with the command you tried; do not
+work around it in the browser or by computing the result locally.

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -1,7 +1,7 @@
 # What is proven on release
 
 Generated from `docs/release-capability-matrix.json`; do not edit by hand.
-The CLI publishes 554 commands. 455 of them bind one of the 528 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (every `view transform *` command submits through `view.task.add`). 262 bound commands ran once successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer.
+The CLI publishes 556 commands. 455 of them bind one of the 528 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (`view transform *` commands submit through `view.task.add`, except `rename-columns` and `sort`, which set view display properties through `view.update`). 262 bound commands ran once successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer.
 
 Status meanings:
 

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/command-index.md

@@ -1,6 +1,6 @@
 # Published CLI command catalog
 
-This generated catalog is a lookup table for every command in the published CLI manifest, currently 554; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
+This generated catalog is a lookup table for every command in the published CLI manifest, currently 556; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
 
 Load only the applicable domain file:
 
@@ -43,7 +43,7 @@ Load only the applicable domain file:
 - [upgrade](commands/upgrade.md) — 1 published commands
 - [user](commands/user.md) — 8 published commands
 - [version](commands/version.md) — 1 published commands
-- [view](commands/view.md) — 116 published commands
+- [view](commands/view.md) — 118 published commands
 - [webhook](commands/webhook.md) — 7 published commands
 - [workflow](commands/workflow.md) — 16 published commands
 - [workspace](commands/workspace.md) — 20 published commands

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -1034,6 +1034,16 @@ Result: `ViewTransformPivotResult`; mutation `reversible_pipeline`, confirmation
 
 Status on release: ran once on CLI 2.0.18 through `view.task.add` and was read back with `view data get`; other inputs for this transform are untried.
 
+### `view.transform.rename-columns`
+
+Run: `mammoth view transform rename-columns`. Exact input fields: `mammoth schema get view.transform.rename-columns`.
+
+Example: `mammoth view transform rename-columns 123 --input '{"renames": {"cust_id": "Customer ID"}, "dataset_id": 456}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `ViewTransformRenameColumnsResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; it submits through `view.task.add`, but this transform was not among those run.
+
 ### `view.transform.replace`
 
 Run: `mammoth view transform replace`. Exact input fields: `mammoth schema get view.transform.replace`.
@@ -1064,6 +1074,16 @@ Result: `ViewTransformSmallLargeResult`; mutation `reversible_pipeline`, confirm
 
 Status on release: untried; it submits through `view.task.add`, but this transform was not among those run.
 
+### `view.transform.sort`
+
+Run: `mammoth view transform sort`. Exact input fields: `mammoth schema get view.transform.sort`.
+
+Example: `mammoth view transform sort 123 --input '{"order_by": [["Revenue", "DESC"]], "dataset_id": 456}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `ViewTransformSortResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; it submits through `view.task.add`, but this transform was not among those run.
+
 ### `view.transform.split`
 
 Run: `mammoth view transform split`. Exact input fields: `mammoth schema get view.transform.split`.

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/end-to-end.md

@@ -22,6 +22,8 @@ mammoth view list CUSTOMERS_DS --project PROJECT_ID # -> CUSTOMERS_VIEW
 # 2. look before you change: column names, types, row_count, a sample
 mammoth view get ORDERS_VIEW ORDERS_DS --project PROJECT_ID
 mammoth view data get ORDERS_VIEW ORDERS_DS --project PROJECT_ID
+#   data.column_warnings: text columns of numbers/dates (with the convert-type fix) and blanks;
+#   plan step 3 from them
 
 # 3. clean orders (each call waits for its job; read back after each value change)
 mammoth view transform discard-duplicates ORDERS_VIEW --project PROJECT_ID \
@@ -43,9 +45,10 @@ mammoth view get ORDERS_VIEW ORDERS_DS --project PROJECT_ID   # row_count before
 # 5. join, then check the match rate before building on it
 mammoth view transform join ORDERS_VIEW --project PROJECT_ID \
   --input '{"dataset_id": ORDERS_DS, "foreign_view": CUSTOMERS_VIEW, "foreign_dataset_id": CUSTOMERS_DS, "join_type": "LEFT", "on": [{"left": "customer_id", "right": "customer_id"}], "select": ["region"]}'
-mammoth view data get ORDERS_VIEW ORDERS_DS --project PROJECT_ID
-#   if region is empty/"Unknown" on most rows, the key does not match: compare the two key columns' values
+#   data.join_check: rows_before/rows_after, match_rate, unmatched_rows, unmatched_keys; report them
+#   if many rows are unmatched, the key does not match: compare the two key columns' values
 #   (type, padding, case) with view data get on both views; do not summarise unmatched data
+#   rows_after > rows_before: a key repeats in the other view (use lookup for one value per key)
 
 # 6. deliverable first: export the cleaned, joined rows before any step that replaces them
 mammoth view export csv ORDERS_VIEW --project PROJECT_ID \

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -73,6 +73,41 @@ mammoth schema get view.transform.join
 mammoth view transform join VIEW_ID --project PROJECT_ID --input INPUT_JSON
 ```
 
+## What most pipelines look like
+
+These patterns come from how Mammoth pipelines are usually built. Use them
+as defaults, and let the user's request override them:
+
+- Keep it short. Most pipelines have one to three steps and touch a few
+  columns. Add only the steps the deliverable needs.
+- New column or overwrite? `set-values`, `math` and `lookup` take
+  `new_column` (add a column) or `existing_column` (replace the values in
+  place), never both. Overwriting is as common as adding. If the user said
+  "fix", "clean" or "change" a column, use `existing_column`. If they said
+  "add", "calculate" or "flag", use `new_column`. If it is not clear, ask.
+- Joins are nearly always `LEFT` on one key column. Use `INNER`, `RIGHT`,
+  `OUTER` or a key of two or more columns only when the user asks for it or
+  the data needs it, and say why in your report.
+- Check the key before a join or lookup. Most keys go in without a prep
+  step, so a type, case or padding difference shows up as unmatched rows. Read
+  both key columns first (`view data get`) and act on `join_check`.
+- Date steps (`increment-date`, `extract-date`, and `text` on date columns)
+  fail more often than other steps. Before a date step, confirm that the
+  column type is `DATE` (`view get`); if it is `TEXT`, run `convert-type`
+  first. Check the result on a few rows.
+- Convert several columns to the same type in one `convert-type` call (one
+  `conversions` entry for each column), not one call for each column.
+- Remove duplicates near the end, after the cleanup and joins, so the check
+  uses the final columns.
+- `filter` also takes a plain-language `prompt` instead of a `condition`.
+  Use a `condition` when the rule is exact (a column, an operator, a value).
+  Use `prompt` only when the user described the rule in words and no exact
+  condition expresses it, then check the kept rows.
+- "Top N" means the largest values first. Use the smallest values first only
+  when the user says "bottom", "lowest" or "smallest".
+- The last step of a pipeline is not a signal that it is finished. Say that
+  the work is done only after you verify the deliverable.
+
 ## Aggregate or summarise
 
 For a grouped summary (totals per region, counts per status) use the typed

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md

@@ -9,11 +9,13 @@ or secrets in an argument, prompt, transcript, or checkpoint.
    from PyPI into a fresh environment and verify it:
 
    ```bash
-   python3 -m venv .mammoth && .mammoth/bin/python -m pip install --upgrade mammoth-cli
+   python3 -m venv .mammoth && .mammoth/bin/python -m pip install --no-cache-dir --upgrade mammoth-cli
    .mammoth/bin/mammoth --version      # or: uv tool install mammoth-cli
    ```
 
-   Pin `mammoth-cli==X.Y.Z` when the task names an approved release. Use the
+   Pin `mammoth-cli==X.Y.Z` when the task names an approved release, and
+   check that `mammoth --version` prints it (a pip cache can serve an older
+   release for a few minutes after a new one is published). Use the
    host installer script (`installers/mammoth-install.sh` in the repository)
    only when the operator names it; do not pipe a remote script to a shell on
    your own initiative. The SDK (`mammoth-io`) comes with the CLI. If a later

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/commands/registry.py

@@ -684,9 +684,11 @@ HANDLERS: dict[str, Handler] = {
     "view.transform.lookup": view_ops_cmd.view_transform_lookup,
     "view.transform.math": view_ops_cmd.view_transform_math,
     "view.transform.pivot": view_ops_cmd.view_transform_pivot,
+    "view.transform.rename-columns": view_ops_cmd.view_transform_rename_columns,
     "view.transform.replace": view_ops_cmd.view_transform_replace,
     "view.transform.set-values": view_ops_cmd.view_transform_set_values,
     "view.transform.small-large": view_ops_cmd.view_transform_small_large,
+    "view.transform.sort": view_ops_cmd.view_transform_sort,
     "view.transform.split": view_ops_cmd.view_transform_split,
     "view.transform.substring": view_ops_cmd.view_transform_substring,
     "view.transform.text": view_ops_cmd.view_transform_text,

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/commands/schema.py

@@ -89,11 +89,11 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "view.transform.convert-type": (
         "convert type cast numeric number text date column parse to number to date"
     ),
-    "view.transform.copy-columns": "copy duplicate rename column into a new column name",
+    "view.transform.copy-columns": "copy duplicate column into a new column",
     "view.transform.crosstab": (
         "crosstab cross tab pivot table matrix rows by columns summary into a new dataset"
     ),
-    "view.transform.date-diff": "date difference days between two date columns age duration",
+    "view.transform.date-diff": "date dates difference days between two date columns age duration",
     "view.transform.delete-columns": "delete drop remove columns",
     "view.transform.discard-duplicates": (
         "duplicate duplicates dedup dedupe deduplicate remove repeated rows unique distinct"
@@ -117,7 +117,7 @@ _COMMAND_DISCOVERY_PURPOSES = {
         "second view views dataset datasets table tables vlookup"
     ),
     "view.transform.json-extract": "json extract parse nested fields keys into columns",
-    "view.transform.limit-rows": "limit top bottom first last n rows order by sorted head",
+    "view.transform.limit-rows": "limit top bottom first last n rows head",
     "view.transform.lookup": (
         "lookup look up vlookup reference table map code to name enrich one value "
         "from another view dataset"
@@ -130,12 +130,19 @@ _COMMAND_DISCOVERY_PURPOSES = {
         "pivot group by aggregate aggregation sum count average summary summarize "
         "summarise per region total"
     ),
+    "view.transform.rename-columns": (
+        "rename column columns header headers relabel change column name names title"
+    ),
     "view.transform.replace": "find replace substitute text value in columns",
     "view.transform.set-values": (
         "set values assign overwrite blank empty default where condition label "
         "category bucket flag if then conditional value"
     ),
     "view.transform.small-large": "nth smallest largest value across columns",
+    "view.transform.sort": (
+        "sort sorting order rows by column ascending descending asc desc arrange "
+        "highest lowest newest oldest latest earliest date dates alphabetical"
+    ),
     "view.transform.split": "split column by delimiter separator into columns",
     "view.transform.substring": "substring left right characters regex pattern extract part text",
     "view.transform.text": (
@@ -404,7 +411,12 @@ def _tokens(value: str) -> frozenset[str]:
 
 
 def _query_tokens(query: str) -> tuple[str, ...]:
-    return tuple(token for token in _tokens(query) if token not in _DISCOVERY_STOPWORDS)
+    # Bare numbers ("top 10") are values, not intent words.
+    return tuple(
+        token
+        for token in _tokens(query)
+        if token not in _DISCOVERY_STOPWORDS and not token.isdigit()
+    )
 
 
 def _token_aliases(token: str) -> frozenset[str]:

{mammoth_cli-2.0.37 → mammoth_cli-2.0.39}/mammoth_cli/commands/view.py

@@ -46,6 +46,7 @@ from mammoth_cli.runtime.confirm import (
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, require_project
 from mammoth_cli.services.conditions import CONDITION_KWARG, compile_condition
+from mammoth_cli.services.data_quality import column_warnings
 
 HandlerResult = tuple[Any, dict[str, Any]]
 
@@ -252,10 +253,33 @@ BRIEF_VIEW_FIELDS: tuple[str, ...] = (
 )
 
 
+def apply_column_renames(record: Any) -> Any:
+    """Show renamed columns under their new names in a dataview record.
+
+    A rename (``view transform rename-columns`` or the web grid) is stored in
+    ``display_properties.COLUMN_NAMES`` as ``{internal_name: name}``; the
+    server's ``metadata`` keeps the name the pipeline produced. Every CLI
+    output uses the name the user sees, so the rename wins.
+    """
+    if not isinstance(record, dict):
+        return record
+    display = record.get("display_properties")
+    renames = display.get("COLUMN_NAMES") if isinstance(display, dict) else None
+    metadata = record.get(_METADATA_KEY)
+    if not isinstance(renames, dict) or not renames or not isinstance(metadata, list):
+        return record
+    columns = []
+    for column in metadata:
+        new_name = renames.get(column.get(_INTERNAL_NAME_KEY)) if isinstance(column, dict) else None
+        columns.append({**column, _DISPLAY_NAME_KEY: new_name} if new_name else column)
+    return {**record, _METADATA_KEY: columns}
+
+
 def brief_view_record(record: Any) -> Any:
-    """Keep only :data:`BRIEF_VIEW_FIELDS` of a dataview record."""
+    """Keep only :data:`BRIEF_VIEW_FIELDS` of a dataview record, renames applied."""
     if not isinstance(record, dict):
         return record
+    record = apply_column_renames(record)
     return {key: record[key] for key in BRIEF_VIEW_FIELDS if key in record}
 
 
@@ -369,6 +393,7 @@ def _dataview_metadata(
         )
     except Exception:  # noqa: BLE001 -- labels are a presentation nicety, never fatal
         return []
+    info = apply_column_renames(info)
     metadata = info.get(_METADATA_KEY) if isinstance(info, dict) else None
     if not isinstance(metadata, list):
         return []
@@ -400,7 +425,7 @@ def _compile_query_filters(
     project_id: int | None,
     document: dict[str, Any],
     kwargs: dict[str, Any],
-) -> dict[str, str] | None:
+) -> tuple[dict[str, str] | None, dict[str, str] | None]:
     """Translate a data query's ``condition`` and ``columns`` to the wire format.
 
     The data route takes the backend condition shape (``{internal: {OP: ...}}``,
@@ -409,11 +434,11 @@ def _compile_query_filters(
     only have one key". The spec is compiled through the shared condition
     service and built against the view's display -> internal name and type
     maps, and ``columns`` given as display names are mapped the same way.
-    Returns the internal -> display map when metadata was fetched, so the row
-    relabelling can reuse it.
+    Returns the internal -> display map and the display -> type map when
+    metadata was fetched, so the row relabelling and checks can reuse them.
     """
     if CONDITION_KWARG not in document and "columns" not in document:
-        return None
+        return None, None
     metadata = _dataview_metadata(service, dataset_id, dataview_id, project_id)
     column_map: dict[str, str] = {}
     column_types: dict[str, str] = {}
@@ -430,7 +455,9 @@ def _compile_query_filters(
     columns = document.get("columns")
     if isinstance(columns, list):
         kwargs["columns"] = [column_map.get(c, c) if isinstance(c, str) else c for c in columns]
-    return {internal: display for display, internal in column_map.items()} if metadata else None
+    if not metadata:
+        return None, None
+    return {internal: display for display, internal in column_map.items()}, column_types
 
 
 def _relabel_columns(
@@ -586,11 +613,14 @@ def view_data_get(invocation: Invocation) -> HandlerResult:
     """Fetch a dataview's data, waiting for the backing job to complete.
 
     The dataset is resolved from the view unless given as a trailing positional
-    or a ``dataset_id`` --input field.
+    or a ``dataset_id`` --input field. ``offset`` (1-based) reads a later page
+    through the query route. The result carries ``column_warnings`` when the
+    rows show a text column of numbers or dates, or blanks.
     """
     project_id = require_project(invocation)
     view_id = _require_int_positional_at(invocation, 0, "view id")
     document = invocation.load_input() or {}
+    limit = document.get("limit", _DATA_GET_DEFAULT_LIMIT)
     with open_service(invocation) as (service, auth):
         dataset_id = _resolve_dataset_id(service, invocation, view_id, document)
         kwargs: dict[str, Any] = {
@@ -598,12 +628,165 @@ def view_data_get(invocation: Invocation) -> HandlerResult:
             "dataview_id": view_id,
             "project_id": project_id,
         }
-        _forward_optional(document, kwargs, ("timeout", "poll_interval", "sequence"))
-        data = service.call(_symbol(invocation), **kwargs)
-        data = _relabel_columns(service, dataset_id, view_id, project_id, data)
-    return _trim_rows(data, document.get("limit", _DATA_GET_DEFAULT_LIMIT)), _meta(
-        invocation, auth.workspace_id, project_id
-    )
+        if document.get("offset") is not None:
+            kwargs["offset"] = int(document["offset"])
+            kwargs["limit"] = int(limit) if int(limit) > 0 else 400
+            _forward_optional(document, kwargs, ("sequence",))
+            data = service.call(_QUERY_DATA_SYMBOL, **kwargs)
+        else:
+            _forward_optional(document, kwargs, ("timeout", "poll_interval", "sequence"))
+            data = service.call(_symbol(invocation), **kwargs)
+        data = _relabel_and_check(service, dataset_id, view_id, project_id, data)
+    return _trim_rows(data, limit), _meta(invocation, auth.workspace_id, project_id)
+
+
+_QUERY_DATA_SYMBOL = "mammoth.api.dataviews.DataviewsAPI.query_data"
+
+_DATA_PAGE_SYMBOL = "mammoth.api.dataviews.DataviewsAPI.get_data"
+_MAX_UNMATCHED_KEYS = 5
+
+
+def join_snapshot(
+    service: Any, dataset_id: int, dataview_id: int, project_id: int | None
+) -> dict[str, Any]:
+    """Row count, columns and the first data page of a view (best effort)."""
+    snapshot: dict[str, Any] = {"row_count": None, "columns": {}, "rows": []}
+    try:
+        info = apply_column_renames(
+            service.call(
+                _DATAVIEW_GET_SYMBOL,
+                dataset_id=dataset_id,
+                dataview_id=dataview_id,
+                project_id=project_id,
+            )
+        )
+        if isinstance(info, dict):
+            snapshot["row_count"] = info.get("row_count")
+            snapshot["columns"] = {
+                c.get(_INTERNAL_NAME_KEY): c.get(_DISPLAY_NAME_KEY)
+                for c in info.get(_METADATA_KEY) or []
+                if isinstance(c, dict)
+            }
+            page = service.call(
+                _DATA_PAGE_SYMBOL,
+                dataset_id=dataset_id,
+                dataview_id=dataview_id,
+                project_id=project_id,
+            )
+            page = _relabel_columns(
+                service, dataset_id, dataview_id, project_id, page, snapshot["columns"]
+            )
+            rows = page.get(_ROWS_KEY) if isinstance(page, dict) else None
+            snapshot["rows"] = [r for r in rows or [] if isinstance(r, dict)]
+    except Exception:  # noqa: BLE001 -- the check is advice; the join already ran
+        return snapshot
+    return snapshot
+
+
+def with_join_check(data: Any, before: Any, after: dict[str, Any], document: dict[str, Any]) -> Any:
+    """Add ``join_check`` (row counts, columns added, match rate) to a join result.
+
+    ``unmatched_rows`` counts rows where every added column is blank: for a
+    LEFT join these are rows whose key found no match in the other view.
+    """
+    if not isinstance(data, dict) or not isinstance(before, dict):
+        return data
+    added = [
+        name
+        for internal, name in after.get("columns", {}).items()
+        if internal not in before.get("columns", {}) and isinstance(name, str)
+    ]
+    rows = after.get("rows") or []
+    check: dict[str, Any] = {
+        "rows_before": before.get("row_count"),
+        "rows_after": after.get("row_count"),
+        "columns_added": added,
+        "rows_checked": len(rows),
+    }
+    notes: list[str] = []
+    on = document.get("on")
+    left_key = None
+    if isinstance(on, list) and on and isinstance(on[0], dict):
+        left_key = on[0].get("left")
+    if added and rows:
+        unmatched = [r for r in rows if all(r.get(c) in (None, "") for c in added)]
+        check["unmatched_rows"] = len(unmatched)
+        check["match_rate"] = round((len(rows) - len(unmatched)) / len(rows), 3)
+        if unmatched:
+            keys = sorted({str(r.get(left_key)) for r in unmatched if left_key in r})
+            check["unmatched_keys"] = keys[:_MAX_UNMATCHED_KEYS]
+            notes.append(
+                f"{len(unmatched)} of {len(rows)} rows found no match. If that is more "
+                "than a few, compare the key columns in both views (type, case, "
+                "padding) before you build on this; otherwise say so in your report."
+            )
+    before_n, after_n = check["rows_before"], check["rows_after"]
+    if isinstance(before_n, int) and isinstance(after_n, int):
+        if after_n > before_n:
+            notes.append(
+                f"The join added {after_n - before_n} rows: a key repeats in the other "
+                "view, so matching rows repeat. Totals over this view count them twice; "
+                "use view transform lookup for one value per key."
+            )
+        elif after_n < before_n:
+            notes.append(
+                f"{before_n - after_n} rows had no match and were dropped "
+                "(an INNER join keeps matched rows only)."
+            )
+    if isinstance(after_n, int) and len(rows) < after_n:
+        notes.append(f"Match rate is from the first {len(rows)} rows of {after_n}.")
+    if notes:
+        check["notes"] = notes
+    return {**data, "join_check": check}
+
+
+def _column_profile(
+    service: Any, dataset_id: int, dataview_id: int, project_id: int | None
+) -> tuple[dict[str, str], dict[str, str]]:
+    """One metadata read: internal-to-display names, and display name to type."""
+    mapping: dict[str, str] = {}
+    types: dict[str, str] = {}
+    for column in _dataview_metadata(service, dataset_id, dataview_id, project_id):
+        internal = column.get(_INTERNAL_NAME_KEY)
+        display = column.get(_DISPLAY_NAME_KEY)
+        if isinstance(internal, str) and isinstance(display, str):
+            mapping[internal] = display
+            types[display] = str(column.get("type") or "")
+    return mapping, types
+
+
+def _relabel_and_check(
+    service: Any,
+    dataset_id: int,
+    view_id: int,
+    project_id: int | None,
+    data: Any,
+    mapping: dict[str, str] | None = None,
+    types: dict[str, str] | None = None,
+) -> Any:
+    """Relabel a data page to display names and add ``column_warnings``.
+
+    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:
+        return _relabel_columns(service, dataset_id, view_id, project_id, data, mapping)
+    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)
+    return _with_column_warnings(data, types, view_id)
+
+
+def _with_column_warnings(data: Any, types: dict[str, str], view_id: int) -> Any:
+    """Add ``column_warnings`` for the rows of a data page (never fatal)."""
+    if not isinstance(data, dict) or not isinstance(data.get(_ROWS_KEY), list) or not types:
+        return data
+    try:
+        warnings = column_warnings(data[_ROWS_KEY], types, view_id)
+    except Exception:  # noqa: BLE001 -- a presentation aid must not fail the read
+        return data
+    return {**data, "column_warnings": warnings} if warnings else data
 
 
 #: Rows a plain ``view data get`` returns unless ``limit`` says otherwise.
@@ -653,9 +836,11 @@ def view_data_query(invocation: Invocation) -> HandlerResult:
             "project_id": project_id,
         }
         _forward_optional(document, kwargs, ("sequence", "offset", "limit", "sort"))
-        mapping = _compile_query_filters(service, dataset_id, view_id, project_id, document, kwargs)
+        mapping, types = _compile_query_filters(
+            service, dataset_id, view_id, project_id, document, kwargs
+        )
         data = service.call(_symbol(invocation), **kwargs)
-        data = _relabel_columns(service, dataset_id, view_id, project_id, data, mapping)
+        data = _relabel_and_check(service, dataset_id, view_id, project_id, data, mapping, types)
     return data, _meta(invocation, auth.workspace_id, project_id)