/*! * Copyright 2019 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. */ import { Service, GoogleAuthOptions } from '@google-cloud/common'; import * as common from '@google-cloud/common'; import { ResourceStream } from '@google-cloud/paginator'; import { PreciseDate } from '@google-cloud/precise-date'; import { Dataset, DatasetOptions } from './dataset'; import { Job, JobOptions, QueryResultsOptions } from './job'; import { Table, TableField, TableSchema, TableRow, JobCallback, JobResponse, RowMetadata } from './table'; import { RetryOptions } from '@google-cloud/common/build/src/util'; import bigquery from './types'; import { setLogFunction } from './logger'; export { common }; export interface RequestCallback { (err: Error | null, response?: T | null): void; } export interface ResourceCallback { (err: Error | null, resource?: T | null, response?: R | null): void; } export type PagedResponse = [T[]] | [T[], Q | null, R]; export interface PagedCallback { (err: Error | null, resource?: T[] | null, nextQuery?: Q | null, response?: R | null): void; } export type JobRequest = J & { jobId?: string; jobPrefix?: string; location?: string; projectId?: string; reservation?: string; }; export type PagedRequest

= P & { autoPaginate?: boolean; maxApiCalls?: number; }; export type QueryResultsResponse = bigquery.IGetQueryResultsResponse | bigquery.IQueryResponse; export type QueryRowsResponse = PagedResponse; export type QueryRowsCallback = PagedCallback; export type SimpleQueryRowsResponse = [RowMetadata[], bigquery.IJob]; export type SimpleQueryRowsCallback = ResourceCallback; type JobCreationMode = bigquery.IQueryRequest['jobCreationMode']; export type Query = JobRequest & { destination?: Table; params?: any[] | { [param: string]: any; }; dryRun?: boolean; labels?: { [label: string]: string; }; types?: QueryParamTypes; job?: Job; maxResults?: number; jobTimeoutMs?: number; reservation?: string; pageToken?: string; wrapIntegers?: boolean | IntegerTypeCastOptions; parseJSON?: boolean; skipParsing?: boolean; jobCreationMode?: JobCreationMode; }; export type QueryParamTypeStruct = { [type: string]: string | string[] | QueryParamTypeStruct | QueryParamTypeStruct[]; }; export type QueryParamTypes = string[] | string[][] | QueryParamTypeStruct | QueryParamTypeStruct[]; export type QueryOptions = QueryResultsOptions; export type QueryStreamOptions = { wrapIntegers?: boolean | IntegerTypeCastOptions; parseJSON?: boolean; }; export type DatasetResource = bigquery.IDataset & { projectId?: string; }; export type ValueType = bigquery.IQueryParameterType; export type GetDatasetsOptions = PagedRequest & { projectId?: string; }; export type DatasetsResponse = PagedResponse; export type DatasetsCallback = PagedCallback; export type DatasetResponse = [Dataset, bigquery.IDataset]; export type DatasetCallback = ResourceCallback; export type GetJobsOptions = PagedRequest; export type GetJobsResponse = PagedResponse; export type GetJobsCallback = PagedCallback; export type JobsQueryResponse = [Job, bigquery.IQueryResponse]; export type JobsQueryCallback = ResourceCallback; export interface BigQueryTimeOptions { hours?: number | string; minutes?: number | string; seconds?: number | string; fractional?: number | string; } export interface BigQueryDateOptions { year?: number | string; month?: number | string; day?: number | string; } export interface BigQueryDatetimeOptions { year?: string | number; month?: string | number; day?: string | number; hours?: string | number; minutes?: string | number; seconds?: string | number; fractional?: string | number; } export interface BigQueryRangeOptions { start?: BigQueryDate | BigQueryDatetime | BigQueryTimestamp | string; end?: BigQueryDate | BigQueryDatetime | BigQueryTimestamp | string; } export type ProvidedTypeArray = Array; export interface ProvidedTypeStruct { [key: string]: string | ProvidedTypeArray | ProvidedTypeStruct; } export type QueryParameter = bigquery.IQueryParameter; export type ParameterMode = bigquery.IJobConfigurationQuery['parameterMode']; export interface BigQueryOptions extends GoogleAuthOptions { /** * Automatically retry requests if the * response is related to rate limits or certain intermittent server errors. * We will exponentially backoff subsequent requests by default. * * Defaults to `true`. * * @deprecated Use retryOptions. */ autoRetry?: boolean; /** * Maximum number of automatic retries * attempted before returning the error. * * Defaults to 3. * * @deprecated Use retryOptions. */ maxRetries?: number; /** * Customize retry configuration for all requests in the SDK. * By default, a request is retried if the response is related to rate limits * or certain intermittent server errors. * We will exponentially backoff subsequent requests by default. * * More on the default retry predicate on the `shouldRetryRequest` method: * https://github.com/googleapis/nodejs-common/blob/main/src/util.ts * * Defaults: * - retryOptions.autoRetry: true * - retryOptions.maxRetries: 3 */ retryOptions?: RetryOptions; /** * The geographic location of all datasets and * jobs referenced and created through the client. */ location?: string; /** * The value to be prepended to the User-Agent * header in API requests. */ userAgent?: string; /** * The API endpoint of the service used to make requests. * Defaults to `bigquery.googleapis.com`. */ apiEndpoint?: string; /** * The Trusted Cloud Domain (TPC) DNS of the service used to make requests. * Defaults to `googleapis.com`. */ universeDomain?: string; /** * Controls the job creation mode used when executing queries that can be * accelerated via the jobs.Query API. Users may experience performance * improvements by leveraging the JOB_CREATION_OPTIONAL mode. */ defaultJobCreationMode?: JobCreationMode; } export interface IntegerTypeCastOptions { integerTypeCastFunction: Function; fields?: string | string[]; } export type IntegerTypeCastValue = { integerValue: string | number; schemaFieldName?: string; }; export declare const PROTOCOL_REGEX: RegExp; /** * @typedef {object} BigQueryOptions * @property {string} [projectId] The project ID from the Google Developer's * Console, e.g. 'grape-spaceship-123'. We will also check the environment * variable `GCLOUD_PROJECT` for your project ID. If your app is running in * an environment which supports {@link * https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application * Application Default Credentials}, your project ID will be detected * automatically. * @property {string} [keyFilename] Full path to the a .json, .pem, or .p12 key * downloaded from the Google Developers Console. If you provide a path to a * JSON file, the `projectId` option above is not necessary. NOTE: .pem and * .p12 require you to specify the `email` option as well. * @property {string} [token] An OAUTH access token. If provided, we will not * manage fetching, re-using, and re-minting access tokens. * @property {string} [email] Account email address. Required when using a .pem * or .p12 keyFilename. * @property {object} [credentials] Credentials object. * @property {string} [credentials.client_email] * @property {string} [credentials.private_key] * @property {Constructor} [promise] Custom promise module to use instead of * native Promises. * @property {string[]} [scopes] Additional OAuth scopes to use in requests. For * example, to access an external data source, you may need the * `https://www.googleapis.com/auth/drive.readonly` scope. */ /** * In the following examples from this page and the other modules (`Dataset`, * `Table`, etc.), we are going to be using a dataset from * {@link http://goo.gl/f2SXcb| data.gov} of higher education institutions. * * We will create a table with the correct schema, import the public CSV file * into that table, and query it for data. * * @class * * See {@link https://cloud.google.com/bigquery/what-is-bigquery| What is BigQuery?} * * @param {BigQueryOptions} options Constructor options. * * @example Install the client library with npm: * ``` * npm install @google-cloud/bigquery * * ``` * @example Import the client library * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * * ``` * @example Create a client that uses Application Default Credentials (ADC): * ``` * const bigquery = new BigQuery(); * * ``` * @example Create a client with explicit credentials: * ``` * const bigquery = new BigQuery({ * projectId: 'your-project-id', * keyFilename: '/path/to/keyfile.json' * }); * * ``` * @example include:samples/quickstart.js * region_tag:bigquery_quickstart * Full quickstart example: */ export declare class BigQuery extends Service { location?: string; private _universeDomain; private _defaultJobCreationMode; createQueryStream(options?: Query | string): ResourceStream; getDatasetsStream(options?: GetDatasetsOptions): ResourceStream; getJobsStream(options?: GetJobsOptions): ResourceStream; constructor(options?: BigQueryOptions); private trace_; get universeDomain(): string; private static sanitizeEndpoint; private static sanitizeDomain; /** * Merge a rowset returned from the API with a table schema. * * @private * * @param {object} schema * @param {array} rows * @param {object} options * @param {boolean|IntegerTypeCastOptions} options.wrapIntegers Wrap values of * 'INT64' type in {@link BigQueryInt} objects. * If a `boolean`, this will wrap values in {@link BigQueryInt} objects. * If an `object`, this will return a value returned by * `wrapIntegers.integerTypeCastFunction`. * Please see {@link IntegerTypeCastOptions} for options descriptions. * @param {array} options.selectedFields List of fields to return. * If unspecified, all fields are returned. * @param {array} options.parseJSON parse a 'JSON' field into a JSON object. * @returns Fields using their matching names from the table's schema. */ static mergeSchemaWithRows_(schema: TableSchema | TableField | undefined, rows: TableRow[], options: { wrapIntegers: boolean | IntegerTypeCastOptions; selectedFields?: string[]; parseJSON?: boolean; listParams?: bigquery.tabledata.IListParams | bigquery.jobs.IGetQueryResultsParams; }): any[]; /** * The `DATE` type represents a logical calendar date, independent of time * zone. It does not represent a specific 24-hour time period. Rather, a given * DATE value represents a different 24-hour period when interpreted in * different time zones, and may represent a shorter or longer day during * Daylight Savings Time transitions. * * @param {object|string} value The date. If a string, this should be in the * format the API describes: `YYYY-[M]M-[D]D`. * Otherwise, provide an object. * @param {string|number} value.year Four digits. * @param {string|number} value.month One or two digits. * @param {string|number} value.day One or two digits. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const date = bigquery.date('2017-01-01'); * * //- * // Alternatively, provide an object. * //- * const date2 = bigquery.date({ * year: 2017, * month: 1, * day: 1 * }); * ``` */ static date(value: BigQueryDateOptions | string): BigQueryDate; /** * @param {object|string} value The date. If a string, this should be in the * format the API describes: `YYYY-[M]M-[D]D`. * Otherwise, provide an object. * @param {string|number} value.year Four digits. * @param {string|number} value.month One or two digits. * @param {string|number} value.day One or two digits. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const date = BigQuery.date('2017-01-01'); * * //- * // Alternatively, provide an object. * //- * const date2 = BigQuery.date({ * year: 2017, * month: 1, * day: 1 * }); * ``` */ date(value: BigQueryDateOptions | string): BigQueryDate; /** * A `DATETIME` data type represents a point in time. Unlike a `TIMESTAMP`, * this does not refer to an absolute instance in time. Instead, it is the * civil time, or the time that a user would see on a watch or calendar. * * @method BigQuery.datetime * @param {object|string} value The time. If a string, this should be in the * format the API describes: `YYYY-[M]M-[D]D[ [H]H:[M]M:[S]S[.DDDDDD]]`. * Otherwise, provide an object. * @param {string|number} value.year Four digits. * @param {string|number} value.month One or two digits. * @param {string|number} value.day One or two digits. * @param {string|number} [value.hours] One or two digits (`00` - `23`). * @param {string|number} [value.minutes] One or two digits (`00` - `59`). * @param {string|number} [value.seconds] One or two digits (`00` - `59`). * @param {string|number} [value.fractional] Up to six digits for microsecond * precision. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const datetime = BigQuery.datetime('2017-01-01 13:00:00'); * * //- * // Alternatively, provide an object. * //- * const datetime = BigQuery.datetime({ * year: 2017, * month: 1, * day: 1, * hours: 14, * minutes: 0, * seconds: 0 * }); * ``` */ /** * A `DATETIME` data type represents a point in time. Unlike a `TIMESTAMP`, * this does not refer to an absolute instance in time. Instead, it is the * civil time, or the time that a user would see on a watch or calendar. * * @param {object|string} value The time. If a string, this should be in the * format the API describes: `YYYY-[M]M-[D]D[ [H]H:[M]M:[S]S[.DDDDDD]]`. * Otherwise, provide an object. * @param {string|number} value.year Four digits. * @param {string|number} value.month One or two digits. * @param {string|number} value.day One or two digits. * @param {string|number} [value.hours] One or two digits (`00` - `23`). * @param {string|number} [value.minutes] One or two digits (`00` - `59`). * @param {string|number} [value.seconds] One or two digits (`00` - `59`). * @param {string|number} [value.fractional] Up to six digits for microsecond * precision. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const datetime = bigquery.datetime('2017-01-01 13:00:00'); * * //- * // Alternatively, provide an object. * //- * const datetime = bigquery.datetime({ * year: 2017, * month: 1, * day: 1, * hours: 14, * minutes: 0, * seconds: 0 * }); * ``` */ static datetime(value: BigQueryDatetimeOptions | string): BigQueryDatetime; datetime(value: BigQueryDatetimeOptions | string): BigQueryDatetime; /** * A `TIME` data type represents a time, independent of a specific date. * * @method BigQuery.time * @param {object|string} value The time. If a string, this should be in the * format the API describes: `[H]H:[M]M:[S]S[.DDDDDD]`. Otherwise, provide * an object. * @param {string|number} [value.hours] One or two digits (`00` - `23`). * @param {string|number} [value.minutes] One or two digits (`00` - `59`). * @param {string|number} [value.seconds] One or two digits (`00` - `59`). * @param {string|number} [value.fractional] Up to six digits for microsecond * precision. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const time = BigQuery.time('14:00:00'); // 2:00 PM * * //- * // Alternatively, provide an object. * //- * const time = BigQuery.time({ * hours: 14, * minutes: 0, * seconds: 0 * }); * ``` */ /** * A `TIME` data type represents a time, independent of a specific date. * * @param {object|string} value The time. If a string, this should be in the * format the API describes: `[H]H:[M]M:[S]S[.DDDDDD]`. Otherwise, provide * an object. * @param {string|number} [value.hours] One or two digits (`00` - `23`). * @param {string|number} [value.minutes] One or two digits (`00` - `59`). * @param {string|number} [value.seconds] One or two digits (`00` - `59`). * @param {string|number} [value.fractional] Up to six digits for microsecond * precision. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const time = bigquery.time('14:00:00'); // 2:00 PM * * //- * // Alternatively, provide an object. * //- * const time = bigquery.time({ * hours: 14, * minutes: 0, * seconds: 0 * }); * ``` */ static time(value: BigQueryTimeOptions | string): BigQueryTime; time(value: BigQueryTimeOptions | string): BigQueryTime; /** * A timestamp represents an absolute point in time, independent of any time * zone or convention such as Daylight Savings Time. * * The recommended input here is a `Date` or `PreciseDate` class. * If passing as a `string`, it should be Timestamp literals: https://cloud.google.com/bigquery/docs/reference/standard-sql/lexical#timestamp_literals. * When passing a `number` input, it should be epoch seconds in float representation. * * @method BigQuery.timestamp * @param {Date|string} value The time. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const timestamp = BigQuery.timestamp(new Date()); * ``` */ static timestamp(value: Date | PreciseDate | string | number): BigQueryTimestamp; /** * A timestamp represents an absolute point in time, independent of any time * zone or convention such as Daylight Savings Time. * * The recommended input here is a `Date` or `PreciseDate` class. * If passing as a `string`, it should be Timestamp literals: https://cloud.google.com/bigquery/docs/reference/standard-sql/lexical#timestamp_literals. * When passing a `number` input, it should be epoch seconds in float representation. * * @param {Date|string|string|number} value The time. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const timestamp = bigquery.timestamp(new Date()); * ``` */ timestamp(value: Date | PreciseDate | string | number): BigQueryTimestamp; /** * A range represents contiguous range between two dates, datetimes, or timestamps. * The lower and upper bound for the range are optional. * The lower bound is inclusive and the upper bound is exclusive. * * @method BigQuery.range * @param {string|BigQueryRangeOptions} value The range API string or start/end with dates/datetimes/timestamp ranges. * @param {string} elementType The range element type - DATE|DATETIME|TIMESTAMP * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const timestampRange = BigQuery.range('[2020-10-01 12:00:00+08, 2020-12-31 12:00:00+08)', 'TIMESTAMP'); * ``` */ static range(value: string | BigQueryRangeOptions, elementType?: string): BigQueryRange; /** * A range represents contiguous range between two dates, datetimes, or timestamps. * The lower and upper bound for the range are optional. * The lower bound is inclusive and the upper bound is exclusive. * * @param {string|BigQueryRangeOptions} value The range API string or start/end with dates/datetimes/timestamp ranges. * @param {string} elementType The range element type - DATE|DATETIME|TIMESTAMP * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const timestampRange = bigquery.range('[2020-10-01 12:00:00+08, 2020-12-31 12:00:00+08)', 'TIMESTAMP'); * ``` */ range(value: string, elementType?: string): BigQueryRange; /** * A BigQueryInt wraps 'INT64' values. Can be used to maintain precision. * * @param {string|number|IntegerTypeCastValue} value The INT64 value to convert. * @param {IntegerTypeCastOptions} typeCastOptions Configuration to convert * value. Must provide an `integerTypeCastFunction` to handle conversion. * @returns {BigQueryInt} * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * * const largeIntegerValue = Number.MAX_SAFE_INTEGER + 1; * * const options = { * integerTypeCastFunction: value => value.split(), * }; * * const bqInteger = bigquery.int(largeIntegerValue, options); * * const customValue = bqInteger.valueOf(); * // customValue is the value returned from your `integerTypeCastFunction`. * ``` */ static int(value: string | number | IntegerTypeCastValue, typeCastOptions?: IntegerTypeCastOptions): BigQueryInt; int(value: string | number | IntegerTypeCastValue, typeCastOptions?: IntegerTypeCastOptions): BigQueryInt; /** * A geography value represents a surface area on the Earth * in Well-known Text (WKT) format. * * @param {string} value The geospatial data. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const geography = bigquery.geography('POINT(1, 2)'); * ``` */ static geography(value: string): Geography; geography(value: string): Geography; /** * Convert an INT64 value to Number. * * @private * @param {object} value The INT64 value to convert. */ static decodeIntegerValue_(value: IntegerTypeCastValue): number; /** * Return a value's provided type. * * @private * * @throws {error} If the type provided is invalid. * * See {@link https://cloud.google.com/bigquery/data-types| Data Type} * * @param {*} providedType The type. * @returns {string} The valid type provided. */ static getTypeDescriptorFromProvidedType_(providedType: string | ProvidedTypeStruct | ProvidedTypeArray): ValueType; /** * Detect a value's type. * * @private * * @throws {error} If the type could not be detected. * * See {@link https://cloud.google.com/bigquery/data-types| Data Type} * * @param {*} value The value. * @returns {string} The type detected from the value. */ static getTypeDescriptorFromValue_(value: unknown): ValueType; /** * Convert a value into a `queryParameter` object. * * @private * * See {@link https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#request-body| Jobs.query API Reference Docs (see `queryParameters`)} * * @param {*} value The value. * @param {string|ProvidedTypeStruct|ProvidedTypeArray} providedType Provided * query parameter type. * @returns {object} A properly-formed `queryParameter` object. */ static valueToQueryParameter_(value: any, providedType?: string | ProvidedTypeStruct | ProvidedTypeArray): bigquery.IQueryParameter; private static _getValue; private static _isCustomType; /** * @callback DatasetCallback * @param {?Error} err Request error, if any. * @param {object} dataset The [dataset resource]{@link https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets#resource}. * @param {object} apiResponse The full API response. */ /** * Create a dataset. * * See {@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/insert| Datasets: insert API Documentation} * * @param {string} id ID of the dataset to create. * @param {object} [options] See a * {@link https://cloud.google.com/bigquery/docs/reference/v2/datasets#resource| Dataset resource}. * @param {DatasetCallback} [callback] The callback function. * @param {?error} callback.err An error returned while making this request * @param {Dataset} callback.dataset The newly created dataset * @param {object} callback.apiResponse The full API response. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * * bigquery.createDataset('my-dataset', function(err, dataset, apiResponse) * {}); * * //- * // If the callback is omitted, we'll return a Promise. * //- * bigquery.createDataset('my-dataset').then(function(data) { * const dataset = data[0]; * const apiResponse = data[1]; * }); * ``` */ createDataset(id: string, options?: DatasetResource): Promise; createDataset(id: string, options: DatasetResource, callback: DatasetCallback): void; createDataset(id: string, callback: DatasetCallback): void; /** * @callback JobCallback * @param {?Error} err Request error, if any. * @param {object} job The newly created job for your query. * @param {object} apiResponse The full API response. */ /** * Run a query as a job. No results are immediately returned. Instead, your * callback will be executed with a {@link Job} object that you must * ping for the results. See the Job documentation for explanations of how to * check on the status of the job. * * See {@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/insert| Jobs: insert API Documentation} * * @param {object|string} options The configuration object. This must be in * the format of the {@link https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationQuery| `configuration.query`} * property of a Jobs resource. If a string is provided, this is used as the * query string, and all other options are defaulted. * @param {Table} [options.destination] The table to save the * query's results to. If omitted, a new table will be created. * @param {boolean} [options.dryRun] If set, don't actually run this job. A * valid query will update the job with processing statistics. These can * be accessed via `job.metadata`. * @param {object} [options.labels] String key/value pairs to be attached as * labels to the newly created Job. * @param {string} [options.location] The geographic location of the job. * Required except for US and EU. * @param {number} [options.jobTimeoutMs] Job timeout in milliseconds. * If this time limit is exceeded, BigQuery might attempt to stop the job. * @param {string} [options.jobId] Custom job id. * @param {string} [options.jobPrefix] Prefix to apply to the job id. * @param {string} options.query A query string, following the BigQuery query * syntax, of the query to execute. * @param {boolean} [options.useLegacySql=false] Option to use legacy sql syntax. * @param {object} [options.defaultDataset] The dataset. This must be in * the format of the {@link https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets#DatasetReference| `DatasetReference`} * @param {boolean} [options.wrapIntegers] Optionally wrap INT64 in BigQueryInt * or custom INT64 value type. * @param {boolean} [options.parseJSON] Optionally parse JSON as a JSON Object. * @param {object|array} [options.params] Option to provide query prarameters. * @param {JobCallback} [callback] The callback function. * @param {?error} callback.err An error returned while making this request. * @param {Job} callback.job The newly created job for your query. * @param {object} callback.apiResponse The full API response. * * @throws {Error} If a query is not specified. * @throws {Error} If a Table is not provided as a destination. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * * const query = 'SELECT url FROM `publicdata.samples.github_nested` LIMIT * 100'; * * //- * // You may pass only a query string, having a new table created to store * the * // results of the query. * //- * bigquery.createQueryJob(query, function(err, job) {}); * * //- * // You can also control the destination table by providing a * // {@link Table} object. * //- * bigquery.createQueryJob({ * destination: bigquery.dataset('higher_education').table('institutions'), * query: query * }, function(err, job) {}); * * //- * // After you have run `createQueryJob`, your query will execute in a job. * Your * // callback is executed with a {@link Job} object so that you may * // check for the results. * //- * bigquery.createQueryJob(query, function(err, job) { * if (!err) { * job.getQueryResults(function(err, rows, apiResponse) {}); * } * }); * * //- * // If the callback is omitted, we'll return a Promise. * //- * bigquery.createQueryJob(query).then(function(data) { * const job = data[0]; * const apiResponse = data[1]; * * return job.getQueryResults(); * }); * ``` */ createQueryJob(options: Query | string): Promise; createQueryJob(options: Query | string, callback: JobCallback): void; private buildQueryParams_; /** * Creates a job. Typically when creating a job you'll have a very specific * task in mind. For this we recommend one of the following methods: * * - {@link BigQuery.createQueryJob} * - {@link Table#createCopyJob} * - {@link Table#createCopyFromJob} * - {@link Table#createExtractJob} * - {@link Table#createLoadJob} * * However in the event you need a finer level of control over the job * creation, you can use this method to pass in a raw {@link https://cloud.google.com/bigquery/docs/reference/rest/v2/Job| Job resource} * object. * * See {@link https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs| Jobs Overview} * See {@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/insert| Jobs: insert API Documentation} * * @param {object} options Object in the form of a {@link https://cloud.google.com/bigquery/docs/reference/rest/v2/Job| Job resource}; * @param {string} [options.jobId] Custom job id. * @param {string} [options.jobPrefix] Prefix to apply to the job id. * @param {string} [options.location] The geographic location of the job. * Required except for US and EU. * @param {JobCallback} [callback] The callback function. * @param {?error} callback.err An error returned while making this request. * @param {Job} callback.job The newly created job. * @param {object} callback.apiResponse The full API response. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * * const options = { * configuration: { * query: { * query: 'SELECT url FROM `publicdata.samples.github_nested` LIMIT 100' * } * } * }; * * bigquery.createJob(options, function(err, job) { * if (err) { * // Error handling omitted. * } * * job.getQueryResults(function(err, rows) {}); * }); * * //- * // If the callback is omitted, we'll return a Promise. * //- * bigquery.createJob(options).then(function(data) { * const job = data[0]; * * return job.getQueryResults(); * }); * ``` */ createJob(options: JobOptions): Promise; createJob(options: JobOptions, callback: JobCallback): void; /** * Create a reference to a dataset. * * @param {string} id ID of the dataset. * @param {object} [options] Dataset options. * @param {string} [options.projectId] The GCP project ID. * @param {string} [options.location] The geographic location of the dataset. * Required except for US and EU. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const dataset = bigquery.dataset('higher_education'); * ``` */ dataset(id: string, options?: DatasetOptions): Dataset; /** * List all or some of the datasets in a project. * * See {@link https://cloud.google.com/bigquery/docs/reference/v2/datasets/list| Datasets: list API Documentation} * * @param {object} [options] Configuration object. * @param {boolean} [options.all] List all datasets, including hidden ones. * @param {string} [options.projectId] The GCP project ID. * @param {boolean} [options.autoPaginate] Have pagination handled automatically. * Default: true. * @param {number} [options.maxApiCalls] Maximum number of API calls to make. * @param {number} [options.maxResults] Maximum number of results to return. * @param {string} [options.pageToken] Token returned from a previous call, to * request the next page of results. * @param {DatasetsCallback} [callback] The callback function. * @param {?error} callback.err An error returned while making this request * @param {Dataset[]} callback.datasets The list of datasets in your project. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * * bigquery.getDatasets(function(err, datasets) { * if (!err) { * // datasets is an array of Dataset objects. * } * }); * * //- * // To control how many API requests are made and page through the results * // manually, set `autoPaginate` to `false`. * //- * function manualPaginationCallback(err, datasets, nextQuery, apiResponse) { * if (nextQuery) { * // More results exist. * bigquery.getDatasets(nextQuery, manualPaginationCallback); * } * } * * bigquery.getDatasets({ * autoPaginate: false * }, manualPaginationCallback); * * //- * // If the callback is omitted, we'll return a Promise. * //- * bigquery.getDatasets().then(function(datasets) {}); * ``` */ getDatasets(options?: GetDatasetsOptions): Promise; getDatasets(options: GetDatasetsOptions, callback: DatasetsCallback): void; getDatasets(callback: DatasetsCallback): void; /** * @callback GetJobsCallback * @param {?Error} err Request error, if any. * @param {object} jobs An array of [Job]{@link https://cloud.google.com/bigquery/docs/reference/v2/Job} objects. */ /** * @typedef {array} GetJobsResponse * @property {object} 0 An array of Job objects. */ /** * Get all of the jobs from your project. * * See {@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/list| Jobs: list API Documentation} * * @param {object} [options] Configuration object. * @param {boolean} [options.allUsers] Display jobs owned by all users in the * project. * @param {boolean} [options.autoPaginate] Have pagination handled * automatically. Default: true. * @param {number} [options.maxApiCalls] Maximum number of API calls to make. * @param {number} [options.maxResults] Maximum number of results to return. * @param {string} [options.pageToken] Token returned from a previous call, to * request the next page of results. * @param {string} [options.projection] Restrict information returned to a set * of selected fields. Acceptable values are "full", for all job data, and * "minimal", to not include the job configuration. * @param {string} [options.stateFilter] Filter for job state. Acceptable * values are "done", "pending", and "running". Sending an array to this * option performs a disjunction. * @param {GetJobsCallback} [callback] The callback function. * @param {?error} callback.err An error returned while making this request * @param {Job[]} callback.jobs The list of jobs in your * project. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * * bigquery.getJobs(function(err, jobs) { * if (!err) { * // jobs is an array of Job objects. * } * }); * * //- * // To control how many API requests are made and page through the results * // manually, set `autoPaginate` to `false`. * //- * function manualPaginationCallback(err, jobs, nextQuery, apiRespose) { * if (nextQuery) { * // More results exist. * bigquery.getJobs(nextQuery, manualPaginationCallback); * } * } * * bigquery.getJobs({ * autoPaginate: false * }, manualPaginationCallback); * * //- * // If the callback is omitted, we'll return a Promise. * //- * bigquery.getJobs().then(function(data) { * const jobs = data[0]; * }); * ``` */ getJobs(options?: GetJobsOptions): Promise; getJobs(options: GetJobsOptions, callback: GetJobsCallback): void; getJobs(callback: GetJobsCallback): void; /** * Create a reference to an existing job. * * @param {string} id ID of the job. * @param {object} [options] Configuration object. * @param {string} [options.location] The geographic location of the job. * Required except for US and EU. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * * const myExistingJob = bigquery.job('job-id'); * ``` */ job(id: string, options?: JobOptions): Job; /** * Run a query scoped to your project. For manual pagination please refer to * {@link BigQuery.createQueryJob}. * * See {@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/query| Jobs: query API Documentation} * * @param {string|object} query A string SQL query or configuration object. * For all available options, see * {@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/query#request-body| Jobs: query request body}. * @param {string} [query.location] The geographic location of the job. * Required except for US and EU. * @param {string} [query.jobId] Custom id for the underlying job. * @param {string} [query.jobPrefix] Prefix to apply to the underlying job id. * @param {object|Array<*>} query.params For positional SQL parameters, provide * an array of values. For named SQL parameters, provide an object which * maps each named parameter to its value. The supported types are * integers, floats, {@link BigQuery.date} objects, {@link BigQuery.datetime} * objects, {@link BigQuery.time} objects, {@link BigQuery.timestamp} * objects, Strings, Booleans, and Objects. * @param {string} query.query A query string, following the BigQuery query * syntax, of the query to execute. * @param {object|Array<*>} query.types Provided types for query parameters. * For positional SQL parameters, provide an array of types. For named * SQL parameters, provide an object which maps each named parameter to * its type. * @param {boolean} [query.useLegacySql=false] Option to use legacy sql syntax. * @param {object} [options] Configuration object for query results. * @param {number} [options.maxResults] Maximum number of results to read. * @param {number} [options.timeoutMs] How long to wait for the query to * complete, in milliseconds, before returning. Default is 10 seconds. * If the timeout passes before the job completes, an error will be returned * and the 'jobComplete' field in the response will be false. * @param {boolean|IntegerTypeCastOptions} [options.wrapIntegers=false] Wrap values * of 'INT64' type in {@link BigQueryInt} objects. * If a `boolean`, this will wrap values in {@link BigQueryInt} objects. * If an `object`, this will return a value returned by * `wrapIntegers.integerTypeCastFunction`. * Please see {@link IntegerTypeCastOptions} for options descriptions. * @param {function} [callback] The callback function. * @param {?error} callback.err An error returned while making this request * @param {array} callback.rows The list of results from your query. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * * const query = 'SELECT url FROM `publicdata.samples.github_nested` LIMIT * 100'; * * bigquery.query(query, function(err, rows) { * if (!err) { * // rows is an array of results. * } * }); * * //- * // Positional SQL parameters are supported. * //- * bigquery.query({ * query: [ * 'SELECT url', * 'FROM `publicdata.samples.github_nested`', * 'WHERE repository.owner = ?' * ].join(' '), * * params: [ * 'google' * ] * }, function(err, rows) {}); * * //- * // Or if you prefer to name them, that's also supported. * //- * bigquery.query({ * query: [ * 'SELECT url', * 'FROM `publicdata.samples.github_nested`', * 'WHERE repository.owner = @owner' * ].join(' '), * params: { * owner: 'google' * } * }, function(err, rows) {}); * * //- * // Providing types for SQL parameters is supported. * //- * bigquery.query({ * query: [ * 'SELECT url', * 'FROM `publicdata.samples.github_nested`', * 'WHERE repository.owner = ?' * ].join(' '), * * params: [ * null * ], * * types: ['string'] * }, function(err, rows) {}); * * //- * // If you need to use a `DATE`, `DATETIME`, `TIME`, or `TIMESTAMP` type in * // your query, see {@link BigQuery.date}, {@link BigQuery.datetime}, * // {@link BigQuery.time}, and {@link BigQuery.timestamp}. * //- * * //- * // If the callback is omitted, we'll return a Promise. * //- * bigquery.query(query).then(function(data) { * const rows = data[0]; * }); * ``` */ query(query: string, options?: QueryOptions): Promise; query(query: Query, options?: QueryOptions): Promise; query(query: string, options: QueryOptions, callback?: QueryRowsCallback): void; query(query: Query, options: QueryOptions, callback?: SimpleQueryRowsCallback): void; query(query: string, callback?: QueryRowsCallback): void; query(query: Query, callback?: SimpleQueryRowsCallback): void; /** * Check if the given Query can run using the `jobs.query` endpoint. * Returns a bigquery.IQueryRequest that can be used to call `jobs.query`. * Return undefined if is not possible to convert to a bigquery.IQueryRequest. * * @param query string | Query * @param options QueryOptions * @returns bigquery.IQueryRequest | undefined */ private buildQueryRequest_; private runJobsQuery; /** * This method will be called by `createQueryStream()`. It is required to * properly set the `autoPaginate` option value. * * @private */ queryAsStream_(query: Query, callback?: SimpleQueryRowsCallback): void; static setLogFunction: typeof setLogFunction; } /** * Range class for BigQuery. * A range represents contiguous range between two dates, datetimes, or timestamps. * The lower and upper bound for the range are optional. * The lower bound is inclusive and the upper bound is exclusive. * See https://cloud.google.com/bigquery/docs/reference/standard-sql/lexical#range_literals */ export declare class BigQueryRange { elementType?: string; start?: BigQueryTimestamp | BigQueryDate | BigQueryDatetime; end?: BigQueryTimestamp | BigQueryDate | BigQueryDatetime; constructor(value: string | BigQueryRangeOptions, elementType?: string); get apiValue(): string; get literalValue(): string; get value(): { start: string; end: string; }; /** * This method returns start and end values for RANGE typed values returned from * the server. It decodes the server RANGE value into start and end values so * they can be used to construct a BigQueryRange. * @private * @param {string} value The range value. * @returns {string[]} The start and end of the range. */ private static fromStringValue_; /** * This method is only used by convertSchemaFieldValue and only when range * values are passed into convertSchemaFieldValue. It produces a value that is * delivered to the user for read calls and it needs to pass along listParams * to ensure TIMESTAMP types are converted properly. * @private * @param {string} value The range value. * @param {string} elementType The element type. * @param {bigquery.tabledata.IListParams | bigquery.jobs.IGetQueryResultsParams} [listParams] The list parameters. * @returns {BigQueryRange} */ static fromSchemaValue_(value: string, elementType: string, listParams?: bigquery.tabledata.IListParams | bigquery.jobs.IGetQueryResultsParams): BigQueryRange; private convertElement_; } /** * Date class for BigQuery. */ export declare class BigQueryDate { value: string; constructor(value: BigQueryDateOptions | string); } /** * Geography class for BigQuery. */ export declare class Geography { value: string; constructor(value: string); } /** * Timestamp class for BigQuery. * * The recommended input here is a `Date` or `PreciseDate` class. * If passing as a `string`, it should be Timestamp literals: https://cloud.google.com/bigquery/docs/reference/standard-sql/lexical#timestamp_literals. * When passing a `number` input, it should be epoch seconds in float representation. * */ export declare class BigQueryTimestamp { value: string; constructor(value: Date | PreciseDate | string | number); fromFloatValue_(value: number): PreciseDate; } /** * Datetime class for BigQuery. */ export declare class BigQueryDatetime { value: string; constructor(value: BigQueryDatetimeOptions | string); } /** * Time class for BigQuery. */ export declare class BigQueryTime { value: string; constructor(value: BigQueryTimeOptions | string); } /** * Build a BigQueryInt object. For long integers, a string can be provided. * * @class * @param {string|number|IntegerTypeCastValue} value The 'INT64' value. * @param {object} [typeCastOptions] Configuration to convert * values of 'INT64' type to a custom value. Must provide an * `integerTypeCastFunction` to handle conversion. * @param {function} typeCastOptions.integerTypeCastFunction A custom user * provided function to convert value. * @param {string|string[]} [typeCastOptions.fields] Schema field * names to be converted using `integerTypeCastFunction`. * * @example * ``` * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const anInt = bigquery.int(7); * ``` */ export declare class BigQueryInt extends Number { type: string; value: string; typeCastFunction?: Function; private _schemaFieldName; constructor(value: string | number | IntegerTypeCastValue, typeCastOptions?: IntegerTypeCastOptions); valueOf(): any; toJSON(): Json; } export interface Json { [field: string]: string; }