From 45cc7bbaa0d8bc076d26f5b02ffe4fea9750be63 Mon Sep 17 00:00:00 2001 From: Ben Hu Date: Mon, 22 Jun 2026 15:42:30 +0000 Subject: [PATCH] feat: BigQuery Storage API v1beta1 migration guide --- .../storage-v1beta1-migration-guide-js.md | 154 +++++++++++++++++ .../storage-v1beta1-migration-guide-ts.md | 163 ++++++++++++++++++ 2 files changed, 317 insertions(+) create mode 100644 bigquery/cloud-client/storage-v1beta1-migration-guide-js.md create mode 100644 bigquery/cloud-client/storage-v1beta1-migration-guide-ts.md diff --git a/bigquery/cloud-client/storage-v1beta1-migration-guide-js.md b/bigquery/cloud-client/storage-v1beta1-migration-guide-js.md new file mode 100644 index 00000000000..56fa3ffb1d5 --- /dev/null +++ b/bigquery/cloud-client/storage-v1beta1-migration-guide-js.md @@ -0,0 +1,154 @@ +# Migrating BigQuery Storage API from v1beta1 to v1: JavaScript + +This guide shows how to migrate JavaScript code using the BigQuery Storage API +from version `v1beta1` to `v1`. + +## Key Changes + +* **Service Client**: `BigQueryStorageClient` (in `v1beta1` namespace) is + replaced by `BigQueryReadClient` (in `v1` namespace). +* **Table Reference**: `tableReference` object is replaced by a simple string + representation of the table path in `readSession.table`. +* **Session Configuration**: Configuration fields (table, format, read + options) have moved into `readSession` object, which is passed in + `createReadSession` request. +* **Parallelism**: `requestedStreams` is replaced by `maxStreamCount`. +* **Sharding Strategy**: `shardingStrategy` is removed. The server now + automatically balances the streams. +* **Read Rows Request**: `readPosition` is flattened. You now pass the stream + name directly as `readStream` and the `offset` as a top-level field in the + `readRows` request. + +## Code Comparison + +### 1. Client Initialization + +**v1beta1:** + +```javascript +const {v1beta1} = require('@google-cloud/bigquery-storage'); +const client = new v1beta1.BigQueryStorageClient(); +``` + +**v1:** + +```javascript +const {v1} = require('@google-cloud/bigquery-storage'); +const client = new v1.BigQueryReadClient(); +``` + +### 2. Creating a Read Session + +**v1beta1:** + +```javascript +const {v1beta1} = require('@google-cloud/bigquery-storage'); + +const tableReference = { + projectId: 'bigquery-public-data', + datasetId: 'usa_names', + tableId: 'usa_1910_current', +}; + +const readOptions = { + selectedFields: ['name'], + rowRestriction: 'state = "WA"', +}; + +const request = { + parent: 'projects/read-session-project', + tableReference: tableReference, + readOptions: readOptions, + requestedStreams: 1, + format: v1beta1.protos.google.cloud.bigquery.storage.v1beta1.DataFormat.AVRO, + shardingStrategy: v1beta1.protos.google.cloud.bigquery.storage.v1beta1.ShardingStrategy.LIQUID, +}; + +const [session] = await client.createReadSession(request); +``` + +**v1:** + +```javascript +const {v1} = require('@google-cloud/bigquery-storage'); + +// Table path is now a string: projects/{project}/datasets/{dataset}/tables/{table} +const tablePath = 'projects/bigquery-public-data/datasets/usa_names/tables/usa_1910_current'; + +const readOptions = { + selectedFields: ['name'], + rowRestriction: 'state = "WA"', +}; + +// ReadSession holds the session configuration +const readSession = { + table: tablePath, + dataFormat: v1.protos.google.cloud.bigquery.storage.v1.DataFormat.AVRO, // format renamed to dataFormat + readOptions: readOptions, +}; + +const request = { + parent: 'projects/read-session-project', + readSession: readSession, + maxStreamCount: 1, // requestedStreams renamed to maxStreamCount +}; + +const [session] = await client.createReadSession(request); +``` + +### 3. Reading Rows + +**v1beta1:** + +```javascript +const stream = session.streams[0]; + +const request = { + readPosition: { + stream: stream, // Stream object + offset: 0, + }, +}; + +const rowStream = client.readRows(request); + +rowStream + .on('data', (response) => { + // Process response.avroRows + }) + .on('error', (err) => { + // Handle error + }) + .on('end', () => { + // Done + }); +``` + +**v1:** + +```javascript +const stream = session.streams?.[0]; +if (!stream) { + throw new Error('No streams available'); +} + +// Request is flattened. Pass readStream (string) and offset directly. +const request = { + readStream: stream.name, // Stream name string + offset: 0, +}; + +const rowStream = client.readRows(request); + +rowStream + .on('data', (response) => { + // Process response.avroRows + // Note: Prefer using response.rowCount over response.avroRows?.rowCount (deprecated) + }) + .on('error', (err) => { + // Handle error + }) + .on('end', () => { + // Done + }); +``` diff --git a/bigquery/cloud-client/storage-v1beta1-migration-guide-ts.md b/bigquery/cloud-client/storage-v1beta1-migration-guide-ts.md new file mode 100644 index 00000000000..8c636d6ac60 --- /dev/null +++ b/bigquery/cloud-client/storage-v1beta1-migration-guide-ts.md @@ -0,0 +1,163 @@ +# Migrating BigQuery Storage API from v1beta1 to v1: TypeScript + +This guide shows how to migrate TypeScript code using the BigQuery Storage API +from version `v1beta1` to `v1`. + +## Key Changes + +* **Service Client**: `BigQueryStorageClient` (in `v1beta1` namespace) is + replaced by `BigQueryReadClient` (in `v1` namespace). +* **Table Reference**: `tableReference` object is replaced by a simple string + representation of the table path in `readSession.table`. +* **Session Configuration**: Configuration fields (table, format, read + options) have moved into `readSession` object, which is passed in + `createReadSession` request. +* **Parallelism**: `requestedStreams` is replaced by `maxStreamCount`. +* **Sharding Strategy**: `shardingStrategy` is removed. The server now + automatically balances the streams. +* **Read Rows Request**: `readPosition` is flattened. You now pass the stream + name directly as `readStream` and the `offset` as a top-level field in the + `readRows` request. + +## Code Comparison + +### 1. Client Initialization + +**v1beta1:** + +```typescript +import {v1beta1} from '@google-cloud/bigquery-storage'; +const client = new v1beta1.BigQueryStorageClient(); +``` + +**v1:** + +```typescript +import {v1} from '@google-cloud/bigquery-storage'; +const client = new v1.BigQueryReadClient(); +``` + +### 2. Creating a Read Session + +**v1beta1:** + +```typescript +import {v1beta1} from '@google-cloud/bigquery-storage'; + +const tableReference = { + projectId: 'bigquery-public-data', + datasetId: 'usa_names', + tableId: 'usa_1910_current', +}; + +const readOptions = { + selectedFields: ['name'], + rowRestriction: 'state = "WA"', +}; + +const request: v1beta1.protos.google.cloud.bigquery.storage.v1beta1.ICreateReadSessionRequest = { + parent: 'projects/read-session-project', + tableReference: tableReference, + readOptions: readOptions, + requestedStreams: 1, + format: v1beta1.protos.google.cloud.bigquery.storage.v1beta1.DataFormat.AVRO, + shardingStrategy: v1beta1.protos.google.cloud.bigquery.storage.v1beta1.ShardingStrategy.LIQUID, +}; + +const [session] = await client.createReadSession(request); +``` + +**v1:** + +```typescript +import {v1} from '@google-cloud/bigquery-storage'; + +// Table path is now a string: projects/{project}/datasets/{dataset}/tables/{table} +const tablePath = 'projects/bigquery-public-data/datasets/usa_names/tables/usa_1910_current'; + +const readOptions = { + selectedFields: ['name'], + rowRestriction: 'state = "WA"', +}; + +// ReadSession holds the session configuration +const readSession = { + table: tablePath, + dataFormat: v1.protos.google.cloud.bigquery.storage.v1.DataFormat.AVRO, // format renamed to dataFormat + readOptions: readOptions, +}; + +const request: v1.protos.google.cloud.bigquery.storage.v1.ICreateReadSessionRequest = { + parent: `projects/read-session-project`, + readSession: readSession, + maxStreamCount: 1, // requestedStreams renamed to maxStreamCount +}; + +const [session] = await client.createReadSession(request); +``` + +### 3. Reading Rows + +In Node.js client, `readRows` returns a stream that emits data events. + +**v1beta1:** + +```typescript +import {v1beta1} from '@google-cloud/bigquery-storage'; + +const stream = session.streams?.[0]; +if (!stream) { + throw new Error('No streams available'); +} + +const request: v1beta1.protos.google.cloud.bigquery.storage.v1beta1.IReadRowsRequest = { + readPosition: { + stream: stream, // Stream object + offset: 0, + }, +}; + +const rowStream = client.readRows(request); + +rowStream + .on('data', (response: v1beta1.protos.google.cloud.bigquery.storage.v1beta1.IReadRowsResponse) => { + // Process response.avroRows + }) + .on('error', (err) => { + // Handle error + }) + .on('end', () => { + // Done + }); +``` + +**v1:** + +```typescript +import {v1} from '@google-cloud/bigquery-storage'; + +const stream = session.streams?.[0]; +if (!stream || !stream.name) { + throw new Error('No streams available'); +} + +// Request is flattened. Pass readStream (string) and offset directly. +const request: v1.protos.google.cloud.bigquery.storage.v1.IReadRowsRequest = { + readStream: stream.name, // Stream name string + offset: 0, +}; + +const rowStream = client.readRows(request); + +rowStream + .on('data', (response: v1.protos.google.cloud.bigquery.storage.v1.IReadRowsResponse) => { + // Process response.avroRows + // Note: Prefer using response.rowCount over response.avroRows?.rowCount (deprecated) + }) + .on('error', (err) => { + // Handle error + }) + .on('end', () => { + // Done + }); +```