1 | /*!
|
2 | * Copyright 2014 Google LLC.
|
3 | *
|
4 | * Licensed under the Apache License, Version 2.0 (the "License");
|
5 | * you may not use this file except in compliance with the License.
|
6 | * You may obtain a copy of the License at
|
7 | *
|
8 | * http://www.apache.org/licenses/LICENSE-2.0
|
9 | *
|
10 | * Unless required by applicable law or agreed to in writing, software
|
11 | * distributed under the License is distributed on an "AS IS" BASIS,
|
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
13 | * See the License for the specific language governing permissions and
|
14 | * limitations under the License.
|
15 | */
|
16 | /// <reference types="node" />
|
17 | /// <reference types="node" />
|
18 | /// <reference types="node" />
|
19 | import { Key } from 'readline';
|
20 | import { Datastore } from '.';
|
21 | import { Entity } from './entity';
|
22 | import { EntityFilter, AllowedFilterValueType } from './filter';
|
23 | import { Transaction } from './transaction';
|
24 | import { CallOptions } from 'google-gax';
|
25 | import { RunQueryStreamOptions } from '../src/request';
|
26 | export type Operator = '=' | '<' | '>' | '<=' | '>=' | 'HAS_ANCESTOR' | '!=' | 'IN' | 'NOT_IN';
|
27 | export interface OrderOptions {
|
28 | descending?: boolean;
|
29 | }
|
30 | export interface Order {
|
31 | name: string;
|
32 | sign: '-' | '+';
|
33 | }
|
34 | export interface Filter {
|
35 | name: string;
|
36 | val: any;
|
37 | op: Operator;
|
38 | }
|
39 | /**
|
40 | * Build a Query object.
|
41 | *
|
42 | * **Queries are built with {module:datastore#createQuery} and
|
43 | * {@link Transaction#createQuery}.**
|
44 | *
|
45 | * @see {@link http://goo.gl/Cag0r6| Datastore Queries}
|
46 | *
|
47 | * @class
|
48 | * @param {Datastore|Transaction} scope The parent scope the query was created
|
49 | * from.
|
50 | * @param {string} [namespace] Namespace to query entities from.
|
51 | * @param {string[]} kinds Kind to query.
|
52 | *
|
53 | * @example
|
54 | * ```
|
55 | * const {Datastore} = require('@google-cloud/datastore');
|
56 | * const datastore = new Datastore();
|
57 | * const query = datastore.createQuery('AnimalNamespace', 'Lion');
|
58 | * ```
|
59 | */
|
60 | declare class Query {
|
61 | scope?: Datastore | Transaction;
|
62 | namespace?: string | null;
|
63 | kinds: string[];
|
64 | filters: Filter[];
|
65 | entityFilters: EntityFilter[];
|
66 | orders: Order[];
|
67 | groupByVal: Array<{}>;
|
68 | selectVal: Array<{}>;
|
69 | startVal: string | Buffer | null;
|
70 | endVal: string | Buffer | null;
|
71 | limitVal: number;
|
72 | offsetVal: number;
|
73 | constructor(scope?: Datastore | Transaction, kinds?: string[] | null);
|
74 | constructor(scope?: Datastore | Transaction, namespace?: string | null, kinds?: string[]);
|
75 | /**
|
76 | * Datastore allows querying on properties. Supported comparison operators
|
77 | * are `=`, `<`, `>`, `<=`, `>=`, `!=`, `HAS_ANCESTOR`, `IN` and `NOT_IN`.
|
78 | *
|
79 | * *To filter by ancestors, see {module:datastore/query#hasAncestor}.*
|
80 | *
|
81 | * @see {//cloud.google.com/datastore/docs/concepts/queries#datastore-property-filter-nodejs| Datastore Filters}
https: |
82 | *
|
83 | * string | EntityFilter} propertyOrFilter The field name.
{ |
84 | * string} [operator="="] Operator (=, <, >, <=, >=).
{ |
85 | * {*} value Value to compare property to.
|
86 | * {Query}
|
87 | *
|
88 | *
|
89 | * ```
|
90 | * const {Datastore} = require('@google-cloud/datastore');
|
91 | * const datastore = new Datastore();
|
92 | * const query = datastore.createQuery('Company');
|
93 | *
|
94 | * //-
|
95 | * // List all companies that are located in California.
|
96 | * //-
|
97 | * const caliQuery = query.filter('state', 'CA');
|
98 | *
|
99 | * //-
|
100 | * // List all companies named Google that have less than 400 employees.
|
101 | * //-
|
102 | * const companyQuery = query
|
103 | * .filter('name', 'Google')
|
104 | * .filter('size', '<', 400);
|
105 | *
|
106 | * //-
|
107 | * // To filter by key, use `__key__` for the property name. Filter on keys
|
108 | * // stored as properties is not currently supported.
|
109 | * //-
|
110 | * const key = datastore.key(['Company', 'Google']);
|
111 | * const keyQuery = query.filter('__key__', key);
|
112 | * ```
|
113 | */
|
114 | filter(filter: EntityFilter): Query;
|
115 | filter<T extends string>(property: T, value: AllowedFilterValueType<T>): Query;
|
116 | filter<T extends string>(property: T, operator: Operator, value: AllowedFilterValueType<T>): Query;
|
117 | /**
|
118 | * Filter a query by ancestors.
|
119 | *
|
120 | * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-ancestor-query-nodejs| Datastore Ancestor Filters}
|
121 | *
|
122 | * @param {Key} key Key object to filter by.
|
123 | * @returns {Query}
|
124 | *
|
125 | * @example
|
126 | * ```
|
127 | * const {Datastore} = require('@google-cloud/datastore');
|
128 | * const datastore = new Datastore();
|
129 | * const query = datastore.createQuery('MyKind');
|
130 | * const ancestoryQuery = query.hasAncestor(datastore.key(['Parent', 123]));
|
131 | * ```
|
132 | */
|
133 | hasAncestor(key: Key): this;
|
134 | /**
|
135 | * Sort the results by a property name in ascending or descending order. By
|
136 | * default, an ascending sort order will be used.
|
137 | *
|
138 | * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-ascending-sort-nodejs| Datastore Sort Orders}
|
139 | *
|
140 | * @param {string} property The property to order by.
|
141 | * @param {object} [options] Options object.
|
142 | * @param {boolean} [options.descending=false] Sort the results by a property
|
143 | * name in descending order.
|
144 | * @returns {Query}
|
145 | *
|
146 | * @example
|
147 | * ```
|
148 | * const {Datastore} = require('@google-cloud/datastore');
|
149 | * const datastore = new Datastore();
|
150 | * const companyQuery = datastore.createQuery('Company');
|
151 | *
|
152 | * // Sort by size ascendingly.
|
153 | * const companiesAscending = companyQuery.order('size');
|
154 | *
|
155 | * // Sort by size descendingly.
|
156 | * const companiesDescending = companyQuery.order('size', {
|
157 | * descending: true
|
158 | * });
|
159 | * ```
|
160 | */
|
161 | order(property: string, options?: OrderOptions): this;
|
162 | /**
|
163 | * Group query results by a list of properties.
|
164 | *
|
165 | * @param {array} properties Properties to group by.
|
166 | * @returns {Query}
|
167 | *
|
168 | * @example
|
169 | * ```
|
170 | * const {Datastore} = require('@google-cloud/datastore');
|
171 | * const datastore = new Datastore();
|
172 | * const companyQuery = datastore.createQuery('Company');
|
173 | * const groupedQuery = companyQuery.groupBy(['name', 'size']);
|
174 | * ```
|
175 | */
|
176 | groupBy(fieldNames: string | string[]): this;
|
177 | /**
|
178 | * Retrieve only select properties from the matched entities.
|
179 | *
|
180 | * Queries that select a subset of properties are called Projection Queries.
|
181 | *
|
182 | * @see {@link https://cloud.google.com/datastore/docs/concepts/projectionqueries| Projection Queries}
|
183 | *
|
184 | * @param {string|string[]} fieldNames Properties to return from the matched
|
185 | * entities.
|
186 | * @returns {Query}
|
187 | *
|
188 | * @example
|
189 | * ```
|
190 | * const {Datastore} = require('@google-cloud/datastore');
|
191 | * const datastore = new Datastore();
|
192 | * const companyQuery = datastore.createQuery('Company');
|
193 | *
|
194 | * // Only retrieve the name property.
|
195 | * const selectQuery = companyQuery.select('name');
|
196 | *
|
197 | * // Only retrieve the name and size properties.
|
198 | * const selectQuery = companyQuery.select(['name', 'size']);
|
199 | * ```
|
200 | */
|
201 | select(fieldNames: string | string[]): this;
|
202 | /**
|
203 | * Set a starting cursor to a query.
|
204 | *
|
205 | * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets| Query Cursors}
|
206 | *
|
207 | * @param {string} cursorToken The starting cursor token.
|
208 | * @returns {Query}
|
209 | *
|
210 | * @example
|
211 | * ```
|
212 | * const {Datastore} = require('@google-cloud/datastore');
|
213 | * const datastore = new Datastore();
|
214 | * const companyQuery = datastore.createQuery('Company');
|
215 | *
|
216 | * const cursorToken = 'X';
|
217 | *
|
218 | * // Retrieve results starting from cursorToken.
|
219 | * const startQuery = companyQuery.start(cursorToken);
|
220 | * ```
|
221 | */
|
222 | start(start: string | Buffer): this;
|
223 | /**
|
224 | * Set an ending cursor to a query.
|
225 | *
|
226 | * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#Datastore_Query_cursors| Query Cursors}
|
227 | *
|
228 | * @param {string} cursorToken The ending cursor token.
|
229 | * @returns {Query}
|
230 | *
|
231 | * @example
|
232 | * ```
|
233 | * const {Datastore} = require('@google-cloud/datastore');
|
234 | * const datastore = new Datastore();
|
235 | * const companyQuery = datastore.createQuery('Company');
|
236 | *
|
237 | * const cursorToken = 'X';
|
238 | *
|
239 | * // Retrieve results limited to the extent of cursorToken.
|
240 | * const endQuery = companyQuery.end(cursorToken);
|
241 | * ```
|
242 | */
|
243 | end(end: string | Buffer): this;
|
244 | /**
|
245 | * Set a limit on a query.
|
246 | *
|
247 | * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-limit-nodejs| Query Limits}
|
248 | *
|
249 | * @param {number} n The number of results to limit the query to.
|
250 | * @returns {Query}
|
251 | *
|
252 | * @example
|
253 | * ```
|
254 | * const {Datastore} = require('@google-cloud/datastore');
|
255 | * const datastore = new Datastore();
|
256 | * const companyQuery = datastore.createQuery('Company');
|
257 | *
|
258 | * // Limit the results to 10 entities.
|
259 | * const limitQuery = companyQuery.limit(10);
|
260 | * ```
|
261 | */
|
262 | limit(n: number): this;
|
263 | /**
|
264 | * Set an offset on a query.
|
265 | *
|
266 | * @see {@link https://cloud.google.com/datastore/docs/concepts/queries#datastore-limit-nodejs| Query Offsets}
|
267 | *
|
268 | * @param {number} n The offset to start from after the start cursor.
|
269 | * @returns {Query}
|
270 | *
|
271 | * @example
|
272 | * ```
|
273 | * const {Datastore} = require('@google-cloud/datastore');
|
274 | * const datastore = new Datastore();
|
275 | * const companyQuery = datastore.createQuery('Company');
|
276 | *
|
277 | * // Start from the 101st result.
|
278 | * const offsetQuery = companyQuery.offset(100);
|
279 | * ```
|
280 | */
|
281 | offset(n: number): this;
|
282 | /**
|
283 | * Run the query.
|
284 | *
|
285 | * @param {object} [options] Optional configuration.
|
286 | * @param {string} [options.consistency] Specify either `strong` or `eventual`.
|
287 | * If not specified, default values are chosen by Datastore for the
|
288 | * operation. Learn more about strong and eventual consistency
|
289 | * [here](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore).
|
290 | * @param {object} [options.gaxOptions] Request configuration options, outlined
|
291 | * here: https://googleapis.github.io/gax-nodejs/global.html#CallOptions.
|
292 | * @param {boolean | IntegerTypeCastOptions} [options.wrapNumbers=false]
|
293 | * Wrap values of integerValue type in {@link Datastore#Int} objects.
|
294 | * If a `boolean`, this will wrap values in {@link Datastore#Int} objects.
|
295 | * If an `object`, this will return a value returned by
|
296 | * `wrapNumbers.integerTypeCastFunction`.
|
297 | * Please see {@link IntegerTypeCastOptions} for options descriptions.
|
298 | * @param {function} [callback] The callback function. If omitted, a readable
|
299 | * stream instance is returned.
|
300 | * @param {?error} callback.err An error returned while making this request
|
301 | * @param {object[]} callback.entities A list of entities.
|
302 | * @param {object} callback.info An object useful for pagination.
|
303 | * @param {?string} callback.info.endCursor Use this in a follow-up query to
|
304 | * begin from where these results ended.
|
305 | * @param {string} callback.info.moreResults Datastore responds with one of:
|
306 | *
|
307 | * - {@link Datastore#MORE_RESULTS_AFTER_LIMIT}: There *may* be more
|
308 | * results after the specified limit.
|
309 | * - {@link Datastore#MORE_RESULTS_AFTER_CURSOR}: There *may* be more
|
310 | * results after the specified end cursor.
|
311 | * - {@link Datastore#NO_MORE_RESULTS}: There are no more results.
|
312 | *
|
313 | * @example
|
314 | * ```
|
315 | * const {Datastore} = require('@google-cloud/datastore');
|
316 | * const datastore = new Datastore();
|
317 | * const query = datastore.createQuery('Company');
|
318 | *
|
319 | * query.run((err, entities, info) => {
|
320 | * // entities = An array of records.
|
321 | *
|
322 | * // Access the Key object for an entity.
|
323 | * const firstEntityKey = entities[0][datastore.KEY];
|
324 | * });
|
325 | *
|
326 | * //-
|
327 | * // A keys-only query returns just the keys of the result entities instead
|
328 | * of
|
329 | * // the entities themselves, at lower latency and cost.
|
330 | * //-
|
331 | * query.select('__key__');
|
332 | *
|
333 | * query.run((err, entities) => {
|
334 | * const keys = entities.map((entity) => {
|
335 | * return entity[datastore.KEY];
|
336 | * });
|
337 | * });
|
338 | *
|
339 | * //-
|
340 | * // If the callback is omitted, we'll return a Promise.
|
341 | * //-
|
342 | * query.run().then((data) => {
|
343 | * const entities = data[0];
|
344 | * });
|
345 | * ```
|
346 | */
|
347 | run(options?: RunQueryOptions): Promise<RunQueryResponse>;
|
348 | run(options: RunQueryOptions, callback: RunQueryCallback): void;
|
349 | run(callback: RunQueryCallback): void;
|
350 | /**
|
351 | * Run the query as a readable object stream.
|
352 | *
|
353 | * @method Query#runStream
|
354 | * @param {object} [options] Optional configuration. See
|
355 | * {@link Query#run} for a complete list of options.
|
356 | * @returns {stream}
|
357 | *
|
358 | * @example
|
359 | * ```
|
360 | * const {Datastore} = require('@google-cloud/datastore');
|
361 | * const datastore = new Datastore();
|
362 | * const query = datastore.createQuery('Company');
|
363 | *
|
364 | * query.runStream()
|
365 | * .on('error', console.error)
|
366 | * .on('data', function (entity) {
|
367 | * // Access the Key object for this entity.
|
368 | * const key = entity[datastore.KEY];
|
369 | * })
|
370 | * .on('info', (info) => {})
|
371 | * .on('end', () => {
|
372 | * // All entities retrieved.
|
373 | * });
|
374 | *
|
375 | * //-
|
376 | * // If you anticipate many results, you can end a stream early to prevent
|
377 | * // unnecessary processing and API requests.
|
378 | * //-
|
379 | * query.runStream()
|
380 | * .on('data', function (entity) {
|
381 | * this.end();
|
382 | * });
|
383 | * ```
|
384 | */
|
385 | runStream(options?: RunQueryStreamOptions): import("stream").Transform;
|
386 | }
|
387 | export interface QueryProto {
|
388 | startCursor?: string | Buffer;
|
389 | distinctOn: {};
|
390 | kind: {};
|
391 | order: {};
|
392 | projection: {};
|
393 | endCursor?: string | Buffer;
|
394 | limit?: {};
|
395 | offset?: number;
|
396 | filter?: {};
|
397 | }
|
398 | /**
|
399 | * Reference to the {@link Query} class.
|
400 | * @name module:@google-cloud/datastore.Query
|
401 | * @see Query
|
402 | */
|
403 | export { Query };
|
404 | export interface IntegerTypeCastOptions {
|
405 | integerTypeCastFunction: Function;
|
406 | properties?: string | string[];
|
407 | }
|
408 | export interface RunQueryOptions {
|
409 | consistency?: 'strong' | 'eventual';
|
410 | readTime?: number;
|
411 | gaxOptions?: CallOptions;
|
412 | wrapNumbers?: boolean | IntegerTypeCastOptions;
|
413 | }
|
414 | export interface RunQueryCallback {
|
415 | (err: Error | null, entities?: Entity[], info?: RunQueryInfo): void;
|
416 | }
|
417 | export type RunQueryResponse = [Entity[], RunQueryInfo];
|
418 | export type RunAggregateQueryResponse = any;
|
419 | export interface RunQueryInfo {
|
420 | endCursor?: string;
|
421 | moreResults?: 'MORE_RESULTS_TYPE_UNSPECIFIED' | 'NOT_FINISHED' | 'MORE_RESULTS_AFTER_LIMIT' | 'MORE_RESULTS_AFTER_CURSOR' | 'NO_MORE_RESULTS';
|
422 | }
|