BatchTransaction

Examples

transaction.begin(function(err) {
  if (!err) {
    // transaction began successfully.
  }
});

If the callback is omitted, the function returns a Promise

transaction.begin()
  .then(function(data) {
    const apiResponse = data[0];
  });

Example

const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');

database.createBatchTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  transaction.close(function(err, apiResponse) {});
});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.createBatchTransaction().then(function(data) {
  const transaction = data[0];
  return transaction.close();
});

Example

  // 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);
  const [transaction] = await database.createBatchTransaction();

  const query = 'SELECT * FROM Singers';

  const [partitions] = await transaction.createQueryPartitions(query);
  console.log(`Successfully created ${partitions.length} query partitions.`);

  let row_count = 0;
  const promises = [];
  partitions.forEach(partition => {
    promises.push(
      transaction.execute(partition).then(results => {
        const rows = results[0].map(row => row.toJSON());
        row_count += rows.length;
      })
    );
  });
  Promise.all(promises)
    .then(() => {
      console.log(
        `Successfully received ${row_count} from executed partitions.`
      );
      transaction.close();
    })
    .then(() => {
      database.close();
    });

Examples

transaction.createReadStream('Singers', {
    keys: ['1'],
    columns: ['SingerId', 'name']
  })
  .on('error', function(err) {})
  .on('data', function(row) {
    // row = [
    //   {
    //     name: 'SingerId',
    //     value: '1'
    //   },
    //   {
    //     name: 'Name',
    //     value: 'Eddie Wilson'
    //   }
    // ]
  })
  .on('end', function() {
    // All results retrieved.
  });

Provide an array for `query.keys` to read with a composite key.

const query = {
  keys: [
    [
      'Id1',
      'Name1'
    ],
    [
      'Id2',
      'Name2'
    ]
  ],
  // ...
};

Rows are returned as an array of object arrays. Each object has a `name` and `value` property. To get a serialized object, call `toJSON()`.

transaction.createReadStream('Singers', {
    keys: ['1'],
    columns: ['SingerId', 'name']
  })
  .on('error', function(err) {})
  .on('data', function(row) {
    // row.toJSON() = {
    //   SingerId: '1',
    //   Name: 'Eddie Wilson'
    // }
  })
  .on('end', function() {
    // All results retrieved.
  });

Alternatively, set `query.json` to `true`, and this step will perform automatically.

transaction.createReadStream('Singers', {
    keys: ['1'],
    columns: ['SingerId', 'name'],
    json: true,
  })
  .on('error', function(err) {})
  .on('data', function(row) {
    // row = {
    //   SingerId: '1',
    //   Name: 'Eddie Wilson'
    // }
  })
  .on('end', function() {
    // All results retrieved.
  });

If you anticipate many results, you can end a stream early to prevent unnecessary processing and API requests.

transaction.createReadStream('Singers', {
    keys: ['1'],
    columns: ['SingerId', 'name']
  })
  .on('data', function(row) {
    this.end();
  });

Examples

Calling `end` on a read only snapshot

database.getSnapshot((err, transaction) => {
  if (err) {
    // Error handling omitted.
  }

  transaction.run('SELECT * FROM Singers', (err, rows) => {
    if (err) {
      // Error handling omitted.
    }

    // End the snapshot.
    transaction.end();
  });
});

Calling `end` on a read/write transaction

database.runTransaction((err, transaction) => {
  if (err) {
    // Error handling omitted.
  }

  const query = 'UPDATE Account SET Balance = 1000 WHERE Key = 1';

  transaction.runUpdate(query, err => {
    if (err) {
      // In the event of an error, there would be nothing to rollback,
so
      // instead of continuing, discard the
transaction. transaction.end(); return;
    }

    transaction.commit(err => {});
  });
});

Example

  // 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';
  // const identifier = {};
  // const partition = {};

  // 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);
  const transaction = database.batchTransaction(identifier);

  const [rows] = await transaction.execute(partition);
  console.log(`Successfully received ${rows.length} from executed partition.`);

Example

const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');

database.createBatchTransaction(function(err, transaction) {
  if (err) {
    // Error handling omitted.
  }

  transaction.createReadPartitions(options, function(err, partitions) {
    const partition = partitions[0];

    transaction
      .executeStream(partition)
      .on('error', function(err) {})
      .on('data', function(row) {
        // row = [
        //   {
        //     name: 'SingerId',
        //     value: '1'
        //   },
        //   {
        //     name: 'Name',
        //     value: 'Eddie Wilson'
        //   }
        // ]
      })
      .on('end', function() {
        // All results retrieved
      });
  });
});

Example

const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');

database.createBatchTransaction(function(err, transaction) {
  const identifier = transaction.identifier();
});

Examples

const query = {
  keys: ['1'],
  columns: ['SingerId', 'name']
};

transaction.read('Singers', query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }

  const firstRow = rows[0];

  // firstRow = [
  //   {
  //     name: 'SingerId',
  //     value: '1'
  //   },
  //   {
  //     name: 'Name',
  //     value: 'Eddie Wilson'
  //   }
  // ]
});

Provide an array for `query.keys` to read with a composite key.

const query = {
  keys: [
    [
      'Id1',
      'Name1'
    ],
    [
      'Id2',
      'Name2'
    ]
  ],
  // ...
};

Rows are returned as an array of object arrays. Each object has a `name` and `value` property. To get a serialized object, call `toJSON()`.

transaction.read('Singers', query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }

  const firstRow = rows[0];

  // firstRow.toJSON() = {
  //   SingerId: '1',
  //   Name: 'Eddie Wilson'
  // }
});

Alternatively, set `query.json` to `true`, and this step will perform automatically.

query.json = true;

transaction.read('Singers', query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }

  const firstRow = rows[0];

  // firstRow = {
  //   SingerId: '1',
  //   Name: 'Eddie Wilson'
  // }
});

Examples

transaction.run(query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }

  // rows = [
  //   {
  //     SingerId: '1',
  //     Name: 'Eddie Wilson'
  //   }
  // ]
});

The SQL query string can contain parameter placeholders. A parameter placeholder consists of '@' followed by the parameter name.

const query = {
  sql: 'SELECT * FROM Singers WHERE name = @name',
  params: {
    name: 'Eddie Wilson'
  }
};

transaction.run(query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }
});

If you need to enforce a specific param type, a types map can be provided. This is typically useful if your param value can be null.

const query = {
  sql: 'SELECT * FROM Singers WHERE name = @name AND id = @id',
  params: {
    id: spanner.int(8),
    name: null
  },
  types: {
    id: 'int64',
    name: 'string'
  }
};

transaction.run(query, function(err, rows) {
  if (err) {
    // Error handling omitted.
  }
});

Examples

const query = 'SELECT * FROM Singers';

transaction.runStream(query)
  .on('error', function(err) {})
  .on('data', function(row) {
    // row = {
    //   SingerId: '1',
    //   Name: 'Eddie Wilson'
    // }
  })
  .on('end', function() {
    // All results retrieved.
  });

The SQL query string can contain parameter placeholders. A parameter placeholder consists of '@' followed by the parameter name.

const query = {
  sql: 'SELECT * FROM Singers WHERE name = @name',
  params: {
    name: 'Eddie Wilson'
  }
};

transaction.runStream(query)
  .on('error', function(err) {})
  .on('data', function(row) {})
  .on('end', function() {});

If you anticipate many results, you can end a stream early to prevent unnecessary processing and API requests.

transaction.runStream(query)
  .on('data', function(row) {
    this.end();
  });