Python Client for BigQuery Storage API (Alpha)#
Quick Start#
In order to use this library, you first need to go through the following steps:
- Select or create a Cloud Platform project.
- Enable billing for your project.
- Enable the BigQuery Storage API.
- Setup Authentication.
Installation#
Install this library in a virtualenv using pip. virtualenv is a tool to create isolated Python environments. The basic problem it addresses is one of dependencies and versions, and indirectly permissions.
With virtualenv, it’s possible to install this library without needing system install permissions, and without clashing with the installed system dependencies.
Supported Python Versions#
Python >= 3.4
Deprecated Python Versions#
Python == 2.7. Python 2.7 support will be removed on January 1, 2020.
Mac/Linux#
pip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install google-cloud-bigquery-storage
Windows#
pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install google-cloud-bigquery-storage
Optional Dependencies#
Several features of google-cloud-bigquery-storage
require additional
dependencies.
Next Steps#
- Read the Client Library Documentation for BigQuery Storage API API to see other available methods on the client.
- Read the BigQuery Storage API Product documentation to learn more about the product and see How-to Guides.
- View this repository’s main README to see the full list of Cloud APIs that we cover.
API Reference#
Example Usage#
from google.cloud import bigquery_storage_v1beta1
# TODO(developer): Set the project_id variable.
# project_id = 'your-project-id'
#
# The read session is created in this project. This project can be
# different from that which contains the table.
client = bigquery_storage_v1beta1.BigQueryStorageClient()
# This example reads baby name data from the public datasets.
table_ref = bigquery_storage_v1beta1.types.TableReference()
table_ref.project_id = "bigquery-public-data"
table_ref.dataset_id = "usa_names"
table_ref.table_id = "usa_1910_current"
# We limit the output columns to a subset of those allowed in the table,
# and set a simple filter to only report names from the state of
# Washington (WA).
read_options = bigquery_storage_v1beta1.types.TableReadOptions()
read_options.selected_fields.append("name")
read_options.selected_fields.append("number")
read_options.selected_fields.append("state")
read_options.row_restriction = 'state = "WA"'
# Set a snapshot time if it's been specified.
modifiers = None
if snapshot_millis > 0:
modifiers = bigquery_storage_v1beta1.types.TableModifiers()
modifiers.snapshot_time.FromMilliseconds(snapshot_millis)
parent = "projects/{}".format(project_id)
session = client.create_read_session(
table_ref, parent, table_modifiers=modifiers, read_options=read_options
) # API request.
# We'll use only a single stream for reading data from the table. Because
# of dynamic sharding, this will yield all the rows in the table. However,
# if you wanted to fan out multiple readers you could do so by having a
# reader process each individual stream.
reader = client.read_rows(
bigquery_storage_v1beta1.types.StreamPosition(stream=session.streams[0])
)
# The read stream contains blocks of Avro-encoded bytes. The rows() method
# uses the fastavro library to parse these blocks as an interable of Python
# dictionaries. Install fastavro with the following command:
#
# pip install google-cloud-bigquery-storage[fastavro]
rows = reader.rows(session)
# Do any local processing by iterating over the rows. The
# google-cloud-bigquery-storage client reconnects to the API after any
# transient network errors or timeouts.
names = set()
states = set()
for row in rows:
names.add(row["name"])
states.add(row["state"])
print("Got {} unique names in states: {}".format(len(names), states))