Class Query (8.4.0)

Build a Query object.

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

Package

@google-cloud/datastore

Example


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

Constructors

(constructor)(scope, kinds)

constructor(scope?: Datastore | Transaction, kinds?: string[] | null);

Constructs a new instance of the Query class

Parameters
NameDescription
scope Datastore | Transaction
kinds string[] | null

(constructor)(scope, namespace, kinds)

constructor(scope?: Datastore | Transaction, namespace?: string | null, kinds?: string[]);

Constructs a new instance of the Query class

Parameters
NameDescription
scope Datastore | Transaction
namespace string | null
kinds string[]

Properties

endVal

endVal: string | Buffer | null;

entityFilters

entityFilters: EntityFilter[];

filters

filters: Filter[];

groupByVal

groupByVal: Array<{}>;

kinds

kinds: string[];

limitVal

limitVal: number;

namespace

namespace?: string | null;

offsetVal

offsetVal: number;

orders

orders: Order[];

scope

scope?: Datastore | Transaction;

selectVal

selectVal: Array<{}>;

startVal

startVal: string | Buffer | null;

Methods

end(end)

end(end: string | Buffer): this;

Set an ending cursor to a query.

Parameter
NameDescription
end string | "\"buffer\"".__global.Buffer
Returns
TypeDescription
this

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

filter(filter: EntityFilter): Query;

Datastore allows querying on properties. Supported comparison operators are =, <, >, <=, >=, !=, HAS_ANCESTOR, IN and NOT_IN.

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

Parameter
NameDescription
filter EntityFilter
Returns
TypeDescription
Query

{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);="">

filter(property, value)

filter<T extends string>(property: T, value: AllowedFilterValueType<T>): Query;
Parameters
NameDescription
property T
value AllowedFilterValueType<T>
Returns
TypeDescription
Query
Type Parameter
NameDescription
T

filter(property, operator, value)

filter<T extends string>(property: T, operator: Operator, value: AllowedFilterValueType<T>): Query;
Parameters
NameDescription
property T
operator Operator
value AllowedFilterValueType<T>
Returns
TypeDescription
Query
Type Parameter
NameDescription
T

groupBy(fieldNames)

groupBy(fieldNames: string | string[]): this;

Group query results by a list of properties.

Parameter
NameDescription
fieldNames string | string[]
Returns
TypeDescription
this

{Query}

Example 

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

hasAncestor(key)

hasAncestor(key: Key): this;

Filter a query by ancestors.

Parameter
NameDescription
key Key

Key object to filter by.

Returns
TypeDescription
this

{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(n)

limit(n: number): this;

Set a limit on a query.

Parameter
NameDescription
n number

The number of results to limit the query to.

Returns
TypeDescription
this

{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(n)

offset(n: number): this;

Set an offset on a query.

Parameter
NameDescription
n number

The offset to start from after the start cursor.

Returns
TypeDescription
this

{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(property, options)

order(property: string, options?: OrderOptions): this;

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

Parameters
NameDescription
property string

The property to order by.

options OrderOptions

Options object.

Returns
TypeDescription
this

{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(options)

run(options?: RunQueryOptions): Promise<RunQueryResponse>;

Run the query.

Parameter
NameDescription
options RunQueryOptions

Optional configuration.

Returns
TypeDescription
Promise<RunQueryResponse>
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];
});

run(options, callback)

run(options: RunQueryOptions, callback: RunQueryCallback): void;
Parameters
NameDescription
options RunQueryOptions
callback RunQueryCallback
Returns
TypeDescription
void

run(callback)

run(callback: RunQueryCallback): void;
Parameter
NameDescription
callback RunQueryCallback
Returns
TypeDescription
void

runStream(options)

runStream(options?: RunQueryStreamOptions): import("stream").Transform;

Run the query as a readable object stream.

Query#runStream

Parameter
NameDescription
options RunQueryStreamOptions

Optional configuration. See for a complete list of options.

Returns
TypeDescription
import("stream")."\"stream\"".internal.Transform

{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(fieldNames)

select(fieldNames: string | string[]): this;

Retrieve only select properties from the matched entities.

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

Parameter
NameDescription
fieldNames string | string[]

Properties to return from the matched entities.

Returns
TypeDescription
this

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

start(start: string | Buffer): this;

Set a starting cursor to a query.

Parameter
NameDescription
start string | "\"buffer\"".__global.Buffer
Returns
TypeDescription
this

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