samples(bigquery-storage): add Arrow query results samples for query_and_wait and read_rows (#18126)

## Description

Adds documentation code snippets and system tests demonstrating
high-performance query result retrieval in Apache Arrow format with LZ4
compression using the BigQuery Storage API:

1. **`query_and_wait()` with Arrow format & LZ4 frame compression**
(`query_and_wait_arrow.py`):
- Demonstrates calling `client.query_and_wait()` with
`query_results_format=enums.QueryResultsFormat.ARROW` and
`compression_codec=enums.QueryResultsCompressionCodec.LZ4_FRAME`.
- Returns results as an iterable of `pyarrow.RecordBatch` via
`results.to_arrow_iterable()`.
- Wrapped in region tag: `[START bigquerystorage_query_and_wait_arrow]`.

2. **Direct `read_rows` on query job default stream**
(`read_rows_query_job.py`):
- Demonstrates directly reading query results using
`BigQueryReadClient.read_rows` against the job stream
`projects/{project}/locations/{location}/jobs/{job_id}/streams/_default`.
   - Deserializes schema and record batches safely via `pyarrow.ipc`.
- Wrapped in region tag: `[START bigquerystorage_read_rows_query_job]`.

3. **Tests & Dependencies**:
- Added `query_and_wait_arrow_test.py` and `read_rows_query_job_test.py`
verifying batch iteration and schema types.
- Added `pyarrow` dependency pins to
`samples/snippets/requirements.txt`.

Follow-up to #18027
Related to #18047

## Checklist
- [x] Ensure the tests and linter pass
- [x] Code coverage does not decrease (if any source code was changed)
- [x] Appropriate docs were updated (if necessary)

Author: alextolpin

packages/google-cloud-bigquery-storage/samples/snippets/query_and_wait_arrow.py

@@ -0,0 +1,53 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START bigquerystorage_query_and_wait_arrow]
+from typing import Iterable
+
+import pyarrow
+from google.cloud.bigquery import enums
+
+from google.cloud import bigquery
+
+
+def query_and_wait_arrow() -> Iterable[pyarrow.RecordBatch]:
+    """Queries BigQuery and returns results as an iterable of Apache Arrow RecordBatches.
+
+    Returns:
+        Iterable[pyarrow.RecordBatch]: An iterable of Apache Arrow RecordBatch objects.
+    """
+    # Initialize a BigQuery client.
+    client = bigquery.Client()
+
+    query = """
+        SELECT name, number, state
+        FROM `bigquery-public-data.usa_names.usa_1910_current`
+        LIMIT 100000
+    """
+
+    # Run the query and wait for results returned directly in Arrow format
+    # compressed with LZ4_FRAME.
+    results = client.query_and_wait(
+        query,
+        query_results_format=enums.QueryResultsFormat.ARROW,
+        compression_codec=enums.QueryResultsCompressionCodec.LZ4_FRAME,
+    )
+
+    # Return results as an iterable of pyarrow.RecordBatch objects.
+    # Each batch contains a slice of the rows in Apache Arrow format.
+    batches = results.to_arrow_iterable()
+    return batches
+
+
+# [END bigquerystorage_query_and_wait_arrow]

packages/google-cloud-bigquery-storage/samples/snippets/query_and_wait_arrow_test.py

@@ -0,0 +1,35 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pyarrow
+
+from . import query_and_wait_arrow
+
+
+def test_query_and_wait_arrow():
+    batches = query_and_wait_arrow.query_and_wait_arrow()
+
+    total_rows = 0
+    batch_count = 0
+    for batch in batches:
+        assert isinstance(batch, pyarrow.RecordBatch)
+        assert batch.schema.names == ["name", "number", "state"]
+        assert batch.schema.field("name").type == pyarrow.string()
+        assert batch.schema.field("number").type == pyarrow.int64()
+        assert batch.schema.field("state").type == pyarrow.string()
+        total_rows += batch.num_rows
+        batch_count += 1
+
+    assert total_rows == 100000
+    assert batch_count > 0

packages/google-cloud-bigquery-storage/samples/snippets/read_rows_query_job.py

@@ -0,0 +1,71 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START bigquerystorage_read_rows_query_job]
+from typing import Iterable, Optional
+
+import pyarrow
+
+from google.cloud import bigquery, bigquery_storage_v1
+
+
+def read_rows_query_job() -> Iterable[pyarrow.RecordBatch]:
+    """Queries BigQuery and yields batches directly via BigQueryReadClient using a job stream.
+
+    Yields:
+        pyarrow.RecordBatch: Apache Arrow RecordBatch objects streamed from BigQuery.
+    """
+    # Initialize BigQuery and BigQuery Storage clients.
+    client = bigquery.Client()
+    read_client = bigquery_storage_v1.BigQueryReadClient()
+
+    query = """
+        SELECT name, number, state
+        FROM `bigquery-public-data.usa_names.usa_1910_current`
+        LIMIT 20000
+    """
+
+    # Start the query job.
+    job = client.query(query)
+
+    # Construct the job default stream name.
+    # Format: projects/{project_id}/locations/{location}/jobs/{job_id}/streams/_default
+    stream = f"projects/{job.project}/locations/{job.location}/jobs/{job.job_id}/streams/_default"
+
+    # Read rows directly from the stream using the Storage Read API.
+    schema: Optional[pyarrow.Schema] = None
+
+    for chunk in read_client.read_rows(name=stream, offset=0):
+        # Extract the schema from the first chunk that provides it.
+        if (
+            schema is None
+            and chunk.arrow_schema
+            and chunk.arrow_schema.serialized_schema
+        ):
+            schema = pyarrow.ipc.read_schema(
+                pyarrow.py_buffer(chunk.arrow_schema.serialized_schema)
+            )
+
+        # Deserialize and yield each record batch using the schema.
+        if (
+            chunk.arrow_record_batch
+            and chunk.arrow_record_batch.serialized_record_batch
+        ):
+            yield pyarrow.ipc.read_record_batch(
+                pyarrow.py_buffer(chunk.arrow_record_batch.serialized_record_batch),
+                schema,
+            )
+
+
+# [END bigquerystorage_read_rows_query_job]

packages/google-cloud-bigquery-storage/samples/snippets/read_rows_query_job_test.py

@@ -0,0 +1,35 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pyarrow
+
+from . import read_rows_query_job
+
+
+def test_read_rows_query_job():
+    batches = read_rows_query_job.read_rows_query_job()
+
+    total_rows = 0
+    batch_count = 0
+    for batch in batches:
+        assert isinstance(batch, pyarrow.RecordBatch)
+        assert batch.schema.names == ["name", "number", "state"]
+        assert batch.schema.field("name").type == pyarrow.string()
+        assert batch.schema.field("number").type == pyarrow.int64()
+        assert batch.schema.field("state").type == pyarrow.string()
+        total_rows += batch.num_rows
+        batch_count += 1
+
+    assert total_rows == 20000
+    assert batch_count > 0

packages/google-cloud-bigquery-storage/samples/snippets/requirements.txt

@@ -1,6 +1,4 @@
-google-cloud-bigquery-storage==2.38.0
-google-cloud-bigquery===3.30.0; python_version <= '3.8'
-google-cloud-bigquery==3.41.0; python_version >= '3.9'
-pytest===7.4.3; python_version == '3.7'
-pytest===8.3.5; python_version == '3.8'
-pytest==9.0.3; python_version >= '3.9'
+google-cloud-bigquery-storage==2.41.0
+google-cloud-bigquery==3.44.0
+pyarrow==24.0.0
+pytest==9.0.3