@google-cloud/datastore
Version:
Cloud Datastore Client Library for Node.js
389 lines • 11.9 kB
JavaScript
"use strict";
/*!
* Copyright 2014 Google LLC.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.Query = void 0;
const arrify = require("arrify");
const filter_1 = require("./filter");
const gaxInstance = require("google-gax");
/**
* A Query object is used to build and execute queries for entities stored in Datastore.
*
* Create a Query object with {@link Datastore#createQuery} or
* {@link Transaction#createQuery}.
*
* @see {@link http://goo.gl/Cag0r6| Datastore Queries}
*
* @class
* @param {Datastore|Transaction} scope The parent scope the query was created
* from.
* @param {string} [namespace] Namespace to query entities from.
* @param {string[]} kinds Kind to query.
*
* @example
* ```
* const {Datastore} = require('@google-cloud/datastore');
* const datastore = new Datastore();
* const query = datastore.createQuery('AnimalNamespace', 'Lion');
* ```
*/
class Query {
scope;
namespace;
kinds;
filters;
entityFilters;
orders;
groupByVal;
selectVal;
startVal;
endVal;
limitVal;
offsetVal;
constructor(scope, namespaceOrKinds, kinds) {
let namespace = namespaceOrKinds;
if (!kinds) {
kinds = namespaceOrKinds;
namespace = null;
}
/**
* @name Query#scope
* @type {Datastore|Transaction}
*/
this.scope = scope;
/**
* @name Query#namespace
* @type {?string}
*/
this.namespace = namespace || null;
/**
* @name Query#kinds
* @type {string}
*/
this.kinds = kinds;
/**
* @name Query#filters
* @type {array}
*/
this.filters = [];
/**
* @name Query#entityFilters
* @type {array}
*/
this.entityFilters = [];
/**
* @name Query#orders
* @type {array}
*/
this.orders = [];
/**
* @name Query#groupByVal
* @type {array}
*/
this.groupByVal = [];
/**
* @name Query#selectVal
* @type {array}
*/
this.selectVal = [];
// pagination
/**
* @name Query#startVal
* @type {?number}
*/
this.startVal = null;
/**
* @name Query#endVal
* @type {?number}
*/
this.endVal = null;
/**
* @name Query#limitVal
* @type {number}
*/
this.limitVal = -1;
/**
* @name Query#offsetVal
* @type {number}
*/
this.offsetVal = -1;
}
filter(propertyOrFilter, operatorOrValue, value) {
if (arguments.length > 1) {
gaxInstance.warn('filter', 'Providing Filter objects like Composite Filter or Property Filter is recommended when using .filter');
}
switch (arguments.length) {
case 1: {
if ((0, filter_1.isFilter)(propertyOrFilter)) {
this.entityFilters.push(propertyOrFilter);
}
break;
}
case 2: {
this.filters.push({
name: propertyOrFilter.trim(),
op: '=',
val: operatorOrValue,
});
break;
}
case 3: {
this.filters.push({
name: propertyOrFilter.trim(),
op: operatorOrValue.trim(),
val: value,
});
}
}
return this;
}
/**
* Filter a query by ancestors.
*
* @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-ancestor-query-nodejs| Datastore Ancestor Filters}
*
* @param {Key} key Key object to filter by.
* @returns {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]));
* ```
*/
hasAncestor(key) {
this.filters.push({ name: '__key__', op: 'HAS_ANCESTOR', val: key });
return this;
}
/**
* Sort the results by a property name in ascending or descending order. By
* default, an ascending sort order will be used.
*
* @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-ascending-sort-nodejs| Datastore Sort Orders}
*
* @param {string} property The property to order by.
* @param {object} [options] Options object.
* @param {boolean} [options.descending=false] Sort the results by a property
* name in descending order.
* @returns {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
* });
* ```
*/
order(property, options) {
const sign = options && options.descending ? '-' : '+';
this.orders.push({ name: property, sign });
return this;
}
/**
* Group query results by a list of properties.
*
* @param {array} properties Properties to group by.
* @returns {Query}
*
* @example
* ```
* const {Datastore} = require('@google-cloud/datastore');
* const datastore = new Datastore();
* const companyQuery = datastore.createQuery('Company');
* const groupedQuery = companyQuery.groupBy(['name', 'size']);
* ```
*/
groupBy(fieldNames) {
this.groupByVal = arrify(fieldNames);
return this;
}
/**
* Retrieve only select properties from the matched entities.
*
* Queries that select a subset of properties are called Projection Queries.
*
* @see {@link https://cloud.google.com/datastore/docs/samples/datastore-projection-query| Projection Queries}
*
* @param {string|string[]} fieldNames Properties to return from the matched
* entities.
* @returns {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']);
* ```
*/
select(fieldNames) {
this.selectVal = arrify(fieldNames);
return this;
}
/**
* Set a starting cursor to a query.
*
* @see {@link https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets| Query Cursors}
*
* @param {string} cursorToken The starting cursor token.
* @returns {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);
* ```
*/
start(start) {
this.startVal = start;
return this;
}
/**
* Set an ending cursor to a query.
*
* @see {@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Query_cursors| Query Cursors}
*
* @param {string} cursorToken The ending cursor token.
* @returns {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);
* ```
*/
end(end) {
this.endVal = end;
return this;
}
/**
* Set a limit on a query.
*
* @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-limit-nodejs| Query Limits}
*
* @param {number} n The number of results to limit the query to.
* @returns {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);
* ```
*/
limit(n) {
this.limitVal = n;
return this;
}
/**
* Set an offset on a query.
*
* @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-limit-nodejs| Query Offsets}
*
* @param {number} n The offset to start from after the start cursor.
* @returns {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);
* ```
*/
offset(n) {
this.offsetVal = n;
return this;
}
run(optionsOrCallback, cb) {
const options = typeof optionsOrCallback === 'object' ? optionsOrCallback : {};
const callback = typeof optionsOrCallback === 'function' ? optionsOrCallback : cb;
const runQuery = this.scope.runQuery.bind(this.scope);
return runQuery(this, options, callback);
}
/**
* Run the query as a readable object stream.
*
* @method Query#runStream
* @param {object} [options] Optional configuration. See
* {@link Query#run} for a complete list of options.
* @returns {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();
* });
* ```
*/
runStream(options) {
return this.scope.runQueryStream(this, options);
}
}
exports.Query = Query;
//# sourceMappingURL=query.js.map