Skip to main content

bigquery/
lib.rs

1//! # BigQuery for Rust
2//!
3//! A client for Google BigQuery that uses gRPC throughout: the Storage Read API for table scans
4//! and large results, the Storage Write API for inserts, and the v2 API for queries, jobs,
5//! datasets and tables.
6//!
7//! Full documentation, with a chapter per topic: <https://bigquery-rust.abdolence.dev>
8//!
9//! ## Example
10//!
11//! ```rust,no_run
12//! use bigquery::*;
13//! use serde::{Deserialize, Serialize};
14//!
15//! #[derive(Debug, Clone, Deserialize, Serialize)]
16//! struct Order {
17//!     id: i64,
18//!     customer: String,
19//!     total: f64,
20//! }
21//!
22//! const SHOP: BigQueryDatasetId = BigQueryDatasetId::from_static("shop");
23//! const ORDERS: BigQueryTableId = BigQueryTableId::from_static("orders");
24//!
25//! # async fn example() -> BigQueryResult<()> {
26//! let db = BigQueryDb::new("my-project-id").await?;
27//!
28//! // Insert through the Storage Write API
29//! let orders = vec![Order {
30//!     id: 1,
31//!     customer: "Alice".to_string(),
32//!     total: 120.0,
33//! }];
34//! db.fluent()
35//!     .insert()
36//!     .into(SHOP.table(ORDERS))
37//!     .objects(&orders)
38//!     .execute()
39//!     .await?;
40//!
41//! // Read the table back through the Storage Read API, with a typed filter
42//! let large_orders: Vec<Order> = db
43//!     .fluent()
44//!     .select()
45//!     .from(SHOP.table(ORDERS))
46//!     .filter(|filter| filter.field(path!(Order::total)).gt(100.0))
47//!     .obj()
48//!     .query()
49//!     .await?;
50//!
51//! // Query with parameters
52//! let alice_orders: Vec<Order> = db
53//!     .fluent()
54//!     .query("SELECT id, customer, total FROM shop.orders WHERE customer = @customer")
55//!     .param("customer", "Alice")
56//!     .obj()
57//!     .query()
58//!     .await?;
59//! # let _ = (large_orders, alice_orders);
60//! # Ok(())
61//! # }
62//! ```
63
64#![forbid(unsafe_code)]
65
66/// The error types of this crate, built around [`BigQueryError`].
67pub mod errors;
68
69mod db;
70
71pub use db::*;
72
73mod fluent_api;
74
75pub use fluent_api::*;
76
77mod types;
78
79pub use types::*;
80
81mod read;
82
83pub use read::*;
84
85mod write;
86
87pub use write::*;
88
89mod query;
90
91pub use query::*;
92
93mod sql;
94
95mod schema;
96
97pub use schema::*;
98
99mod admin;
100
101pub use admin::*;
102
103pub mod testing;
104
105mod struct_path_macro;
106
107/// The `struct_path` crate the [`path!`] and [`paths!`] macros expand to, for its
108/// `StructPath` derive.
109pub extern crate struct_path;
110
111/// The gcloud-sdk version this crate is built against, for [`GoogleAuthHeaders`] and the
112/// raw gRPC clients.
113///
114/// [`GoogleAuthHeaders`]: gcloud_sdk::GoogleAuthHeaders
115pub use gcloud_sdk;
116
117pub use arrow_array;
118pub use arrow_schema;
119pub use jiff;
120pub use url;
121
122/// An exact instant in time, used by this library for the times BigQuery reports about a
123/// dataset, a table, a job or a write: creation and last modified times, a job's start and end,
124/// a table's expiration, a commit time, and a read's snapshot time.
125///
126/// This is an alias for [`jiff::Timestamp`]. Prefer this alias over naming `jiff::Timestamp`
127/// directly, so that your code does not need an explicit `jiff` dependency and stays insulated
128/// from changes of the underlying implementation.
129///
130/// It is not a TIMESTAMP column value: a column in your rows is a [`BigQueryTimestamp`], or a
131/// plain `jiff::Timestamp`, as the type mapping describes.
132///
133/// ```rust
134/// use bigquery::*;
135///
136/// let since: BigQueryInstant = "2026-10-01T00:00:00Z".parse()?;
137/// let params = BigQueryListJobsParams::new().with_min_creation_time(since);
138/// # let _ = params;
139/// # Ok::<(), jiff::Error>(())
140/// ```
141pub type BigQueryInstant = jiff::Timestamp;
142
143use crate::errors::BigQueryError;
144
145/// The result type of every fallible call in this crate.
146pub type BigQueryResult<T> = std::result::Result<T, BigQueryError>;
147
148#[cfg(doctest)]
149mod book;