Class Transaction (8.3.0)

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.

Inheritance

DatastoreRequest > Transaction

Package

@google-cloud/datastore

Example


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

Constructors

(constructor)(datastore, options)

constructor(datastore: Datastore, options?: TransactionOptions);

Constructs a new instance of the Transaction class

Parameters
NameDescription
datastore Datastore
options TransactionOptions

Properties

modifiedEntities_

modifiedEntities_: ModifiedEntities;

namespace

namespace?: string;

readOnly

readOnly: boolean;

request

request: Function;

skipCommit

skipCommit?: boolean;

Methods

commit(gaxOptions)

commit(gaxOptions?: CallOptions): Promise<CommitResponse>;

Commit the remote transaction and finalize the current transaction instance.

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

Parameter
NameDescription
gaxOptions CallOptions

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

Returns
TypeDescription
Promise<CommitResponse>
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];
});

commit(callback)

commit(callback: CommitCallback): void;
Parameter
NameDescription
callback CommitCallback
Returns
TypeDescription
void

commit(gaxOptions, callback)

commit(gaxOptions: CallOptions, callback: CommitCallback): void;
Parameters
NameDescription
gaxOptions CallOptions
callback CommitCallback
Returns
TypeDescription
void

createAggregationQuery(query)

createAggregationQuery(query: Query): AggregateQuery;

Create an aggregation query from the query specified. See {module:datastore/query} for all of the available methods.

Parameter
NameDescription
query Query
Returns
TypeDescription
AggregateQuery

createQuery(kind)

createQuery(kind?: string): Query;

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

Parameter
NameDescription
kind string

The kind to query.

Returns
TypeDescription
Query

{Query}

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 ancestorKey = datastore.key(['ParentCompany', 'Alphabet']);

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

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

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

// Run the query inside the transaction.with namespace
transaction.run((err) => {
  if (err) {
    // Error handling omitted.
  }
  const ancestorKey = datastore.key(['ParentCompany', 'Alphabet']);

  const query = transaction.createQuery('CompanyNamespace', 'Company')
      .hasAncestor(ancestorKey);

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

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

createQuery(kind)

createQuery(kind?: string[]): Query;
Parameter
NameDescription
kind string[]
Returns
TypeDescription
Query

createQuery(namespace, kind)

createQuery(namespace: string, kind: string): Query;
Parameters
NameDescription
namespace string
kind string
Returns
TypeDescription
Query

createQuery(namespace, kind)

createQuery(namespace: string, kind: string[]): Query;
Parameters
NameDescription
namespace string
kind string[]
Returns
TypeDescription
Query

delete(entities)

delete(entities?: Entities): any;

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

Parameter
NameDescription
entities Entities
Returns
TypeDescription
any
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.
    }
  });
});

insert(entities)

insert(entities: Entities): void;

Maps to Datastore#save, forcing the method to be insert.

Parameter
NameDescription
entities Entities

Datastore key object(s).

Returns
TypeDescription
void

rollback(callback)

rollback(callback: RollbackCallback): void;

Reverse a transaction remotely and finalize the current transaction instance.

Parameter
NameDescription
callback RollbackCallback

The callback function.

Returns
TypeDescription
void
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];
});

rollback(gaxOptions)

rollback(gaxOptions?: CallOptions): Promise<RollbackResponse>;
Parameter
NameDescription
gaxOptions CallOptions
Returns
TypeDescription
Promise<RollbackResponse>

rollback(gaxOptions, callback)

rollback(gaxOptions: CallOptions, callback: RollbackCallback): void;
Parameters
NameDescription
gaxOptions CallOptions
callback RollbackCallback
Returns
TypeDescription
void

run(options)

run(options?: RunOptions): Promise<RunResponse>;

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

Parameter
NameDescription
options RunOptions

Configuration object.

Returns
TypeDescription
Promise<RunResponse>
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];
});

run(callback)

run(callback: RunCallback): void;
Parameter
NameDescription
callback RunCallback
Returns
TypeDescription
void

run(options, callback)

run(options: RunOptions, callback: RunCallback): void;
Parameters
NameDescription
options RunOptions
callback RunCallback
Returns
TypeDescription
void

save(entities)

save(entities: Entities): void;

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.

Parameter
NameDescription
entities Entities

Datastore key object(s).

Returns
TypeDescription
void
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.
    }
  });
});

update(entities)

update(entities: Entities): void;

Maps to Datastore#save, forcing the method to be update.

Parameter
NameDescription
entities Entities

Datastore key object(s).

Returns
TypeDescription
void

upsert(entities)

upsert(entities: Entities): void;

Maps to Datastore#save, forcing the method to be upsert.

Parameter
NameDescription
entities Entities

Datastore key object(s).

Returns
TypeDescription
void