google_cloud_bigquery/

lib.rs

// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Google Cloud Client Libraries for Rust - BigQuery
//!
//! **NOTE:** While the version is still `0.x`, we believe the APIs to be stable.
//! We plan to release a `1.0` version of this crate in the following release.
//!
//! We welcome feedback about the APIs, documentation, missing features, bugs, etc.
//!
//! This crate contains traits, types, and functions to interact with
//! [Google Cloud BigQuery][bigquery]. Most applications will use the structs
//! defined in the [client] module.
//!
//! For executing queries and managing jobs:
//! * [BigQuery][client::BigQuery]
//!
//! For reading query results efficiently:
//! * [Read][client::Read]
//!
//! For streaming data to BigQuery:
//! * [Write][client::Write]
//!
//! [bigquery]: https://cloud.google.com/bigquery
//!
//! # Example: Executing a Query
//!
//! ```
//! # use google_cloud_bigquery::client::BigQuery;
//! # async fn sample() -> anyhow::Result<()> {
//! // Create a client configured with a default project ID.
//! let client = BigQuery::builder()
//!     .with_project_id("my-project-id")
//!     .build()
//!     .await?;
//!
//! // Configure, run, and read query results.
//! let mut rows = client
//!     .query("SELECT 'hello world' AS greeting")
//!     .until_done()
//!     .await?
//!     .read();
//!
//! while let Some(row) = rows.next().await.transpose()? {
//!     let greeting: String = row.get("greeting")?;
//!     println!("Greeting: {greeting}");
//! }
//! # Ok(())
//! # }
//! ```
//!
//! # Example: Mapping Rows to Rust Structs
//!
//! Define typed Rust structs with `#[derive(FromRow)]` to convert rows
//! directly into domain types using `TryFrom<Row>`:
//!
//! ```
//! # use google_cloud_bigquery::client::BigQuery;
//! # use google_cloud_bigquery::query::FromRow;
//! #[derive(FromRow, Debug)]
//! struct UserStats {
//!     name: String,
//!     number: i64,
//! }
//!
//! # async fn sample(client: BigQuery) -> anyhow::Result<()> {
//! let mut rows = client
//!     .query("SELECT name, number FROM `bigquery-public-data.usa_names.usa_1910_2013` WHERE state = 'WA' LIMIT 5")
//!     .until_done()
//!     .await?
//!     .read();
//!
//! while let Some(row) = rows.next().await.transpose()? {
//!     let user: UserStats = row.try_into()?;
//!     println!("{} has count {}", user.name, user.number);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! # Example: Reading from BigQuery
//!
//! ```
//! use google_cloud_bigquery::client::Read;
//! use google_cloud_bigquery::model::{DataFormat, ReadSession};
//! # async fn sample() -> anyhow::Result<()> {
//! let client = Read::builder().build().await?;
//!
//! let session = client
//!     .create_read_session()
//!     .set_parent("projects/my-project")
//!     .set_read_session(
//!         ReadSession::new()
//!             .set_data_format(DataFormat::Arrow)
//!             .set_table("projects/my-project/datasets/my-dataset/tables/my-table"),
//!     )
//!     .set_max_stream_count(1)
//!     .send()
//!     .await?;
//!
//! for stream in &session.streams {
//!     let mut rows = client
//!         .read_rows()
//!         .set_read_stream(&stream.name)
//!         .send()
//!         .await?;
//!
//!     while let Some(response) = rows.next().await.transpose()? {
//!         println!("Read {} rows", response.row_count);
//!     }
//! }
//! # Ok(())
//! # }
//! ```
//!
//! # Example: Writing to BigQuery
//!
//! ```
//! use google_cloud_bigquery::client::Write;
//! use google_cloud_bigquery::model::{ArrowSchema, ArrowRecordBatch};
//! # async fn sample() -> anyhow::Result<()> {
//! let client = Write::builder().build().await?;
//! let writer = client
//!     .open_default_stream("projects/my-project/datasets/my-dataset/tables/my-table")
//!     .build_arrow(schema())
//!     .await?;
//!
//! let f1 = writer.append(rows()).send();
//! let f2 = writer.append(rows()).send();
//!
//! let _ = f1.await?;
//! let _ = f2.await?;
//! # Ok(()) }
//!
//! fn schema() -> ArrowSchema {
//!     todo!("Define your table's schema...")
//! }
//! fn rows() -> ArrowRecordBatch {
//!     todo!("Serialize your rows...")
//! }
//! ```

pub use google_cloud_gax::Result;
pub use google_cloud_gax::error::Error;

pub(crate) mod generated;

/// Clients to interact with Google Cloud BigQuery.
pub mod client {
    pub use crate::query::client::BigQuery;
    pub use crate::write::client::Write;
    pub use crate::write::generated::gapic_storage::client::Read;
    // TODO(#6152) - add Write admin client
}

pub use crate::write::generated::gapic_storage::model;

/// Extends [crate::model].
///
/// Note that there is no real distinction between the types in `model` and
/// `model_ext`. The two modules are separate for library maintenance reasons.
pub mod model_ext {
    pub use crate::generated::{CompleteQueryMetadata, QueryMetadata, QueryRequest};
    pub use crate::write::append_response::AppendResponse;
}

/// Request and client builders.
pub mod builder {
    /// Request and client builders for the [BigQuery][crate::client::BigQuery] client.
    pub mod bigquery {
        pub use crate::generated::QueryRequest;
        pub use crate::query::builder::Query;
        pub use crate::query::client_builder::ClientBuilder;
    }
    /// Request and client builders for the [Write][crate::client::Write] client.
    pub mod write {
        pub use crate::write::builder::{Append, AppendWithOffset};
        pub use crate::write::client_builder::ClientBuilder;
        pub use crate::write::writer_builder::WriterBuilder;
    }
    pub use crate::write::generated::gapic_storage::builder::read;
}

/// Traits to mock the clients in this library.
pub mod stub {
    pub use crate::write::generated::gapic_storage::stub::Read;
}

/// Custom errors for the BigQuery clients.
pub mod error;

/// Types related to querying with a [BigQuery][crate::client::BigQuery] client.
pub mod query;

/// Types related to writing with a [Write][crate::client::Write] client.
pub mod write;

pub mod datatypes;

pub(crate) use google_cloud_gax::client_builder::internal::{
    ClientFactory, new_builder as new_client_builder,
};
pub(crate) use google_cloud_gax::client_builder::{ClientBuilder, Result as ClientBuilderResult};
pub(crate) use google_cloud_gax::options::RequestOptions;
pub(crate) use google_cloud_gax::options::internal::RequestBuilder;
pub(crate) use google_cloud_gax::response::Response;

#[allow(dead_code)]
pub(crate) mod google {
    pub mod api {
        include!("write/generated/protos/storage/google.api.rs");
    }
    pub mod cloud {
        pub mod bigquery {
            pub mod storage {
                pub mod v1 {
                    #![allow(deprecated)]
                    include!("write/generated/protos/storage/google.cloud.bigquery.storage.v1.rs");
                    include!("write/generated/convert/storage/convert.rs");
                }
            }
        }
    }
    pub mod rpc {
        include!("write/generated/protos/storage/google.rpc.rs");
    }
}