From ddc6df31b897def358f806d7d2ec5dffdfd6dd69 Mon Sep 17 00:00:00 2001
From: Jack Ye <yezhaoqin@gmail.com>
Date: Wed, 7 Oct 2026 23:03:39 -0700
Subject: [PATCH] docs(sql): a parameterized query's status follows its result
 stream

describe() reports running until the reader has received every row of a parameterized query, so callers should open the reader directly instead of waiting for finished.
---
 python/python/lancedb/db.py    | 4 +++-
 rust/lancedb/src/connection.rs | 5 ++++-
 rust/lancedb/src/sql.rs        | 9 +++++++++
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/python/python/lancedb/db.py b/python/python/lancedb/db.py
index 76e5c2ff4..aff86e9bf 100644
--- a/python/python/lancedb/db.py
+++ b/python/python/lancedb/db.py
@@ -1219,7 +1219,9 @@ class DBConnection(EnforceOverrides):
         Parameters are supported in queries, not in DDL or DML. A
         parameterized query runs on the call that returns its rows:
         cancelling it, or dropping its handle before reading, stops it on the
-        server.
+        server. Its status follows that stream as well: ``describe()``
+        reports ``running`` until the reader has received every row, so open
+        ``reader()`` directly rather than waiting for ``finished``.
 
         Local connections do not support SQL.
         """
diff --git a/rust/lancedb/src/connection.rs b/rust/lancedb/src/connection.rs
index 23a9231a0..c6138bcdd 100644
--- a/rust/lancedb/src/connection.rs
+++ b/rust/lancedb/src/connection.rs
@@ -375,7 +375,10 @@ impl ExecuteQueryAsyncBuilder {
     ///
     /// A parameterized statement runs on the call that returns its rows rather
     /// than detached from it: cancelling the query, or dropping its handle
-    /// before reading it, stops the statement on the server.
+    /// before reading it, stops the statement on the server. Its status follows
+    /// that stream too -- it reports `Running` until the reader has received
+    /// every row -- so open the reader directly rather than waiting for
+    /// `Finished`.
     ///
     /// # Example
     ///
diff --git a/rust/lancedb/src/sql.rs b/rust/lancedb/src/sql.rs
index b96fceb33..c2ef13ba5 100644
--- a/rust/lancedb/src/sql.rs
+++ b/rust/lancedb/src/sql.rs
@@ -17,6 +17,10 @@ pub enum QueryStatus {
     /// The server is still executing the query.
     Running,
     /// The server has made the complete result available.
+    ///
+    /// A query submitted with parameters streams its rows on the call that
+    /// runs it, so it reports `Finished` only once its reader has received
+    /// the last batch. Read it rather than waiting for this status.
     Finished,
     /// The server accepted cancellation but has not confirmed it yet.
     Cancelling,
@@ -90,6 +94,11 @@ impl Query {
     }
 
     /// Get a point-in-time description of the query.
+    ///
+    /// For a query submitted with parameters the status follows its result
+    /// stream: it stays [`QueryStatus::Running`] until the reader has received
+    /// every row, so open [`Self::reader`] directly instead of polling for
+    /// [`QueryStatus::Finished`] first.
     pub async fn describe(&self) -> Result<QueryDescription> {
         self.handle.describe().await
     }