mammoth-cli 2.2.30__tar.gz → 2.2.32__tar.gz

{mammoth_cli-2.2.30 → mammoth_cli-2.2.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.30
+Version: 2.2.32
 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.2.30 → mammoth_cli-2.2.32}/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.30"
+__version__ = "2.2.32"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.30 → mammoth_cli-2.2.32}/mammoth_cli/bundled_skill/mammoth-cli/references/about-mammoth.md

@@ -106,7 +106,7 @@ Checkpoint Alert are the `view data-check` and `view checkpoint` families.
 | Add columns from another view by matching keys | Join | `join` (`INNER`, `LEFT`, `RIGHT`, `OUTER`) |
 | Bring one value per key from another view | Lookup | `lookup` |
 | Totals, counts, averages per group | Group & Pivot | `pivot` (replaces the view's columns) |
-| A rows-by-columns summary table | Group & Pivot (crosstab) | `crosstab` (writes a new dataset) |
+| A rows-by-columns summary table | Group & Pivot (crosstab) | `crosstab` (writes a new dataset, and keeps rewriting it on every pipeline run of the view) |
 | Turn wide columns into label/value rows | Unpivot | `unnest` |
 | Read fields out of a JSON column | Extract JSON | `json-extract` |
 | Classify, tag or summarise rows with AI | Generative AI | `ai` |
@@ -146,7 +146,12 @@ No command:
   every source column to an existing target column. A partial mapping, or a
   destination the target lacks, is refused with `append_mapping_incomplete`
   before anything is written (the backend would append only the mapped columns
-  and add a new column for the unknown name). An append is a standing link: it is stored
+  and add a new column for the unknown name). A target column the append
+  leaves unfilled would be NULL in every appended row: it is refused with
+  `append_leaves_columns_blank` unless the input names exactly those columns,
+  e.g. `"blank_columns": ["id","score"]` (a deliberate partial append, such as
+  mapping only `name`); never delete source columns or clone the source view to
+  get around it. An append is a standing link: it is stored
   as a pipeline step of the source view, so every later re-run of that view
   appends again into the target dataset, not just the first run. A column
   with the same name but a different type in the source view and the target

{mammoth_cli-2.2.30 → mammoth_cli-2.2.32}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/exports.md

@@ -55,7 +55,11 @@ there is no separate Auto-Sync endpoint or field to find.
 `target_ds_id` writes into an existing dataset instead of creating one
 (`save_as_mode` `REPLACE_IN_DS` or `APPEND_TO_DS`). Read the delivery back in
 the target project (`view list N --project P`, `view data get`) before
-reporting it. Do not build this with `view export create`: the raw
+reporting it. An append that leaves target columns unfilled (a partial
+`column_mapping`, or a source with fewer columns) is refused with
+`append_leaves_columns_blank` unless the input lists exactly those columns,
+`"blank_columns": ["id","score"]`; confirm that with the user, and never
+clone the source view or delete its columns to get around the refusal. Do not build this with `view export create`: the raw
 `internal_dataset` spec needs `USER_ID` and the `export_project` /
 `project_id` / `source_project_id` trio, and without them the backend answers
 `4GENR007 Validation error` with no detail; the typed command fills them.
@@ -84,7 +88,7 @@ the run log. The connector command is `external_effect` with
 mammoth schema get view.export.postgres   # read secret_fields, required fields
 # operator writes /private/path/request.json (mode 0600):
 # {"host":"db.example","port":5432,"database":"analytics","table":"exports",
-#  "username":"agent","password":"…","dataset_id":DATASET_ID}
+#  "username":"agent","password":"…","replace_table":true,"dataset_id":DATASET_ID}
 mammoth view export postgres VIEW_ID DATASET_ID --project PROJECT_ID \
   --input /private/path/request.json --yes
 mammoth view export list VIEW_ID DATASET_ID --project PROJECT_ID
@@ -93,6 +97,16 @@ mammoth view export list VIEW_ID DATASET_ID --project PROJECT_ID
 If the operator has not supplied such a file, stop and ask for it; do not
 compose the body yourself from values seen in chat.
 
+A database export (`postgres`, `mysql`, `mssql`, `redshift`, `bigquery` with
+`export_type` REPLACE, and `publish-db`) drops and recreates its destination
+table now and on every later run of the view's pipeline, so any existing table
+of that name is lost. It is refused (`replace_table_not_acknowledged`) unless
+the input says `"replace_table": true`; only set that for a table the user said
+may be overwritten. `postgres` and `mysql` also cut a table name to 60
+characters and write a different table, so a longer name is refused
+(`table_name_too_long`). The result carries `refreshes_on_pipeline_run` and a
+`note` saying so.
+
 ## Generic export routes
 
 `view export csv` and the typed destination commands are the proven path. The

{mammoth_cli-2.2.30 → mammoth_cli-2.2.32}/mammoth_cli/commands/batch.py

@@ -25,6 +25,10 @@ from mammoth_cli.manifest.loader import command_by_id
 from mammoth_cli.runtime.confirm import POLICY_PROMPT_OR_YES, enforce_confirmation
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, require_project
+from mammoth_cli.services.append_blank_columns import (
+    BLANK_COLUMNS_FIELD,
+    acknowledged_blank_columns,
+)
 
 HandlerResult = tuple[Any, dict[str, Any]]
 
@@ -221,15 +225,32 @@ def _reject_type_change(item: dict[str, Any], dest_col: dict[str, Any], dataset_
     )
 
 
+def _filled_destination_names(
+    items: list[dict[str, Any]], dest: list[dict[str, Any]], source: list[dict[str, Any]]
+) -> set[str]:
+    """Destination column names some mapping item fills (``add_column`` items included)."""
+    dest_names = {col["c_name"] for col in dest}
+    filled: set[str] = set()
+    for item in items:
+        _, dest_col = _resolve_item(item, source, dest)
+        if dest_col is not None:
+            filled.add(dest_col["c_name"])
+        elif item.get("action") == "add_column" and item.get("destination_c_name") in dest_names:
+            filled.add(item["destination_c_name"])
+    return filled
+
+
 def _checked_batch_mapping(
-    service: Any, dataset_id: int, source_id: int, mapping: Any
+    service: Any, dataset_id: int, source_id: int, mapping: Any, blank_columns: Any = None
 ) -> tuple[list[dict[str, Any]], list[str]]:
     """Validate a batch mapping against both schemas; return typed items and warnings.
 
     Refuses unmapped source columns and unknown destinations (the backend appends
     only the mapped columns) and stamps every item with the destination's actual
     current type, so no destination column is silently re-typed. A mapped pair
-    whose source and destination types differ is returned as a warning.
+    whose source and destination types differ is returned as a warning. A
+    destination column no item fills is refused unless ``blank_columns`` names
+    exactly those columns; the confirmed blanks are returned as a warning.
     """
     source = _dataset_columns(service, source_id, "source")
     dest = _dataset_columns(service, dataset_id, "target")
@@ -258,7 +279,8 @@ def _checked_batch_mapping(
     _reject_incomplete_batch_mapping(
         (dataset_id, source_id), {col["c_name"] for col in source}, mapped_sources, unknown
     )
-    return typed, warnings
+    blank = sorted({col["c_name"] for col in dest} - _filled_destination_names(typed, dest, source))
+    return typed, acknowledged_blank_columns(dataset_id, blank, blank_columns) + warnings
 
 
 def batch_create(invocation: Invocation) -> HandlerResult:
@@ -297,7 +319,7 @@ def batch_create(invocation: Invocation) -> HandlerResult:
         )
     with open_service(invocation) as (service, auth):
         kwargs["mapping"], warnings = _checked_batch_mapping(
-            service, dataset_id, source_id, mapping
+            service, dataset_id, source_id, mapping, document.get(BLANK_COLUMNS_FIELD)
         )
         data = service.call(_symbol(invocation), **kwargs)
     if warnings and isinstance(data, dict):

{mammoth_cli-2.2.30 → mammoth_cli-2.2.32}/mammoth_cli/commands/view.py

@@ -55,6 +55,10 @@ from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, require_project
 from mammoth_cli.services import conditional_format as cf_rules
 from mammoth_cli.services import read_queries, text_dates
+from mammoth_cli.services.append_blank_columns import (
+    BLANK_COLUMNS_FIELD,
+    acknowledged_blank_columns,
+)
 from mammoth_cli.services.conditions import CONDITION_KWARG, compile_condition
 from mammoth_cli.services.dashboard_review import UPLOAD_NOTE, upload_hints
 from mammoth_cli.services.data_quality import column_warnings, duplicate_rows_fact
@@ -2963,13 +2967,53 @@ def view_pipeline_rerun(invocation: Invocation) -> HandlerResult:
                 service, invocation, dataview_id, document, 1
             )
         before = _rows_before(service, dataset_id, dataview_id, invocation.project)
+        fired = _end_of_pipeline_exports(service, dataview_id, dataset_id)
         data = service.call(_symbol(invocation), **kwargs)
         data = _settle_async_view_write(
             service, dataset_id, dataview_id, invocation.project, data, before
         )
+    if fired and isinstance(data, dict):
+        data = {**data, "exports_fired": fired}
     return data, _meta(invocation, auth.workspace_id, None)
 
 
+#: Non-secret ``target_properties`` keys that say where an export writes.
+_EXPORT_TARGET_HINT_KEYS = ("table", "host", "database", "TARGET_DS_ID", "DS_NAME", "emails")
+
+
+def _end_of_pipeline_exports(
+    service: Any, dataview_id: int, dataset_id: int | None
+) -> list[dict[str, Any]]:
+    """The live end-of-pipeline exports a rerun of this view fires again.
+
+    A rerun re-sends every one of them to its destination (database, email, REST
+    endpoint, another dataset), so the caller is told which, not just that the
+    pipeline ran. Soft-deleted exports do not fire.
+    """
+    listing = service.call(
+        _EXPORTS_LIST_SYMBOL,
+        dataview_id=dataview_id,
+        dataset_id=dataset_id,
+        end_of_pipeline=True,
+    )
+    fired: list[dict[str, Any]] = []
+    for export in getattr(listing, "exports", None) or []:
+        if export.status is ExportStatus.DELETED:
+            continue
+        handler = export.handler_type
+        properties = export.target_properties or {}
+        fired.append(
+            {
+                "export_id": export.id,
+                "handler_type": getattr(handler, "value", handler),
+                "target": {
+                    key: properties[key] for key in _EXPORT_TARGET_HINT_KEYS if key in properties
+                },
+            }
+        )
+    return fired
+
+
 #: Seconds ``view pipeline wait`` waits when the caller names no ``timeout`` (the SDK's own
 #: default is an hour, one request every few seconds for as long as it runs).
 _PIPELINE_WAIT_TIMEOUT = 300.0
@@ -3261,20 +3305,24 @@ def view_export_publish_db(invocation: Invocation) -> HandlerResult:
     document = invocation.load_input()
     odbc_type = _require_field(document, "odbc_type")
     target_properties = _require_field(document, "target_properties")
+    assert document is not None
+    table = target_properties.get("table") if isinstance(target_properties, dict) else None
     enforce_confirmation(
         invocation, policy=POLICY_YES_ALWAYS, action=f"publish-db on view {dataview_id}"
     )
+    table_note = _reject_unacknowledged_table_replace(invocation.command_id, document, table)
     kwargs: dict[str, Any] = {
         "dataview_id": dataview_id,
         "odbc_type": odbc_type,
         "target_properties": target_properties,
         "project_id": project_id,
     }
-    assert document is not None
     _forward_optional(document, kwargs, ("dataset_id",))
     with open_service(invocation) as (service, auth):
         _require_exact_parent(service, invocation, dataview_id, kwargs)
         data = service.call(_symbol(invocation), **kwargs)
+    if table_note is not None:
+        data = _with_recurrence_note(data, table_note)
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
@@ -3453,6 +3501,81 @@ def _reject_export_into_draft(service: Any, dataview_id: int, dataset_id: int) -
     )
 
 
+# Database exports rebuild their destination table: the distributary drops it
+# and recreates it from the view on the first write and on every later pipeline
+# run (BigQuery only for export_type REPLACE, its WRITE_TRUNCATE mode). Postgres
+# and MySQL also cut a table name to 60 characters, silently writing elsewhere.
+_REPLACE_TABLE_FIELD = "replace_table"
+_DB_REPLACE_ROUTES = frozenset(
+    {
+        "view.export.postgres",
+        "view.export.mysql",
+        "view.export.mssql",
+        "view.export.redshift",
+        "view.export.bigquery",
+    }
+)
+_DB_TABLE_NAME_LIMIT_ROUTES = frozenset({"view.export.postgres", "view.export.mysql"})
+_DB_TABLE_NAME_LIMIT = 60
+
+
+def _replaces_table(command_id: str, document: dict[str, Any]) -> bool:
+    """Whether this database export drops and recreates its destination table."""
+    if command_id == "view.export.bigquery":
+        return str(document.get("export_type") or "REPLACE").upper() == "REPLACE"
+    return command_id in _DB_REPLACE_ROUTES or command_id == "view.export.publish-db"
+
+
+def _reject_unacknowledged_table_replace(
+    command_id: str, document: dict[str, Any], table: Any
+) -> str | None:
+    """Refuse a database export that is not explicitly allowed to replace its table.
+
+    Returns the recurrence note for the result, or ``None`` when the export
+    does not replace a table.
+    """
+    if not _replaces_table(command_id, document):
+        return None
+    name = str(table)
+    if command_id in _DB_TABLE_NAME_LIMIT_ROUTES and len(name) > _DB_TABLE_NAME_LIMIT:
+        raise CliError(
+            code="table_name_too_long",
+            message=(
+                f"Table name {name!r} is {len(name)} characters; the database export cuts "
+                f"table names to {_DB_TABLE_NAME_LIMIT} and would write a different table "
+                f"({name[:_DB_TABLE_NAME_LIMIT]!r})."
+            ),
+            exit_status=EXIT_USAGE,
+            hint=f"Use a table name of at most {_DB_TABLE_NAME_LIMIT} characters.",
+            details={"table": name, "length": len(name), "limit": _DB_TABLE_NAME_LIMIT},
+        )
+    if document.get(_REPLACE_TABLE_FIELD) is not True:
+        raise CliError(
+            code="replace_table_not_acknowledged",
+            message=(
+                f"This export drops and recreates table {name!r} in the destination database "
+                "now and on every pipeline run of the view; any existing table of that name "
+                "and its rows are lost."
+            ),
+            exit_status=EXIT_USAGE,
+            hint=(
+                f'Pick a table that may be overwritten, then add "{_REPLACE_TABLE_FIELD}": true '
+                "to the input to confirm."
+            ),
+            details={"table": name, "field": _REPLACE_TABLE_FIELD},
+        )
+    return f"drops and recreates {name} now and on every pipeline run"
+
+
+def _with_recurrence_note(data: Any, note: str) -> dict[str, Any]:
+    """The export result as a mapping carrying ``refreshes_on_pipeline_run`` and ``note``."""
+    result = data.model_dump(mode="json") if hasattr(data, "model_dump") else data
+    record = dict(result) if isinstance(result, dict) else {"result": result}
+    record["refreshes_on_pipeline_run"] = True
+    record["note"] = note
+    return record
+
+
 def view_export_specialized(invocation: Invocation) -> HandlerResult:
     """Run one of the SDK's typed ``View.export`` destination helpers."""
     route = _SPECIAL_EXPORTS.get(invocation.command_id)
@@ -3493,6 +3616,10 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
     )
     common_fields = _SPECIAL_EXPORT_COMMON_FIELDS if accepts_var_keyword else frozenset()
     allowed = explicit_fields | common_fields | {_DATASET_ID_FIELD}
+    if invocation.command_id in _DB_REPLACE_ROUTES:
+        allowed = allowed | {_REPLACE_TABLE_FIELD}
+    if invocation.command_id == "view.export.dataset":
+        allowed = allowed | {BLANK_COLUMNS_FIELD}
     unknown = sorted(set(document) - allowed)
     if unknown:
         raise CliError(
@@ -3520,8 +3647,13 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
         policy=str(export_record.get("confirmation") or POLICY_YES_ALWAYS),
         action=f"export view {dataview_id} via {invocation.command_id.rsplit('.', 1)[-1]}",
     )
+    table_note = _reject_unacknowledged_table_replace(
+        invocation.command_id, document, document.get("table")
+    )
     kwargs = dict(document)
     kwargs.pop(_DATASET_ID_FIELD, None)
+    kwargs.pop(_REPLACE_TABLE_FIELD, None)
+    blank_columns = kwargs.pop(BLANK_COLUMNS_FIELD, None)
     is_dataset_route = invocation.command_id == "view.export.dataset"
     target_ds_id = kwargs.get("target_ds_id") if is_dataset_route else None
     save_as_mode = kwargs.get("save_as_mode") if is_dataset_route else None
@@ -3530,62 +3662,39 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
     with open_service(invocation) as (service, auth):
         if dataset_id is None:
             dataset_id = _resolve_dataset_id(service, invocation, dataview_id, document)
-        if target_ds_id is not None and int(target_ds_id) == dataset_id:
-            raise CliError(
-                code=CODE_INVALID_ARGUMENTS,
-                message="target_ds_id equals the view's own dataset.",
-                exit_status=EXIT_USAGE,
-                hint=(
-                    "A view cannot write into its own dataset. Export to a new "
-                    "dataset name (omit target_ds_id), or target a different dataset."
-                ),
-                details={"dataset_id": dataset_id, "target_ds_id": int(target_ds_id)},
-            )
         if is_dataset_route:
-            _reject_export_into_draft(service, dataview_id, dataset_id)
+            reject_dataset_export_conflicts(
+                service,
+                dataview_id,
+                dataset_id,
+                int(target_ds_id) if target_ds_id is not None else None,
+            )
         target_view_before = None
+        blank_warnings: list[str] = []
         target_only_columns: list[str] = []
         mapped_type_warnings: list[str] = []
+        hidden_left_out = (
+            _hidden_column_names(service, dataset_id, dataview_id, project_id)
+            if is_dataset_route and target_ds_id is None
+            else []
+        )
         if target_ds_id is not None:
-            # Each `view export dataset` call creates its own PERSISTENT
-            # export trigger on this view, which re-runs on every pipeline
-            # run; REPLACE_IN_DS/APPEND_TO_DS only ever touch that trigger's
-            # OWN rows. A second export from this view into the same target
-            # is therefore a second writer, not a refresh of the first --
-            # the fix is to rerun the pipeline, not to export again.
-            existing_export = _existing_internal_dataset_export(
-                service, dataview_id, dataset_id, int(target_ds_id)
-            )
-            if existing_export is not None:
-                raise CliError(
-                    code="export_already_exists",
-                    message=(
-                        f"View {dataview_id} already exports into dataset "
-                        f"{int(target_ds_id)} (export {existing_export.id}). This export "
-                        "re-runs on every pipeline run, and REPLACE_IN_DS replaces only "
-                        "its own rows -- a second export into the same target duplicates "
-                        "rows instead of refreshing them."
-                    ),
-                    exit_status=EXIT_USAGE,
-                    hint="Refresh the target by rerunning the pipeline, not by exporting again.",
-                    recovery_commands=[f"mammoth view pipeline rerun {dataview_id}"],
-                    details={
-                        "dataview_id": dataview_id,
-                        "target_ds_id": int(target_ds_id),
-                        "export_id": existing_export.id,
-                    },
-                )
             # rows_before is the target's own count ahead of this write, read
             # before the call so a later re-read can never be confused with it.
             target_view_before = _dataset_view_info(service, int(target_ds_id), result_project_id)
-            if save_as_mode == "APPEND_TO_DS":
-                target_only_columns, mapped_type_warnings = _reject_append_schema_mismatch(
-                    service,
-                    dataview_id,
-                    dataset_id,
-                    int(target_ds_id),
-                    kwargs.get("column_mapping"),
-                )
+            # REPLACE_IN_DS into an existing target runs the same backend
+            # append code as APPEND_TO_DS (same mapping and schema handling),
+            # so both modes get the same guards.
+            target_only_columns, mapped_type_warnings = _reject_append_schema_mismatch(
+                service,
+                dataview_id,
+                dataset_id,
+                int(target_ds_id),
+                kwargs.get("column_mapping"),
+            )
+            blank_warnings = acknowledged_blank_columns(
+                int(target_ds_id), target_only_columns, blank_columns
+            )
         try:
             data = service.call_view(dataview_id, method, dataset_id=dataset_id, **kwargs)
         except CliError as error:
@@ -3642,19 +3751,19 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
                 # a non-increase here as unverified, not just an omitted count.
                 row_check["expected_row_increase"] = True
             warnings = list(mapped_type_warnings)
-            if target_only_columns:
-                # Allowed -- an append never has to cover every target column
-                # -- but worth surfacing rather than leaving silent.
-                warnings.insert(
-                    0,
-                    "target dataset has column(s) the source view does not (kept "
-                    "as-is): " + ", ".join(target_only_columns),
+            if hidden_left_out:
+                warnings.append(
+                    "hidden column(s) of the source view are not in the new dataset: "
+                    + ", ".join(hidden_left_out)
                 )
+            warnings[:0] = blank_warnings
             if warnings:
                 row_check["warnings"] = warnings
             data["row_check"] = row_check
             if pipeline_error is not None:
                 data["pipeline_error"] = pipeline_error
+    if table_note is not None:
+        data = _with_recurrence_note(data, table_note)
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
@@ -3721,6 +3830,82 @@ def _existing_internal_dataset_export(
     return max(matches, key=lambda export: export.id or 0) if matches else None
 
 
+def _hidden_column_names(
+    service: Any, dataset_id: int, dataview_id: int, project_id: int | None
+) -> list[str]:
+    """Display names of the view's hidden columns, which a new-dataset export leaves out."""
+    info = apply_column_renames(
+        service.call(
+            _DATAVIEW_GET_SYMBOL,
+            dataset_id=dataset_id,
+            dataview_id=dataview_id,
+            project_id=project_id,
+        )
+    )
+    if not isinstance(info, dict):
+        return []
+    display = info.get("display_properties")
+    hidden = display.get("HIDDEN_COLUMNS") if isinstance(display, dict) else None
+    if not isinstance(hidden, list) or not hidden:
+        return []
+    names = {
+        column.get(_INTERNAL_NAME_KEY): column.get(_DISPLAY_NAME_KEY) or column.get("name")
+        for column in info.get(_METADATA_KEY) or []
+        if isinstance(column, dict)
+    }
+    return [str(names.get(column) or column) for column in hidden]
+
+
+def reject_dataset_export_conflicts(
+    service: Any, dataview_id: int, dataset_id: int, target_ds_id: int | None
+) -> None:
+    """Refuse a dataset export (or crosstab) that cannot write, or would double-write.
+
+    Not into the view's own dataset, not from a view holding its changes in a
+    draft, and not into a target this view already exports into. Each dataset
+    export creates its own PERSISTENT trigger on the view, which re-runs on
+    every pipeline run; REPLACE_IN_DS/APPEND_TO_DS only touch that trigger's OWN
+    rows, so a second export into the same target is a second writer, not a
+    refresh -- the fix is to rerun the pipeline, not to export again.
+    """
+    if target_ds_id is not None and target_ds_id == dataset_id:
+        raise CliError(
+            code=CODE_INVALID_ARGUMENTS,
+            message="target_ds_id equals the view's own dataset.",
+            exit_status=EXIT_USAGE,
+            hint=(
+                "A view cannot write into its own dataset. Export to a new "
+                "dataset name (omit target_ds_id), or target a different dataset."
+            ),
+            details={"dataset_id": dataset_id, "target_ds_id": target_ds_id},
+        )
+    _reject_export_into_draft(service, dataview_id, dataset_id)
+    if target_ds_id is None:
+        return
+    existing_export = _existing_internal_dataset_export(
+        service, dataview_id, dataset_id, target_ds_id
+    )
+    if existing_export is not None:
+        raise CliError(
+            code="export_already_exists",
+            message=(
+                f"View {dataview_id} already exports into dataset "
+                f"{target_ds_id} (export {existing_export.id}). This export "
+                "re-runs on every pipeline run, and REPLACE_IN_DS replaces only "
+                "its own rows -- a second export into the same target duplicates "
+                "rows instead of refreshing them."
+            ),
+            exit_status=EXIT_USAGE,
+            hint="Refresh the target by rerunning the pipeline, not by exporting again.",
+            recovery_commands=[f"mammoth view pipeline rerun {dataview_id}"],
+            details={
+                "dataview_id": dataview_id,
+                "target_ds_id": target_ds_id,
+                "export_id": existing_export.id,
+            },
+        )
+
+
 _DATASET_GET_SYMBOL = "mammoth.api.datasets.DatasetsAPI.get"
 
 
@@ -3874,7 +4059,8 @@ def _reject_append_schema_mismatch(
     target_ds_id: int,
     column_mapping: Any,
 ) -> tuple[list[str], list[str]]:
-    """Refuse an ``APPEND_TO_DS`` export whose source has a column the target
+    """Refuse an ``APPEND_TO_DS``/``REPLACE_IN_DS`` export into an existing target
+    whose source has a column the target
     dataset's schema does not, and ``column_mapping`` does not cover.
 
     A non-empty ``column_mapping`` is stricter: the backend then copies only

{mammoth_cli-2.2.30 → mammoth_cli-2.2.32}/mammoth_cli/commands/view_ops.py

@@ -36,6 +36,7 @@ from mammoth_cli.commands.view import (
     join_after_snapshot,
     join_dry_run_preview,
     join_snapshot,
+    reject_dataset_export_conflicts,
     wait_for_followon_job,
     wait_for_pipeline_to_settle,
     wait_for_view_row_count,
@@ -230,6 +231,32 @@ def _resolve_exact_dataset_id(
     return value
 
 
+def _require_one_destination(document: dict[str, Any], command_id: str) -> None:
+    """Refuse a transform that names both ``new_column`` and ``existing_column``, or neither.
+
+    The SDK silently keeps only ``new_column`` when both are given, and a step
+    with neither is saved and then fails in the worker ("No destination for
+    operation") after the pipeline has already been changed.
+    """
+    given = [name for name in ("new_column", "existing_column") if document.get(name) is not None]
+    if len(given) == 1:
+        return
+    command = command_id.replace(".", " ")
+    raise CliError(
+        code=CODE_INVALID_ARGUMENTS,
+        message=(
+            f"'{command}' needs exactly one of new_column or existing_column, "
+            + ("not both: existing_column would be ignored." if given else "but got neither.")
+        ),
+        exit_status=EXIT_USAGE,
+        hint=(
+            "Set new_column to write a new column, or existing_column to overwrite "
+            "one that is already in the view."
+        ),
+        details={"given": given},
+    )
+
+
 def _require_field(document: dict[str, Any] | None, field: str) -> Any:
     """Return a required field from the ``--input`` document, or raise usage."""
     if document is None or field not in document:
@@ -979,6 +1006,7 @@ def view_transform_combine_columns(invocation: Invocation) -> HandlerResult:
     document = invocation.load_input()
     _require_field(document, "sources")
     assert document is not None
+    _require_one_destination(document, invocation.command_id)
     kwargs = _bind_transform_inputs(invocation, document)
     return _dispatch_view(invocation, view_id, "combine_columns", **kwargs)
 
@@ -1063,7 +1091,27 @@ def view_transform_crosstab(invocation: Invocation) -> HandlerResult:
     _require_field(document, "dataset_name")
     assert document is not None
     kwargs = _bind_transform_inputs(invocation, document)
-    return _dispatch_view(invocation, view_id, "crosstab", **kwargs)
+
+    def guard_target(service: Any, dataset_id: int, call_kwargs: dict[str, Any]) -> None:
+        target = call_kwargs.get("target_ds_id")
+        reject_dataset_export_conflicts(
+            service, view_id, dataset_id, int(target) if target is not None else None
+        )
+
+    def name_persistence(_service: Any, _dataset_id: int, _state: Any, data: Any) -> Any:
+        return {
+            "dataset_id": data,
+            "source_view_id": view_id,
+            "refreshes_on_pipeline_run": True,
+            "note": (
+                f"This crosstab is a standing export on view {view_id}: it rewrites dataset "
+                f"{data} on every pipeline run of that view, not just now."
+            ),
+        }
+
+    return _dispatch_view(
+        invocation, view_id, "crosstab", prepare=guard_target, after=name_persistence, **kwargs
+    )
 
 
 def view_transform_date_diff(invocation: Invocation) -> HandlerResult:
@@ -1325,6 +1373,7 @@ def view_transform_lookup(invocation: Invocation) -> HandlerResult:
     _require_field(document, "key")
     _require_field(document, "value")
     assert document is not None
+    _require_one_destination(document, invocation.command_id)
     kwargs = _bind_transform_inputs(invocation, document)
     return _dispatch_view(invocation, view_id, "lookup", **kwargs)
 
@@ -1335,6 +1384,7 @@ def view_transform_math(invocation: Invocation) -> HandlerResult:
     document = invocation.load_input()
     _require_field(document, "expression")
     assert document is not None
+    _require_one_destination(document, invocation.command_id)
     kwargs = _bind_transform_inputs(invocation, document)
     return _dispatch_view(invocation, view_id, "math", **kwargs)
 
@@ -1369,6 +1419,7 @@ def view_transform_set_values(invocation: Invocation) -> HandlerResult:
     document = invocation.load_input()
     _require_field(document, "values")
     assert document is not None
+    _require_one_destination(document, invocation.command_id)
     kwargs = _bind_transform_inputs(invocation, document)
     return _dispatch_view(invocation, view_id, "set_values", **kwargs)
 
@@ -1432,5 +1483,6 @@ def view_transform_window(invocation: Invocation) -> HandlerResult:
     document = invocation.load_input()
     _require_field(document, "function")
     assert document is not None
+    _require_one_destination(document, invocation.command_id)
     kwargs = _bind_transform_inputs(invocation, document)
     return _dispatch_view(invocation, view_id, "window", **kwargs)