@google-cloud/datastore 4.1.0

Properties

endVal
filters
groupByVal
kinds

limitVal
namespace
offsetVal
orders

scope
selectVal
startVal

Methods

end(cursorToken)
filter(property[, operator], value)
groupBy(properties)
hasAncestor(key)

limit(n)
offset(n)
order(property[, options])
run([options][, callback])

runStream([options])
select(fieldNames)
start(cursorToken)

new Query(scope[, namespace], kinds)

Example

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

Parameters

Name	Optional	Description
scope		The parent scope the query was created from.
namespace	Yes	Namespace to query entities from.
kinds		Kind to query.

See also: Datastore Queries

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(cursorToken) → Query

Set an ending cursor to a 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);

Parameter

Name	Type	Optional	Description
cursorToken	string		The ending cursor token.

See also: Query Cursors
Returns: Query

filter(property[, operator], 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}.

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

Parameters

Name Type Optional Description

Name	Type	Optional	Description
property	string		The field name.
operator	string	Yes	Operator (=, <, >, <=, >=). Defaults to `"="`.
value	any type		Value to compare property to.

property

string

The field name.

operator

string

Yes

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

Defaults to "=".

value

any type

Value to compare property to.

See also: Datastore Filters
Returns: Query

groupBy(properties) → Query

Group query results by a list of properties.

Example

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

Parameter

Name	Type	Optional	Description
properties	array		Properties to group by.

Returns: Query

hasAncestor(key) → Query

Filter a query by ancestors.

Example

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

Parameter

Name	Type	Optional	Description
key	Key		Key object to filter by.

See also: Datastore Ancestor Filters
Returns: Query

limit(n) → Query

Set a limit on a 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);

Parameter

Name	Type	Optional	Description
n	number		The number of results to limit the query to.

See also: Query Limits
Returns: Query

offset(n) → Query

Set an offset on a 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);

Parameter

Name	Type	Optional	Description
n	number		The offset to start from after the start cursor.

See also: Query Offsets
Returns: Query

order(property[, options]) → Query

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

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

Parameters

Name Type Optional Description

property

string

The property to order by.

options

object

Yes

Options object.

Values in options have the following properties:

Name Type Optional Description

descending

boolean

Yes

Sort the results by a property name in descending order.

Defaults to false.

See also: Datastore Sort Orders
Returns: Query

run([options][, callback])

Run the query.

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

Parameters

Name Type Optional Description

options

object

Yes

Optional configuration.

Values in options have the following properties:

Name	Type	Optional	Description
consistency	string	Yes	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.

callback

function()

Yes

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

Values in callback have the following properties:

Name	Type	Description
err	error	An error returned while making this request Value can be null.
entities	Array of object	A list of entities.
info	object	An object useful for pagination.
info.endCursor	string	Use this in a follow-up query to begin from where these results ended. Value can be null.
info.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.`

runStream([options]) → stream

Run the query as a readable object 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();
  });

Parameter

Name	Type	Optional	Description
options	object	Yes	Optional configuration. See Query#run for a complete list of options.

Returns: stream

select(fieldNames) → Query

Retrieve only select properties from the matched entities.

Queries that select a subset of properties are called 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']);

Parameter

Name	Type	Optional	Description
fieldNames	(string or Array of string)		Properties to return from the matched entities.

See also: Projection Queries
Returns: Query

start(cursorToken) → Query

Set a starting cursor to a 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);

Parameter

Name	Type	Optional	Description
cursorToken	string		The starting cursor token.

See also: Query Cursors
Returns: Query