fix: update snapshot_when doc with trigger table being append-only re…

…quirement when history is requested. (#5853)

Fixes #5841

engine/table/src/main/java/io/deephaven/engine/table/impl/QueryTable.java

@@ -2401,7 +2401,9 @@ private static long snapshotHistoryInternal(
     private Table snapshotHistory(final String nuggetName, final Table baseTable,
             Collection<? extends JoinAddition> stampColumns) {
         return QueryPerformanceRecorder.withNugget(nuggetName, baseTable.sizeForInstrumentation(),
-                () -> maybeViewForSnapshot(stampColumns).snapshotHistoryInternal(baseTable));
+                () -> ((QueryTable) withAttributes(Map.of(APPEND_ONLY_TABLE_ATTRIBUTE, TRUE)))
+                        .maybeViewForSnapshot(stampColumns)
+                        .snapshotHistoryInternal(baseTable));
     }
 
     private Table snapshotHistoryInternal(final Table baseTable) {

py/server/deephaven/table.py

@@ -725,6 +725,10 @@ def snapshot_when(self, trigger_table: Table, stamp_cols: Union[str, List[str]]
         table. The "stamp key" is the last row of the trigger_table, limited by the stamp_cols. If trigger_table is
         empty, the "stamp key" will be represented by NULL values.
 
+        Note: the trigger_table must be append-only when the history flag is set to True. If the trigger_table is not
+        append-only and has modified or removed rows in its updates, the result snapshot table will be put in a failure
+        state and become unusable.
+
         Args:
             trigger_table (Table): the trigger table
             stamp_cols (Union[str, Sequence[str]): The columns from trigger_table that form the "stamp key", may be

py/server/tests/test_table.py

@@ -1,6 +1,7 @@
 #
 # Copyright (c) 2016-2024 Deephaven Data Labs and Patent Pending
 #
+import random
 import unittest
 from types import SimpleNamespace
 from typing import List, Any
@@ -13,6 +14,7 @@
 from deephaven.html import to_html
 from deephaven.jcompat import j_hashmap
 from deephaven.pandas import to_pandas
+from deephaven.stream.table_publisher import table_publisher
 from deephaven.table import Table, SearchDisplayMode
 from tests.testbase import BaseTestCase, table_equals
 
@@ -551,6 +553,13 @@ def test_snapshot_when_with_history(self):
         self.assertEqual(1 + len(self.test_table.columns), len(snapshot_hist.columns))
         self.assertEqual(self.test_table.size, snapshot_hist.size)
 
+        t = time_table("PT0.1S").update("X = i % 2 == 0 ? i : i - 1").sort("X").tail(10)
+        with update_graph.shared_lock(t):
+            snapshot_hist = self.test_table.snapshot_when(t, history=True)
+            self.assertFalse(snapshot_hist.j_table.isFailed())
+        self.wait_ticking_table_update(t, row_count=10, timeout=2)
+        self.assertTrue(snapshot_hist.j_table.isFailed())
+
     def test_agg_all_by(self):
         test_table = empty_table(10)
         test_table = test_table.update(

table-api/src/main/java/io/deephaven/api/snapshot/SnapshotWhenOptions.java

@@ -39,7 +39,8 @@ public enum Flag {
         INCREMENTAL,
         /**
          * Whether the resulting table should keep history. A history table appends a full snapshot of {@code base} and
-         * the "stamp key" as opposed to updating existing rows.
+         * the "stamp key" as opposed to updating existing rows. When this flag is used, the trigger table must be
+         * append-only.
          *
          * <p>
          * Note: this flag is currently incompatible with {@link #INITIAL} and {@link #INCREMENTAL}.