From de8e072d96cfabf58533536ae4316b56405f4178 Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Sun, 31 May 2026 13:02:13 -0700 Subject: [PATCH] More clarity in docs --- docs/internals.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/internals.rst b/docs/internals.rst index 7f679867..f269155a 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -1942,22 +1942,24 @@ The optional ``request=`` argument is used internally by Datasette to pass reque The method will block until the operation is completed, and the return value will be an ``ExecuteWriteResult`` object. This imitates a subset of the ``sqlite3.Cursor`` object: ``.rowcount`` - The number of rows modified by the statement, or ``-1`` if SQLite cannot provide that information. + The number of rows modified by the statement, or ``-1`` if that number is unavailable. ``.lastrowid`` The row ID of the last modified row, as returned by ``sqlite3.Cursor.lastrowid``. ``.description`` - Column metadata for statements that return rows, otherwise ``None``. + The same column metadata exposed by Python's `sqlite3.Cursor.description `__: one tuple per returned column, or ``None`` if the statement does not return rows. ``.truncated`` ``True`` if the statement returned more rows than ``returning_limit``. ``.fetchall()`` - Returns any rows returned by the statement, such as rows from SQLite's ``RETURNING`` clause. This method returns buffered rows and empties that buffer, so calling it again will return an empty list. + Returns any rows buffered by Datasette from the statement, such as rows from SQLite's ``RETURNING`` clause. This may be limited by ``returning_limit`` unless ``return_all=True`` was used. This method empties the buffer, so calling it again will return an empty list. SQLite statements using ``RETURNING`` must have their rows consumed before the transaction can commit. Datasette will fetch up to ``returning_limit + 1`` rows before committing, store up to ``returning_limit`` rows on the result object and set ``.truncated`` if there were more. The default ``returning_limit`` is ``10``. +When ``.truncated`` is ``True``, ``.rowcount`` will be ``-1``. SQLite only reports the final row count for a ``RETURNING`` statement after every returned row has been fetched, and Datasette has deliberately stopped fetching rows after ``returning_limit`` to avoid buffering a potentially large result in memory. + If you need to retrieve every row returned by a statement, pass ``return_all=True``. This will buffer all returned rows in memory before committing. If you pass ``block=False`` this behavior changes to "fire and forget" - queries will be added to the write queue and executed in a separate thread while your code can continue to do other things. The method will return a UUID representing the queued task.