class

Transaction

A transaction is a set of Datastore operations on one or more entities. Each transaction is guaranteed to be atomic, which means that transactions are never partially applied. Either all of the operations in the transaction are applied, or none of them are applied.

Mixes in: module:datastore/request

Properties

datastore

namespace

projectId

Methods

commit([gaxOptions], callback)
createQuery([namespace], kind)

delete(key)
rollback([gaxOptions], callback)

run([options], callback)
save(entities)

new Transaction(datastore)

Example

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();

Parameter

Name	Type	Optional	Description
datastore			A Datastore instance.

Extends: Request
Mixes in: module:datastore/request
See also: Transactions Reference

Properties

datastore Datastore

namespace string

projectId string

Methods

commit([gaxOptions], callback)

Commit the remote transaction and finalize the current transaction instance.

If the commit request fails, we will automatically rollback the transaction.

Example

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();

transaction.commit((err, apiResponse) => {
  if (err) {
    // Transaction could not be committed.
  }
});

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

Parameters

Name Type Optional Description

gaxOptions

object

Yes

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.

callback

function()

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request. If the commit fails, we automatically try to rollback the transaction (see {module:datastore/transaction#rollback}).

Value can be null.

apiResponse

object

The full API response.

createQuery([namespace], kind) → Query

Create a query for the specified kind. See {module:datastore/query} for all of the available methods.

Example

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();

// Run the query inside the transaction.
transaction.run((err) => {
  if (err) {
    // Error handling omitted.
  }

  const query = transaction.createQuery('Company');

  query.run((err, entities) => {
    if (err) {
      // Error handling omitted.
    }

    transaction.commit((err) => {
      if (!err) {
        // Transaction committed successfully.
      }
    });
  });
});

Parameters

Name	Type	Optional	Description
namespace	string	Yes	Namespace.
kind	string		The kind to query.

See also: Datastore Queries; Query
Returns: Query

delete(key)

Delete all entities identified with the specified key(s) in the current transaction.

Example

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();

transaction.run((err) => {
  if (err) {
    // Error handling omitted.
  }

  // Delete a single entity.
  transaction.delete(datastore.key(['Company', 123]));

  // Delete multiple entities at once.
  transaction.delete([
    datastore.key(['Company', 123]),
    datastore.key(['Product', 'Computer'])
  ]);

  transaction.commit((err) => {
    if (!err) {
      // Transaction committed successfully.
    }
  });
});

Parameter

Name	Type	Optional	Description
key	(Key or Array of Key)		Datastore key object(s).

rollback([gaxOptions], callback)

Reverse a transaction remotely and finalize the current transaction instance.

Example

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();

transaction.run((err) => {
  if (err) {
    // Error handling omitted.
  }

  transaction.rollback((err) => {
    if (!err) {
      // Transaction rolled back successfully.
    }
  });
});

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

Parameters

Name Type Optional Description

gaxOptions

object

Yes

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.

callback

function()

The callback function.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

apiResponse

object

The full API response.

run([options], callback)

Begin a remote transaction. In the callback provided, run your transactional commands.

Example

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();

transaction.run((err, transaction) => {
  // Perform Datastore transactional operations.
  const key = datastore.key(['Company', 123]);

  transaction.get(key, (err, entity) => {
    entity.name = 'Google';

    transaction.save({
      key: key,
      data: entity
    });

    transaction.commit((err) => {
      if (!err) {
        // Data saved successfully.
      }
    });
  });
});

//-
// If the callback is omitted, we'll return a Promise.
//-
transaction.run().then((data) => {
  const transaction = data[0];
  const apiResponse = data[1];
});

Parameters

Name Type Optional Description

options

object

Yes

Configuration object.

Values in options have the following properties:

Name Type Optional Description

gaxOptions

object

Yes

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.

readOnly

boolean

Yes

A read-only transaction cannot modify entities.

Defaults to false.

transactionId

string

Yes

The ID of a previous transaction.

callback

function()

The function to execute within the context of a transaction.

Values in callback have the following properties:

Name

Type

Optional

Description

err

error

An error returned while making this request.

Value can be null.

transaction

Transaction

This transaction instance.

apiResponse

object

The full API response.

save(entities)

Insert or update the specified object(s) in the current transaction. If a key is incomplete, its associated object is inserted and the original Key object is updated to contain the generated ID.

This method will determine the correct Datastore method to execute (upsert, insert, or update) by using the key(s) provided. For example, if you provide an incomplete key (one without an ID), the request will create a new entity and have its ID automatically assigned. If you provide a complete key, the entity will be updated with the data specified.

By default, all properties are indexed. To prevent a property from being included in all indexes, you must supply an excludeFromIndexes array. See below for an example.

Examples

Save a single entity.

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();

// Notice that we are providing an incomplete key. After the transaction is
// committed, the Key object held by the `key` variable will be populated
// with a path containing its generated ID.
//-
const key = datastore.key('Company');

transaction.run((err) => {
  if (err) {
    // Error handling omitted.
  }

  transaction.save({
    key: key,
    data: {
      rating: '10'
    }
  });

  transaction.commit((err) => {
    if (!err) {
      // Data saved successfully.
    }
  });
});

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();

// Use an array, `excludeFromIndexes`, to exclude properties from indexing.
// This will allow storing string values larger than 1500 bytes.

transaction.run((err) => {
  if (err) {
    // Error handling omitted.
  }

  transaction.save({
    key: key,
    excludeFromIndexes: [
      'description',
      'embeddedEntity.description',
      'arrayValue[].description'
    ],
    data: {
      description: 'Long string (...)',
      embeddedEntity: {
        description: 'Long string (...)'
      },
      arrayValue: [
        {
          description: 'Long string (...)'
        }
      ]
    }
  });

  transaction.commit((err) => {
    if (!err) {
      // Data saved successfully.
    }
  });
});

Save multiple entities at once.

const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();
const companyKey = datastore.key(['Company', 123]);
const productKey = datastore.key(['Product', 'Computer']);

transaction.run((err) => {
  if (err) {
    // Error handling omitted.
  }

  transaction.save([
    {
      key: companyKey,
      data: {
        HQ: 'Dallas, TX'
      }
    },
    {
      key: productKey,
      data: {
        vendor: 'Dell'
      }
    }
  ]);

  transaction.commit((err) => {
    if (!err) {
      // Data saved successfully.
    }
  });
});

Parameters

Name Type Optional Description

entities

(object or Array of object)

Datastore key object(s).

Values in entities have the following properties:

Name	Type	Optional	Description
key	Key		Datastore key object.
excludeFromIndexes	Array of string	Yes	Exclude properties from indexing using a simple JSON path notation. See the example below to see how to target properties at different levels of nesting within your entity.
data	object		Data to save with the provided key.