Class Transaction (8.7.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
Name	Description
`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
Name	Description
`gaxOptions`	`CallOptions` Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.

Returns
Type	Description
`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
Name	Description
`callback`	`CommitCallback`

Returns
Type	Description
`void`

commit(gaxOptions, callback)

commit(gaxOptions: CallOptions, callback: CommitCallback): void;

Parameters
Name	Description
`gaxOptions`	`CallOptions`
`callback`	`CommitCallback`

Returns
Type	Description
`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
Name	Description
`query`	`Query`

Returns
Type	Description
`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
Name	Description
`kind`	`string` The kind to query.

Returns
Type	Description
`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
Name	Description
`kind`	`string[]`

Returns
Type	Description
`Query`

createQuery(namespace, kind)

createQuery(namespace: string, kind: string): Query;

Parameters
Name	Description
`namespace`	`string`
`kind`	`string`

Returns
Type	Description
`Query`

createQuery(namespace, kind)

createQuery(namespace: string, kind: string[]): Query;

Parameters
Name	Description
`namespace`	`string`
`kind`	`string[]`

Returns
Type	Description
`Query`

delete(entities)

delete(entities?: Entities): any;

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

Parameter
Name	Description
`entities`	`Entities`

Returns
Type	Description
`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.
    }
  });
});

get(keys, options)

get(keys: entity.Key | entity.Key[], options?: CreateReadStreamOptions): Promise<GetResponse>;

This function calls get on the super class. If the transaction has not been started yet then the transaction is started before the get call is made.

Parameters
Name	Description
`keys`	`entity.Key \| entity.Key[]` Datastore key object(s).
`options`	`CreateReadStreamOptions` Optional configuration.

Returns
Type	Description
`Promise<GetResponse>`

get(keys, callback)

get(keys: entity.Key | entity.Key[], callback: GetCallback): void;

Parameters
Name	Description
`keys`	`entity.Key \| entity.Key[]`
`callback`	`GetCallback`

Returns
Type	Description
`void`

get(keys, options, callback)

get(keys: entity.Key | entity.Key[], options: CreateReadStreamOptions, callback: GetCallback): void;

Parameters
Name	Description
`keys`	`entity.Key \| entity.Key[]`
`options`	`CreateReadStreamOptions`
`callback`	`GetCallback`

Returns
Type	Description
`void`

insert(entities)

insert(entities: Entities): void;

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

Parameter
Name	Description
`entities`	`Entities` Datastore key object(s).

Returns
Type	Description
`void`

rollback(callback)

rollback(callback: RollbackCallback): void;

Reverse a transaction remotely and finalize the current transaction instance.

Parameter
Name	Description
`callback`	`RollbackCallback` The callback function.

Returns
Type	Description
`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
Name	Description
`gaxOptions`	`CallOptions`

Returns
Type	Description
`Promise<RollbackResponse>`

rollback(gaxOptions, callback)

rollback(gaxOptions: CallOptions, callback: RollbackCallback): void;

Parameters
Name	Description
`gaxOptions`	`CallOptions`
`callback`	`RollbackCallback`

Returns
Type	Description
`void`

run(options)

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

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

Parameter
Name	Description
`options`	`RunOptions` Configuration object.

Returns
Type	Description
`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
Name	Description
`callback`	`RunCallback`

Returns
Type	Description
`void`

run(options, callback)

run(options: RunOptions, callback: RunCallback): void;

Parameters
Name	Description
`options`	`RunOptions`
`callback`	`RunCallback`

Returns
Type	Description
`void`

runAggregationQuery(query, options)

runAggregationQuery(query: AggregateQuery, options?: RunQueryOptions): Promise<RunQueryResponse>;

This function calls runAggregationQuery on the super class. If the transaction has not been started yet then the transaction is started before the runAggregationQuery call is made.

Parameters
Name	Description
`query`	`AggregateQuery` AggregateQuery object.
`options`	`RunQueryOptions` Optional configuration

Returns
Type	Description
`Promise<RunQueryResponse>`

runAggregationQuery(query, options, callback)

runAggregationQuery(query: AggregateQuery, options: RunQueryOptions, callback: RequestCallback): void;

Parameters
Name	Description
`query`	`AggregateQuery`
`options`	`RunQueryOptions`
`callback`	`RequestCallback`

Returns
Type	Description
`void`

runAggregationQuery(query, callback)

runAggregationQuery(query: AggregateQuery, callback: RequestCallback): void;

Parameters
Name	Description
`query`	`AggregateQuery`
`callback`	`RequestCallback`

Returns
Type	Description
`void`

runQuery(query, options)

runQuery(query: Query, options?: RunQueryOptions): Promise<RunQueryResponse>;

This function calls runQuery on the super class. If the transaction has not been started yet then the transaction is started before the runQuery call is made.

Parameters
Name	Description
`query`	`Query` Query object.
`options`	`RunQueryOptions` Optional configuration.

Returns
Type	Description
`Promise<RunQueryResponse>`

runQuery(query, options, callback)

runQuery(query: Query, options: RunQueryOptions, callback: RunQueryCallback): void;

Parameters
Name	Description
`query`	`Query`
`options`	`RunQueryOptions`
`callback`	`RunQueryCallback`

Returns
Type	Description
`void`

runQuery(query, callback)

runQuery(query: Query, callback: RunQueryCallback): void;

Parameters
Name	Description
`query`	`Query`
`callback`	`RunQueryCallback`

Returns
Type	Description
`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
Name	Description
`entities`	`Entities` Datastore key object(s).

Returns
Type	Description
`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
Name	Description
`entities`	`Entities` Datastore key object(s).

Returns
Type	Description
`void`

upsert(entities)

upsert(entities: Entities): void;

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

Parameter
Name	Description
`entities`	`Entities` Datastore key object(s).

Returns
Type	Description
`void`