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

@@ -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.
         """

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
     ///

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
     }