Opt in to dropping revision on metadata update. (#972)

* Opt in to dropping revision on metadata update.

* Update CHANGELOG

* Use unique key (Windows Zarr test failure)

Author: danielballan

CHANGELOG.md

@@ -2,6 +2,16 @@
 Write the date in place of the "Unreleased" in the case a new version is released. -->
 # Changelog
 
+## Unreleased
+
+### Added
+
+- New query parameter `drop_revision` on endpoints `PUT /metadata/{path}`
+  and `PATCH /metadata/{path}`. If set to true, the version replaced by
+  the update is _not_ saved as a revision. This is exposed in the Python
+  client via a new keyword-only argument `drop_revision` in
+  `update_metadata`, `patch_metadata`, and `replace_metadata`.
+
 ## 0.1.0-b25 (2025-05-06)
 
 ### Added

tiled/_tests/test_writing.py

@@ -406,6 +406,23 @@ def test_metadata_revisions(tree):
             ac.metadata_revisions.delete_revision(1)
 
 
+def test_drop_revision(tree):
+    key = "test_drop_revision"
+    with Context.from_app(build_app(tree)) as context:
+        client = from_context(context)
+        # Set metadata color=blue.
+        ac = client.write_array([1, 2, 3], metadata={"color": "blue"}, key=key)
+        assert ac.metadata["color"] == "blue"
+        assert client[key].metadata["color"] == "blue"
+        assert len(ac.metadata_revisions[:]) == 0
+        # Update metadata to color=red, but drop revision.
+        ac.update_metadata(metadata={"color": "red"}, drop_revision=True)
+        # Metadata is updated; no revision is saved.
+        assert ac.metadata["color"] == "red"
+        assert client[key].metadata["color"] == "red"
+        assert len(ac.metadata_revisions) == 0
+
+
 def test_merge_patching(tree):
     "Test merge patching of metadata and specs"
     with Context.from_app(build_app(tree)) as context:

tiled/catalog/adapter.py

@@ -955,7 +955,7 @@ async def delete_revision(self, number):
             ), f"Deletion would affect {result.rowcount} rows; rolling back"
             await db.commit()
 
-    async def replace_metadata(self, metadata=None, specs=None):
+    async def replace_metadata(self, metadata=None, specs=None, *, drop_revision=False):
         values = {}
         if metadata is not None:
             # Trailing underscore in 'metadata_' avoids collision with
@@ -964,28 +964,31 @@ async def replace_metadata(self, metadata=None, specs=None):
         if specs is not None:
             values["specs"] = [s.model_dump() for s in specs]
         async with self.context.session() as db:
-            current = (
-                await db.execute(select(orm.Node).where(orm.Node.id == self.node.id))
-            ).scalar_one()
-            next_revision_number = 1 + (
-                (
+            if not drop_revision:
+                current = (
                     await db.execute(
-                        select(func.max(orm.Revision.revision_number)).where(
-                            orm.Revision.node_id == self.node.id
-                        )
+                        select(orm.Node).where(orm.Node.id == self.node.id)
                     )
                 ).scalar_one()
-                or 0
-            )
-            revision = orm.Revision(
-                # Trailing underscore in 'metadata_' avoids collision with
-                # SQLAlchemy reserved word 'metadata'.
-                metadata_=current.metadata_,
-                specs=current.specs,
-                node_id=current.id,
-                revision_number=next_revision_number,
-            )
-            db.add(revision)
+                next_revision_number = 1 + (
+                    (
+                        await db.execute(
+                            select(func.max(orm.Revision.revision_number)).where(
+                                orm.Revision.node_id == self.node.id
+                            )
+                        )
+                    ).scalar_one()
+                    or 0
+                )
+                revision = orm.Revision(
+                    # Trailing underscore in 'metadata_' avoids collision with
+                    # SQLAlchemy reserved word 'metadata'.
+                    metadata_=current.metadata_,
+                    specs=current.specs,
+                    node_id=current.id,
+                    revision_number=next_revision_number,
+                )
+                db.add(revision)
             await db.execute(
                 update(orm.Node).where(orm.Node.id == self.node.id).values(**values)
             )

tiled/client/base.py

@@ -446,7 +446,7 @@ def formats(self):
         )
         return sorted(formats)
 
-    def update_metadata(self, metadata=None, specs=None):
+    def update_metadata(self, metadata=None, specs=None, *, drop_revision=False):
         """
         EXPERIMENTAL: Update metadata via a `dict.update`- like interface.
 
@@ -461,6 +461,9 @@ def update_metadata(self, metadata=None, specs=None):
         specs : List[str], optional
             List of names that are used to label that the data and/or metadata
             conform to some named standard specification.
+        drop_revision : bool, optional
+            Replace current version without saving current version as a revision.
+            Use with caution.
 
         See Also
         --------
@@ -506,7 +509,11 @@ def update_metadata(self, metadata=None, specs=None):
         metadata_patch, specs_patch = self.build_metadata_patches(
             metadata=metadata, specs=specs
         )
-        self.patch_metadata(metadata_patch=metadata_patch, specs_patch=specs_patch)
+        self.patch_metadata(
+            metadata_patch=metadata_patch,
+            specs_patch=specs_patch,
+            drop_revision=drop_revision,
+        )
 
     def build_metadata_patches(self, metadata=None, specs=None):
         """
@@ -619,6 +626,7 @@ def patch_metadata(
         metadata_patch=None,
         specs_patch=None,
         content_type=patch_mimetypes.JSON_PATCH,
+        drop_revision=False,
     ):
         """
         EXPERIMENTAL: Patch metadata using a JSON Patch (RFC6902).
@@ -639,6 +647,9 @@ def patch_metadata(
               (See https://datatracker.ietf.org/doc/html/rfc6902)
             * "application/merge-patch+json"
               (See https://datatracker.ietf.org/doc/html/rfc7386)
+        drop_revision : bool, optional
+            Replace current version without saving current version as a revision.
+            Use with caution.
 
         See Also
         --------
@@ -689,13 +700,17 @@ def patcher(doc, patch, patch_type):
             "metadata": metadata_patch,
             "specs": normalized_specs_patch,
         }
+        params = {}
+        if drop_revision:
+            params["drop_revision"] = True
 
         for attempt in retry_context():
             with attempt:
                 content = handle_error(
                     self.context.http_client.patch(
                         self.item["links"]["self"],
                         content=safe_json_dump(data),
+                        params=params,
                     )
                 ).json()
 
@@ -716,7 +731,7 @@ def patcher(doc, patch, patch_type):
             patched_specs = patcher(current_specs, normalized_specs_patch, content_type)
             self._item["attributes"]["specs"] = patched_specs
 
-    def replace_metadata(self, metadata=None, specs=None):
+    def replace_metadata(self, metadata=None, specs=None, drop_revision=False):
         """
         EXPERIMENTAL: Replace metadata entirely (see update_metadata).
 
@@ -730,6 +745,9 @@ def replace_metadata(self, metadata=None, specs=None):
         specs : List[str], optional
             List of names that are used to label that the data and/or metadata
             conform to some named standard specification.
+        drop_revision : bool, optional
+            Replace current version without saving current version as a revision.
+            Use with caution.
 
         See Also
         --------
@@ -751,12 +769,17 @@ def replace_metadata(self, metadata=None, specs=None):
             "metadata": metadata,
             "specs": normalized_specs,
         }
+        params = {}
+        if drop_revision:
+            params["drop_revision"] = True
 
         for attempt in retry_context():
             with attempt:
                 content = handle_error(
                     self.context.http_client.put(
-                        self.item["links"]["self"], content=safe_json_dump(data)
+                        self.item["links"]["self"],
+                        content=safe_json_dump(data),
+                        params=params,
                     )
                 ).json()
 

tiled/server/router.py

@@ -1429,6 +1429,7 @@ async def patch_metadata(
         body: schemas.PatchMetadataRequest,
         settings: Settings = Depends(get_settings),
         entry: MapAdapter = Security(get_entry(), scopes=["write:metadata"]),
+        drop_revision: bool = False,
     ):
         if not hasattr(entry, "replace_metadata"):
             raise HTTPException(
@@ -1476,7 +1477,9 @@ async def patch_metadata(
             settings=settings,
         )
 
-        await entry.replace_metadata(metadata=metadata, specs=specs)
+        await entry.replace_metadata(
+            metadata=metadata, specs=specs, drop_revision=drop_revision
+        )
 
         response_data = {"id": entry.key}
         if metadata_modified:
@@ -1489,6 +1492,7 @@ async def put_metadata(
         body: schemas.PutMetadataRequest,
         settings: Settings = Depends(get_settings),
         entry: MapAdapter = Security(get_entry(), scopes=["write:metadata"]),
+        drop_revision: bool = False,
     ):
         if not hasattr(entry, "replace_metadata"):
             raise HTTPException(
@@ -1511,7 +1515,9 @@ async def put_metadata(
             settings=settings,
         )
 
-        await entry.replace_metadata(metadata=metadata, specs=specs)
+        await entry.replace_metadata(
+            metadata=metadata, specs=specs, drop_revision=drop_revision
+        )
 
         response_data = {"id": entry.key}
         if metadata_modified: