mammoth-cli 2.2.28__tar.gz → 2.2.29__tar.gz

{mammoth_cli-2.2.28 → mammoth_cli-2.2.29}/PKG-INFO

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

{mammoth_cli-2.2.28 → mammoth_cli-2.2.29}/mammoth_cli/bundled_skill/mammoth-cli/references/about-mammoth.md

@@ -141,7 +141,12 @@ No command:
 - **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
-  `save_as_mode` `APPEND_TO_DS`). An append is a standing link: it is stored
+  `save_as_mode` `APPEND_TO_DS`). Omit `column_mapping` and every column is
+  matched by name; a non-empty `column_mapping` is used as-is, so it must map
+  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
   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.28 → mammoth_cli-2.2.29}/mammoth_cli/commands/view.py

@@ -3545,6 +3545,7 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
             _reject_export_into_draft(service, dataview_id, dataset_id)
         target_view_before = None
         target_only_columns: list[str] = []
+        mapped_type_warnings: list[str] = []
         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
@@ -3578,7 +3579,7 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
             # 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 = _reject_append_schema_mismatch(
+                target_only_columns, mapped_type_warnings = _reject_append_schema_mismatch(
                     service,
                     dataview_id,
                     dataset_id,
@@ -3640,13 +3641,17 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
                 # An append is expected to grow the target; verify.py treats
                 # 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.
-                row_check["warnings"] = [
+                warnings.insert(
+                    0,
                     "target dataset has column(s) the source view does not (kept "
-                    "as-is): " + ", ".join(target_only_columns)
-                ]
+                    "as-is): " + ", ".join(target_only_columns),
+                )
+            if warnings:
+                row_check["warnings"] = warnings
             data["row_check"] = row_check
             if pipeline_error is not None:
                 data["pipeline_error"] = pipeline_error
@@ -3799,24 +3804,92 @@ def _reject_append_type_mismatch(
     )
 
 
+def _reject_partial_append_mapping(
+    source_names: set[str],
+    target_names: set[str],
+    mapping: dict[str, str],
+    ids: tuple[int, int],
+) -> None:
+    """Refuse a non-empty append ``column_mapping`` that drops or invents columns.
+
+    The backend maps every column by name when the mapping is empty, but uses
+    a non-empty one as-is: unmapped source columns are not appended (their
+    target cells stay NULL) and a destination the target lacks becomes a new
+    column named after the source.
+    """
+    if not mapping:
+        return
+    unknown = {src: dest for src, dest in sorted(mapping.items()) if dest not in target_names}
+    unmapped = sorted(source_names - set(mapping))
+    if not unknown and not unmapped:
+        return
+    view_id, target_ds_id = ids
+    problems = []
+    if unknown:
+        listed = ", ".join(f"{dest!r} (for {src!r})" for src, dest in unknown.items())
+        problems.append(f"destination column(s) not in target dataset {target_ds_id}: {listed}")
+    if unmapped:
+        problems.append(f"source column(s) left unmapped and not appended: {', '.join(unmapped)}")
+    raise CliError(
+        code="append_mapping_incomplete",
+        message=(
+            f"column_mapping for appending view {view_id} into dataset {target_ds_id} would "
+            f"corrupt the append: {'; '.join(problems)}. A non-empty column_mapping is used "
+            "as-is: unmapped columns are not appended and an unknown destination creates a "
+            "new column."
+        ),
+        exit_status=EXIT_USAGE,
+        hint=(
+            "Omit column_mapping to map all columns by name, or map every source column to "
+            f"an existing column of dataset {target_ds_id}."
+        ),
+        details={
+            "unknown_destinations": unknown,
+            "unmapped_source_columns": unmapped,
+            "target_columns": sorted(target_names),
+        },
+    )
+
+
+def _mapped_type_warnings(
+    source_types: Any, target_schema: dict[str, str], mapping: dict[str, str]
+) -> list[str]:
+    """Warn where a mapped source column's type differs from its target column's."""
+    if not isinstance(source_types, dict):
+        return []
+    return [
+        f"mapped column {src!r} is {str(source_types[src]).lower()} but target column "
+        f"{dest!r} is {target_schema[dest].lower()}"
+        for src, dest in sorted(mapping.items())
+        if source_types.get(src)
+        and target_schema.get(dest)
+        and str(source_types[src]).lower() != target_schema[dest].lower()
+    ]
+
+
 def _reject_append_schema_mismatch(
     service: Any,
     dataview_id: int,
     dataset_id: int | None,
     target_ds_id: int,
     column_mapping: Any,
-) -> list[str]:
+) -> tuple[list[str], list[str]]:
     """Refuse an ``APPEND_TO_DS`` export 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
+    the mapped columns and turns an unknown destination into a new column, so
+    every source column must be mapped to a column the target already has
+    (``_reject_partial_append_mapping``).
+
     An append writes into rows the target dataset already has; a source
     column with no home in the target schema and no explicit mapping would
     otherwise reach the backend as a malformed write. Checked here, before
     the call, so the refusal costs nothing and names exactly what to fix.
 
     Returns the target-only column names (present in the target schema, not
-    in the source, not a ``column_mapping`` destination) -- allowed, but
-    worth a warning rather than silence.
+    in the source, not a ``column_mapping`` destination) and the type
+    warnings for mapped pairs -- both allowed, but worth a warning.
     """
     source_columns = service.call_view(dataview_id, "columns", dataset_id=dataset_id)
     if not isinstance(source_columns, dict):
@@ -3833,14 +3906,11 @@ def _reject_append_schema_mismatch(
     # dict keys are display names, matching what the backend's own schema
     # match compares by -- never the internal ids in the dict's values.
     source_names = set(source_columns)
+    _reject_partial_append_mapping(source_names, target_names, mapping, (dataview_id, target_ds_id))
     source_only = sorted(source_names - target_names - set(mapping))
     target_only = sorted(target_names - source_names - set(mapping.values()))
-    _reject_append_type_mismatch(
-        service.call_view(dataview_id, "column_types", dataset_id=dataset_id),
-        target_schema,
-        mapping,
-        (dataview_id, target_ds_id),
-    )
+    source_types = service.call_view(dataview_id, "column_types", dataset_id=dataset_id)
+    _reject_append_type_mismatch(source_types, target_schema, mapping, (dataview_id, target_ds_id))
     if source_only:
         raise CliError(
             code="append_schema_mismatch",
@@ -3855,7 +3925,7 @@ def _reject_append_schema_mismatch(
             ),
             details={"source_only": source_only, "target_only": target_only},
         )
-    return target_only
+    return target_only, _mapped_type_warnings(source_types, target_schema, mapping)
 
 
 def _dataset_view_info(

{mammoth_cli-2.2.28 → mammoth_cli-2.2.29}/mammoth_cli/errors/envelope.py

@@ -77,6 +77,7 @@ ERROR_SUMMARIES: dict[str, str] = {
         "More than one item matched, so the assistant needs to be more specific."
     ),
     "api_error": "Mammoth couldn't complete this step.",
+    "append_mapping_incomplete": "The column mapping would leave columns out or add new ones.",
     "append_schema_mismatch": "The new data doesn't line up with the existing columns.",
     "append_type_mismatch": "A column has a different type than in the existing data.",
     "append_schema_unreadable": "The columns of the existing data couldn't be read.",

{mammoth_cli-2.2.28 → mammoth_cli-2.2.29}/pyproject.toml

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

{mammoth_cli-2.2.28 → mammoth_cli-2.2.29}/spec/manifests/commands/view.yaml

@@ -2261,7 +2261,7 @@ commands:
   - CT-VIEW-EXPORT-DATASET-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'Mutation class dynamic: benign_mutation for a new target, destructive when replacing an existing target. The export is appended to the source pipeline (end_of_pipeline) and re-runs with it; target_project_id sends the dataset into another project (cross-project branch-out, proven on release). Result: {dataset_id, project_id, source_view_id, next}. Not a plain copy: this leaves a live export on the source and the new dataset refreshes from the source view, so keep that working view and name it as the new dataset''s source. For an independent copy of a dataset use dataset create with ds_creation_type clone.'
+  known_restrictions: 'Mutation class dynamic: benign_mutation for a new target, destructive when replacing an existing target. The export is appended to the source pipeline (end_of_pipeline) and re-runs with it; target_project_id sends the dataset into another project (cross-project branch-out, proven on release). Result: {dataset_id, project_id, source_view_id, next}. Not a plain copy: this leaves a live export on the source and the new dataset refreshes from the source view, so keep that working view and name it as the new dataset''s source. For an independent copy of a dataset use dataset create with ds_creation_type clone. Appending into an existing dataset (save_as_mode APPEND_TO_DS with target_ds_id): omit column_mapping and every column is mapped by name; a non-empty column_mapping is used as-is, so it must map every source column to an existing target column, and a partial mapping or an unknown destination is refused (append_mapping_incomplete) before anything is written. A mapped pair of different types is reported in row_check.warnings.'
   reviewed_by: primary
 - command_id: view.export.delete
   command_path: view export delete