feat: query client based on autogen package

package.json

@@ -45,13 +45,16 @@
     "test": "c8 mocha build/test"
   },
   "dependencies": {
+    "big.js": "^7.0.1",
     "google-gax": "^5.0.0"
   },
   "devDependencies": {
+    "@types/big.js": "^6.2.2",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.15.21",
     "@types/sinon": "^17.0.4",
     "c8": "^10.1.3",
+    "eslint-plugin-prettier": "^5.5.1",
     "gapic-tools": "^1.0.2",
     "gts": "^6.0.2",
     "jsdoc": "^4.0.4",

src/index.ts

@@ -46,3 +46,4 @@ export {
 };
 import * as protos from '../protos/protos';
 export {protos};
+export * as query from './query';

src/query/builder.ts

@@ -0,0 +1,36 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {protos} from '../';
+
+/**
+ * fromSQL creates a query configuration from a SQL string.
+ * @param {string} sql The SQL query.
+ * @returns {protos.google.cloud.bigquery.v2.IPostQueryRequest}
+ */
+export function fromSQL(
+  projectId: string,
+  sql: string,
+): protos.google.cloud.bigquery.v2.IPostQueryRequest {
+  return {
+    queryRequest: {
+      query: sql,
+      useLegacySql: {value: false},
+      formatOptions: {
+        useInt64Timestamp: true,
+      },
+    },
+    projectId,
+  };
+}

src/query/client.ts

@@ -0,0 +1,172 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {
+  BigQueryClient,
+  BigQueryClientOptions,
+} from '../bigquery';
+import {QueryJob, CallOptions} from './job';
+import {protos} from '../';
+import {fromSQL as builderFromSQL} from './builder';
+
+/**
+ * QueryClient is a client for running queries in BigQuery.
+ */
+export class QueryClient {
+  private client: BigQueryClient;
+  projectId: string;
+  private billingProjectId: string;
+
+  /**
+   * @param {BigQueryClientOptions} options - The configuration object.
+   */
+  constructor(
+    options?: BigQueryClientOptions,
+  ) {
+    this.client = new BigQueryClient(options);
+    this.projectId = '';
+    this.billingProjectId = '';
+    void this.initialize();
+  }
+
+  async getProjectId(): Promise<string> {
+    if (this.projectId) {
+      return this.projectId;
+    }
+    const {jobClient} = this.getBigQueryClient();
+    const projectId = await jobClient.getProjectId();
+    this.projectId = projectId;
+    return projectId;
+  }
+  /**
+   * Initialize the client.
+   * Performs asynchronous operations (such as authentication) and prepares the client.
+   * This function will be called automatically when any class method is called for the
+   * first time, but if you need to initialize it before calling an actual method,
+   * feel free to call initialize() directly.
+   *
+   * You can await on this method if you want to make sure the client is initialized.
+   *
+   * @returns {Promise} A promise that resolves when auth is complete.
+   */
+  initialize = async (): Promise<void> => {
+    if (this.projectId) {
+      return;
+    }
+    const {jobClient} = this.getBigQueryClient();
+    await jobClient.initialize();
+    const projectId = await this.getProjectId();
+    this.projectId = projectId;
+    if (this.billingProjectId !== '') {
+      this.billingProjectId = projectId;
+    }
+  };
+
+  setBillingProjectId(projectId: string) {
+    this.billingProjectId = projectId;
+  }
+
+  /**
+   * fromSQL creates a query configuration from a SQL string.
+   * @param {string} sql The SQL query.
+   * @returns {protos.google.cloud.bigquery.v2.IPostQueryRequest}
+   */
+  fromSQL(sql: string): protos.google.cloud.bigquery.v2.IPostQueryRequest {
+    const req = builderFromSQL(this.projectId, sql);
+    return req;
+  }
+
+  /**
+   * Runs a query and returns a QueryJob handle.
+   *
+   * @param {protos.google.cloud.bigquery.v2.IPostQueryRequest} request
+   *   The request object that will be sent.
+   * @param {CallOptions} [options]
+   *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+   * @returns {Promise<QueryJob>}
+   */
+  async startQuery(
+    request: protos.google.cloud.bigquery.v2.IPostQueryRequest,
+    options?: CallOptions,
+  ): Promise<QueryJob> {
+    const [response] = await this.client.jobClient.query(request, options);
+    return new QueryJob(this, response);
+  }
+
+  /**
+   * Runs a query and returns a QueryJob handle.
+   *
+   * @param {protos.google.cloud.bigquery.v2.IQueryRequest} request
+   *   The request object that will be sent.
+   * @param {CallOptions} [options]
+   *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+   * @returns {Promise<QueryJob>}
+   */
+  async startQueryRequest(
+    request: protos.google.cloud.bigquery.v2.IQueryRequest,
+    options?: CallOptions,
+  ): Promise<QueryJob> {
+    return this.startQuery(
+      {
+        queryRequest: request,
+        projectId: this.projectId,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Starts a new asynchronous job.
+   *
+   * @param {protos.google.cloud.bigquery.v2.IJob} job
+   *   A job resource to insert
+   * @param {CallOptions} [options]
+   *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+   * @returns {Promise<QueryJob>}
+   */
+  async startQueryJob(
+    job: protos.google.cloud.bigquery.v2.IJob,
+    options?: CallOptions,
+  ): Promise<QueryJob> {
+    const [response] = await this.client.jobClient.insertJob(
+      {
+        projectId: this.projectId,
+        job,
+      },
+      options,
+    );
+    return new QueryJob(this, {jobReference: response.jobReference});
+  }
+
+  /**
+   * Create a managed QueryJob from a job reference.
+   *
+   * @param {protos.google.cloud.bigquery.v2.IJob} job
+   *   A job resource to insert
+   * @param {CallOptions} [options]
+   *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
+   * @returns {Promise<QueryJob>}
+   */
+  async attachJob(
+    jobRef: protos.google.cloud.bigquery.v2.IJobReference,
+  ): Promise<QueryJob> {
+    return new QueryJob(this, {
+      jobReference: jobRef,
+    });
+  }
+
+  getBigQueryClient(): BigQueryClient {
+    return this.client;
+  }
+}

src/query/format.ts

@@ -0,0 +1,47 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export function civilDateString(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+export function civilTimeString(value: string | Date): string {
+  if (value instanceof Date) {
+    const h = `${value.getHours()}`.padStart(2, '0');
+    const m = `${value.getMinutes()}`.padStart(2, '0');
+    const s = `${value.getSeconds()}`.padStart(2, '0');
+    const f = `${value.getMilliseconds() * 1000}`.padStart(6, '0');
+    return `${h}:${m}:${s}.${f}`;
+  }
+  return value;
+}
+
+export function civilDateTimeString(value: Date | string): string {
+  if (value instanceof Date) {
+    let time;
+    if (value.getHours()) {
+      time = civilTimeString(value);
+    }
+    const y = `${value.getFullYear()}`.padStart(2, '0');
+    const m = `${value.getMonth() + 1}`.padStart(2, '0');
+    const d = `${value.getDate()}`.padStart(2, '0');
+    time = time ? 'T' + time : '';
+    return `${y}-${m}-${d}${time}`;
+  }
+  return value.replace(/^(.*)T(.*)Z$/, '$1 $2');
+}
+
+export function timestampString(ts: Date): string {
+  return ts.toISOString().replace('T', ' ').replace('Z', '');
+}

src/query/index.ts

@@ -0,0 +1,19 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export {QueryClient} from './client';
+export {QueryJob} from './job';
+export {Row} from './row';
+export {RowIterator} from './iterator';
+export {fromSQL} from './builder';

src/query/iterator.ts

@@ -0,0 +1,60 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {QueryJob} from './job';
+import {Row} from './row';
+
+/**
+ * RowIterator iterates over the results of a query.
+ */
+export class RowIterator {
+  private job: QueryJob;
+  private pageToken?: string;
+  private rows: Row[] = [];
+
+  constructor(
+    job: QueryJob,
+    opts?: {
+      rows?: Row[];
+      pageToken?: string;
+    },
+  ) {
+    this.job = job;
+    this.pageToken = opts?.pageToken;
+    this.rows = opts?.rows ?? [];
+  }
+
+  async fetchRows() {
+    const [rows, _, pageToken] = await this.job._getRows(this.pageToken);
+    this.rows = rows;
+    this.pageToken = pageToken || undefined;
+  }
+
+  /**
+   * Asynchronously iterates over the rows in the query result.
+   */
+  async *[Symbol.asyncIterator](): AsyncGenerator<Row> {
+    if (this.rows.length > 0) {
+      for (const row of this.rows) {
+        yield row;
+      }
+    }
+    while (this.pageToken) {
+      await this.fetchRows();
+      for (const row of this.rows) {
+        yield row;
+      }
+    }
+  }
+}