From 2f1bfa4858b6d9ef98d6149bf77f6da41280814a Mon Sep 17 00:00:00 2001
From: Aaron Wolen <aaron@wolen.com>
Date: Tue, 21 Apr 2026 16:13:20 -0500
Subject: [PATCH] py: add warnings for updating obs and var after deletion

- Document limitations of `update_obs` and `update_var` methods
- Note that deletion creates gaps in `soma_joinid` values
- Recommend using `DataFrame.write` as a workaround
---
 apis/python/src/tiledbsoma/_experiment.py | 14 ++++++++++++++
 apis/python/src/tiledbsoma/io/ingest.py   | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/apis/python/src/tiledbsoma/_experiment.py b/apis/python/src/tiledbsoma/_experiment.py
index 04168cd878..bf62620e38 100644
--- a/apis/python/src/tiledbsoma/_experiment.py
+++ b/apis/python/src/tiledbsoma/_experiment.py
@@ -169,6 +169,13 @@ def obs_axis_delete(
 
         Note: Deleting observations does not change the size of the current domain or possible enumeration values.
 
+        .. warning::
+
+            After deleting observations, :func:`~tiledbsoma.io.update_obs` cannot
+            cannot be used to update the remaining ``obs`` data. Deletion creates gaps in
+            ``soma_joinid`` values that ``update_obs`` does not currently handle.
+            Use :meth:`DataFrame.write` directly as a workaround.
+
         Args:
             coords:
                 A per-dimension ``Sequence`` of scalar, slice, sequence of scalar or
@@ -233,6 +240,13 @@ def var_axis_delete(
 
         Note: Deleting variables does not change the size of the current domain or possible enumeration values.
 
+        .. warning::
+
+            After deleting variables, :func:`~tiledbsoma.io.update_var` cannot
+            be used to update the remaining ``var`` data. Deletion creates gaps in
+            ``soma_joinid`` values that ``update_var`` does not currently handle.
+            Use :meth:`DataFrame.write` directly as a workaround.
+
         Args:
             coords:
                 A per-dimension ``Sequence`` of scalar, slice, sequence of scalar or
diff --git a/apis/python/src/tiledbsoma/io/ingest.py b/apis/python/src/tiledbsoma/io/ingest.py
index 0b05a23e8c..64f839482a 100644
--- a/apis/python/src/tiledbsoma/io/ingest.py
+++ b/apis/python/src/tiledbsoma/io/ingest.py
@@ -1412,6 +1412,13 @@ def update_obs(
         2. Modify values / add or drop columns while preserving row order.
         3. Pass the modified DataFrame as ``new_data``.
 
+    .. warning::
+
+        Currently this function does not work on Experiments that have had
+        observations deleted via :func:`obs_axis_delete`. Deletion creates gaps
+        in ``soma_joinid`` values, which causes an internal validation check to
+        fail. As a workaround, use :meth:`DataFrame.write` directly.
+
     Args:
         exp: :class:`Experiment` opened for write.
         new_data: A :class:`pandas.DataFrame` containing the final desired data for the existing ``obs`` DataFrame.
@@ -1450,6 +1457,13 @@ def update_var(
 
     Analogous to ``update_obs``, but replaces the ``var`` DataFrame within a specific :class:`Measurement`. See :func:`update_obs` for details.
 
+    .. warning::
+
+        This function does not work on Experiments that have had variables
+        deleted via :func:`var_axis_delete`. Deletion creates gaps in
+        ``soma_joinid`` values, which causes an internal validation check to
+        fail. As a workaround, use :meth:`DataFrame.write` directly.
+
     Args:
         exp: :class:`Experiment` opened for write.
         new_data: A ``pandas.DataFrame`` containing the final desired data for the ``Measurement``'s ``var``.