From 2b831635e3506f64471a6cdd6ce7a288d365c59d Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Fri, 20 Nov 2026 22:08:57 +0000 Subject: [PATCH] docs(bigquery): document BigQuery interface scope, lifecycle, and thread safety Update com.google.cloud.bigquery.BigQuery class Javadoc to: - Summarize the synchronous operations provided by the interface (resources, queries, jobs, and data ingestion). - Document singleton reuse across threads, calling close() on shutdown to release cached background resources (such as Storage Read API clients), and non-thread-safe stateful helpers (Connection and TableDataWriteChannel). - Update the legacy cloud.google.com/bigquery/what-is-bigquery link to https://docs.cloud.google.com/bigquery/docs/introduction. Verified with fmt:check, checkstyle:check@checkstyle, test-compile, and javadoc -Xdoclint:syntax,html,reference. --- .../java/com/google/cloud/bigquery/BigQuery.java | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java index f2de6cd0da05..c6f7035ee040 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/BigQuery.java @@ -38,7 +38,18 @@ /** * An interface for Google Cloud BigQuery. * - * @see Google Cloud BigQuery + *

Provides synchronous operations to manage BigQuery resources ({@link Dataset}, {@link Table}, + * {@link Model}, {@link Routine}), run SQL queries ({@link #query(QueryJobConfiguration, + * JobOption...)}), submit and monitor asynchronous {@link Job}s, and ingest data ({@link #writer}, + * {@link #insertAll}). + * + *

Typically, create one {@code BigQuery} instance per application via {@link + * BigQueryOptions#getService()} and reuse it across threads. Call {@link #close()} on application + * shutdown to release cached background resources (such as Storage Read API clients used for query + * streaming). Operations on {@code BigQuery} are thread-safe, except for stateful helpers returned + * by this client such as {@link Connection} and {@link TableDataWriteChannel}. + * + * @see Google Cloud BigQuery */ public interface BigQuery extends Service, AutoCloseable {