Class DatastoreRequest (8.6.0)

Version 8.6.0

• 9.1.0 (latest)
• 8.7.0
• 8.6.0
• 8.5.0
• 8.4.0
• 8.3.0
• 8.2.2
• 8.1.0
• 8.0.0
• 6.6.2
• 6.5.0
• 6.4.8
• 6.3.1

Handle logic for Datastore API operations. Handles request logic for Datastore.

Creates requests to the Datastore endpoint. Designed to be inherited by the Datastore and Transaction classes.

Package

@google-cloud/datastore

Properties

datastore

datastore: Datastore;

id

id: string | undefined | Uint8Array | null;

requestCallbacks_

requestCallbacks_: Array<(err: Error | null, resp: Entity | null) => void> | Entity;

requests_

requests_: Entity | {
        mutations: Array<{}>;
    };

Methods

allocateIds(key, options)

allocateIds(key: entity.Key, options: AllocateIdsOptions | number): Promise<AllocateIdsResponse>;

Generate IDs without creating entities.

Parameters
Name	Description
key	Key The key object to complete.
options	AllocateIdsOptions | number Either the number of IDs to allocate or an options object for further customization of the request.

Returns
Type	Description
Promise<AllocateIdsResponse>

Example

const incompleteKey = datastore.key(['Company']);

//-
// The following call will create 100 new IDs from the Company kind, which
// exists under the default namespace.
//-
datastore.allocateIds(incompleteKey, 100, (err, keys) => {});

//-
// Or, if you're using a transaction object.
//-
const transaction = datastore.transaction();

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

  transaction.allocateIds(incompleteKey, 100, (err, keys) => {
    if (err) {
      // Error handling omitted.
    }

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

//-
// You may prefer to create IDs from a non-default namespace by providing
an
// incomplete key with a namespace. Similar to the previous example, the
call
// below will create 100 new IDs, but from the Company kind that exists
under
// the "ns-test" namespace.
//-
const incompleteKey = datastore.key({
  namespace: 'ns-test',
  path: ['Company']
});

function callback(err, keys, apiResponse) {}

datastore.allocateIds(incompleteKey, 100, callback);

//-
// Returns a Promise if callback is omitted.
//-
datastore.allocateIds(incompleteKey, 100).then((data) => {
  const keys = data[0];
  const apiResponse = data[1];
});

allocateIds(key, options, callback)

allocateIds(key: entity.Key, options: AllocateIdsOptions | number, callback: AllocateIdsCallback): void;

Parameters
Name	Description
key	Key
options	AllocateIdsOptions | number
callback	AllocateIdsCallback

Returns
Type	Description
void

createReadStream(keys, options)

createReadStream(keys: Entities, options?: CreateReadStreamOptions): Transform;

Retrieve the entities as a readable object stream.

Parameters
Name	Description
keys	Entities Datastore key object(s).
options	CreateReadStreamOptions Optional configuration. See for a complete list of options.

Returns
Type	Description
Transform

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(keys, gaxOptions)

delete(keys: Entities, gaxOptions?: CallOptions): Promise<DeleteResponse>;

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

Parameters
Name	Description
keys	Entities
gaxOptions	CallOptions Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.

Returns
Type	Description
Promise<DeleteResponse>

Example

const key = datastore.key(['Company', 123]);
datastore.delete(key, (err, apiResp) => {});

//-
// Or, if you're using a transaction object.
//-
const transaction = datastore.transaction();

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

  transaction.delete(key);

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

//-
// Delete multiple entities at once.
//-
datastore.delete([
  datastore.key(['Company', 123]),
  datastore.key(['Product', 'Computer'])
], (err, apiResponse) => {});

//-
// Returns a Promise if callback is omitted.
//-
datastore.delete().then((data) => {
  const apiResponse = data[0];
});

delete(keys, callback)

delete(keys: Entities, callback: DeleteCallback): void;

Parameters
Name	Description
keys	Entities
callback	DeleteCallback

Returns
Type	Description
void

delete(keys, gaxOptions, callback)

delete(keys: Entities, gaxOptions: CallOptions, callback: DeleteCallback): void;

Parameters
Name	Description
keys	Entities
gaxOptions	CallOptions
callback	DeleteCallback

Returns
Type	Description
void

get(keys, options)

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

Retrieve the entities identified with the specified key(s) in the current transaction. Get operations require a valid key to retrieve the key-identified entity from Datastore.

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

Returns
Type	Description
Promise<GetResponse>

Example

//-
// Get a single entity.
//-
const key = datastore.key(['Company', 123]);

datastore.get(key, (err, entity) => {});

//-
// Or, if you're using a transaction object.
//-
const transaction = datastore.transaction();

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

  transaction.get(key, (err, entity) => {
    if (err) {
      // Error handling omitted.
    }

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

//-
// Get multiple entities at once with a callback.
//-
const keys = [
  datastore.key(['Company', 123]),
  datastore.key(['Product', 'Computer'])
];

datastore.get(keys, (err, entities) => {});

//-
// Below is how to update the value of an entity with the help of the
// `save` method.
//-
datastore.get(key, (err, entity) => {
  if (err) {
    // Error handling omitted.
  }

  entity.newValue = true;

  datastore.save({
    key: key,
    data: entity
  }, (err) => {});
});

//-
// Returns a Promise if callback is omitted.
//-
datastore.get(keys).then((data) => {
  const entities = data[0];
});

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

merge(entities)

merge(entities: Entities): Promise<CommitResponse>;

Merge the specified object(s). If a key is incomplete, its associated object is inserted and the original Key object is updated to contain the generated ID. 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 get the data from datastore and merge 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.

Maps to , forcing the method to be upsert.

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

Returns
Type	Description
Promise<CommitResponse>

merge(entities, callback)

merge(entities: Entities, callback: SaveCallback): void;

Parameters
Name	Description
entities	Entities
callback	SaveCallback

Returns
Type	Description
void

prepareGaxRequest_(config, callback)

prepareGaxRequest_(config: RequestConfig, callback: Function): void;

Parameters
Name	Description
config	RequestConfig
callback	Function

Returns
Type	Description
void

request_(config, callback)

request_(config: RequestConfig, callback: RequestCallback): void;

Make a request to the API endpoint. Properties to indicate a transactional or non-transactional operation are added automatically.

Parameters
Name	Description
config	RequestConfig Configuration object.
callback	RequestCallback The callback function.

Returns
Type	Description
void

requestStream_(config)

requestStream_(config: RequestConfig): AbortableDuplex;

Make a request as a stream.

Parameter
Name	Description
config	RequestConfig Configuration object.

Returns
Type	Description
AbortableDuplex

runAggregationQuery(query, options)

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

Datastore allows you to run aggregate queries by supplying aggregate fields which will determine the type of aggregation that is performed.

The query is run, and the results are returned in the second argument of the callback provided.

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>;

Datastore allows you to query entities by kind, filter them by property filters, and sort them by a property name. Projection and pagination are also supported.

The query is run, and the results are returned as the second argument to your callback. A third argument may also exist, which is a query object that uses the end cursor from the previous query as the starting cursor for the next query. You can pass that object back to this method to see if more results exist.

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

Returns
Type	Description
Promise<RunQueryResponse>

Example

//-
// Where you see `transaction`, assume this is the context that's relevant
to
// your use, whether that be a Datastore or a Transaction object.
//-
const query = datastore.createQuery('Lion');

datastore.runQuery(query, (err, entities, info) => {
  // entities = An array of records.

  // Access the Key object for an entity.
  const firstEntityKey = entities[0][datastore.KEY];
});

//-
// Or, if you're using a transaction object.
//-
const transaction = datastore.transaction();

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

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

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

//-
// A keys-only query returns just the keys of the result entities instead
of
// the entities themselves, at lower latency and cost.
//-
const keysOnlyQuery = datastore.createQuery('Lion').select('__key__');

datastore.runQuery(keysOnlyQuery, (err, entities) => {
  const keys = entities.map((entity) => {
    return entity[datastore.KEY];
  });
});

//-
// Returns a Promise if callback is omitted.
//-
datastore.runQuery(query).then((data) => {
  const entities = data[0];
});

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

runQueryStream(query, options)

runQueryStream(query: Query, options?: RunQueryStreamOptions): Transform;

Get a list of entities as a readable object stream.

See for a list of all available options.

Parameters
Name	Description
query	Query Query object.
options	RunQueryStreamOptions Optional configuration.

Returns
Type	Description
Transform

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();
  });