feat: job creation mode GA (#1480)

alvarowolfx · web-flow · commit b51359a61d93 · 2025-05-28T12:06:15.000-04:00
diff --git a/README.md b/README.md
@@ -153,6 +153,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/nodejs-bigquery/tr
 | Query Dry Run | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryDryRun.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryDryRun.js,samples/README.md) |
 | Query External GCS Perm | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryExternalGCSPerm.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryExternalGCSPerm.js,samples/README.md) |
 | Query External GCS Temp | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryExternalGCSTemp.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryExternalGCSTemp.js,samples/README.md) |
+| Query Job Optional | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryJobOptional.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryJobOptional.js,samples/README.md) |
 | Query Legacy | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryLegacy.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryLegacy.js,samples/README.md) |
 | Query Legacy Large Results | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryLegacyLargeResults.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryLegacyLargeResults.js,samples/README.md) |
 | Query Pagination | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryPagination.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryPagination.js,samples/README.md) |
@@ -163,7 +164,6 @@ Samples are in the [`samples/`](https://github.com/googleapis/nodejs-bigquery/tr
 | Query Params Positional Types | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryParamsPositionalTypes.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryParamsPositionalTypes.js,samples/README.md) |
 | Query Params Structs | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryParamsStructs.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryParamsStructs.js,samples/README.md) |
 | Query Params Timestamps | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryParamsTimestamps.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryParamsTimestamps.js,samples/README.md) |
-| Query Short Mode | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryShortMode.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryShortMode.js,samples/README.md) |
 | Query Stack Overflow | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryStackOverflow.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryStackOverflow.js,samples/README.md) |
 | Quickstart | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/quickstart.js,samples/README.md) |
 | Relax Column | [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/relaxColumn.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/relaxColumn.js,samples/README.md) |
diff --git a/samples/README.md b/samples/README.md
@@ -86,6 +86,7 @@
   * [Query Dry Run](#query-dry-run)
   * [Query External GCS Perm](#query-external-gcs-perm)
   * [Query External GCS Temp](#query-external-gcs-temp)
+  * [Query Job Optional](#query-job-optional)
   * [Query Legacy](#query-legacy)
   * [Query Legacy Large Results](#query-legacy-large-results)
   * [Query Pagination](#query-pagination)
@@ -96,7 +97,6 @@
   * [Query Params Positional Types](#query-params-positional-types)
   * [Query Params Structs](#query-params-structs)
   * [Query Params Timestamps](#query-params-timestamps)
-  * [Query Short Mode](#query-short-mode)
   * [Query Stack Overflow](#query-stack-overflow)
   * [Quickstart](#quickstart)
   * [Relax Column](#relax-column)
@@ -1408,6 +1408,23 @@ __Usage:__
 
 
 
+### Query Job Optional
+
+View the [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryJobOptional.js).
+
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryJobOptional.js,samples/README.md)
+
+__Usage:__
+
+
+`node samples/queryJobOptional.js`
+
+
+-----
+
+
+
+
 ### Query Legacy
 
 View the [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryLegacy.js).
@@ -1578,23 +1595,6 @@ __Usage:__
 
 
 
-### Query Short Mode
-
-View the [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryShortMode.js).
-
-[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-bigquery&page=editor&open_in_editor=samples/queryShortMode.js,samples/README.md)
-
-__Usage:__
-
-
-`node samples/queryShortMode.js`
-
-
------
-
-
-
-
 ### Query Stack Overflow
 
 View the [source code](https://github.com/googleapis/nodejs-bigquery/blob/main/samples/queryStackOverflow.js).
diff --git a/samples/queryJobOptional.js b/samples/queryJobOptional.js
@@ -15,16 +15,17 @@
 'use strict';
 
 function main() {
-  // [START bigquery_query_shortmode]
+  // [START bigquery_query_job_optional]
   // Demonstrates issuing a query that may be run in short query mode.
-  // To enable the short query mode preview feature, the QUERY_PREVIEW_ENABLED
-  // environmental variable should be set to `TRUE`.
 
   // Import the Google Cloud client library
   const {BigQuery} = require('@google-cloud/bigquery');
-  const bigquery = new BigQuery();
+  const bigquery = new BigQuery({
+    // default behavior is to create jobs when using the jobs.query API
+    defaultJobCreationMode: 'JOB_CREATION_REQUIRED',
+  });
 
-  async function queryShortMode() {
+  async function queryJobOptional() {
     // SQL query to run.
 
     const sqlQuery = `
@@ -35,7 +36,11 @@ function main() {
       LIMIT 10`;
 
     // Run the query
-    const [rows, , res] = await bigquery.query(sqlQuery);
+    const [rows, , res] = await bigquery.query({
+      query: sqlQuery,
+      // Skip job creation to enable short mode.
+      jobCreationMode: 'JOB_CREATION_OPTIONAL',
+    });
 
     if (!res.jobReference) {
       console.log(`Query was run in short mode. Query ID: ${res.queryId}`);
@@ -50,7 +55,7 @@ function main() {
     console.log('Rows:');
     rows.forEach(row => console.log(row));
   }
-  // [END bigquery_query_shortmode]
-  queryShortMode();
+  // [END bigquery_query_job_optional]
+  queryJobOptional();
 }
 main(...process.argv.slice(2));
diff --git a/samples/test/queries.test.js b/samples/test/queries.test.js
@@ -70,8 +70,8 @@ describe('Queries', () => {
     assert.match(output, /name/);
   });
 
-  it('should run a query in short mode', async () => {
-    const output = execSync('node queryShortMode.js');
+  it('should run a query stateless mode', async () => {
+    const output = execSync('node queryJobOptional.js');
     assert.match(output, /Rows:/);
     assert.match(output, /name/);
   });
diff --git a/src/bigquery.ts b/src/bigquery.ts
@@ -105,6 +105,8 @@ export type SimpleQueryRowsCallback = ResourceCallback<
   bigquery.IJob
 >;
 
+type JobCreationMode = bigquery.IQueryRequest['jobCreationMode'];
+
 export type Query = JobRequest<bigquery.IJobConfigurationQuery> & {
   destination?: Table;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -119,6 +121,8 @@ export type Query = JobRequest<bigquery.IJobConfigurationQuery> & {
   pageToken?: string;
   wrapIntegers?: boolean | IntegerTypeCastOptions;
   parseJSON?: boolean;
+  // Overrides default job creation mode set on the client.
+  jobCreationMode?: JobCreationMode;
 };
 
 export type QueryParamTypeStruct = {
@@ -271,6 +275,13 @@ export interface BigQueryOptions extends GoogleAuthOptions {
    * Defaults to `googleapis.com`.
    */
   universeDomain?: string;
+
+  /**
+   * Controls the job creation mode used when executing queries that can be
+   * accelerated via the jobs.Query API. Users may experience performance
+   * improvements by leveraging the JOB_CREATION_OPTIONAL mode.
+   */
+  defaultJobCreationMode?: JobCreationMode;
 }
 
 export interface IntegerTypeCastOptions {
@@ -320,12 +331,6 @@ export const PROTOCOL_REGEX = /^(\w*):\/\//;
  * We will create a table with the correct schema, import the public CSV file
  * into that table, and query it for data.
  *
- * This client supports enabling query-related preview features via environmental
- * variables.  By setting the environment variable QUERY_PREVIEW_ENABLED to the string
- * "TRUE", the client will enable preview features, though behavior may still be
- * controlled via the bigquery service as well.  Currently, the feature(s) in scope
- * include: stateless queries (query execution without corresponding job metadata).
- *
  * @class
  *
  * See {@link https://cloud.google.com/bigquery/what-is-bigquery| What is BigQuery?}
@@ -362,7 +367,7 @@ export const PROTOCOL_REGEX = /^(\w*):\/\//;
 export class BigQuery extends Service {
   location?: string;
   private _universeDomain: string;
-  private _enableQueryPreview: boolean;
+  private _defaultJobCreationMode: JobCreationMode;
 
   createQueryStream(options?: Query | string): ResourceStream<RowMetadata> {
     // placeholder body, overwritten in constructor
@@ -421,12 +426,8 @@ export class BigQuery extends Service {
 
     super(config, options);
 
-    const QUERY_PREVIEW_ENABLED = process.env.QUERY_PREVIEW_ENABLED;
-    this._enableQueryPreview = false;
-    if (typeof QUERY_PREVIEW_ENABLED === 'string') {
-      if (QUERY_PREVIEW_ENABLED.toUpperCase() === 'TRUE') {
-        this._enableQueryPreview = true;
-      }
+    if (options.defaultJobCreationMode) {
+      this._defaultJobCreationMode = options.defaultJobCreationMode;
     }
 
     this._universeDomain = universeDomain;
@@ -2338,7 +2339,7 @@ export class BigQuery extends Service {
       query: queryObj.query,
       useLegacySql: false,
       requestId: randomUUID(),
-      jobCreationMode: 'JOB_CREATION_OPTIONAL',
+      jobCreationMode: this._defaultJobCreationMode,
       reservation: queryObj.reservation,
       continuous: queryObj.continuous,
       destinationEncryptionConfiguration:
@@ -2347,8 +2348,9 @@ export class BigQuery extends Service {
       connectionProperties: queryObj.connectionProperties,
       preserveNulls: queryObj.preserveNulls,
     };
-    if (!this._enableQueryPreview) {
-      delete req.jobCreationMode;
+    if (queryObj.jobCreationMode) {
+      // override default job creation mode
+      req.jobCreationMode = queryObj.jobCreationMode;
     }
     const {parameterMode, params} = this.buildQueryParams_(
       queryObj.params,
diff --git a/test/bigquery.ts b/test/bigquery.ts
@@ -189,8 +189,10 @@ describe('BigQuery', () => {
   beforeEach(() => {
     Object.assign(fakeUtil, originalFakeUtil);
     BigQuery = Object.assign(BigQuery, BigQueryCached);
-    bq = new BigQuery({projectId: PROJECT_ID});
-    bq._enableQueryPreview = true;
+    bq = new BigQuery({
+      projectId: PROJECT_ID,
+      defaultJobCreationMode: 'JOB_CREATION_OPTIONAL',
+    });
   });
 
   after(() => {
@@ -3360,6 +3362,7 @@ describe('BigQuery', () => {
         labels: {
           key: 'value',
         },
+        jobCreationMode: 'JOB_CREATION_REQUIRED',
       };
       const req = bq.buildQueryRequest_(q, {});
       for (const key in req) {
@@ -3392,7 +3395,7 @@ describe('BigQuery', () => {
         labels: {
           key: 'value',
         },
-        jobCreationMode: 'JOB_CREATION_OPTIONAL',
+        jobCreationMode: 'JOB_CREATION_REQUIRED',
         formatOptions: {
           useInt64Timestamp: true,
         },
