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 | */
|
16 | /*!
|
17 | * @module bigquery/job
|
18 | */
|
19 | import { MetadataCallback, Operation } from '@google-cloud/common';
|
20 | import { ResourceStream } from '@google-cloud/paginator';
|
21 | import { BigQuery, IntegerTypeCastOptions, JobRequest, PagedRequest, QueryRowsCallback, QueryRowsResponse, RequestCallback } from './bigquery';
|
22 | import { RowMetadata } from './table';
|
23 | import bigquery from './types';
|
24 | export type JobMetadata = bigquery.IJob;
|
25 | export type JobOptions = JobRequest<JobMetadata>;
|
26 | export type CancelCallback = RequestCallback<bigquery.IJobCancelResponse>;
|
27 | export type CancelResponse = [bigquery.IJobCancelResponse];
|
28 | export type QueryResultsOptions = {
|
29 | job?: Job;
|
30 | wrapIntegers?: boolean | IntegerTypeCastOptions;
|
31 | parseJSON?: boolean;
|
32 | } & PagedRequest<bigquery.jobs.IGetQueryResultsParams> & {
|
33 | /**
|
34 | * internal properties
|
35 | */
|
36 | _cachedRows?: any[];
|
37 | };
|
38 | /**
|
39 | * @callback QueryResultsCallback
|
40 | * @param {?Error} err An error returned while making this request.
|
41 | * @param {array} rows The results of the job.
|
42 | */
|
43 | /**
|
44 | * @callback ManualQueryResultsCallback
|
45 | * @param {?Error} err An error returned while making this request.
|
46 | * @param {array} rows The results of the job.
|
47 | * @param {?object} nextQuery A pre-made configuration object for your next
|
48 | * request. This will be `null` if no additional results are available.
|
49 | * If the query is not yet complete, you may get empty `rows` and
|
50 | * non-`null` `nextQuery` that you should use for your next request.
|
51 | * @param {object} apiResponse The full API response.
|
52 | */
|
53 | /**
|
54 | * Job objects are returned from various places in the BigQuery API:
|
55 | *
|
56 | * - {@link BigQuery#getJobs}
|
57 | * - {@link BigQuery#job}
|
58 | * - {@link BigQuery#query}
|
59 | * - {@link BigQuery#createJob}
|
60 | * - {@link Table#copy}
|
61 | * - {@link Table#createWriteStream}
|
62 | * - {@link Table#extract}
|
63 | * - {@link Table#load}
|
64 | *
|
65 | * They can be used to check the status of a running job or fetching the results
|
66 | * of a previously-executed one.
|
67 | *
|
68 | * @class
|
69 | * @param {BigQuery} bigQuery {@link BigQuery} instance.
|
70 | * @param {string} id The ID of the job.
|
71 | * @param {object} [options] Configuration object.
|
72 | * @param {string} [options.location] The geographic location of the job.
|
73 | * Required except for US and EU.
|
74 | *
|
75 | * @example
|
76 | * ```
|
77 | * const {BigQuery} = require('@google-cloud/bigquery');
|
78 | * const bigquery = new BigQuery();
|
79 | *
|
80 | * const job = bigquery.job('job-id');
|
81 | *
|
82 | * //-
|
83 | * // All jobs are event emitters. The status of each job is polled
|
84 | * // continuously, starting only after you register a "complete" listener.
|
85 | * //-
|
86 | * job.on('complete', (metadata) => {
|
87 | * // The job is complete.
|
88 | * });
|
89 | *
|
90 | * //-
|
91 | * // Be sure to register an error handler as well to catch any issues which
|
92 | * // impeded the job.
|
93 | * //-
|
94 | * job.on('error', (err) => {
|
95 | * // An error occurred during the job.
|
96 | * });
|
97 | *
|
98 | * //-
|
99 | * // To force the Job object to stop polling for updates, simply remove any
|
100 | * // "complete" listeners you've registered.
|
101 | * //
|
102 | * // The easiest way to do this is with `removeAllListeners()`.
|
103 | * //-
|
104 | * job.removeAllListeners();
|
105 | * ```
|
106 | */
|
107 | declare class Job extends Operation {
|
108 | bigQuery: BigQuery;
|
109 | location?: string;
|
110 | projectId?: string;
|
111 | getQueryResultsStream(options?: QueryResultsOptions): ResourceStream<RowMetadata>;
|
112 | constructor(bigQuery: BigQuery, id: string, options?: JobOptions);
|
113 | private trace_;
|
114 | /**
|
115 | * @callback CancelCallback
|
116 | * @param {?Error} err Request error, if any.
|
117 | * {object} metadata The job metadata.
|
118 | * {object} apiResponse The full API response.
|
119 | */
|
120 | /**
|
121 | * @typedef {array} CancelResponse
|
122 | * @property {object} 0 The job metadata.
|
123 | * @property {object} 1 The full API response.
|
124 | */
|
125 | /**
|
126 | * Cancel a job. Use {@link Job#getMetadata} to see if the cancel
|
127 | * completes successfully. See an example implementation below.
|
128 | *
|
129 | * See {@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/cancel| Jobs: get API Documentation}
|
130 | *
|
131 | * @param {CancelCallback} [callback] The callback function.
|
132 | * @param {?error} callback.err An error returned while making this request.
|
133 | * @param {object} callback.apiResponse The full API response.
|
134 | * @returns {Promise<CancelResponse>}
|
135 | *
|
136 | * @example
|
137 | * ```
|
138 | * const {BigQuery} = require('@google-cloud/bigquery');
|
139 | * const bigquery = new BigQuery();
|
140 | *
|
141 | * const job = bigquery.job('job-id');
|
142 | *
|
143 | * job.cancel((err, apiResponse) =>{
|
144 | * // Check to see if the job completes successfully.
|
145 | * job.on('error', (err) => {});
|
146 | * job.on('complete', (metadata) => {});
|
147 | * });
|
148 | *
|
149 | * //-
|
150 | * // If the callback is omitted, we'll return a Promise.
|
151 | * //-
|
152 | * job.cancel().then((data) => {
|
153 | * const apiResponse = data[0];
|
154 | * });
|
155 | * ```
|
156 | */
|
157 | cancel(): Promise<CancelResponse>;
|
158 | cancel(callback: CancelCallback): void;
|
159 | /**
|
160 | * Get the results of a job.
|
161 | *
|
162 | * See {@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/getQueryResults| Jobs: getQueryResults API Documentation}
|
163 | *
|
164 | * @param {object} [options] Configuration object.
|
165 | * @param {boolean} [options.autoPaginate=true] Have pagination handled
|
166 | * automatically.
|
167 | * @param {number} [options.maxApiCalls] Maximum number of API calls to make.
|
168 | * @param {number} [options.maxResults] Maximum number of results to read.
|
169 | * @param {string} [options.pageToken] Page token, returned by a previous call,
|
170 | * to request the next page of results. Note: This is automatically added
|
171 | * to the `nextQuery` argument of your callback.
|
172 | * @param {number} [options.startIndex] Zero-based index of the starting row.
|
173 | * @param {number} [options.timeoutMs] How long to wait for the query to
|
174 | * complete, in milliseconds, before returning. Default is 10 seconds.
|
175 | * If the timeout passes before the job completes, an error will be returned
|
176 | * and the 'jobComplete' field in the response will be false.
|
177 | * @param {boolean|IntegerTypeCastOptions} [options.wrapIntegers=false] Wrap values
|
178 | * of 'INT64' type in {@link BigQueryInt} objects.
|
179 | * If a `boolean`, this will wrap values in {@link BigQueryInt} objects.
|
180 | * If an `object`, this will return a value returned by
|
181 | * `wrapIntegers.integerTypeCastFunction`.
|
182 | * @param {QueryResultsCallback|ManualQueryResultsCallback} [callback] The
|
183 | * callback function. If `autoPaginate` is set to false a
|
184 | * {@link ManualQueryResultsCallback} should be used.
|
185 | * @returns {Promise<QueryResultsCallback>}
|
186 | *
|
187 | * @example
|
188 | * ```
|
189 | * const {BigQuery} = require('@google-cloud/bigquery');
|
190 | * const bigquery = new BigQuery();
|
191 | *
|
192 | * const job = bigquery.job('job-id');
|
193 | *
|
194 | * //-
|
195 | * // Get all of the results of a query.
|
196 | * //-
|
197 | * job.getQueryResults((err, rows) => {
|
198 | * if (!err) {
|
199 | * // rows is an array of results.
|
200 | * }
|
201 | * });
|
202 | *
|
203 | * //-
|
204 | * // Customize the results you want to fetch.
|
205 | * //-
|
206 | * job.getQueryResults({
|
207 | * maxResults: 100
|
208 | * }, (err, rows) => {});
|
209 | *
|
210 | * //-
|
211 | * // To control how many API requests are made and page through the results
|
212 | * // manually, set `autoPaginate` to `false`.
|
213 | * //-
|
214 | * function manualPaginationCallback(err, rows, nextQuery, apiResponse) {
|
215 | * if (nextQuery) {
|
216 | * // More results exist.
|
217 | * job.getQueryResults(nextQuery, manualPaginationCallback);
|
218 | * }
|
219 | * }
|
220 | *
|
221 | * job.getQueryResults({
|
222 | * autoPaginate: false
|
223 | * }, manualPaginationCallback);
|
224 | *
|
225 | * //-
|
226 | * // If the callback is omitted, we'll return a Promise.
|
227 | * //-
|
228 | * job.getQueryResults().then((data) => {
|
229 | * const rows = data[0];
|
230 | * });
|
231 | * ```
|
232 | */
|
233 | getQueryResults(options?: QueryResultsOptions): Promise<QueryRowsResponse>;
|
234 | getQueryResults(options: QueryResultsOptions, callback: QueryRowsCallback): void;
|
235 | getQueryResults(callback: QueryRowsCallback): void;
|
236 | /**
|
237 | * This method will be called by `getQueryResultsStream()`. It is required to
|
238 | * properly set the `autoPaginate` option value.
|
239 | *
|
240 | * @private
|
241 | */
|
242 | getQueryResultsAsStream_(options: QueryResultsOptions, callback: QueryRowsCallback): void;
|
243 | /**
|
244 | * Poll for a status update. Execute the callback:
|
245 | *
|
246 | * - callback(err): Job failed
|
247 | * - callback(): Job incomplete
|
248 | * - callback(null, metadata): Job complete
|
249 | *
|
250 | * @private
|
251 | *
|
252 | * @param {function} callback
|
253 | */
|
254 | poll_(callback: MetadataCallback): void;
|
255 | }
|
256 | /**
|
257 | * Reference to the {@link Job} class.
|
258 | * @name module:@google-cloud/bigquery.Job
|
259 | * @see Job
|
260 | */
|
261 | export { Job };
|