Query

Query

Build a Query object.

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

Constructor

new Query(scope, namespaceopt, kinds)

Parameters:
Name Type Attributes Description
scope Datastore | Transaction

The parent scope the query was created from.
namespace string <optional>

Namespace to query entities from.
kinds Array.<string>

Kind to query.
See:
Example
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const query = datastore.createQuery('AnimalNamespace', 'Lion');

Members

(nullable) endVal :number

filters :array

groupByVal :array

kinds :string

limitVal :number

(nullable) namespace :string

offsetVal :number

orders :array

scope :Datastore|Transaction

selectVal :array

(nullable) startVal :number

Methods

end(cursorToken) → {Query}

Set an ending cursor to a query.

Parameters:
Name Type Description
cursorToken string

The ending cursor token.
See:
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(property, operatoropt, value) → {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}.

Parameters:
Name Type Attributes Default Description
property string

The field name.
operator string <optional>
 "="

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

Value to compare property to.
See:
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(properties) → {Query}

Group query results by a list of properties.

Parameters:
Name Type Description
properties array

Properties to group by.
Example
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const companyQuery = datastore.createQuery('Company');
const groupedQuery = companyQuery.groupBy(['name', 'size']);

hasAncestor(key) → {Query}

Filter a query by ancestors.

Parameters:
Name Type Description
key Key

Key object to filter by.
See:
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(n) → {Query}

Set a limit on a query.

Parameters:
Name Type Description
n number

The number of results to limit the query to.
See:
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(n) → {Query}

Set an offset on a query.

Parameters:
Name Type Description
n number

The offset to start from after the start cursor.
See:
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(property, optionsopt) → {Query}

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

Parameters:
Name Type Attributes Description
property string

The property to order by.
options object <optional>

Options object.

Properties
Name Type Attributes Default Description
descending boolean <optional>
 false

Sort the results by a property name in descending order.
See:
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(optionsopt, callbackopt)

Run the query.

Parameters:
Name Type Attributes Description
options object <optional>

Optional configuration.

Properties
Name Type Attributes Default Description
consistency string <optional>

Specify either strong or eventual. If not specified, default values are chosen by Datastore for the operation. Learn more about strong and eventual consistency here.
gaxOptions object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
wrapNumbers boolean | IntegerTypeCastOptions <optional>
 false

Wrap values of integerValue type in Datastore#Int objects. If a boolean, this will wrap values in Datastore#Int objects. If an object, this will return a value returned by wrapNumbers.integerTypeCastFunction. Please see IntegerTypeCastOptions for options descriptions.
callback function <optional>

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

Properties
Name Type Attributes Description
err error <nullable>

An error returned while making this request
entities Array.<object>

A list of entities.
info object

An object useful for pagination.

Properties
Name Type Attributes Description
endCursor string <nullable>

Use this in a follow-up query to begin from where these results ended.
moreResults string

Datastore responds with one of:

- Datastore#MORE_RESULTS_AFTER_LIMIT: There *may* be more
  results after the specified limit.
- Datastore#MORE_RESULTS_AFTER_CURSOR: There *may* be more
  results after the specified end cursor.
- Datastore#NO_MORE_RESULTS: There are no more results.
Example
const {Datastore} = require('@google-cloud/datastore');
const datastore = new Datastore();
const query = datastore.createQuery('Company');

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

  // Access the Key object for an entity.
  const 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((err, entities) => {
  const keys = entities.map((entity) => {
    return entity[datastore.KEY];
  });
});

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

runStream(optionsopt) → {stream}

Run the query as a readable object stream.

Parameters:
Name Type Attributes Description
options object <optional>

Optional configuration. See Query#run for a complete list of options.
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(fieldNames) → {Query}

Retrieve only select properties from the matched entities.

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

Parameters:
Name Type Description
fieldNames string | Array.<string>

Properties to return from the matched entities.
See:
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(cursorToken) → {Query}

Set a starting cursor to a query.

Parameters:
Name Type Description
cursorToken string

The starting cursor token.
See:
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);