Query - Documentation

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.

Source:

query.js, line 39

See:

Datastore Queries

Example

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

Members

(nullable) endVal :number

Source:

query.js, line 86

filters :array

Source:

query.js, line 60

groupByVal :array

Source:

query.js, line 70

kinds :string

Source:

query.js, line 55

limitVal :number

Source:

query.js, line 91

(nullable) namespace :string

Source:

query.js, line 50

offsetVal :number

Source:

query.js, line 96

orders :array

Source:

query.js, line 65

scope :Datastore|Transaction

Source:

query.js, line 45

selectVal :array

Source:

query.js, line 75

(nullable) startVal :number

Source:

query.js, line 81

Methods

end(cursorToken) → {Query}

Set an ending cursor to a query.

Parameters:

Name	Type	Description
`cursorToken`	string	The ending cursor token.

Source:

query.js, line 283

See:

Query Cursors

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.

Source:

query.js, line 140

See:

Datastore Filters

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.

Source:

query.js, line 213

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.

Source:

query.js, line 167

See:

Datastore Ancestor Filters

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.

Source:

query.js, line 303

See:

Query Limits

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.

Source:

query.js, line 323

See:

Query Offsets

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

Options object.

Properties

Name	Type	Attributes	Default	Description
`descending`	boolean	<optional>	false	Sort the results by a property name in descending order.

Source:

query.js, line 196

See:

Datastore Sort Orders

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

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

Properties

Name Type Attributes Description

err

error

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

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.

Source:

query.js, line 390

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.

Source:

query.js, line 397

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.

Source:

query.js, line 239

See:

Projection Queries

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.

Source:

query.js, line 261

See:

Query Cursors

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