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

endVal

entityFilters

filters

groupByVal

kinds

limitVal

namespace

offsetVal

orders

scope

selectVal

startVal

Methods

end(cursorToken) → {Query}

Set an ending cursor to a query.

Parameters:
Name Type Description
cursorToken string

The ending cursor token.
Returns:
Type Description
Query
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);
```

groupBy(properties) → {Query}

Group query results by a list of properties.

Parameters:
Name Type Description
properties array

Properties to group by.
Returns:
Type Description
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) → {Query}

Filter a query by ancestors.

Parameters:
Name Type Description
key Key

Key object to filter by.
Returns:
Type Description
Query
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.
Returns:
Type Description
Query
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.
Returns:
Type Description
Query
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.
Returns:
Type Description
Query
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
});
```

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.
Returns:
Type Description
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) → {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.
Returns:
Type Description
Query
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.
Returns:
Type Description
Query
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);
```