Skip to content

docs(bigquery): document BigQuery interface scope, lifecycle, and thread safety - #15117

Merged
lqiu96 merged 1 commit into
googleapis:mainfrom
lqiu96:docs/bq-1b-bigquery-client-javadoc
Nov 20, 2026
Merged

lqiu96 merged 1 commit into
googleapis:mainfrom
lqiu96:docs/bq-1b-bigquery-client-javadoc

Conversation

@lqiu96

@lqiu96 lqiu96 commented Nov 20, 2026

Copy link
Copy Markdown
Member

Update com.google.cloud.bigquery.BigQuery interface Javadoc to concisely document the interface itself (modeled on Spanner and Storage conventions).

Summary of Changes

  • Summarize the synchronous operations provided by BigQuery (managing Dataset, Table, Model, and Routine resources, running SQL queries, submitting and monitoring asynchronous Jobs, and ingesting data via writer and insertAll).
  • Document single-instance reuse across threads via BigQueryOptions#getService(), calling close() on shutdown to release cached background resources (such as Storage Read API clients used for query streaming), and stateful non-thread-safe helpers (Connection and TableDataWriteChannel).
  • Update the legacy https://cloud.google.com/bigquery/what-is-bigquery @see link to https://docs.cloud.google.com/bigquery/docs/introduction.

Verification

  • Verified fmt:check, checkstyle:check@checkstyle, test-compile, and javadoc -Xdoclint:syntax,html,reference on java-bigquery/google-cloud-bigquery.
  • Verified the updated documentation link returns HTTP 200.
  • Javadoc-only change with no behavioral impact.

…ead 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.
@lqiu96
lqiu96 requested review from a team as code owners November 20, 2026 22:09

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the Javadoc for the BigQuery interface to provide detailed documentation on its synchronous operations, thread-safety, resource management, and usage guidelines, as well as updating the reference link. There are no review comments, and I have no feedback to provide.

@lqiu96
lqiu96 merged commit 62fda1c into googleapis:main Nov 20, 2026
198 checks passed
lqiu96 added a commit that referenced this pull request Nov 21, 2026
Updates 157 malformed, legacy, and broken-anchor documentation URLs
across 33 files in `java-bigquery` (Javadoc and comment-only, no
behavioral changes).

### Summary of changes

- Fix malformed `hhttps://` URL in `ExternalTableDefinition.java`.
- Replace pre-`/docs/` `cloud.google.com/bigquery/...` links (which no
longer resolve to canonical documentation pages or drop section anchors)
with canonical `https://docs.cloud.google.com/bigquery/...` destinations
and exact section anchors (for example, `quotas#query_jobs`,
`sessions#create-session`, `adding-labels#adding_dataset_labels`, and
`biglake-intro#metadata_caching_for_performance`).
- Update legacy `/docs/reference/v2/...` URLs and broken camelCase
anchors to `/docs/reference/rest/v2/...` with live REST schema, field,
and enum anchors (including pointing `JobInfo` and `BigQuery.JobField`
to `/rest/v2/Job`, `LoadConfiguration.setFormatOptions` to
`Job#JobConfigurationLoad.FIELDS.source_format`,
`ExternalTableDefinition` and `CopyJobConfiguration` to exact
`.FIELDS.*` anchors, `RoutineInfo` to `#routinetype` and
`#datagovernancetype`, and `BigQuery.TableMetadataView`'s link label to
`TableMetadataView`).
- Fix wrong-topic links for `TableDefinition.Type.MATERIALIZED_VIEW`
(`materialized-views-intro`), `ModelTableDefinition`, and
`TableDefinition.Type.MODEL` (`bqml-introduction`).
- Replace the legacy `developers.google.com` Discovery Javadoc link in
`BigQueryDryRunResult.java` with the canonical REST
`Job#JobStatistics2.FIELDS.undeclared_query_parameters` anchor.
- Update broken `cloud.google.com/bigquery/pricing#storage` and
`#long-term-storage` anchors to `#storage-pricing`.
- Migrate remaining `cloud.google.com/bigquery/docs/...` and
`cloud.google.com/iam/docs/...` links to `docs.cloud.google.com`.

Note: Four lines currently touched by open PRs #15117 and #15118 are
skipped here to avoid merge conflicts (`DatasetInfo.java:41` will be
updated in a follow-up after #15118 merges). Historical GitHub issue
comments are preserved.

### Verification

- Every unique target URL (71/71) verified live with HTTP 200, 0
redirects, and matching HTML `id=` anchors where fragments are present
- `mvn -pl java-bigquery/google-cloud-bigquery
com.spotify.fmt:fmt-maven-plugin:check -Dlint
checkstyle:check@checkstyle test-compile` (0 Checkstyle violations)
- `javadoc -Xdoclint:syntax,html,reference` on all 33 modified files (0
warnings/errors)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants