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.
Constructors
BigQueryReadClient(BigQueryReadClient const &)
Copy and move support
| Parameter | |
|---|---|
| Name | Description |
|
BigQueryReadClient const &
|
BigQueryReadClient(BigQueryReadClient &&)
Copy and move support
| Parameter | |
|---|---|
| Name | Description |
|
BigQueryReadClient &&
|
BigQueryReadClient(std::shared_ptr< BigQueryReadConnection >, Options)
| Parameters | |
|---|---|
| Name | Description |
connection |
std::shared_ptr< BigQueryReadConnection >
|
opts |
Options
|
Operators
operator=(BigQueryReadClient const &)
Copy and move support
| Parameter | |
|---|---|
| Name | Description |
|
BigQueryReadClient const &
|
| Returns | |
|---|---|
| Type | Description |
BigQueryReadClient & |
|
operator=(BigQueryReadClient &&)
Copy and move support
| Parameter | |
|---|---|
| Name | Description |
|
BigQueryReadClient &&
|
| Returns | |
|---|---|
| Type | Description |
BigQueryReadClient & |
|
Functions
CreateReadSession(std::string const &, google::cloud::bigquery::storage::v1::ReadSession const &, std::int32_t, Options)
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 | |
|---|---|
| Name | Description |
parent |
std::string const &
Required. The request project that owns the session, in the form of |
read_session |
google::cloud::bigquery::storage::v1::ReadSession const &
Required. Session to be created. |
max_stream_count |
std::int32_t
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. |
opts |
Options
Optional. Override the class-level options, such as retry and backoff policies. |
| Returns | |
|---|---|
| Type | Description |
StatusOr< google::cloud::bigquery::storage::v1::ReadSession > |
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 |
CreateReadSession(google::cloud::bigquery::storage::v1::CreateReadSessionRequest const &, Options)
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 | |
|---|---|
| Name | Description |
request |
google::cloud::bigquery::storage::v1::CreateReadSessionRequest const &
Unary RPCs, such as the one wrapped by this function, receive a single |
opts |
Options
Optional. Override the class-level options, such as retry and backoff policies. |
| Returns | |
|---|---|
| Type | Description |
StatusOr< google::cloud::bigquery::storage::v1::ReadSession > |
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 |
ReadRows(std::string const &, std::int64_t, Options)
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 | |
|---|---|
| Name | Description |
read_stream |
std::string const &
Required. Stream to read rows from. |
offset |
std::int64_t
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 |
Options
Optional. Override the class-level options, such as retry and backoff policies. |
| Returns | |
|---|---|
| Type | Description |
StreamRange< google::cloud::bigquery::storage::v1::ReadRowsResponse > |
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 |
ReadRows(google::cloud::bigquery::storage::v1::ReadRowsRequest const &, Options)
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 | |
|---|---|
| Name | Description |
request |
google::cloud::bigquery::storage::v1::ReadRowsRequest const &
Unary RPCs, such as the one wrapped by this function, receive a single |
opts |
Options
Optional. Override the class-level options, such as retry and backoff policies. |
| Returns | |
|---|---|
| Type | Description |
StreamRange< google::cloud::bigquery::storage::v1::ReadRowsResponse > |
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 |
SplitReadStream(google::cloud::bigquery::storage::v1::SplitReadStreamRequest const &, Options)
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 | |
|---|---|
| Name | Description |
request |
google::cloud::bigquery::storage::v1::SplitReadStreamRequest const &
Unary RPCs, such as the one wrapped by this function, receive a single |
opts |
Options
Optional. Override the class-level options, such as retry and backoff policies. |
| Returns | |
|---|---|
| Type | Description |
StatusOr< google::cloud::bigquery::storage::v1::SplitReadStreamResponse > |
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 |