vgi-python 0.31.4__py3-none-any.whl → 0.32.0__py3-none-any.whl

vgi/__init__.py

@@ -129,10 +129,15 @@ from vgi.table_in_out_function import (
     TableInOutGenerator,
 )
 from vgi.worker import Worker
+from vgi.write_results import WriteOperation, WriteResultMode, write_changes_batch, write_result_schema
 
 __all__ = [
     "AggregateBindParams",
     "AggregateFunction",
+    "WriteOperation",
+    "WriteResultMode",
+    "write_result_schema",
+    "write_changes_batch",
     "AnyArrow",
     "AnyArrowValue",
     "Arg",

vgi/_test_fixtures/schema_reconcile/worker.py

@@ -528,9 +528,7 @@ class SchemaReconcileCatalog(ReadOnlyCatalogInterface):
             not_null_constraints=[],
             unique_constraints=[],
             check_constraints=[],
-            supports_insert=True,
-            supports_update=True,
-            supports_delete=True,
+            write_result_modes={"insert": "changes", "update": "changes", "delete": "changes"},
         )
 
     def schemas(

vgi/_test_fixtures/simple_writable.py

@@ -13,7 +13,7 @@ Three pre-defined tables are exposed under the ``main`` schema:
 
 * ``items`` — supports INSERT/UPDATE/DELETE with RETURNING.
 * ``items_no_returning`` — supports INSERT/UPDATE/DELETE *without* RETURNING.
-  Used to exercise the supports_returning=False rejection path.
+  Used to exercise the ``count``-only RETURNING rejection path.
 * ``items_insert_only`` — supports INSERT only (no UPDATE/DELETE/RETURNING).
 
 State is held module-global, keyed by ``attach_opaque_data``. Per the
@@ -60,6 +60,7 @@ from vgi.schema_utils import schema as build_schema
 from vgi.table_function import BindParams, InitParams, ProcessParams, TableFunctionGenerator
 from vgi.table_in_out_function import TableInOutGenerator
 from vgi.worker import Worker
+from vgi.write_results import WriteResultMode, coerce_write_result_mode, write_changes_batch, write_result_schema
 
 if TYPE_CHECKING:
     from vgi.catalog.catalog_interface import (
@@ -82,7 +83,7 @@ CATALOG_NAME = "simple_writable"
 _ROWID_FIELD = pa.field("rowid", pa.int64(), metadata={b"is_row_id": b""})
 
 # Output schema for write functions returning affected row counts.
-_COUNT_SCHEMA = build_schema(count=pa.int64())
+_COUNT_SCHEMA = pa.schema([pa.field("count", pa.int64(), nullable=False)])
 
 
 # ============================================================================
@@ -116,7 +117,7 @@ def _table_specs() -> dict[str, pa.Schema]:
         "items": build_schema(id=pa.int64(), name=pa.string(), qty=pa.int64()),
         "items_no_returning": build_schema(id=pa.int64(), name=pa.string(), qty=pa.int64()),
         "items_insert_only": build_schema(id=pa.int64(), name=pa.string()),
-        # Lies: catalog advertises supports_returning=True but the insert
+        # Lies: catalog advertises rows support but the insert
         # function always emits a (count BIGINT) batch. Used by tests to verify
         # the C++ extension rejects the mismatched batch with a clean IOException
         # instead of crashing inside ArrowToDuckDB.
@@ -124,8 +125,12 @@ def _table_specs() -> dict[str, pa.Schema]:
     }
 
 
-def _table_supports_returning(name: str) -> bool:
-    return name != "items_no_returning"
+def _table_result_mode(name: str) -> str:
+    if name == "items_no_returning":
+        return "count"
+    if name == "items_broken_returning":
+        return "rows"
+    return "changes"
 
 
 def _table_supports_update_delete(name: str) -> bool:
@@ -224,20 +229,25 @@ def _attach_opaque_data_from_process(params: ProcessParams[None]) -> bytes:
     return bytes(aid)
 
 
-def _parse_write_options(params: BindParams[None]) -> dict[str, Any]:
+def _parse_write_options(params: BindParams[None] | ProcessParams[None]) -> dict[str, Any]:
     """Decode the write_options batch passed in named arguments."""
-    defaults: dict[str, Any] = {"return_chunks": False, "on_conflict": "throw", "on_conflict_columns": []}
-    if not (params.bind_call.arguments and params.bind_call.arguments.named):
+    defaults: dict[str, Any] = {"result_mode": "count", "on_conflict": "throw", "on_conflict_columns": []}
+    if isinstance(params, BindParams):
+        bind_call = params.bind_call
+    else:
+        assert params.init_call is not None
+        bind_call = params.init_call.bind_call
+    if not (bind_call.arguments and bind_call.arguments.named):
         return defaults
-    val = params.bind_call.arguments.named.get("write_options")
+    val = bind_call.arguments.named.get("write_options")
     if val is None:
         return defaults
     from vgi_rpc.utils import deserialize_record_batch
 
     batch, _ = deserialize_record_batch(val.as_py())
     out = dict(defaults)
-    if "return_chunks" in batch.schema.names:
-        out["return_chunks"] = batch.column("return_chunks")[0].as_py()
+    if "result_mode" in batch.schema.names:
+        out["result_mode"] = coerce_write_result_mode(batch.column("result_mode")[0].as_py())
     if "on_conflict" in batch.schema.names:
         out["on_conflict"] = batch.column("on_conflict")[0].as_py()
     if "on_conflict_columns" in batch.schema.names:
@@ -245,6 +255,26 @@ def _parse_write_options(params: BindParams[None]) -> dict[str, Any]:
     return out
 
 
+def _emit_changes(
+    out: OutputCollector,
+    table_schema: pa.Schema,
+    old_rows: Sequence[tuple[Any, ...] | None],
+    new_rows: Sequence[tuple[Any, ...] | None],
+) -> None:
+    names = table_schema.names
+
+    def as_struct(row: tuple[Any, ...] | None) -> dict[str, Any] | None:
+        return None if row is None else dict(zip(names, row, strict=True))
+
+    out.emit(
+        write_changes_batch(
+            table_schema,
+            [as_struct(row) for row in old_rows],
+            [as_struct(row) for row in new_rows],
+        )
+    )
+
+
 def _user_schema_from_bind(params: BindParams[None]) -> pa.Schema:
     qualified = _qualified_from_bind(params)
     return _get_user_schema(qualified)
@@ -329,9 +359,8 @@ class SimpleInsert(TableInOutGenerator[None, None]):
     @classmethod
     def on_bind(cls, params: BindParams[None]) -> BindResponse:
         opts = _parse_write_options(params)
-        if opts["return_chunks"]:
-            return BindResponse(output_schema=_user_schema_from_bind(params))
-        return BindResponse(output_schema=_COUNT_SCHEMA)
+        mode = opts["result_mode"]
+        return BindResponse(output_schema=write_result_schema(mode, _user_schema_from_bind(params)))
 
     @classmethod
     def process(
@@ -345,7 +374,7 @@ class SimpleInsert(TableInOutGenerator[None, None]):
         attach_opaque_data = _attach_opaque_data_from_process(params)
         bare = _bare_name(qualified)
         user_schema = _get_user_schema(qualified)
-        return_chunks = params.output_schema != _COUNT_SCHEMA
+        result_mode: WriteResultMode = _parse_write_options(params)["result_mode"]
 
         col_names = [f.name for f in user_schema]
         cols_sql = ", ".join(f'"{c}"' for c in col_names)
@@ -362,12 +391,14 @@ class SimpleInsert(TableInOutGenerator[None, None]):
             )
             conn.execute("COMMIT")
 
-        if return_chunks:
+        if result_mode == "rows":
             out_cols: dict[str, list[Any]] = {c: [] for c in col_names}
             for row in rows_to_insert:
                 for c, v in zip(col_names, row, strict=True):
                     out_cols[c].append(v)
             out.emit(pa.RecordBatch.from_pydict(out_cols, schema=user_schema))
+        elif result_mode == "changes":
+            _emit_changes(out, user_schema, [None] * len(rows_to_insert), rows_to_insert)
         else:
             out.emit(pa.RecordBatch.from_pydict({"count": [batch.num_rows]}, schema=_COUNT_SCHEMA))
 
@@ -381,9 +412,8 @@ class SimpleUpdate(TableInOutGenerator[None, None]):
     @classmethod
     def on_bind(cls, params: BindParams[None]) -> BindResponse:
         opts = _parse_write_options(params)
-        if opts["return_chunks"]:
-            return BindResponse(output_schema=_user_schema_from_bind(params))
-        return BindResponse(output_schema=_COUNT_SCHEMA)
+        mode = opts["result_mode"]
+        return BindResponse(output_schema=write_result_schema(mode, _user_schema_from_bind(params)))
 
     @classmethod
     def process(
@@ -397,7 +427,7 @@ class SimpleUpdate(TableInOutGenerator[None, None]):
         attach_opaque_data = _attach_opaque_data_from_process(params)
         bare = _bare_name(qualified)
         user_schema = _get_user_schema(qualified)
-        return_chunks = params.output_schema != _COUNT_SCHEMA
+        result_mode: WriteResultMode = _parse_write_options(params)["result_mode"]
 
         update_cols = [n for n in batch.schema.names if n != "rowid"]
         set_clause = ", ".join(f'"{c}"=?' for c in update_cols)
@@ -405,23 +435,31 @@ class SimpleUpdate(TableInOutGenerator[None, None]):
         select_list = ", ".join(f'"{c}"' for c in user_col_names)
 
         rowid_col = batch.column("rowid")
+        old_rows: list[tuple[Any, ...]] = []
         updated: list[tuple[Any, ...]] = []
         with _connect(attach_opaque_data) as conn:
             conn.execute("BEGIN")
             for i in range(batch.num_rows):
                 rowid = rowid_col[i].as_py()
+                old_row = conn.execute(f'SELECT {select_list} FROM "{bare}" WHERE rowid=?', (rowid,)).fetchone()
+                if old_row is None:
+                    conn.execute("ROLLBACK")
+                    raise ValueError(f"Update target rowid {rowid} not in table {qualified}")
                 values = tuple(batch.column(c)[i].as_py() for c in update_cols)
                 cur = conn.execute(f'UPDATE "{bare}" SET {set_clause} WHERE rowid=?', (*values, rowid))
                 if cur.rowcount == 0:
                     conn.execute("ROLLBACK")
                     raise ValueError(f"Update target rowid {rowid} not in table {qualified}")
                 row = conn.execute(f'SELECT {select_list} FROM "{bare}" WHERE rowid=?', (rowid,)).fetchone()
+                old_rows.append(old_row)
                 updated.append(row)
             conn.execute("COMMIT")
 
-        if return_chunks:
+        if result_mode == "rows":
             cols = {c: [row[i] for row in updated] for i, c in enumerate(user_col_names)}
             out.emit(pa.RecordBatch.from_pydict(cols, schema=user_schema))
+        elif result_mode == "changes":
+            _emit_changes(out, user_schema, old_rows, updated)
         else:
             out.emit(pa.RecordBatch.from_pydict({"count": [batch.num_rows]}, schema=_COUNT_SCHEMA))
 
@@ -435,9 +473,8 @@ class SimpleDelete(TableInOutGenerator[None, None]):
     @classmethod
     def on_bind(cls, params: BindParams[None]) -> BindResponse:
         opts = _parse_write_options(params)
-        if opts["return_chunks"]:
-            return BindResponse(output_schema=_user_schema_from_bind(params))
-        return BindResponse(output_schema=_COUNT_SCHEMA)
+        mode = opts["result_mode"]
+        return BindResponse(output_schema=write_result_schema(mode, _user_schema_from_bind(params)))
 
     @classmethod
     def process(
@@ -451,7 +488,7 @@ class SimpleDelete(TableInOutGenerator[None, None]):
         attach_opaque_data = _attach_opaque_data_from_process(params)
         bare = _bare_name(qualified)
         user_schema = _get_user_schema(qualified)
-        return_chunks = params.output_schema != _COUNT_SCHEMA
+        result_mode: WriteResultMode = _parse_write_options(params)["result_mode"]
 
         user_col_names = [f.name for f in user_schema]
         select_list = ", ".join(f'"{c}"' for c in user_col_names)
@@ -470,9 +507,11 @@ class SimpleDelete(TableInOutGenerator[None, None]):
                 deleted.append(row)
             conn.execute("COMMIT")
 
-        if return_chunks:
+        if result_mode == "rows":
             cols = {c: [row[i] for row in deleted] for i, c in enumerate(user_col_names)}
             out.emit(pa.RecordBatch.from_pydict(cols, schema=user_schema))
+        elif result_mode == "changes":
+            _emit_changes(out, user_schema, deleted, [None] * len(deleted))
         else:
             out.emit(pa.RecordBatch.from_pydict({"count": [batch.num_rows]}, schema=_COUNT_SCHEMA))
 
@@ -491,7 +530,7 @@ class BrokenReturningInsert(TableInOutGenerator[None, None]):
 
     @classmethod
     def on_bind(cls, params: BindParams[None]) -> BindResponse:
-        # Always advertise the count surface, even when return_chunks=True.
+        # Always advertise the count surface, even when result_mode=rows.
         # The C++ side will see this at bind via the worker's output schema and
         # tries to route the responses through ArrowToDuckDB on the table-row
         # schema — that mismatch is what we want to catch at runtime.
@@ -524,7 +563,7 @@ class BrokenReturningInsert(TableInOutGenerator[None, None]):
                 rows_to_insert,
             )
             conn.execute("COMMIT")
-        # Always emit count, regardless of return_chunks — that's the bug.
+        # Always emit count, regardless of result_mode — that's the bug.
         out.emit(pa.RecordBatch.from_pydict({"count": [batch.num_rows]}, schema=_COUNT_SCHEMA))
 
 
@@ -619,10 +658,11 @@ class SimpleWritableCatalog(ReadOnlyCatalogInterface):
             check_constraints=[],
             primary_key_constraints=[],
             foreign_key_constraints=[],
-            supports_insert=True,
-            supports_update=ud,
-            supports_delete=ud,
-            supports_returning=_table_supports_returning(name),
+            write_result_modes={
+                operation: _table_result_mode(name)
+                for operation, supported in (("insert", True), ("update", ud), ("delete", ud))
+                if supported
+            },
         )
 
     def table_get(

vgi/_test_fixtures/writable/generic.py

@@ -27,12 +27,14 @@ from vgi._test_fixtures.writable.table import (
     _get_attach_opaque_data,
     _get_pushdown_filters,
     _get_tx_id,
-    _is_returning,
+    _parse_write_options,
+    _result_mode,
     transactor_proxy,
 )
 from vgi.invocation import BindResponse, GlobalInitResponse
 from vgi.table_function import BindParams, InitParams, ProcessParams, TableFunctionGenerator
 from vgi.table_in_out_function import TableInOutGenerator
+from vgi.write_results import WriteResultMode, coerce_write_result_mode, write_result_schema
 
 __all__ = [
     "GenericTableDelete",
@@ -141,15 +143,16 @@ class _GenericWriteBase(TableInOutGenerator[None, None]):
 
     @classmethod
     def on_bind(cls, params: BindParams[None]) -> BindResponse:
-        """Bind: query transactor for table schema to use for RETURNING."""
+        """Bind using the exact result schema requested by the client."""
         table_name = _get_table_name_from_bind(params)
-        if _is_returning(params):
+        result_mode = _result_mode(params)
+        if result_mode != "count":
             attach_opaque_data = params.attach_opaque_data  # unwrapped plaintext
             tx_id = params.bind_call.transaction_opaque_data
             assert attach_opaque_data is not None and tx_id is not None
             table_schema = _get_table_schema_from_transactor(table_name, attach_opaque_data, tx_id)
             user_fields = [f for f in table_schema if f.name not in ("rowid", "row_id")]
-            return BindResponse(output_schema=pa.schema(user_fields))
+            return BindResponse(output_schema=write_result_schema(result_mode, pa.schema(user_fields)))
         return BindResponse(output_schema=_COUNT_SCHEMA)
 
     @classmethod
@@ -159,7 +162,7 @@ class _GenericWriteBase(TableInOutGenerator[None, None]):
         attach_opaque_data: bytes,
         tx_id: bytes,
         table_name: str,
-        returning: bool,
+        result_mode: WriteResultMode,
         batch: pa.RecordBatch,
     ) -> Any:
         """Open a write stream. Override for operations needing extra args."""
@@ -167,7 +170,7 @@ class _GenericWriteBase(TableInOutGenerator[None, None]):
             attach_opaque_data=attach_opaque_data,
             tx_id=tx_id,
             table_name=table_name,
-            returning=returning,
+            result_mode=result_mode,
         )
 
     @classmethod
@@ -176,9 +179,10 @@ class _GenericWriteBase(TableInOutGenerator[None, None]):
         table_name = _get_table_name_from_process(params)
         attach_opaque_data = _get_attach_opaque_data(params)
         tx_id = _get_tx_id(params)
-        returning = params.output_schema != _COUNT_SCHEMA
+        assert params.init_call is not None
+        result_mode = coerce_write_result_mode(str(_parse_write_options(params.init_call.bind_call)["result_mode"]))
         proxy = transactor_proxy._get_proxy()
-        with cls._open_stream(proxy, attach_opaque_data, tx_id, table_name, returning, batch) as stream:
+        with cls._open_stream(proxy, attach_opaque_data, tx_id, table_name, result_mode, batch) as stream:
             response = stream.exchange(AnnotatedBatch(batch=batch))
             out.emit(response.batch)
 
@@ -211,7 +215,7 @@ class GenericTableUpdate(_GenericWriteBase):
         attach_opaque_data: bytes,
         tx_id: bytes,
         table_name: str,
-        returning: bool,
+        result_mode: WriteResultMode,
         batch: pa.RecordBatch,
     ) -> Any:
         """Open an update stream with column list derived from the batch."""
@@ -221,7 +225,7 @@ class GenericTableUpdate(_GenericWriteBase):
             tx_id=tx_id,
             table_name=table_name,
             columns=update_cols,
-            returning=returning,
+            result_mode=result_mode,
         )
 
 

vgi/_test_fixtures/writable/table.py

@@ -16,7 +16,6 @@ from typing import TYPE_CHECKING, Annotated
 import pyarrow as pa
 from vgi_rpc import AnnotatedBatch, ArrowSerializableDataclass, Transient
 
-from vgi.schema_utils import schema
 from vgi.table_function import BindParams, ProcessParams
 
 if TYPE_CHECKING:
@@ -24,6 +23,7 @@ if TYPE_CHECKING:
 
 from vgi.transactor.client import TransactorClient
 from vgi.transactor.protocol import TransactorProtocol
+from vgi.write_results import WriteResultMode, coerce_write_result_mode
 
 __all__ = [
     "TransactorProxy",
@@ -32,17 +32,17 @@ __all__ = [
 ]
 
 # Output schema for write functions returning affected row counts.
-_COUNT_SCHEMA = schema(count=pa.int64())
+_COUNT_SCHEMA = pa.schema([pa.field("count", pa.int64(), nullable=False)])
 
 # DuckDB's native rowid pseudocolumn, marked with is_row_id metadata so the
 # C++ extension knows which column carries the physical row identifier.
 _ROWID_FIELD = pa.field("rowid", pa.int64(), metadata={b"is_row_id": b""})
 
 
-def _parse_write_options(bind_call: BindRequest) -> dict[str, bool | str | list[str]]:
+def _parse_write_options(bind_call: BindRequest) -> dict[str, str | list[str]]:
     """Parse the write_options RecordBatch from the bind call's named arguments."""
-    defaults: dict[str, bool | str | list[str]] = {
-        "return_chunks": False,
+    defaults: dict[str, str | list[str]] = {
+        "result_mode": "count",
         "on_conflict": "throw",
         "on_conflict_columns": [],
     }
@@ -56,8 +56,8 @@ def _parse_write_options(bind_call: BindRequest) -> dict[str, bool | str | list[
     options_bytes = val.as_py()
     batch, _ = deserialize_record_batch(options_bytes)
     result = dict(defaults)
-    if "return_chunks" in batch.schema.names:
-        result["return_chunks"] = batch.column("return_chunks")[0].as_py()
+    if "result_mode" in batch.schema.names:
+        result["result_mode"] = coerce_write_result_mode(batch.column("result_mode")[0].as_py())
     if "on_conflict" in batch.schema.names:
         result["on_conflict"] = batch.column("on_conflict")[0].as_py()
     if "on_conflict_columns" in batch.schema.names:
@@ -65,10 +65,10 @@ def _parse_write_options(bind_call: BindRequest) -> dict[str, bool | str | list[
     return result
 
 
-def _is_returning(params: BindParams[None]) -> bool:
-    """Check if the C++ operator requested RETURNING rows."""
+def _result_mode(params: BindParams[None]) -> WriteResultMode:
+    """Return the exact writable result mode requested by the client."""
     opts = _parse_write_options(params.bind_call)
-    return bool(opts.get("return_chunks", False))
+    return coerce_write_result_mode(str(opts["result_mode"]))
 
 
 def _get_tx_id(params: ProcessParams[None]) -> bytes:

vgi/_test_fixtures/writable/worker.py

@@ -907,10 +907,7 @@ class WritableCatalog(ReadOnlyCatalogInterface):
             check_constraints=check_constraints,
             primary_key_constraints=primary_key_constraints,
             foreign_key_constraints=foreign_key_constraints,
-            supports_insert=True,
-            supports_update=True,
-            supports_delete=True,
-            supports_returning=True,
+            write_result_modes={"insert": "changes", "update": "changes", "delete": "changes"},
             comment=table_comment,
             tags={},
         )

vgi/catalog/__init__.py

@@ -44,6 +44,7 @@ from vgi.catalog.descriptors import Catalog, ForeignKeyDef, Index, Macro, Schema
 from vgi.catalog.secret_type import SecretTypeSpec
 from vgi.catalog.setting import Setting, SettingSpec
 from vgi.catalog.storage import CatalogStorage, CatalogStorageSqlite
+from vgi.write_results import WriteOperation, WriteResultMode, write_changes_batch, write_result_schema
 
 __all__ = [
     # Type aliases
@@ -89,6 +90,10 @@ __all__ = [
     "Sql",
     "Table",
     "View",
+    "WriteOperation",
+    "WriteResultMode",
+    "write_result_schema",
+    "write_changes_batch",
     # Interfaces
     "CatalogInterface",
     "ReadOnlyCatalogInterface",

vgi/catalog/catalog_interface.py

@@ -422,13 +422,10 @@ class TableInfo(CatalogSchemaObject, ArrowSerializableDataclass):
         check_constraints: SQL CHECK constraint expressions.
         primary_key_constraints: Column-index groups forming the primary key.
         foreign_key_constraints: Serialized foreign-key constraint specs.
-        supports_insert: Write-support flag — whether the table supports INSERT.
-        supports_update: Write-support flag — whether the table supports UPDATE.
-        supports_delete: Write-support flag — whether the table supports DELETE.
-        supports_returning: When False (the default), the C++ extension rejects
-            INSERT/UPDATE/DELETE ... RETURNING at plan time with a
-            BinderException. Workers that can emit the affected rows from their
-            write functions must opt in by setting this to True.
+        write_result_modes: Maximum result mode supported for each writable
+            operation. Keys are ``insert``, ``update``, and ``delete``; a missing
+            key means the operation is unsupported. Values are ordered
+            ``count < rows < changes`` and promise every lower mode.
         supports_column_statistics: Statistics capability flag — indicates this
             table can provide column statistics.
         scan_function: Optional inlined function-discovery result. When
@@ -503,10 +500,9 @@ class TableInfo(CatalogSchemaObject, ArrowSerializableDataclass):
     )
     foreign_key_constraints: Annotated[list[bytes], ArrowType(pa.list_(pa.binary()))] = field(default_factory=list)
 
-    supports_insert: bool = False
-    supports_update: bool = False
-    supports_delete: bool = False
-    supports_returning: bool = False
+    write_result_modes: Annotated[dict[str, str], ArrowType(pa.map_(pa.string(), pa.string()))] = field(
+        default_factory=dict
+    )
 
     supports_column_statistics: bool = False
 

vgi/catalog/descriptors.py

@@ -41,6 +41,7 @@ from vgi.catalog.catalog_interface import (
 from vgi.invocation import BindResponse, FunctionType
 from vgi.metadata import CatalogFunctionType
 from vgi.schema_path import SchemaPath, schema_path_display, schema_path_key
+from vgi.write_results import validate_write_result_modes
 
 if TYPE_CHECKING:
     from vgi.function import Function
@@ -268,6 +269,9 @@ class Table:
         delete_function: [`TableInOutGenerator`][] class backing DELETE. Requires
             a scan ``function`` to provide row IDs. ``None`` means DELETE is
             unsupported.
+        write_result_modes: Maximum result mode for each configured write
+            function. Omitted operations default to ``count``. Modes are ordered
+            ``count < rows < changes``.
         not_null: Tuple of column names with NOT NULL constraints.
         unique: Tuple of column name tuples for UNIQUE constraints.
         check: Tuple of SQL expressions for CHECK constraints.
@@ -332,6 +336,7 @@ class Table:
     insert_function: type[TableInOutGenerator[Any, Any]] | None = None
     update_function: type[TableInOutGenerator[Any, Any]] | None = None
     delete_function: type[TableInOutGenerator[Any, Any]] | None = None
+    write_result_modes: dict[str, str] = field(default_factory=dict)
     not_null: tuple[str, ...] = ()
     unique: tuple[tuple[str, ...], ...] = ()
     check: tuple[str, ...] = ()
@@ -388,6 +393,19 @@ class Table:
                         f"override or leave inline_bind=False."
                     )
 
+        modes = validate_write_result_modes(self.write_result_modes)
+        functions = {
+            "insert": self.insert_function,
+            "update": self.update_function,
+            "delete": self.delete_function,
+        }
+        for operation in modes:
+            if functions[operation] is None:
+                raise ValueError(
+                    f"Table '{self.name}': write_result_modes declares {operation!r} "
+                    f"without a corresponding {operation}_function"
+                )
+
         # Resolve columns to validate constraints
         resolved = self._get_resolved_columns()
         column_names = {f.name for f in resolved}
@@ -650,9 +668,15 @@ class Table:
             check_constraints=list(self.check),
             primary_key_constraints=self._resolve_primary_key_indices(),
             foreign_key_constraints=self._serialize_foreign_keys(schema_path),
-            supports_insert=self.insert_function is not None,
-            supports_update=self.update_function is not None,
-            supports_delete=self.delete_function is not None,
+            write_result_modes={
+                operation: self.write_result_modes.get(operation, "count")
+                for operation, function in (
+                    ("insert", self.insert_function),
+                    ("update", self.update_function),
+                    ("delete", self.delete_function),
+                )
+                if function is not None
+            },
             supports_column_statistics=bool(self.statistics),
             comment=self.comment,
             tags=dict(self.tags),