@google-cloud/bigquery/build/src/table.d.ts

/*!
 * Copyright 2014 Google Inc. All Rights Reserved.
 *
 * 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.
 */
/// <reference types="node" />
import * as common from '@google-cloud/common';
import { ResourceStream } from '@google-cloud/paginator';
import { BigQuery, Job, Dataset, Query, SimpleQueryRowsResponse, SimpleQueryRowsCallback, ResourceCallback, RequestCallback, PagedResponse, PagedCallback, JobRequest, PagedRequest } from '.';
import { Duplex, Writable } from 'stream';
import { JobMetadata } from './job';
import bigquery from './types';
import { IntegerTypeCastOptions } from './bigquery';
export interface File {
    bucket: any;
    kmsKeyName?: string;
    userProject?: string;
    name: string;
    generation?: number;
}
export declare type JobMetadataCallback = RequestCallback<JobMetadata>;
export declare type JobMetadataResponse = [JobMetadata];
export declare type RowMetadata = any;
export declare type InsertRowsOptions = bigquery.ITableDataInsertAllRequest & {
    createInsertId?: boolean;
    partialRetries?: number;
    raw?: boolean;
    schema?: string | {};
};
export declare type InsertRowsResponse = [bigquery.ITableDataInsertAllResponse | bigquery.ITable];
export declare type InsertRowsCallback = RequestCallback<bigquery.ITableDataInsertAllResponse | bigquery.ITable>;
export declare type RowsResponse = PagedResponse<RowMetadata, GetRowsOptions, bigquery.ITableDataList | bigquery.ITable>;
export declare type RowsCallback = PagedCallback<RowMetadata, GetRowsOptions, bigquery.ITableDataList | bigquery.ITable>;
export interface InsertRow {
    insertId?: string;
    json?: bigquery.IJsonObject;
}
export declare type TableRow = bigquery.ITableRow;
export declare type TableRowField = bigquery.ITableCell;
export declare type TableRowValue = string | TableRow;
export declare type GetRowsOptions = PagedRequest<bigquery.tabledata.IListParams> & {
    wrapIntegers?: boolean | IntegerTypeCastOptions;
};
export declare type JobLoadMetadata = JobRequest<bigquery.IJobConfigurationLoad> & {
    format?: string;
};
export declare type CreateExtractJobOptions = JobRequest<bigquery.IJobConfigurationExtract> & {
    format?: 'CSV' | 'JSON' | 'AVRO' | 'PARQUET' | 'ORC';
    gzip?: boolean;
};
export declare type JobResponse = [Job, bigquery.IJob];
export declare type JobCallback = ResourceCallback<Job, bigquery.IJob>;
export declare type CreateCopyJobMetadata = CopyTableMetadata;
export declare type SetTableMetadataOptions = TableMetadata;
export declare type CopyTableMetadata = JobRequest<bigquery.IJobConfigurationTableCopy>;
export declare type TableMetadata = bigquery.ITable & {
    name?: string;
    schema?: string | TableField[] | TableSchema;
    partitioning?: string;
    view?: string | ViewDefinition;
};
export declare type ViewDefinition = bigquery.IViewDefinition;
export declare type FormattedMetadata = bigquery.ITable;
export declare type TableSchema = bigquery.ITableSchema;
export declare type TableField = bigquery.ITableFieldSchema;
export interface PartialInsertFailure {
    message: string;
    reason: string;
    row: RowMetadata;
}
export declare type Policy = bigquery.IPolicy;
export declare type GetPolicyOptions = bigquery.IGetPolicyOptions;
export declare type SetPolicyOptions = Omit<bigquery.ISetIamPolicyRequest, 'policy'>;
export declare type PolicyRequest = bigquery.IGetIamPolicyRequest;
export declare type PolicyResponse = [Policy];
export declare type PolicyCallback = RequestCallback<PolicyResponse>;
export declare type PermissionsResponse = [bigquery.ITestIamPermissionsResponse];
export declare type PermissionsCallback = RequestCallback<PermissionsResponse>;
export interface TableOptions {
    location?: string;
}
/**
 * Table objects are returned by methods such as
 * {@link Dataset#table}, {@link Dataset#createTable}, and
 * {@link Dataset#getTables}.
 *
 * @class
 * @param {Dataset} dataset {@link Dataset} instance.
 * @param {string} id The ID of the table.
 * @param {object} [options] Table options.
 * @param {string} [options.location] The geographic location of the table, by
 *      default this value is inherited from the dataset. This can be used to
 *      configure the location of all jobs created through a table instance. It
 *      cannot be used to set the actual location of the table. This value will
 *      be superseded by any API responses containing location data for the
 *      table.
 *
 * @example
 * const {BigQuery} = require('@google-cloud/bigquery');
 * const bigquery = new BigQuery();
 * const dataset = bigquery.dataset('my-dataset');
 *
 * const table = dataset.table('my-table');
 */
declare class Table extends common.ServiceObject {
    dataset: Dataset;
    bigQuery: BigQuery;
    location?: string;
    createReadStream: (options?: GetRowsOptions) => ResourceStream<RowMetadata>;
    constructor(dataset: Dataset, id: string, options?: TableOptions);
    /**
     * Convert a comma-separated name:type string to a table schema object.
     *
     * @static
     * @private
     *
     * @param {string} str Comma-separated schema string.
     * @returns {object} Table schema in the format the API expects.
     */
    static createSchemaFromString_(str: string): TableSchema;
    /**
     * Convert a row entry from native types to their encoded types that the API
     * expects.
     *
     * @static
     * @private
     *
     * @param {*} value The value to be converted.
     * @returns {*} The converted value.
     */
    static encodeValue_(value?: {} | null): {} | null;
    /**
     * @private
     */
    static formatMetadata_(options: TableMetadata): FormattedMetadata;
    copy(destination: Table, metadata?: CopyTableMetadata): Promise<JobMetadataResponse>;
    copy(destination: Table, metadata: CopyTableMetadata, callback: JobMetadataCallback): void;
    copy(destination: Table, callback: JobMetadataCallback): void;
    copyFrom(sourceTables: Table | Table[], metadata?: CopyTableMetadata): Promise<JobMetadataResponse>;
    copyFrom(sourceTables: Table | Table[], metadata: CopyTableMetadata, callback: JobMetadataCallback): void;
    copyFrom(sourceTables: Table | Table[], callback: JobMetadataCallback): void;
    createCopyJob(destination: Table, metadata?: CreateCopyJobMetadata): Promise<JobResponse>;
    createCopyJob(destination: Table, metadata: CreateCopyJobMetadata, callback: JobCallback): void;
    createCopyJob(destination: Table, callback: JobCallback): void;
    createCopyFromJob(source: Table | Table[], metadata?: CopyTableMetadata): Promise<JobResponse>;
    createCopyFromJob(source: Table | Table[], metadata: CopyTableMetadata, callback: JobCallback): void;
    createCopyFromJob(source: Table | Table[], callback: JobCallback): void;
    createExtractJob(destination: File, options?: CreateExtractJobOptions): Promise<JobResponse>;
    createExtractJob(destination: File, options: CreateExtractJobOptions, callback: JobCallback): void;
    createExtractJob(destination: File, callback: JobCallback): void;
    createLoadJob(source: string | File, metadata?: JobLoadMetadata): Promise<JobResponse>;
    createLoadJob(source: string | File, metadata: JobLoadMetadata, callback: JobCallback): void;
    createLoadJob(source: string | File, callback: JobCallback): void;
    /**
     * @param {string | File | File[]} source
     * @param {JobLoadMetadata} metadata
     * @returns {Promise<JobResponse>}
     * @private
     */
    _createLoadJob(source: string | File | File[], metadata: JobLoadMetadata): Promise<JobResponse>;
    createQueryJob(options: Query): Promise<JobResponse>;
    createQueryJob(options: Query, callback: JobCallback): void;
    /**
     * Run a query scoped to your dataset as a readable object stream.
     *
     * See {@link BigQuery#createQueryStream} for full documentation of this
     * method.
     *
     * @param {object} query See {@link BigQuery#createQueryStream} for full
     *     documentation of this method.
     * @returns {stream} See {@link BigQuery#createQueryStream} for full
     *     documentation of this method.
     */
    createQueryStream(query: Query): Duplex;
    /**
     * Creates a write stream. Unlike the public version, this will not
     * automatically poll the underlying job.
     *
     * @private
     *
     * @param {string|object} [metadata] Metadata to set with the load operation.
     *     The metadata object should be in the format of the
     *     [`configuration.load`](https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad)
     * property of a Jobs resource. If a string is given, it will be used
     * as the filetype.
     * @param {string} [metadata.jobId] Custom job id.
     * @param {string} [metadata.jobPrefix] Prefix to apply to the job id.
     * @returns {WritableStream}
     */
    createWriteStream_(metadata: JobLoadMetadata | string): Writable;
    /**
     * Load data into your table from a readable stream of AVRO, CSV, JSON, ORC,
     * or PARQUET data.
     *
     * @see [Jobs: insert API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/insert}
     *
     * @param {string|object} [metadata] Metadata to set with the load operation.
     *     The metadata object should be in the format of the
     *     [`configuration.load`](https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad)
     * property of a Jobs resource. If a string is given,
     * it will be used as the filetype.
     * @param {string} [metadata.jobId] Custom job id.
     * @param {string} [metadata.jobPrefix] Prefix to apply to the job id.
     * @returns {WritableStream}
     *
     * @throws {Error} If source format isn't recognized.
     *
     * @example
     * const {BigQuery} = require('@google-cloud/bigquery');
     * const bigquery = new BigQuery();
     * const dataset = bigquery.dataset('my-dataset');
     * const table = dataset.table('my-table');
     *
     * //-
     * // Load data from a CSV file.
     * //-
     * const request = require('request');
     *
     * const csvUrl = 'http://goo.gl/kSE7z6';
     *
     * const metadata = {
     *   allowJaggedRows: true,
     *   skipLeadingRows: 1
     * };
     *
     * request.get(csvUrl)
     *   .pipe(table.createWriteStream(metadata))
     *   .on('job', (job) => {
     *     // `job` is a Job object that can be used to check the status of the
     *     // request.
     *   })
     *   .on('complete', (job) => {
     *     // The job has completed successfully.
     *   });
     *
     * //-
     * // Load data from a JSON file.
     * //-
     * const fs = require('fs');
     *
     * fs.createReadStream('./test/testdata/testfile.json')
     *   .pipe(table.createWriteStream('json'))
     *   .on('job', (job) => {
     *     // `job` is a Job object that can be used to check the status of the
     *     // request.
     *   })
     *   .on('complete', (job) => {
     *     // The job has completed successfully.
     *   });
     */
    createWriteStream(metadata: JobLoadMetadata | string): Writable;
    extract(destination: File, options?: CreateExtractJobOptions): Promise<JobMetadataResponse>;
    extract(destination: File, options: CreateExtractJobOptions, callback?: JobMetadataCallback): void;
    extract(destination: File, callback?: JobMetadataCallback): void;
    getRows(options?: GetRowsOptions): Promise<RowsResponse>;
    getRows(options: GetRowsOptions, callback: RowsCallback): void;
    getRows(callback: RowsCallback): void;
    insert(rows: RowMetadata | RowMetadata[], options?: InsertRowsOptions): Promise<InsertRowsResponse>;
    insert(rows: RowMetadata | RowMetadata[], options: InsertRowsOptions, callback: InsertRowsCallback): void;
    insert(rows: RowMetadata | RowMetadata[], callback: InsertRowsCallback): void;
    /**
     * Insert rows with retries, but will create the table if not exists.
     *
     * @param {RowMetadata | RowMetadata[]} rows
     * @param {InsertRowsOptions} options
     * @returns {Promise<bigquery.ITableDataInsertAllResponse | bigquery.ITable>}
     * @private
     */
    private _insertAndCreateTable;
    /**
     * This method will attempt to insert rows while retrying any partial failures
     * that occur along the way. Because partial insert failures are returned
     * differently, we can't depend on our usual retry strategy.
     *
     * @private
     *
     * @param {RowMetadata|RowMetadata[]} rows The rows to insert.
     * @param {InsertRowsOptions} options Insert options.
     * @returns {Promise<bigquery.ITableDataInsertAllResponse>}
     */
    private _insertWithRetry;
    /**
     * This method does the bulk of the work for processing options and making the
     * network request.
     *
     * @private
     *
     * @param {RowMetadata|RowMetadata[]} rows The rows to insert.
     * @param {InsertRowsOptions} options Insert options.
     * @returns {Promise<bigquery.ITableDataInsertAllResponse>}
     */
    private _insert;
    load(source: string | File, metadata?: JobLoadMetadata): Promise<JobMetadataResponse>;
    load(source: string | File, metadata: JobLoadMetadata, callback: JobMetadataCallback): void;
    load(source: string | File, callback: JobMetadataCallback): void;
    query(query: Query): Promise<SimpleQueryRowsResponse>;
    query(query: string): Promise<SimpleQueryRowsResponse>;
    query(query: Query, callback: SimpleQueryRowsCallback): void;
    setMetadata(metadata: SetTableMetadataOptions): Promise<common.SetMetadataResponse>;
    setMetadata(metadata: SetTableMetadataOptions, callback: common.ResponseCallback): void;
    getIamPolicy(optionsOrCallback?: GetPolicyOptions | PolicyCallback): Promise<PolicyResponse>;
    getIamPolicy(options: GetPolicyOptions, callback: PolicyCallback): void;
    setIamPolicy(policy: Policy, options?: SetPolicyOptions): Promise<PolicyResponse>;
    setIamPolicy(policy: Policy, options: SetPolicyOptions, callback: PolicyCallback): void;
    setIamPolicy(policy: Policy, callback: PolicyCallback): void;
    testIamPermissions(permissions: string | string[]): Promise<PermissionsResponse>;
    testIamPermissions(permissions: string | string[], callback: PermissionsCallback): void;
}
/**
 * Reference to the {@link Table} class.
 * @name module:@google-cloud/bigquery.Table
 * @see Table
 */
export { Table };