Constructor

Query

new Query(scope, namespace, kinds)

Parameter

scope

(Datastore or Transaction)

The parent scope the query was created from.

namespace

Optional

string

Namespace to query entities from.

kinds

Array of 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);

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.

Values in options have the following properties:

Parameter

descending

Optional

boolean

Sort the results by a property name in descending order.

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

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.
    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.
//-
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);