google_cloud_bigquery/
lib.rs

1// Copyright 2025 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Google Cloud Client Libraries for Rust - BigQuery
16//!
17//! **WARNING:** this is a preview release of the crate. We believe the APIs to be
18//! stable. We also are seeking feedback about the APIs and may need to make
19//! breaking changes if we discover that some parts are hard to use.
20//!
21//! We welcome feedback about the APIs, documentation, missing features, bugs, etc.
22//!
23//! This crate contains traits, types, and functions to interact with
24//! [Google Cloud BigQuery][bigquery]. Most applications will use the structs
25//! defined in the [client] module.
26//!
27//! For executing queries and managing jobs:
28//! * [BigQuery][client::BigQuery]
29//!
30//! For reading query results efficiently:
31//! * [Read][client::Read]
32//!
33//! For streaming data to BigQuery:
34//! * [Write][client::Write]
35//!
36//! [bigquery]: https://cloud.google.com/bigquery
37//!
38//! # Example: Executing a Query
39//!
40//! ```
41//! # use google_cloud_bigquery::client::BigQuery;
42//! # async fn sample() -> anyhow::Result<()> {
43//! // Create a client configured with a default project ID.
44//! let client = BigQuery::builder()
45//!     .with_project_id("my-project-id")
46//!     .build()
47//!     .await?;
48//!
49//! // Configure, run, and read query results.
50//! let mut rows = client
51//!     .query("SELECT 'hello world' AS greeting")
52//!     .until_done()
53//!     .await?
54//!     .read();
55//!
56//! while let Some(row) = rows.next().await.transpose()? {
57//!     let greeting: String = row.get("greeting")?;
58//!     println!("Greeting: {greeting}");
59//! }
60//! # Ok(())
61//! # }
62//! ```
63//!
64//! # Example: Mapping Rows to Rust Structs
65//!
66//! Define typed Rust structs with `#[derive(FromRow)]` to convert rows
67//! directly into domain types using `TryFrom<Row>`:
68//!
69//! ```
70//! # use google_cloud_bigquery::client::BigQuery;
71//! # use google_cloud_bigquery::query::FromRow;
72//! #[derive(FromRow, Debug)]
73//! struct UserStats {
74//!     name: String,
75//!     number: i64,
76//! }
77//!
78//! # async fn sample(client: BigQuery) -> anyhow::Result<()> {
79//! let mut rows = client
80//!     .query("SELECT name, number FROM `bigquery-public-data.usa_names.usa_1910_2013` WHERE state = 'WA' LIMIT 5")
81//!     .until_done()
82//!     .await?
83//!     .read();
84//!
85//! while let Some(row) = rows.next().await.transpose()? {
86//!     let user: UserStats = row.try_into()?;
87//!     println!("{} has count {}", user.name, user.number);
88//! }
89//! # Ok(())
90//! # }
91//! ```
92//!
93//! # Example: Writing to BigQuery
94//!
95//! ```
96//! use google_cloud_bigquery::client::Write;
97//! use google_cloud_bigquery::model::{ArrowSchema, ArrowRecordBatch};
98//! # async fn sample() -> anyhow::Result<()> {
99//! let client = Write::builder().build().await?;
100//! let writer = client
101//!     .open_default_stream("projects/my-project/datasets/my-dataset/tables/my-table")
102//!     .build_arrow(schema())
103//!     .await?;
104//!
105//! let f1 = writer.append(rows()).send();
106//! let f2 = writer.append(rows()).send();
107//!
108//! let _ = f1.await?;
109//! let _ = f2.await?;
110//! # Ok(()) }
111//!
112//! fn schema() -> ArrowSchema {
113//!     todo!("Define your table's schema...")
114//! }
115//! fn rows() -> ArrowRecordBatch {
116//!     todo!("Serialize your rows...")
117//! }
118//! ```
119
120pub use google_cloud_gax::Result;
121pub use google_cloud_gax::error::Error;
122
123pub(crate) mod generated;
124
125/// Clients to interact with Google Cloud BigQuery.
126pub mod client {
127    pub use crate::query::client::BigQuery;
128    pub use crate::write::client::Write;
129    pub use crate::write::generated::gapic_storage::client::Read;
130    // TODO(#6152) - add Write admin client
131}
132
133/// The messages and enums that are part of this client library
134pub use crate::write::generated::gapic_storage::model;
135
136/// Extends [crate::model].
137///
138/// Note that there is no real distinction between the types in `model` and
139/// `model_ext`. The two modules are separate for library maintenance reasons.
140pub mod model_ext {
141    pub use crate::generated::{CompleteQueryMetadata, QueryMetadata, QueryRequest};
142    pub use crate::write::append_response::AppendResponse;
143}
144
145/// Request and client builders.
146pub mod builder {
147    /// Request and client builders for the [BigQuery][crate::client::BigQuery] client.
148    pub mod bigquery {
149        pub use crate::generated::QueryRequest;
150        pub use crate::query::builder::Query;
151        pub use crate::query::client_builder::ClientBuilder;
152    }
153    /// Request and client builders for the [Write][crate::client::Write] client.
154    pub mod write {
155        pub use crate::write::builder::{Append, AppendWithOffset};
156        pub use crate::write::client_builder::ClientBuilder;
157        pub use crate::write::writer_builder::WriterBuilder;
158    }
159    pub use crate::write::generated::gapic_storage::builder::read;
160}
161
162/// Traits to mock the clients in this library.
163pub mod stub {
164    pub use crate::write::generated::gapic_storage::stub::Read;
165}
166
167/// Custom errors for the BigQuery clients.
168pub mod error;
169
170/// Types related to querying with a [BigQuery][crate::client::BigQuery] client.
171pub mod query;
172
173/// Types related to writing with a [Write][crate::client::Write] client.
174pub mod write;
175
176pub mod datatypes;
177
178pub(crate) use google_cloud_gax::client_builder::internal::{
179    ClientFactory, new_builder as new_client_builder,
180};
181pub(crate) use google_cloud_gax::client_builder::{ClientBuilder, Result as ClientBuilderResult};
182pub(crate) use google_cloud_gax::options::RequestOptions;
183pub(crate) use google_cloud_gax::options::internal::RequestBuilder;
184pub(crate) use google_cloud_gax::response::Response;
185
186#[allow(dead_code)]
187pub(crate) mod google {
188    pub mod api {
189        include!("write/generated/protos/storage/google.api.rs");
190    }
191    pub mod cloud {
192        pub mod bigquery {
193            pub mod storage {
194                pub mod v1 {
195                    #![allow(deprecated)]
196                    include!("write/generated/protos/storage/google.cloud.bigquery.storage.v1.rs");
197                    include!("write/generated/convert/storage/convert.rs");
198                }
199            }
200        }
201    }
202    pub mod rpc {
203        include!("write/generated/protos/storage/google.rpc.rs");
204    }
205}
google_cloud_bigquery/lib.rs

google_cloud_bigquery/
lib.rs
