Google Cloud BigQuery C++ Client  2.1.0
A C++ Client Library for Google Cloud BigQuery
Public Member Functions | Friends | List of all members
google::cloud::bigquery::BigQueryReadClient Class Reference

BigQuery Read API. More...

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

Public Member Functions

 BigQueryReadClient (std::shared_ptr< BigQueryReadConnection > connection, Options opts={})
 
 ~BigQueryReadClient ()
 
 BigQueryReadClient (BigQueryReadClient const &)=default
 
BigQueryReadClientoperator= (BigQueryReadClient const &)=default
 
 BigQueryReadClient (BigQueryReadClient &&)=default
 
BigQueryReadClientoperator= (BigQueryReadClient &&)=default
 
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...
 

Friends

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.

Definition at line 63 of file bigquery_read_client.h.

Constructor & Destructor Documentation

◆ BigQueryReadClient() [1/3]

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

◆ ~BigQueryReadClient()

google::cloud::bigquery::BigQueryReadClient::~BigQueryReadClient ( )

◆ BigQueryReadClient() [2/3]

google::cloud::bigquery::BigQueryReadClient::BigQueryReadClient ( BigQueryReadClient const &  )
default

◆ BigQueryReadClient() [3/3]

google::cloud::bigquery::BigQueryReadClient::BigQueryReadClient ( BigQueryReadClient &&  )
default

Member Function Documentation

◆ CreateReadSession() [1/2]

StatusOr<google::cloud::bigquery::storage::v1::ReadSession> google::cloud::bigquery::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
requestgoogle::cloud::bigquery::storage::v1::CreateReadSessionRequest
optsOptional. Override the class-level options, such as retry and backoff policies.
Returns
google::cloud::bigquery::storage::v1::ReadSession

◆ CreateReadSession() [2/2]

StatusOr<google::cloud::bigquery::storage::v1::ReadSession> google::cloud::bigquery::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
parentRequired. The request project that owns the session, in the form of projects/{project_id}.
read_sessionRequired. Session to be created.
max_stream_countMax 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.
optsOptional. Override the class-level options, such as retry and backoff policies.
Returns
google::cloud::bigquery::storage::v1::ReadSession

◆ operator=() [1/2]

BigQueryReadClient& google::cloud::bigquery::BigQueryReadClient::operator= ( BigQueryReadClient &&  )
default

◆ operator=() [2/2]

BigQueryReadClient& google::cloud::bigquery::BigQueryReadClient::operator= ( BigQueryReadClient const &  )
default

◆ ReadRows() [1/2]

StreamRange<google::cloud::bigquery::storage::v1::ReadRowsResponse> google::cloud::bigquery::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
requestgoogle::cloud::bigquery::storage::v1::ReadRowsRequest
optsOptional. Override the class-level options, such as retry and backoff policies.
Returns
google::cloud::bigquery::storage::v1::ReadRowsResponse

◆ ReadRows() [2/2]

StreamRange<google::cloud::bigquery::storage::v1::ReadRowsResponse> google::cloud::bigquery::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_streamRequired. Stream to read rows from.
offsetThe 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.
optsOptional. Override the class-level options, such as retry and backoff policies.
Returns
google::cloud::bigquery::storage::v1::ReadRowsResponse

◆ SplitReadStream()

StatusOr<google::cloud::bigquery::storage::v1::SplitReadStreamResponse> google::cloud::bigquery::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
requestgoogle::cloud::bigquery::storage::v1::SplitReadStreamRequest
optsOptional. Override the class-level options, such as retry and backoff policies.
Returns
google::cloud::bigquery::storage::v1::SplitReadStreamResponse

Friends And Related Function Documentation

◆ operator!=

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

Definition at line 83 of file bigquery_read_client.h.

◆ operator==

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

Definition at line 79 of file bigquery_read_client.h.