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

[alextolpin]

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

• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)

[snippet-bot]

Here is the summary of changes.

You are about to add 2 region tags.

• packages/google-cloud-bigquery-storage/samples/snippets/query_and_wait_arrow.py:15, tag bigquerystorage_query_and_wait_arrow
• packages/google-cloud-bigquery-storage/samples/snippets/read_rows_query_job.py:15, tag bigquerystorage_read_rows_query_job

---

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

• Refresh this comment

[gemini-code-assist]

Code Review

This pull request introduces two new code snippets and their corresponding tests to demonstrate reading BigQuery query results in Apache Arrow format. Specifically, query_and_wait_arrow.py uses the query_and_wait method to fetch Arrow RecordBatches directly, while read_rows_query_job.py initiates a query job and streams the results using the BigQuery Storage Read API. A critical issue was identified in read_rows_query_job.py where the query job is started asynchronously, but the code immediately attempts to read from the stream without waiting for the job to complete. It is recommended to call job.result() to ensure the query finishes before reading.

[parthea]

From the Kokoro System Tests presubmit,

=================================== FAILURES ===================================
__________________________ test_query_and_wait_arrow ___________________________

project_id = 'precise-truck-742'

    def test_query_and_wait_arrow(project_id: str):
>       batches = query_and_wait_arrow.query_and_wait_arrow(project_id=project_id)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

samples/snippets/query_and_wait_arrow_test.py:21: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

project_id = 'precise-truck-742'

    def query_and_wait_arrow(
        project_id: Optional[str] = None,
    ) -> Iterable[pyarrow.RecordBatch]:
        """Queries BigQuery and returns results as an iterable of Apache Arrow RecordBatches.
    
        Args:
            project_id (Optional[str]): The Google Cloud project ID to bill for the query.
                If not specified, the project is inferred from the environment.
    
        Returns:
            Iterable[pyarrow.RecordBatch]: An iterable of Apache Arrow RecordBatch objects.
        """
        # Initialize a BigQuery client.
        client = bigquery.Client(project=project_id) if project_id else 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,
        )
E       AttributeError: module 'google.cloud.bigquery.enums' has no attribute 'QueryResultsFormat'

samples/snippets/query_and_wait_arrow.py:48: AttributeError
- generated xml file: /tmpfs/src/github/google-cloud-python/packages/google-cloud-bigquery-storage/system_3.12_sponge_log.xml -
=========================== short test summary info ============================
FAILED samples/snippets/query_and_wait_arrow_test.py::test_query_and_wait_arrow
========================= 1 failed, 5 passed in 30.39s =========================

[parthea]

3.9 is no longer supported. We can use pyarrow==24.0.0

Suggested change

	pyarrow===12.0.1; python_version == '3.7'
	pyarrow===17.0.0; python_version == '3.8'
	pyarrow==24.0.0; python_version >= '3.9'
	pyarrow===12.0.1; python_version == '3.7'
	pyarrow===17.0.0; python_version == '3.8'
	pyarrow==24.0.0