feat: CommitStats in CommitResponse

samples/crud.js

@@ -335,6 +335,8 @@ async function readStaleData(instanceId, databaseId, projectId) {
   // [END spanner_read_stale_data]
 }
 
+const {getCommitStats} = require('./get-commit-stats');
+
 require('yargs')
   .demand(1)
   .command(
@@ -373,12 +375,19 @@ require('yargs')
     {},
     opts => readStaleData(opts.instanceName, opts.databaseName, opts.projectId)
   )
+  .command(
+    'getCommitStats <instanceName> <databaseName> <projectId>',
+    'Updates rows in example Cloud Spanner table and reads CommitStats.',
+    {},
+    opts => getCommitStats(opts.instanceName, opts.databaseName, opts.projectId)
+  )
   .example('node $0 update "my-instance" "my-database" "my-project-id"')
   .example('node $0 query "my-instance" "my-database" "my-project-id"')
   .example('node $0 insert "my-instance" "my-database" "my-project-id"')
   .example('node $0 delete "my-instance" "my-database" "my-project-id"')
   .example('node $0 read "my-instance" "my-database" "my-project-id"')
   .example('node $0 read-stale "my-instance" "my-database" "my-project-id"')
+  .example('node $0 getCommitStats "my-instance" "my-database" "my-project-id"')
   .wrap(120)
   .recommendCommands()
   .epilogue('For more information, see https://cloud.google.com/spanner/docs')

samples/get-commit-stats.js

@@ -0,0 +1,62 @@
+// Copyright 2021 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
+//
+//      http://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.
+
+'use strict';
+
+async function getCommitStats(instanceId, databaseId, projectId) {
+  // [START spanner_get_commit_stats]
+  // Imports the Google Cloud client library.
+  const {Spanner} = require('@google-cloud/spanner');
+
+  /**
+   * TODO(developer): Uncomment the following lines before running the sample.
+   */
+  // const projectId = 'my-project-id';
+  // const instanceId = 'my-instance';
+  // const databaseId = 'my-database';
+
+  // Creates a client.
+  const spanner = new Spanner({
+    projectId: projectId,
+  });
+
+  // Gets a reference to a Cloud Spanner instance and database.
+  const instance = spanner.instance(instanceId);
+  const database = instance.database(databaseId);
+
+  // Instantiate Spanner table objects.
+  const albumsTable = database.table('Albums');
+
+  // Updates rows in the Venues table.
+  try {
+    const [response] = await albumsTable.upsert(
+      [
+        {SingerId: '1', AlbumId: '1', MarketingBudget: '200000'},
+        {SingerId: '2', AlbumId: '2', MarketingBudget: '400000'},
+      ],
+      {returnCommitStats: true}
+    );
+    console.log(
+      `Updated data with ${response.commitStats.mutationCount} mutations.`
+    );
+  } catch (err) {
+    console.error('ERROR:', err);
+  } finally {
+    // Close the database when finished.
+    database.close();
+  }
+  // [END spanner_get_commit_stats]
+}
+
+module.exports.getCommitStats = getCommitStats;

samples/system-test/spanner.test.js

@@ -932,4 +932,12 @@ describe('Spanner', () => {
     );
     assert.match(output, /record inserted./);
   });
+
+  // get_commit_stats
+  it('should update rows in Albums example table and return CommitStats', async () => {
+    const output = execSync(
+      `${crudCmd} getCommitStats ${INSTANCE_ID} ${DATABASE_ID} ${PROJECT_ID}`
+    );
+    assert.match(output, new RegExp('Updated data with (\\d+) mutations'));
+  });
 });

src/table.ts

@@ -22,6 +22,7 @@ import {PartialResultStream, Row} from './partial-result-stream';
 import {
   ReadRequest,
   TimestampBounds,
+  CommitOptions,
   CommitResponse,
   ReadResponse,
   ReadCallback,
@@ -44,18 +45,23 @@ export type DropTableCallback = UpdateSchemaCallback;
 
 export type DeleteRowsCallback = CommitCallback;
 export type DeleteRowsResponse = CommitResponse;
+export type DeleteRowsOptions = CommitOptions;
 
 export type InsertRowsCallback = CommitCallback;
 export type InsertRowsResponse = CommitResponse;
+export type InsertRowsOptions = CommitOptions;
 
 export type ReplaceRowsCallback = CommitCallback;
 export type ReplaceRowsResponse = CommitResponse;
+export type ReplaceRowsOptions = CommitOptions;
 
 export type UpdateRowsCallback = CommitCallback;
 export type UpdateRowsResponse = CommitResponse;
+export type UpdateRowsOptions = CommitOptions;
 
 export type UpsertRowsCallback = CommitCallback;
 export type UpsertRowsResponse = CommitResponse;
+export type UpsertRowsOptions = CommitOptions;
 /**
  * Create a Table object to interact with a table in a Cloud Spanner
  * database.
@@ -315,12 +321,12 @@ class Table {
   }
   deleteRows(
     keys: Key[],
-    gaxOptions?: CallOptions
+    options?: DeleteRowsOptions
   ): Promise<DeleteRowsResponse>;
   deleteRows(keys: Key[], callback: DeleteRowsCallback): void;
   deleteRows(
     keys: Key[],
-    gaxOptions: CallOptions,
+    options: DeleteRowsOptions,
     callback: DeleteRowsCallback
   ): void;
   /**
@@ -331,8 +337,7 @@ class Table {
    * @param {array} keys The keys for the rows to delete. If using a
    *     composite key, provide an array within this array. See the example
    * below.
-   * @param {object} [gaxOptions] Request configuration options, outlined here:
-   *     https://googleapis.github.io/gax-nodejs/classes/CallSettings.html.
+   * @param {DeleteRowsOptions} [options] Options for configuring the request.
    * @param {BasicCallback} [callback] Callback function.
    * @returns {Promise<BasicResponse>}
    *
@@ -372,15 +377,15 @@ class Table {
    */
   deleteRows(
     keys: Key[],
-    gaxOptionsOrCallback?: CallOptions | DeleteRowsCallback,
+    optionsOrCallback?: DeleteRowsOptions | DeleteRowsCallback,
     cb?: DeleteRowsCallback
   ): Promise<DeleteRowsResponse> | void {
-    const gaxOptions =
-      typeof gaxOptionsOrCallback === 'object' ? gaxOptionsOrCallback : {};
+    const options =
+      typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
     const callback =
-      typeof gaxOptionsOrCallback === 'function' ? gaxOptionsOrCallback : cb!;
+      typeof optionsOrCallback === 'function' ? optionsOrCallback : cb!;
 
-    return this._mutate('deleteRows', keys, gaxOptions, callback!);
+    return this._mutate('deleteRows', keys, options, callback!);
   }
   drop(gaxOptions?: CallOptions): Promise<DropTableResponse>;
   drop(callback: DropTableCallback): void;
@@ -441,12 +446,12 @@ class Table {
   }
   insert(
     rows: object | object[],
-    gaxOptions?: CallOptions
+    options?: InsertRowsOptions
   ): Promise<InsertRowsResponse>;
   insert(rows: object | object[], callback: InsertRowsCallback): void;
   insert(
     rows: object | object[],
-    gaxOptions: CallOptions,
+    options: InsertRowsOptions,
     callback: InsertRowsCallback
   ): void;
   /**
@@ -456,8 +461,7 @@ class Table {
    *
    * @param {object|object[]} rows A map of names to values of data to insert
    *     into this table.
-   * @param {object} [gaxOptions] Request configuration options, outlined here:
-   *     https://googleapis.github.io/gax-nodejs/classes/CallSettings.html.
+   * @param {DeleteRowsOptions} [options] Options for configuring the request.
    * @param {BasicCallback} [callback] Callback function.
    * @returns {Promise<BasicResponse>}
    *
@@ -509,15 +513,15 @@ class Table {
    */
   insert(
     rows: object | object[],
-    gaxOptionsOrCallback?: CallOptions | InsertRowsCallback,
+    optionsOrCallback?: InsertRowsOptions | InsertRowsCallback,
     cb?: InsertRowsCallback
   ): Promise<InsertRowsResponse> | void {
-    const gaxOptions =
-      typeof gaxOptionsOrCallback === 'object' ? gaxOptionsOrCallback : {};
+    const options =
+      typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
     const callback =
-      typeof gaxOptionsOrCallback === 'function' ? gaxOptionsOrCallback : cb!;
+      typeof optionsOrCallback === 'function' ? optionsOrCallback : cb!;
 
-    this._mutate('insert', rows, gaxOptions, callback!);
+    this._mutate('insert', rows, options, callback!);
   }
   read(request: ReadRequest, options?: TimestampBounds): Promise<ReadResponse>;
   read(request: ReadRequest, callback: ReadCallback): void;
@@ -699,12 +703,12 @@ class Table {
   }
   replace(
     rows: object | object[],
-    gaxOptions?: CallOptions
+    options?: ReplaceRowsOptions
   ): Promise<ReplaceRowsResponse>;
   replace(rows: object | object[], callback: ReplaceRowsCallback): void;
   replace(
     rows: object | object[],
-    gaxOptions: CallOptions,
+    options: ReplaceRowsOptions,
     callback: ReplaceRowsCallback
   ): void;
   /**
@@ -714,8 +718,7 @@ class Table {
    *
    * @param {object|object[]} rows A map of names to values of data to insert
    *     into this table.
-   * @param {object} [gaxOptions] Request configuration options, outlined here:
-   *     https://googleapis.github.io/gax-nodejs/classes/CallSettings.html.
+   * @param {ReplaceRowsOptions} [options] Options for configuring the request.
    * @param {BasicCallback} [callback] Callback function.
    * @returns {Promise<BasicResponse>}
    *
@@ -750,24 +753,24 @@ class Table {
    */
   replace(
     rows: object | object[],
-    gaxOptionsOrCallback?: CallOptions | ReplaceRowsCallback,
+    optionsOrCallback?: ReplaceRowsOptions | ReplaceRowsCallback,
     cb?: ReplaceRowsCallback
   ): Promise<ReplaceRowsResponse> | void {
-    const gaxOptions =
-      typeof gaxOptionsOrCallback === 'object' ? gaxOptionsOrCallback : {};
+    const options =
+      typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
     const callback =
-      typeof gaxOptionsOrCallback === 'function' ? gaxOptionsOrCallback : cb!;
+      typeof optionsOrCallback === 'function' ? optionsOrCallback : cb!;
 
-    this._mutate('replace', rows, gaxOptions, callback!);
+    this._mutate('replace', rows, options, callback!);
   }
   update(
     rows: object | object[],
-    gaxOptions?: CallOptions
+    options?: UpdateRowsOptions
   ): Promise<UpdateRowsResponse>;
   update(rows: object | object[], callback: UpdateRowsCallback): void;
   update(
     rows: object | object[],
-    gaxOptions: CallOptions,
+    options: UpdateRowsOptions,
     callback: UpdateRowsCallback
   ): void;
   /**
@@ -777,8 +780,7 @@ class Table {
    *
    * @param {object|object[]} rows A map of names to values of data to insert
    *     into this table.
-   * @param {object} [gaxOptions] Request configuration options, outlined here:
-   *     https://googleapis.github.io/gax-nodejs/classes/CallSettings.html.
+   * @param {UpdateRowsOptions} [options] Options for configuring the request.
    * @param {BasicCallback} [callback] Callback function.
    * @returns {Promise<BasicResponse>}
    *
@@ -817,24 +819,24 @@ class Table {
    */
   update(
     rows: object | object[],
-    gaxOptionsOrCallback?: CallOptions | UpdateRowsCallback,
+    optionsOrCallback?: UpdateRowsOptions | UpdateRowsCallback,
     cb?: UpdateRowsCallback
   ): Promise<UpdateRowsResponse> | void {
-    const gaxOptions =
-      typeof gaxOptionsOrCallback === 'object' ? gaxOptionsOrCallback : {};
+    const options =
+      typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
     const callback =
-      typeof gaxOptionsOrCallback === 'function' ? gaxOptionsOrCallback : cb!;
+      typeof optionsOrCallback === 'function' ? optionsOrCallback : cb!;
 
-    this._mutate('update', rows, gaxOptions, callback!);
+    this._mutate('update', rows, options, callback!);
   }
   upsert(
     rows: object | object[],
-    gaxOptions?: CallOptions
+    options?: UpsertRowsOptions
   ): Promise<UpsertRowsResponse>;
   upsert(rows: object | object[], callback: UpsertRowsCallback): void;
   upsert(
     rows: object | object[],
-    gaxOptions: CallOptions,
+    options: UpsertRowsOptions,
     callback: UpsertRowsCallback
   ): void;
   /**
@@ -845,8 +847,7 @@ class Table {
    * @param {object|object[]} rows A map of names to values of data to insert
    *     into this table.
    *
-   * @param {object} [gaxOptions] Request configuration options, outlined here:
-   *     https://googleapis.github.io/gax-nodejs/classes/CallSettings.html.
+   * @param {UpsertRowsOptions} [options] Options for configuring the request.
    * @param {BasicCallback} [callback] Callback function.
    * @returns {Promise<BasicResponse>}
    *
@@ -881,15 +882,15 @@ class Table {
    */
   upsert(
     rows: object | object[],
-    gaxOptionsOrCallback?: CallOptions | UpsertRowsCallback,
+    optionsOrCallback?: UpsertRowsOptions | UpsertRowsCallback,
     cb?: UpsertRowsCallback
   ): Promise<UpsertRowsResponse> | void {
-    const gaxOptions =
-      typeof gaxOptionsOrCallback === 'object' ? gaxOptionsOrCallback : {};
+    const options =
+      typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
     const callback =
-      typeof gaxOptionsOrCallback === 'function' ? gaxOptionsOrCallback : cb!;
+      typeof optionsOrCallback === 'function' ? optionsOrCallback : cb!;
 
-    this._mutate('upsert', rows, gaxOptions, callback!);
+    this._mutate('upsert', rows, options, callback!);
   }
   /**
    * Creates a new transaction and applies the desired mutation via
@@ -907,7 +908,7 @@ class Table {
   private _mutate(
     method: 'deleteRows' | 'insert' | 'replace' | 'update' | 'upsert',
     rows: object | object[],
-    gaxOptions: CallOptions = {},
+    options: CommitOptions = {},
     callback: CommitCallback
   ): void {
     this.database.runTransaction((err, transaction) => {
@@ -917,7 +918,7 @@ class Table {
       }
 
       transaction![method](this.name, rows as Key[]);
-      transaction!.commit(gaxOptions, callback);
+      transaction!.commit(options, callback);
     });
   }
 }