Constructor

Query

new Query(scope, namespace, kind)

Build a Query object.

Queries are built with {module:datastore#createQuery} and Transaction#createQuery.

Parameter

scope

(Datastore or Transaction)

The parent scope the query was created from.

namespace

Optional

string

Namespace to query entities from.

kind

string

Kind to query.

See also

Datastore Queries

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const query = datastore.createQuery('AnimalNamespace', 'Lion');

Properties

endVal

nullable number

filters

array

groupByVal

array

kinds

string

limitVal

number

namespace

nullable string

offsetVal

number

orders

array

scope

(Datastore or Transaction)

selectVal

array

startVal

nullable number

Methods

end

end(cursorToken) returns Query

Set an ending cursor to a query.

Parameter

cursorToken

string

The ending cursor token.

See also

Query Cursors

Returns

Query 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const companyQuery = datastore.createQuery('Company');

const cursorToken = 'X';

// Retrieve results limited to the extent of cursorToken.
const endQuery = companyQuery.end(cursorToken);

filter

filter(property, operator, value) returns Query

Datastore allows querying on properties. Supported comparison operators are =, <, >, <=, and >=. "Not equal" and IN operators are currently not supported.

To filter by ancestors, see {module:datastore/query#hasAncestor}.

Parameter

property

string

The field name.

operator

Optional

string

Operator (=, <, >, <=, >=).

value

any type

Value to compare property to.

See also

Datastore Filters

Returns

Query 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const query = datastore.createQuery('Company');

//-
// List all companies that are located in California.
//-
const caliQuery = query.filter('state', 'CA');

//-
// List all companies named Google that have less than 400 employees.
//-
const companyQuery = query
  .filter('name', 'Google')
  .filter('size', '<', 400);

//-
// To filter by key, use `__key__` for the property name. Filter on keys
// stored as properties is not currently supported.
//-
const key = datastore.key(['Company', 'Google']);
const keyQuery = query.filter('__key__', key);

groupBy

groupBy(properties) returns Query

Group query results by a list of properties.

Parameter

properties

array

Properties to group by.

Returns

Query 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const companyQuery = datastore.createQuery('Company');
const groupedQuery = companyQuery.groupBy(['name', 'size']);

hasAncestor

hasAncestor(key) returns Query

Filter a query by ancestors.

Parameter

key

Key

Key object to filter by.

See also

Datastore Ancestor Filters

Returns

Query 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const query = datastore.createQuery('MyKind');
const ancestoryQuery = query.hasAncestor(datastore.key(['Parent', 123]));

limit

limit(n) returns Query

Set a limit on a query.

Parameter

n

number

The number of results to limit the query to.

See also

Query Limits

Returns

Query 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const companyQuery = datastore.createQuery('Company');

// Limit the results to 10 entities.
const limitQuery = companyQuery.limit(10);

offset

offset(n) returns Query

Set an offset on a query.

Parameter

n

number

The offset to start from after the start cursor.

See also

Query Offsets

Returns

Query 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const companyQuery = datastore.createQuery('Company');

// Start from the 101st result.
const offsetQuery = companyQuery.offset(100);

order

order(property, options) returns Query

Sort the results by a property name in ascending or descending order. By default, an ascending sort order will be used.

Parameter

property

string

The property to order by.

options

Optional

object

Options object.

See also

Datastore Sort Orders

Returns

Query 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const companyQuery = datastore.createQuery('Company');

// Sort by size ascendingly.
const companiesAscending = companyQuery.order('size');

// Sort by size descendingly.
const companiesDescending = companyQuery.order('size', {
  descending: true
});

run

run(options, callback)

Run the query.

Parameter

options

Optional

object

Optional configuration.

callback

Optional

function()

The callback function. If omitted, a readable stream instance is returned.

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const query = datastore.createQuery('Company');

query.run(function(err, entities, info) {
  // entities = An array of records.

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

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

query.run(function(err, entities) {
  var keys = entities.map(function(entity) {
    return entity[datastore.KEY];
  });
});

//-
// If the callback is omitted, we'll return a Promise.
//-
query.run().then(function(data) {
  var entities = data[0];
});

runStream

runStream(options) returns stream

Run the query as a readable object stream.

Parameter

options

Optional

object

Optional configuration. See Query#run for a complete list of options.

Returns

stream 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const query = datastore.createQuery('Company');

query.runStream()
  .on('error', console.error)
  .on('data', function (entity) {
    // Access the Key object for this entity.
    var key = entity[datastore.KEY];
  })
  .on('info', function(info) {})
  .on('end', function() {
    // All entities retrieved.
  });

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

select

select(fieldNames) returns Query

Retrieve only select properties from the matched entities.

Queries that select a subset of properties are called Projection Queries.

Parameter

fieldNames

(string or Array of string)

Properties to return from the matched entities.

See also

Projection Queries

Returns

Query 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const companyQuery = datastore.createQuery('Company');

// Only retrieve the name property.
const selectQuery = companyQuery.select('name');

// Only retrieve the name and size properties.
const selectQuery = companyQuery.select(['name', 'size']);

start

start(cursorToken) returns Query

Set a starting cursor to a query.

Parameter

cursorToken

string

The starting cursor token.

See also

Query Cursors

Returns

Query 

Example

const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const companyQuery = datastore.createQuery('Company');

const cursorToken = 'X';

// Retrieve results starting from cursorToken.
const startQuery = companyQuery.start(cursorToken);