changed my mind on maintenance

Author: rambleraptor

mkdocs/docs/cli.md

@@ -43,19 +43,20 @@ Options:
   --help                Show this message and exit.
 
 Commands:
-  create      Operation to create a namespace.
-  describe    Describe a namespace or a table.
-  drop        Operations to drop a namespace or table.
-  files       List all the files of the table.
-  list        List tables or namespaces.
-  list-refs   List all the refs in the provided table.
-  location    Return the location of the table.
-  properties  Properties on tables/namespaces.
-  rename      Rename a table.
-  schema      Get the schema of the table.
-  spec        Return the partition spec of the table.
-  uuid        Return the UUID of the table.
-  version     Print pyiceberg version.
+  create            Operation to create a namespace.
+  describe          Describe a namespace or a table.
+  drop              Operations to drop a namespace or table.
+  expire-snapshots  Expire snapshots from a table by ID or age.
+  files             List all the files of the table.
+  list              List tables or namespaces.
+  list-refs         List all the refs in the provided table.
+  location          Return the location of the table.
+  properties        Properties on tables/namespaces.
+  rename            Rename a table.
+  schema            Get the schema of the table.
+  spec              Return the partition spec of the table.
+  uuid              Return the UUID of the table.
+  version           Print pyiceberg version.
 ```
 
 This example assumes that you have a default catalog set. If you want to load another catalog, for example, the rest example above. Then you need to set `--catalog rest`.
@@ -254,3 +255,26 @@ To request purge for the underlying table files through the configured catalog,
 ➜  pyiceberg drop table nyc.taxis --purge
 Dropped table: nyc.taxis (purge requested)
 ```
+
+## Expire snapshots
+
+`expire-snapshots` removes snapshots from a table. Snapshots that are the HEAD of a branch or that are referenced by a tag are protected and will be skipped.
+
+Pass `--snapshot-id` one or more times to expire snapshots by ID, and/or `--older-than <ISO datetime>` to expire all unprotected snapshots older than the given timestamp. At least one of the two options is required.
+
+```sh
+➜  pyiceberg expire-snapshots nyc.taxis --snapshot-id 5937117119577207079
+Expired snapshots on nyc.taxis
+```
+
+```sh
+➜  pyiceberg expire-snapshots nyc.taxis \
+    --snapshot-id 5937117119577207079 \
+    --snapshot-id 4123987645210000000
+Expired snapshots on nyc.taxis
+```
+
+```sh
+➜  pyiceberg expire-snapshots nyc.taxis --older-than 2024-01-01T00:00:00
+Expired snapshots on nyc.taxis
+```

pyiceberg/cli/console.py

@@ -559,12 +559,7 @@ def _retention_properties(ref: SnapshotRef, table_properties: dict[str, str]) ->
     return retention_properties
 
 
-@run.group()
-def maintenance() -> None:
-    """Run maintenance operations on a table."""
-
-
-@maintenance.command("expire-snapshots")
+@run.command("expire-snapshots")
 @click.argument("identifier")
 @click.option(
     "--snapshot-id",

tests/cli/test_console.py

@@ -1332,7 +1332,9 @@ def _create_table_with_expirable_snapshot(catalog: InMemoryCatalog) -> int:
     )
     table.append(pa.Table.from_pylist([{"x": 1, "y": 2, "z": 3}], schema=arrow_schema))
     table.refresh()
-    older_snapshot_id = table.current_snapshot().snapshot_id
+    older_snapshot = table.current_snapshot()
+    assert older_snapshot is not None
+    older_snapshot_id = older_snapshot.snapshot_id
     table.append(pa.Table.from_pylist([{"x": 4, "y": 5, "z": 6}], schema=arrow_schema))
     return older_snapshot_id
 
@@ -1346,17 +1348,15 @@ def test_expire_snapshots_requires_option(catalog: InMemoryCatalog) -> None:
     )
 
     runner = CliRunner()
-    result = runner.invoke(run, ["maintenance", "expire-snapshots", "default.my_table"])
+    result = runner.invoke(run, ["expire-snapshots", "default.my_table"])
 
     assert result.exit_code == 1
     assert "Must provide at least one of --snapshot-id or --older-than." in result.output
 
 
 def test_expire_snapshots_table_does_not_exists(catalog: InMemoryCatalog) -> None:
-    # pylint: disable=unused-argument
-
     runner = CliRunner()
-    result = runner.invoke(run, ["maintenance", "expire-snapshots", "default.doesnotexist", "--snapshot-id", "1"])
+    result = runner.invoke(run, ["expire-snapshots", "default.doesnotexist", "--snapshot-id", "1"])
 
     assert result.exit_code == 1
     assert result.output == "Table does not exist: default.doesnotexist\n"
@@ -1366,7 +1366,7 @@ def test_expire_snapshots_by_id(catalog: InMemoryCatalog) -> None:
     snapshot_id = _create_table_with_expirable_snapshot(catalog)
 
     runner = CliRunner()
-    result = runner.invoke(run, ["maintenance", "expire-snapshots", "default.my_table", "--snapshot-id", str(snapshot_id)])
+    result = runner.invoke(run, ["expire-snapshots", "default.my_table", "--snapshot-id", str(snapshot_id)])
 
     assert result.exit_code == 0
     assert result.output == "Expired snapshots on default.my_table\n"
@@ -1383,7 +1383,6 @@ def test_expire_snapshots_older_than(catalog: InMemoryCatalog) -> None:
     result = runner.invoke(
         run,
         [
-            "maintenance",
             "expire-snapshots",
             "default.my_table",
             "--older-than",
@@ -1407,7 +1406,7 @@ def test_expire_snapshots_unknown_snapshot_id(catalog: InMemoryCatalog) -> None:
     )
 
     runner = CliRunner()
-    result = runner.invoke(run, ["maintenance", "expire-snapshots", "default.my_table", "--snapshot-id", "999"])
+    result = runner.invoke(run, ["expire-snapshots", "default.my_table", "--snapshot-id", "999"])
 
     assert result.exit_code == 1
     assert "Snapshot with ID 999 does not exist." in result.output
@@ -1419,7 +1418,7 @@ def test_json_expire_snapshots_by_id(catalog: InMemoryCatalog) -> None:
     runner = CliRunner()
     result = runner.invoke(
         run,
-        ["--output=json", "maintenance", "expire-snapshots", "default.my_table", "--snapshot-id", str(snapshot_id)],
+        ["--output=json", "expire-snapshots", "default.my_table", "--snapshot-id", str(snapshot_id)],
     )
 
     assert result.exit_code == 0