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

= P & { autoPaginate?: boolean; maxApiCalls?: number; }; export declare type QueryRowsResponse = PagedResponse; export declare type QueryRowsCallback = PagedCallback; export declare type SimpleQueryRowsResponse = [RowMetadata[], bigquery.IJob]; export declare type SimpleQueryRowsCallback = ResourceCallback; export declare type Query = JobRequest & { destination?: Table; params?: any[] | { [param: string]: any; }; dryRun?: boolean; labels?: { [label: string]: string; }; types?: string[] | string[][] | { [type: string]: string | string[]; }; job?: Job; maxResults?: number; jobTimeoutMs?: number; pageToken?: string; wrapIntegers?: boolean | IntegerTypeCastOptions; }; export declare type QueryOptions = QueryResultsOptions; export declare type QueryStreamOptions = { wrapIntegers?: boolean | IntegerTypeCastOptions; }; export declare type DatasetResource = bigquery.IDataset; export declare type ValueType = bigquery.IQueryParameterType; export declare type GetDatasetsOptions = PagedRequest; export declare type DatasetsResponse = PagedResponse; export declare type DatasetsCallback = PagedCallback; export declare type DatasetResponse = [Dataset, bigquery.IDataset]; export declare type DatasetCallback = ResourceCallback; export declare type GetJobsOptions = PagedRequest; export declare type GetJobsResponse = PagedResponse; export declare type GetJobsCallback = PagedCallback; 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 declare type ProvidedTypeArray = Array; export interface ProvidedTypeStruct { [key: string]: string | ProvidedTypeArray | ProvidedTypeStruct; } export declare type QueryParameter = bigquery.IQueryParameter; export interface BigQueryOptions extends common.GoogleAuthOptions { autoRetry?: boolean; maxRetries?: number; location?: string; userAgent?: string; /** * The API endpoint of the service used to make requests. * Defaults to `bigquery.googleapis.com`. */ apiEndpoint?: string; } export interface IntegerTypeCastOptions { integerTypeCastFunction: Function; fields?: string | string[]; } export declare 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 {boolean} [autoRetry=true] Automatically retry requests if the * response is related to rate limits or certain intermittent server errors. * We will exponentially backoff subsequent requests by default. * @property {number} [maxRetries=3] Maximum number of automatic retries * attempted before returning the error. * @property {Constructor} [promise] Custom promise module to use instead of * native Promises. * @property {string} [location] The geographic location of all datasets and * jobs referenced and created through the client. * @property {string} [userAgent] The value to be prepended to the User-Agent * header in API requests. * @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. * @property {string=} apiEndpoint The API endpoint of the service used to make requests. Defaults to `bigquery.googleapis.com`. */ /** * In the following examples from this page and the other modules (`Dataset`, * `Table`, etc.), we are going to be using a dataset from * [data.gov](http://goo.gl/f2SXcb) 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 [What is BigQuery?]{@link https://cloud.google.com/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 common.Service { location?: string; createQueryStream: (options?: Query | string) => ResourceStream; getDatasetsStream: (options?: GetDatasetsOptions) => ResourceStream; getJobsStream: (options?: GetJobsOptions) => ResourceStream; constructor(options?: BigQueryOptions); private static sanitizeEndpoint; /** * Merge a rowset returned from the API with a table schema. * * @private * * @param {object} schema * @param {array} rows * @param {boolean|IntegerTypeCastOptions} 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} selectedFields List of fields to return. * If unspecified, all fields are returned. * @returns {array} Fields using their matching names from the table's schema. */ static mergeSchemaWithRows_(schema: TableSchema | TableField, rows: TableRow[], wrapIntegers: boolean | IntegerTypeCastOptions, selectedFields?: string[]): 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. * @returns {BigQueryDate} * * @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. * @returns {BigQueryDatetime} * * @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. * * @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 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. * @returns {BigQueryTime} * * @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. * * @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 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. * * @method BigQuery.timestamp * @param {Date|string} value The time. * * @example * const {BigQuery} = require('@google-cloud/bigquery'); * const timestamp = BigQuery.timestamp(new Date()); */ /** * A timestamp represents an absolute point in time, independent of any time * zone or convention such as Daylight Savings Time. * * @method BigQuery#timestamp * @param {Date|string} value The time. * @returns {BigQueryTimestamp} * * @example * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const timestamp = bigquery.timestamp(new Date()); */ static timestamp(value: Date | string): BigQueryTimestamp; timestamp(value: Date | string): BigQueryTimestamp; /** * A BigQueryInt wraps 'INT64' values. Can be used to maintain precision. * * @method BigQuery#int * @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. * * @method BigQuery.geography * @param {string} value The geospatial data. * * @example * const {BigQuery} = require('@google-cloud/bigquery'); * const geography = BigQuery.geography('POINT(1, 2)'); */ /** * A geography value represents a surface area on the Earth * in Well-known Text (WKT) format. * * @method BigQuery#geography * @param {string} value The geospatial data. * @returns {Geography} * * @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 [Data Type]{@link https://cloud.google.com/bigquery/data-types} * * @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 [Data Type]{@link https://cloud.google.com/bigquery/data-types} * * @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 [Jobs.query API Reference Docs (see `queryParameters`)]{@link https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#request-body} * * @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; createDataset(id: string, options?: DatasetResource): Promise; createDataset(id: string, options: DatasetResource, callback: DatasetCallback): void; createDataset(id: string, callback: DatasetCallback): void; createQueryJob(options: Query | string): Promise; createQueryJob(options: Query | string, callback: JobCallback): void; 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.location] The geographic location of the dataset. * Required except for US and EU. * @returns {Dataset} * * @example * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * const dataset = bigquery.dataset('higher_education'); */ dataset(id: string, options?: DatasetOptions): Dataset; getDatasets(options?: GetDatasetsOptions): Promise; getDatasets(options: GetDatasetsOptions, callback: DatasetsCallback): void; getDatasets(callback: DatasetsCallback): void; 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. * @returns {Job} * * @example * const {BigQuery} = require('@google-cloud/bigquery'); * const bigquery = new BigQuery(); * * const myExistingJob = bigquery.job('job-id'); */ job(id: string, options?: JobOptions): Job; 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; /** * This method will be called by `createQueryStream()`. It is required to * properly set the `autoPaginate` option value. * * @private */ queryAsStream_(query: Query, optionsOrCallback?: QueryStreamOptions, cb?: SimpleQueryRowsCallback): void; } /** * 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. */ export declare class BigQueryTimestamp { value: string; constructor(value: Date | string); } /** * 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; }