Transaction

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.

Constructor

new Transaction(datastore)

Parameters:
Name Type Description
datastore Datastore

A Datastore instance.
Mixes In:
  • module:datastore/request
See:
Example
```
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const transaction = datastore.transaction();
```

Extends

Members

datastore

namespace

Methods

createAggregationQuery(query)

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

Parameters:
Name Type Description
query Query

A Query object

createReadStream(keys, optionsopt)

Retrieve the entities as a readable object stream.

Parameters:
Name Type Attributes Description
keys Key | Array.<Key>

Datastore key object(s).
options object <optional>

Optional configuration. See Datastore#get for a complete list of options.
Overrides:
Throws:

  • If at least one Key object is not provided.

    Type
    Error

  • If read time and read consistency cannot both be specified.

    Type
    Error
Example
```
const keys = [
  datastore.key(['Company', 123]),
  datastore.key(['Product', 'Computer'])
];

datastore.createReadStream(keys)
  .on('error', (err) =>  {})
  .on('data', (entity) => {
    // entity is an entity object.
  })
  .on('end', () => {
    // All entities retrieved.
  });
```

delete(key)

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

Parameters:
Name Type Description
key Key | Array.<Key>

Datastore key object(s).
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.
    }
  });
});
```

getQueryOptions(queryopt, optionsopt)

Gets request options from a RunQueryStream options configuration

Parameters:
Name Type Attributes Description
query Query <optional>

A Query object
options RunQueryStreamOptions <optional>

The RunQueryStream options configuration
Overrides:

getRequestOptions(optionsopt)

Gets request options from a RunQueryStream options configuration

Parameters:
Name Type Attributes Description
options RunQueryStreamOptions <optional>

The RunQueryStream options configuration
Overrides:

insert(entities)

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

Parameters:
Name Type Description
entities object | Array.<object>

Datastore key object(s).

Properties
Name Type Attributes Description
key Key

Datastore key object.
excludeFromIndexes Array.<string> <optional>

Exclude properties from indexing using a simple JSON path notation. See the examples in Datastore#save to see how to target properties at different levels of nesting within your entity.
data object

Data to save with the provided key.

parseTransactionResponse(responseopt)

This function saves results from a successful beginTransaction call.

Parameters:
Name Type Attributes Description
response object <optional>

The response from a call to begin a transaction that completed successfully.
Overrides:

requestStream_(config)

Make a request as a stream.

Parameters:
Name Type Description
config object

Configuration object.

Properties
Name Type Description
gaxOpts object

GAX options.
client string

The name of the gax client.
method string

The gax method to call.
reqOpts object

Request options.
Overrides:

runQueryStream(query, optionsopt)

Get a list of entities as a readable object stream.

See Datastore#runQuery for a list of all available options.

Parameters:
Name Type Attributes Description
query Query

A Query object
options object <optional>

Optional configuration.

Properties
Name Type Attributes Description
gaxOptions object <optional>

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

If read time and read consistency cannot both be specified.

Type
Error
Example
```
datastore.runQueryStream(query)
  .on('error', console.error)
  .on('data', (entity) => {
    // Access the Key object for this entity.
    const key = entity[datastore.KEY];
  })
  .on('info', (info) => {})
  .on('end', () => {
    // All entities retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
datastore.runQueryStream(query)
  .on('data', (entity) => {
    this.end();
  });
```

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.

Parameters:
Name Type Description
entities object | Array.<object>

Datastore key object(s).

Properties
Name Type Attributes Description
key Key

Datastore key object.
excludeFromIndexes Array.<string> <optional>

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.
Examples
```
<caption>Save a single entity.</caption>
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.
    }
  });
});

```
```
<caption>Save multiple entities at once.</caption>
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)

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

Parameters:
Name Type Description
entities object | Array.<object>

Datastore key object(s).

Properties
Name Type Attributes Description
key Key

Datastore key object.
excludeFromIndexes Array.<string> <optional>

Exclude properties from indexing using a simple JSON path notation. See the examples in Datastore#save to see how to target properties at different levels of nesting within your entity.
data object

Data to save with the provided key.

upsert(entities)

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

Parameters:
Name Type Description
entities object | Array.<object>

Datastore key object(s).

Properties
Name Type Attributes Description
key Key

Datastore key object.
excludeFromIndexes Array.<string> <optional>

Exclude properties from indexing using a simple JSON path notation. See the examples in Datastore#save to see how to target properties at different levels of nesting within your entity.
data object

Data to save with the provided key.