UNPKG

24.2 kBTypeScriptView Raw
1/*!
2 * Copyright 2014 Google Inc. All Rights Reserved.
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 */
16import { DeleteCallback, Metadata, ServiceObject } from '@google-cloud/common';
17import { ResourceStream } from '@google-cloud/paginator';
18import { Duplex } from 'stream';
19import { BigQuery, PagedCallback, PagedRequest, PagedResponse, Query, QueryRowsResponse, ResourceCallback, SimpleQueryRowsCallback } from './bigquery';
20import { JobCallback, JobResponse, Table, TableMetadata, TableOptions } from './table';
21import { Model } from './model';
22import { Routine } from './routine';
23import bigquery from './types';
24export interface DatasetDeleteOptions {
25 force?: boolean;
26}
27export interface DatasetOptions {
28 location?: string;
29 projectId?: string;
30}
31export type CreateDatasetOptions = bigquery.IDataset;
32export type GetModelsOptions = PagedRequest<bigquery.models.IListParams>;
33export type GetModelsResponse = PagedResponse<Model, GetModelsOptions, bigquery.IListModelsResponse>;
34export type GetModelsCallback = PagedCallback<Model, GetModelsOptions, bigquery.IListModelsResponse>;
35export type GetRoutinesOptions = PagedRequest<bigquery.routines.IListParams>;
36export type GetRoutinesResponse = PagedResponse<Routine, GetRoutinesOptions, bigquery.IListRoutinesResponse>;
37export type GetRoutinesCallback = PagedCallback<Routine, GetRoutinesOptions, bigquery.IListRoutinesResponse>;
38export type GetTablesOptions = PagedRequest<bigquery.tables.IListParams>;
39export type GetTablesResponse = PagedResponse<Table, GetTablesOptions, bigquery.ITableList>;
40export type GetTablesCallback = PagedCallback<Table, GetTablesOptions, bigquery.ITableList>;
41export type RoutineMetadata = bigquery.IRoutine;
42export type RoutineResponse = [Routine, bigquery.IRoutine];
43export type RoutineCallback = ResourceCallback<Routine, bigquery.IRoutine>;
44export type TableResponse = [Table, bigquery.ITable];
45export type TableCallback = ResourceCallback<Table, bigquery.ITable>;
46/**
47 * Interact with your BigQuery dataset. Create a Dataset instance with
48 * {@link BigQuery#createDataset} or {@link BigQuery#dataset}.
49 *
50 * @class
51 * @param {BigQuery} bigQuery {@link BigQuery} instance.
52 * @param {string} id The ID of the Dataset.
53 * @param {object} [options] Dataset options.
54 * @param {string} [options.projectId] The GCP project ID.
55 * @param {string} [options.location] The geographic location of the dataset.
56 * Defaults to US.
57 *
58 * @example
59 * ```
60 * const {BigQuery} = require('@google-cloud/bigquery');
61 * const bigquery = new BigQuery();
62 * const dataset = bigquery.dataset('institutions');
63 * ```
64 */
65declare class Dataset extends ServiceObject {
66 bigQuery: BigQuery;
67 location?: string;
68 projectId: string;
69 getModelsStream(options?: GetModelsOptions): ResourceStream<Model>;
70 getRoutinesStream(options?: GetRoutinesOptions): ResourceStream<Routine>;
71 getTablesStream(options?: GetTablesOptions): ResourceStream<Table>;
72 constructor(bigQuery: BigQuery, id: string, options?: DatasetOptions);
73 /**
74 * Run a query as a job. No results are immediately returned. Instead, your
75 * callback will be executed with a {@link Job} object that you must
76 * ping for the results. See the Job documentation for explanations of how to
77 * check on the status of the job.
78 *
79 * See {@link BigQuery#createQueryJob} for full documentation of this method.
80 *
81 * @param {object} options See {@link BigQuery#createQueryJob} for full documentation of this method.
82 * @param {JobCallback} [callback] See {@link BigQuery#createQueryJob} for full documentation of this method.
83 * @returns {Promise<JobResponse>} See {@link BigQuery#createQueryJob} for full documentation of this method.
84 */
85 createQueryJob(options: string | Query): Promise<JobResponse>;
86 createQueryJob(options: string | Query, callback: JobCallback): void;
87 /**
88 * Run a query scoped to your dataset as a readable object stream.
89 *
90 * See {@link BigQuery#createQueryStream} for full documentation of this
91 * method.
92 *
93 * @param {object} options See {@link BigQuery#createQueryStream} for full
94 * documentation of this method.
95 * @returns {stream}
96 */
97 createQueryStream(options: Query | string): Duplex;
98 /**
99 * @callback CreateRoutineCallback
100 * @param {?Error} err Request error, if any.
101 * @param {Routine} routine The newly created routine.
102 * @param {object} response The full API response body.
103 */
104 /**
105 * @typedef {array} CreateRoutineResponse
106 * @property {Routine} 0 The newly created routine.
107 * @property {object} 1 The full API response body.
108 */
109 /**
110 * Create a {@link Routine}.
111 *
112 * See {@link https://cloud.google.com/bigquery/docs/reference/rest/v2/routines/insert| Routines: insert API Documentation}
113 *
114 * @param {string} id The routine ID.
115 * @param {object} config A [routine resource]{@link https://cloud.google.com/bigquery/docs/reference/rest/v2/routines#Routine}.
116 * @param {CreateRoutineCallback} [callback] The callback function.
117 * @returns {Promise<CreateRoutineResponse>}
118 *
119 * @example
120 * ```
121 * const {BigQuery} = require('@google-cloud/bigquery');
122 * const bigquery = new BigQuery();
123 * const dataset = bigquery.dataset('my-dataset');
124 *
125 * const id = 'my-routine';
126 * const config = {
127 * arguments: [{
128 * name: 'x',
129 * dataType: {
130 * typeKind: 'INT64'
131 * }
132 * }],
133 * definitionBody: 'x * 3',
134 * routineType: 'SCALAR_FUNCTION',
135 * returnType: {
136 * typeKind: 'INT64'
137 * }
138 * };
139 *
140 * dataset.createRoutine(id, config, (err, routine, apiResponse) => {
141 * if (!err) {
142 * // The routine was created successfully.
143 * }
144 * });
145 *
146 * ```
147 * @example If the callback is omitted a Promise will be returned
148 * ```
149 * const [routine, apiResponse] = await dataset.createRoutine(id, config);
150 * ```
151 */
152 createRoutine(id: string, config: RoutineMetadata): Promise<RoutineResponse>;
153 createRoutine(id: string, config: RoutineMetadata, callback: RoutineCallback): void;
154 /**
155 * @callback TableCallback
156 * @param {?Error} err Request error, if any.
157 * @param {Table} table The table.
158 * @param {object} apiResponse The full API response body.
159 */
160 /**
161 * @typedef {array} TableResponse
162 * @property {Table} 0 The table.
163 * @property {object} 1 The full API response body.
164 */
165 /**
166 * Create a {@link Table} given a tableId or configuration object.
167 *
168 * See {@link https://cloud.google.com/bigquery/docs/reference/v2/tables/insert| Tables: insert API Documentation}
169 *
170 * @param {string} id Table id.
171 * @param {object} [options] See a
172 * {@link https://cloud.google.com/bigquery/docs/reference/v2/tables#resource| Table resource}.
173 * @param {string|object} [options.schema] A comma-separated list of name:type
174 * pairs. Valid types are "string", "integer", "float", "boolean", and
175 * "timestamp". If the type is omitted, it is assumed to be "string".
176 * Example: "name:string, age:integer". Schemas can also be specified as a
177 * JSON array of fields, which allows for nested and repeated fields. See
178 * a {@link http://goo.gl/sl8Dmg| Table resource} for more detailed information.
179 * @param {TableCallback} [callback] The callback function.
180 * @param {?error} callback.err An error returned while making this request
181 * @param {Table} callback.table The newly created table.
182 * @param {object} callback.apiResponse The full API response.
183 * @returns {Promise<TableResponse>}
184 *
185 * @example
186 * ```
187 * const {BigQuery} = require('@google-cloud/bigquery');
188 * const bigquery = new BigQuery();
189 * const dataset = bigquery.dataset('institutions');
190 *
191 * const tableId = 'institution_data';
192 *
193 * const options = {
194 * // From the data.gov CSV dataset (http://goo.gl/kSE7z6):
195 * schema: 'UNITID,INSTNM,ADDR,CITY,STABBR,ZIP,FIPS,OBEREG,CHFNM,...'
196 * };
197 *
198 * dataset.createTable(tableId, options, (err, table, apiResponse) => {});
199 *
200 * //-
201 * // If the callback is omitted, we'll return a Promise.
202 * //-
203 * dataset.createTable(tableId, options).then((data) => {
204 * const table = data[0];
205 * const apiResponse = data[1];
206 * });
207 * ```
208 */
209 createTable(id: string, options: TableMetadata): Promise<TableResponse>;
210 createTable(id: string, options: TableMetadata, callback: TableCallback): void;
211 createTable(id: string, callback: TableCallback): void;
212 /**
213 * @callback DeleteCallback
214 * @param {?Error} err Request error, if any.
215 * @param {object} apiResponse The full API response body.
216 */
217 /**
218 * @typedef {array} Metadata
219 * @property {object} 0 The full API response body.
220 */
221 /**
222 * Delete the dataset.
223 *
224 * See {@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/delete| Datasets: delete API Documentation}
225 *
226 * @param {object} [options] The configuration object.
227 * @param {boolean} [options.force=false] Force delete dataset and all tables.
228 * @param {DeleteCallback} [callback] The callback function.
229 * @param {?error} callback.err An error returned while making this request
230 * @param {object} callback.apiResponse The full API response.
231 * @returns {Promise<Metadata>}
232 *
233 * @example
234 * ```
235 * const {BigQuery} = require('@google-cloud/bigquery');
236 * const bigquery = new BigQuery();
237 * const dataset = bigquery.dataset('institutions');
238 *
239 * //-
240 * // Delete the dataset, only if it does not have any tables.
241 * //-
242 * dataset.delete((err, apiResponse) => {});
243 *
244 * //-
245 * // Delete the dataset and any tables it contains.
246 * //-
247 * dataset.delete({ force: true }, (err, apiResponse) => {});
248 *
249 * //-
250 * // If the callback is omitted, we'll return a Promise.
251 * //-
252 * dataset.delete().then((data) => {
253 * const apiResponse = data[0];
254 * });
255 * ```
256 */
257 delete(options?: DatasetDeleteOptions): Promise<[Metadata]>;
258 delete(options: DatasetDeleteOptions, callback: DeleteCallback): void;
259 delete(callback: DeleteCallback): void;
260 /**
261 * @typedef {object} GetModelsOptions
262 * @property {boolean} [autoPaginate=true] Have pagination handled
263 * automatically.
264 * @property {number} [maxApiCalls] Maximum number of API calls to make.
265 * @property {number} [maxResults] Maximum number of results to return.
266 * @property {string} [pageToken] Token returned from a previous call, to
267 * request the next page of results.
268 */
269 /**
270 * @callback GetModelsCallback
271 * @param {?Error} err Request error, if any.
272 * @param {Model[]} models List of model objects.
273 * @param {GetModelsOptions} nextQuery If `autoPaginate` is set to true,
274 * this will be a prepared query for the next page of results.
275 * @param {object} response The full API response.
276 */
277 /**
278 * @typedef {array} GetModelsResponse
279 * @property {Model[]} 0 A list of the dataset's {@link Model} objects.
280 * @property {GetModelsOptions} 1 If `autoPaginate` is set to true, this
281 * will be a prepared query for the next page of results.
282 * @property {object} 2 The full API response.
283 */
284 /**
285 * Get a list of {@link Model} resources.
286 *
287 * See {@link https://cloud.google.com/bigquery/docs/reference/rest/v2/models/list| Models: list API Documentation}
288 *
289 * @param {GetModelsOptions} [options] Configuration object.
290 * @param {boolean} [options.autoPaginate=true] Have pagination handled
291 * automatically.
292 * @param {number} [options.maxApiCalls] Maximum number of API calls to make.
293 * @param {number} [options.maxResults] Maximum number of results to return.
294 * @param {string} [options.pageToken] Token returned from a previous call, to
295 * request the next page of results.
296 * @param {GetModelsCallback} [callback] The callback function.
297 * @param {?error} callback.err An error returned while making this request
298 * @param {Model[]} callback.models The list of models from
299 * your Dataset.
300 * @param {GetModelsOptions} callback.nextQuery If `autoPaginate` is set to true, this
301 * will be a prepared query for the next page of results.
302 * @param {object} callback.apiResponse The full API response.
303 * @returns {Promise<GetModelsResponse>}
304 *
305 * @example
306 * ```
307 * const {BigQuery} = require('@google-cloud/bigquery');
308 * const bigquery = new BigQuery();
309 * const dataset = bigquery.dataset('institutions');
310 *
311 * dataset.getModels((err, models) => {
312 * // models is an array of `Model` objects.
313 * });
314 *
315 * ```
316 * @example To control how many API requests are made and page through the results manually, set `autoPaginate` to `false`.
317 * ```
318 * function manualPaginationCallback(err, models, nextQuery, apiResponse) {
319 * if (nextQuery) {
320 * // More results exist.
321 * dataset.getModels(nextQuery, manualPaginationCallback);
322 * }
323 * }
324 *
325 * dataset.getModels({
326 * autoPaginate: false
327 * }, manualPaginationCallback);
328 *
329 * ```
330 * @example If the callback is omitted, we'll return a Promise.
331 * ```
332 * dataset.getModels().then((data) => {
333 * const models = data[0];
334 * });
335 * ```
336 */
337 getModels(options?: GetModelsOptions): Promise<GetModelsResponse>;
338 getModels(options: GetModelsOptions, callback: GetModelsCallback): void;
339 getModels(callback: GetModelsCallback): void;
340 /**
341 * @typedef {object} GetRoutinesOptions
342 * @property {boolean} [autoPaginate=true] Have pagination handled
343 * automatically.
344 * @property {number} [maxApiCalls] Maximum number of API calls to make.
345 * @property {number} [maxResults] Maximum number of results to return.
346 * @property {string} [pageToken] Token returned from a previous call, to
347 * request the next page of results.
348 */
349 /**
350 * @callback GetRoutinesCallback
351 * @param {?Error} err Request error, if any.
352 * @param {Routine[]} routines List of routine objects.
353 * @param {GetRoutinesOptions} nextQuery If `autoPaginate` is set to true,
354 * this will be a prepared query for the next page of results.
355 * @param {object} response The full API response.
356 */
357 /**
358 * @typedef {array} GetRoutinesResponse
359 * @property {Routine[]} 0 List of {@link Routine} objects.
360 * @property {GetRoutinesOptions} 1 If `autoPaginate` is set to true, this
361 * will be a prepared query for the next page of results.
362 * @property {object} 2 The full API response.
363 */
364 /**
365 * Get a list of routines.
366 *
367 * See {@link https://cloud.google.com/bigquery/docs/reference/rest/v2/routines/list| Routines: list API Documentation}
368 *
369 * @param {GetRoutinesOptions} [options] Request options.
370 * @param {boolean} [options.autoPaginate=true] Have pagination handled
371 * automatically.
372 * @param {number} [options.maxApiCalls] Maximum number of API calls to make.
373 * @param {number} [options.maxResults] Maximum number of results to return.
374 * @param {string} [options.pageToken] Token returned from a previous call, to
375 * request the next page of results.
376 * @param {GetRoutinesCallback} [callback] The callback function.
377 * @param {?error} callback.err An error returned while making this request
378 * @param {Routine[]} callback.routines The list of models from
379 * your Dataset.
380 * @param {GetRoutinesOptions} callback.nextQuery If `autoPaginate` is set to true, this
381 * will be a prepared query for the next page of results.
382 * @param {object} callback.apiResponse The full API response.
383 * @returns {Promise<GetRoutinesResponse>}
384 *
385 * @example
386 * ```
387 * const {BigQuery} = require('@google-cloud/bigquery');
388 * const bigquery = new BigQuery();
389 * const dataset = bigquery.dataset('institutions');
390 *
391 * dataset.getRoutines((err, routines) => {
392 * // routines is an array of `Routine` objects.
393 * });
394 *
395 * ```
396 * @example To control how many API requests are made and page through the results manually, set `autoPaginate` to `false`.
397 * ```
398 * function manualPaginationCallback(err, routines, nextQuery, apiResponse) {
399 * if (nextQuery) {
400 * // More results exist.
401 * dataset.getRoutines(nextQuery, manualPaginationCallback);
402 * }
403 * }
404 *
405 * dataset.getRoutines({
406 * autoPaginate: false
407 * }, manualPaginationCallback);
408 *
409 * ```
410 * @example If the callback is omitted a Promise will be returned
411 * ```
412 * const [routines] = await dataset.getRoutines();
413 * ```
414 */
415 getRoutines(options?: GetRoutinesOptions): Promise<GetRoutinesResponse>;
416 getRoutines(options: GetRoutinesOptions, callback: GetRoutinesCallback): void;
417 getRoutines(callback: GetRoutinesCallback): void;
418 /**
419 * @typedef {object} GetTablesOptions
420 * @property {boolean} [autoPaginate=true] Have pagination handled
421 * automatically.
422 * @property {number} [maxApiCalls] Maximum number of API calls to make.
423 * @property {number} [maxResults] Maximum number of results to return.
424 * @property {string} [pageToken] Token returned from a previous call, to
425 * request the next page of results.
426 */
427 /**
428 * @callback GetTablesCallback
429 * @param {?Error} err Request error, if any.
430 * @param {Table[]} tables List of {@link Table} objects.
431 * @param {GetTablesOptions} nextQuery If `autoPaginate` is set to true,
432 * this will be a prepared query for the next page of results.
433 * @param {object} response The full API response.
434 */
435 /**
436 * @typedef {array} GetTablesResponse
437 * @property {Table[]} 0 List of {@link Table} objects.
438 * @property {GetTablesOptions} 1 If `autoPaginate` is set to true, this
439 * will be a prepared query for the next page of results.
440 * @property {object} 2 The full API response.
441 */
442 /**
443 * Get a list of {@link Table} resources.
444 *
445 * See {@link https://cloud.google.com/bigquery/docs/reference/v2/tables/list| Tables: list API Documentation}
446 *
447 * @param {GetTablesOptions} options Configuration object.
448 * @param {boolean} [options.autoPaginate=true] Have pagination handled automatically.
449 * @param {number} [options.maxApiCalls] Maximum number of API calls to make.
450 * @param {number} [options.maxResults] Maximum number of results to return.
451 * @param {string} [options.pageToken] Token returned from a previous call, to
452 * request the next page of results.
453 * @param {GetTablesCallback} [callback] The callback function.
454 * @param {?error} callback.err An error returned while making this request
455 * @param {Table[]} callback.tables The list of tables from
456 * your Dataset.
457 * @param {GetTablesOptions} callback.nextQuery If `autoPaginate` is set to true, this
458 * will be a prepared query for the next page of results.
459 * @param {object} callback.apiResponse The full API response.
460 * @returns {Promise<GetTablesResponse>}
461 *
462 * @example
463 * ```
464 * const {BigQuery} = require('@google-cloud/bigquery');
465 * const bigquery = new BigQuery();
466 * const dataset = bigquery.dataset('institutions');
467 *
468 * dataset.getTables((err, tables) => {
469 * // tables is an array of `Table` objects.
470 * });
471 *
472 * //-
473 * // To control how many API requests are made and page through the results
474 * // manually, set `autoPaginate` to `false`.
475 * //-
476 * function manualPaginationCallback(err, tables, nextQuery, apiResponse) {
477 * if (nextQuery) {
478 * // More results exist.
479 * dataset.getTables(nextQuery, manualPaginationCallback);
480 * }
481 * }
482 *
483 * dataset.getTables({
484 * autoPaginate: false
485 * }, manualPaginationCallback);
486 *
487 * //-
488 * // If the callback is omitted, we'll return a Promise.
489 * //-
490 * dataset.getTables().then((data) => {
491 * const tables = data[0];
492 * });
493 * ```
494 */
495 getTables(options?: GetTablesOptions): Promise<GetTablesResponse>;
496 getTables(options: GetTablesOptions, callback: GetTablesCallback): void;
497 getTables(callback: GetTablesCallback): void;
498 /**
499 * Create a {@link Model} object.
500 *
501 * @throws {TypeError} if model ID is missing.
502 *
503 * @param {string} id The ID of the model.
504 * @return {Model}
505 *
506 * @example
507 * ```
508 * const {BigQuery} = require('@google-cloud/bigquery');
509 * const bigquery = new BigQuery();
510 * const dataset = bigquery.dataset('institutions');
511 *
512 * const model = dataset.model('my-model');
513 * ```
514 */
515 model(id: string): Model;
516 /**
517 * Run a query scoped to your dataset.
518 *
519 * See {@link BigQuery#query} for full documentation of this method.
520 *
521 * @param {object} options See {@link BigQuery#query} for full documentation of this method.
522 * @param {function} [callback] See {@link BigQuery#query} for full documentation of this method.
523 * @returns {Promise<SimpleQueryRowsResponse>}
524 * @returns {Promise<QueryRowsResponse>} See {@link BigQuery#query} for full documentation of this method.
525 */
526 query(options: Query): Promise<QueryRowsResponse>;
527 query(options: string): Promise<QueryRowsResponse>;
528 query(options: Query, callback: SimpleQueryRowsCallback): void;
529 query(options: string, callback: SimpleQueryRowsCallback): void;
530 /**
531 * Create a {@link Routine} object.
532 *
533 * @throws {TypeError} if routine ID is missing.
534 *
535 * @param {string} id The ID of the routine.
536 * @returns {Routine}
537 *
538 * @example
539 * ```
540 * const {BigQuery} = require('@google-cloud/bigquery');
541 * const bigquery = new BigQuery();
542 * const dataset = bigquery.dataset('institutions');
543 *
544 * const routine = dataset.routine('my_routine');
545 * ```
546 */
547 routine(id: string): Routine;
548 /**
549 * Create a {@link Table} object.
550 *
551 * @throws {TypeError} if table ID is missing.
552 *
553 * @param {string} id The ID of the table.
554 * @param {object} [options] Table options.
555 * @param {string} [options.location] The geographic location of the table, by
556 * default this value is inherited from the dataset. This can be used to
557 * configure the location of all jobs created through a table instance.
558 * It cannot be used to set the actual location of the table. This value will
559 * be superseded by any API responses containing location data for the
560 * table.
561 * @return {Table}
562 *
563 * @example
564 * ```
565 * const {BigQuery} = require('@google-cloud/bigquery');
566 * const bigquery = new BigQuery();
567 * const dataset = bigquery.dataset('institutions');
568 *
569 * const institutions = dataset.table('institution_data');
570 * ```
571 */
572 table(id: string, options?: TableOptions): Table;
573}
574/**
575 * Reference to the {@link Dataset} class.
576 * @name module:@google-cloud/bigquery.Dataset
577 * @see Dataset
578 */
579export { Dataset };