bigquery 0.10.0

Library provides a simple API for Google BigQuery based on the gRPC Storage Read/Write and v2 APIs
Documentation
# Table reads or queries

The library reads data in two ways:

- a [table read]./reading-tables.md, `select().from(..)` with `.filter(..)`, goes through the
  Storage Read API. It runs no query and no job;
- a [query]./queries.md, `query(..)` with named parameters, runs GoogleSQL through the v2
  `Query` call.

Both decode rows with the same Arrow decoder, so a type maps the same way in each, see
[Type mapping](./types.md).

The same rows both ways:

```rust,no_run
# use bigquery::*;
# use serde::Deserialize;
# const SHOP: BigQueryDatasetId = BigQueryDatasetId::from_static("shop");
# const PEOPLE: BigQueryTableId = BigQueryTableId::from_static("people");
#[derive(Debug, Deserialize)]
struct Person {
    name: String,
    city: String,
}

# async fn example(db: BigQueryDb) -> BigQueryResult<()> {
let read: Vec<Person> = db
    .fluent()
    .select()
    .from(SHOP.table(PEOPLE))
    .filter(|filter| filter.field(path!(Person::city)).eq("Malmö"))
    .obj()
    .query()
    .await?;

let queried: Vec<Person> = db
    .fluent()
    .query("SELECT name, city FROM shop.people WHERE city = @city")
    .param("city", "Malmö")
    .obj::<Person>()
    .query()
    .await?;
# let _ = (read, queried);
# Ok(())
# }
```

## Comparison

| | Table read | Query |
|---|---|---|
| What it reads | One table: the columns you select, the rows the filter keeps, at a snapshot time or as a sample | Any GoogleSQL: joins, aggregates, `ORDER BY`, `LIMIT`, views, computed columns |
| Writes | No | DML and DDL |
| Values in conditions | Escaped literals in the session's `row_restriction`, Storage Read has no parameters | Query parameters, the value never becomes SQL text |
| Job | None, so no job stats, dry run or cancellation | Short query mode answers small ones without a job, others get one |
| Columns read | The ones your structure names, by itself | The ones the `SELECT` names |
| First row of a small result | After opening a read session | Inline in the first response, about 0.1 s in the [benchmarks]./benchmarks.md#small-query-latency |
| Large results | Several streams in parallel, each resumed at its row offset after a retryable error | Read from the job's destination table, through the same Storage Read path |
| Billing | Storage Read: bytes read | Query: bytes processed, then nothing for reading the result |

Be aware that Storage Read cannot read views, logical or materialized, and external tables, as
the [Storage Read API limitations](https://cloud.google.com/bigquery/docs/reference/storage#limitations)
say. Query them instead.

## Billing hints

Prices here are the on-demand list prices in USD from
[BigQuery pricing](https://cloud.google.com/bigquery/pricing) in October 2026, so check them for
your region and contract:

- a table read is billed $1.10 per TiB read, and the first 300 TiB a month for each billing
  account are free. Reads within the same location are free of data transfer;
- a query is billed $6.25 per TiB processed, with the first 1 TiB a month free. It bills every
  column the query touches over the whole table, unless partitioning or clustering prune it,
  even with `LIMIT`, and at least 10 MB per table referenced;
- reading a query result is free: the result is a temporary table, and reads of those are not
  billed. Neither is a query answered from the query cache;
- a table read bills the columns it reads, so select only the ones you need. The automatic
  projection from your structure does it for you, see
  [Selecting columns]./reading-tables.md#selecting-columns.

So for a scan of a large table a table read is much cheaper: a bit more than a sixth of the
query price per byte, and free under the monthly allowance. In the
[benchmarks](./benchmarks.md#cost) the 215 MB table scans went through the Storage Read free
tier, while each `SELECT *` scan of the official crate billed the table. Row filters were not
measured for bytes billed, so do not count on a filter making a table read cheaper.

`.maximum_bytes_billed(..)` makes a query fail without running if it would bill more, and a
[dry run](./queries.md#dry-run) tells you the bytes before you run it.

## Which one to use

- **Rows of one table, filtered by values**: a table read. Exports, syncs, full scans, "the
  orders of this customer". It needs no job, reads in parallel and resumes by itself;
- **Joins, aggregates, ordering, `LIMIT`, views or computed columns**: a query, with named
  parameters for every value;
- **A small lookup, a few rows by key**: a query. Short query mode returns it in one
  call, while a table read opens a session first;
- **DML, DDL, or when you need job stats, labels on the job or a dry run**: a query;
- **Arrow for your own processing**: either, both have `record_batches()`.

## Many rows from a complex query

A query with joins or aggregates that returns a lot of rows needs no table of your own and no
second step. BigQuery writes every query result to a temporary table, and the library reads a
large one from there through the Storage Read API, in parallel streams, see
[Where the rows come from](./queries.md#where-the-rows-come-from). Stream the rows instead of
collecting them all:

```rust,no_run
# use bigquery::*;
# use futures::StreamExt;
# use serde::Deserialize;
#[derive(Debug, Deserialize)]
struct OrderWithCity {
    id: i64,
    total: f64,
    city: String,
}

# async fn example(db: BigQueryDb) -> BigQueryResult<()> {
let mut orders = db
    .fluent()
    .query(
        "SELECT o.id, o.total, c.city FROM shop.orders o \
         JOIN shop.customers c ON c.id = o.customer_id \
         WHERE o.total > @minimum",
    )
    .param("minimum", 100.0)
    .obj::<OrderWithCity>()
    .stream_query()
    .await?;
while let Some(order) = orders.next().await {
    println!("{order:?}");
}
# Ok(())
# }
```

Reading that temporary table is free, so you pay only for the query. `.read_options(..)` sets
the number of read streams and the compression, as for a table read.

BigQuery limits how large a query result can be in its temporary table, see the maximum response
size in [Quotas and limits](https://cloud.google.com/bigquery/quotas#query_jobs). For a result
above it, write the result into a table of your own with `.destination_table(..)`, see
[Destination tables](./queries.md#destination-tables). The query is the same, and the rows are
read back from that table through the same Storage Read path:

```rust,no_run
# use bigquery::*;
# use futures::StreamExt;
# use serde::Deserialize;
# #[derive(Debug, Deserialize)]
# struct OrderWithCity {
#     id: i64,
#     total: f64,
#     city: String,
# }
const SHOP: BigQueryDatasetId = BigQueryDatasetId::from_static("shop");
const ORDERS_EXPORT: BigQueryTableId = BigQueryTableId::from_static("orders_export");

# async fn example(db: BigQueryDb) -> BigQueryResult<()> {
let mut orders = db
    .fluent()
    .query(
        "SELECT o.id, o.total, c.city FROM shop.orders o \
         JOIN shop.customers c ON c.id = o.customer_id",
    )
    .destination_table(SHOP.table(ORDERS_EXPORT))
    .obj::<OrderWithCity>()
    .stream_query()
    .await?;
while let Some(order) = orders.next().await {
    println!("{order:?}");
}

db.fluent().schema().table(SHOP.table(ORDERS_EXPORT)).delete().await?;
# Ok(())
# }
```

The default refuses to write into a table that already holds rows, so a second run fails until
the table is deleted. Use `.dangerously_overwrite_destination_table(..)` to replace it instead.
Give the dataset a default table expiration, so the table does not stay behind if your process
stops before the delete.

That table is a table of your own, so its storage is billed while it exists, and reading it back
is billed as Storage Read, see [Billing hints](#billing-hints).

Be aware not to splice values into SQL text in either path. Use `.filter(..)` instead of
`.filter_sql(..)`, and `.param(..)` instead of `format!` in the query text.