google::cloud::bigquery_storage_v1::BigQueryReadClient Class Reference

BigQuery Read API. More...

#include <google/cloud/bigquery/storage/v1/bigquery_read_client.h>

Public Member Functions
	BigQueryReadClient (std::shared_ptr< BigQueryReadConnection > connection, Options opts={})
	~BigQueryReadClient ()
StatusOr< google::cloud::bigquery::storage::v1::ReadSession >	CreateReadSession (std::string const &parent, google::cloud::bigquery::storage::v1::ReadSession const &read_session, std::int32_t max_stream_count, Options opts={})
	Creates a new read session. More...
StatusOr< google::cloud::bigquery::storage::v1::ReadSession >	CreateReadSession (google::cloud::bigquery::storage::v1::CreateReadSessionRequest const &request, Options opts={})
	Creates a new read session. More...
StreamRange< google::cloud::bigquery::storage::v1::ReadRowsResponse >	ReadRows (std::string const &read_stream, std::int64_t offset, Options opts={})
	Reads rows from the stream in the format prescribed by the ReadSession. More...
StreamRange< google::cloud::bigquery::storage::v1::ReadRowsResponse >	ReadRows (google::cloud::bigquery::storage::v1::ReadRowsRequest const &request, Options opts={})
	Reads rows from the stream in the format prescribed by the ReadSession. More...
StatusOr< google::cloud::bigquery::storage::v1::SplitReadStreamResponse >	SplitReadStream (google::cloud::bigquery::storage::v1::SplitReadStreamRequest const &request, Options opts={})
	Splits a given ReadStream into two ReadStream objects. More...
Copy and move support
	BigQueryReadClient (BigQueryReadClient const &)=default
BigQueryReadClient &	operator= (BigQueryReadClient const &)=default
	BigQueryReadClient (BigQueryReadClient &&)=default
BigQueryReadClient &	operator= (BigQueryReadClient &&)=default

Friends
Equality
bool	operator== (BigQueryReadClient const &a, BigQueryReadClient const &b)
bool	operator!= (BigQueryReadClient const &a, BigQueryReadClient const &b)

Detailed Description

BigQuery Read API.

The Read API can be used to read data from BigQuery.

Equality

Instances of this class created via copy-construction or copy-assignment always compare equal. Instances created with equal std::shared_ptr<*Connection> objects compare equal. Objects that compare equal share the same underlying resources.

Performance

Creating a new instance of this class is a relatively expensive operation, new objects establish new connections to the service. In contrast, copy-construction, move-construction, and the corresponding assignment operations are relatively efficient as the copies share all underlying resources.

Thread Safety

Concurrent access to different instances of this class, even if they compare equal, is guaranteed to work. Two or more threads operating on the same instance of this class is not guaranteed to work. Since copy-construction and move-construction is a relatively efficient operation, consider using such a copy when using this class from multiple threads.

Constructor & Destructor Documentation

BigQueryReadClient() [1/3]

google::cloud::bigquery_storage_v1::BigQueryReadClient::BigQueryReadClient ( std::shared_ptr< BigQueryReadConnection >  connection, Options  opts = {}  )

explicit

~BigQueryReadClient()

google::cloud::bigquery_storage_v1::BigQueryReadClient::~BigQueryReadClient

(

)

BigQueryReadClient() [2/3]

google::cloud::bigquery_storage_v1::BigQueryReadClient::BigQueryReadClient ( BigQueryReadClient const &  )

default

BigQueryReadClient() [3/3]

google::cloud::bigquery_storage_v1::BigQueryReadClient::BigQueryReadClient ( BigQueryReadClient &&  )

default

Member Function Documentation

CreateReadSession() [1/2]

StatusOr< google::cloud::bigquery::storage::v1::ReadSession > google::cloud::bigquery_storage_v1::BigQueryReadClient::CreateReadSession	(	google::cloud::bigquery::storage::v1::CreateReadSessionRequest const &	request,
		Options	opts = {}
	)

Creates a new read session.

A read session divides the contents of a BigQuery table into one or more streams, which can then be used to read data from the table. The read session also specifies properties of the data to be read, such as a list of columns or a push-down filter describing the rows to be returned.

A particular row can be read by at most one stream. When the caller has reached the end of each stream in the session, then all the data in the table has been read.

Data is assigned to each stream such that roughly the same number of rows can be read from each stream. Because the server-side unit for assigning data is collections of rows, the API does not guarantee that each stream will return the same number or rows. Additionally, the limits are enforced based on the number of pre-filtered rows, so some filters can lead to lopsided assignments.

Read sessions automatically expire 6 hours after they are created and do not require manual clean-up by the caller.

Parameters

request	Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.bigquery.storage.v1.CreateReadSessionRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.
opts	Optional. Override the class-level options, such as retry and backoff policies.

Returns

the result of the RPC. The response message type (google.cloud.bigquery.storage.v1.ReadSession) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the `StatusOr` contains the error details.

CreateReadSession() [2/2]

StatusOr< google::cloud::bigquery::storage::v1::ReadSession > google::cloud::bigquery_storage_v1::BigQueryReadClient::CreateReadSession	(	std::string const &	parent,
		google::cloud::bigquery::storage::v1::ReadSession const &	read_session,
		std::int32_t	max_stream_count,
		Options	opts = {}
	)

Creates a new read session.

A read session divides the contents of a BigQuery table into one or more streams, which can then be used to read data from the table. The read session also specifies properties of the data to be read, such as a list of columns or a push-down filter describing the rows to be returned.

A particular row can be read by at most one stream. When the caller has reached the end of each stream in the session, then all the data in the table has been read.

Data is assigned to each stream such that roughly the same number of rows can be read from each stream. Because the server-side unit for assigning data is collections of rows, the API does not guarantee that each stream will return the same number or rows. Additionally, the limits are enforced based on the number of pre-filtered rows, so some filters can lead to lopsided assignments.

Read sessions automatically expire 6 hours after they are created and do not require manual clean-up by the caller.

Parameters

parent	Required. The request project that owns the session, in the form of projects/{project_id}.
read_session	Required. Session to be created.
max_stream_count	Max initial number of streams. If unset or zero, the server will provide a value of streams so as to produce reasonable throughput. Must be non-negative. The number of streams may be lower than the requested number, depending on the amount parallelism that is reasonable for the table. There is a default system max limit of 1,000. This must be greater than or equal to preferred_min_stream_count. Typically, clients should either leave this unset to let the system to determine an upper bound OR set this a size for the maximum "units of work" it can gracefully handle.
opts	Optional. Override the class-level options, such as retry and backoff policies.

Returns

the result of the RPC. The response message type (google.cloud.bigquery.storage.v1.ReadSession) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the `StatusOr` contains the error details.

operator=() [1/2]

BigQueryReadClient & google::cloud::bigquery_storage_v1::BigQueryReadClient::operator= ( BigQueryReadClient &&  )

default

operator=() [2/2]

BigQueryReadClient & google::cloud::bigquery_storage_v1::BigQueryReadClient::operator= ( BigQueryReadClient const &  )

default

ReadRows() [1/2]

StreamRange< google::cloud::bigquery::storage::v1::ReadRowsResponse > google::cloud::bigquery_storage_v1::BigQueryReadClient::ReadRows	(	google::cloud::bigquery::storage::v1::ReadRowsRequest const &	request,
		Options	opts = {}
	)

Reads rows from the stream in the format prescribed by the ReadSession.

Each response contains one or more table rows, up to a maximum of 100 MiB per response; read requests which attempt to read individual rows larger than 100 MiB will fail.

Each request also returns a set of stream statistics reflecting the current state of the stream.

Parameters

request	Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.bigquery.storage.v1.ReadRowsRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.
opts	Optional. Override the class-level options, such as retry and backoff policies.

Returns

the result of the RPC. The response message type (google.cloud.bigquery.storage.v1.ReadRowsResponse) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the `StatusOr` contains the error details.

ReadRows() [2/2]

StreamRange< google::cloud::bigquery::storage::v1::ReadRowsResponse > google::cloud::bigquery_storage_v1::BigQueryReadClient::ReadRows	(	std::string const &	read_stream,
		std::int64_t	offset,
		Options	opts = {}
	)

Reads rows from the stream in the format prescribed by the ReadSession.

Each response contains one or more table rows, up to a maximum of 100 MiB per response; read requests which attempt to read individual rows larger than 100 MiB will fail.

Each request also returns a set of stream statistics reflecting the current state of the stream.

Parameters

read_stream	Required. Stream to read rows from.
offset	The offset requested must be less than the last row read from Read. Requesting a larger offset is undefined. If not specified, start reading from offset zero.
opts	Optional. Override the class-level options, such as retry and backoff policies.

Returns

the result of the RPC. The response message type (google.cloud.bigquery.storage.v1.ReadRowsResponse) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the `StatusOr` contains the error details.

SplitReadStream()

StatusOr< google::cloud::bigquery::storage::v1::SplitReadStreamResponse > google::cloud::bigquery_storage_v1::BigQueryReadClient::SplitReadStream	(	google::cloud::bigquery::storage::v1::SplitReadStreamRequest const &	request,
		Options	opts = {}
	)

Splits a given ReadStream into two ReadStream objects.

These ReadStream objects are referred to as the primary and the residual streams of the split. The original ReadStream can still be read from in the same manner as before. Both of the returned ReadStream objects can also be read from, and the rows returned by both child streams will be the same as the rows read from the original stream.

Moreover, the two child streams will be allocated back-to-back in the original ReadStream. Concretely, it is guaranteed that for streams original, primary, and residual, that original[0-j] = primary[0-j] and original[j-n] = residual[0-m] once the streams have been read to completion.

Parameters

request	Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.cloud.bigquery.storage.v1.SplitReadStreamRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.
opts	Optional. Override the class-level options, such as retry and backoff policies.

Returns

the result of the RPC. The response message type (google.cloud.bigquery.storage.v1.SplitReadStreamResponse) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the `StatusOr` contains the error details.

Friends And Related Function Documentation

operator!=

bool operator!= ( BigQueryReadClient const &  a, BigQueryReadClient const &  b  )

friend

operator==

bool operator== ( BigQueryReadClient const &  a, BigQueryReadClient const &  b  )

friend