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

Google BigQuery Client Library for Node.js

/*!
 * Copyright 2026 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 { ResourceStream } from '@google-cloud/paginator';
import type { RecordBatch, Schema } from 'apache-arrow';
import type { BigQuery, Query } from './bigquery';
import type bigquery from './types';
type ArrowModule = typeof import('apache-arrow');
interface ReadRowsStream extends NodeJS.EventEmitter {
    cancel(): void;
    pause(): void;
    resume(): void;
}
interface IReadSession {
    arrowSchema?: {
        serializedSchema?: Uint8Array | string | null;
    } | null;
    streams?: Array<{
        name?: string | null;
    }> | null;
}
/**
 * The `CreateReadSession` request that {@link BigQuery#createQueryArrowStream}
 * sends. Exported for tests.
 *
 * @private
 */
export interface CreateReadSessionRequest {
    parent: string;
    readSession: {
        table: string;
        dataFormat: 'ARROW';
        readOptions?: {
            arrowSerializationOptions?: ArrowSerializationOptions;
        };
    };
    maxStreamCount: number;
}
/**
 * The part of `@google-cloud/bigquery-storage`'s `BigQueryReadClient` that
 * {@link BigQuery#createQueryArrowStream} uses. Exported for tests.
 *
 * @private
 */
export interface BigQueryReadClient {
    createReadSession(request: CreateReadSessionRequest): Promise<[IReadSession, ...unknown[]]>;
    readRows(request: {
        readStream: string;
        offset?: number;
        arrowSerializationOptions?: ArrowSerializationOptions;
    }): ReadRowsStream;
}
/**
 * The part of the `@google-cloud/bigquery-storage` module that
 * {@link BigQuery#createQueryArrowStream} uses. Exported for tests.
 *
 * @private
 */
export interface StorageModule {
    BigQueryReadClient: new (options?: Record<string, unknown>) => BigQueryReadClient;
}
/**
 * [Beta] A stream of Apache Arrow `RecordBatch` objects returned by
 * {@link BigQuery#createQueryArrowStream}.
 *
 * `queryId` and `jobReference` are set once BigQuery responds to the query,
 * before the first batch is emitted.
 *
 * @beta
 */
export type ArrowRecordBatchStream = ResourceStream<RecordBatch> & {
    /** The query ID, when the query runs through `jobs.query`. */
    queryId?: string;
    /** The job reference, when BigQuery creates a job for the query. */
    jobReference?: bigquery.IJobReference;
};
/**
 * [Beta] Options for {@link BigQuery#createQueryArrowStream}: the
 * {@link Query} options plus options that only apply to Arrow queries.
 *
 * @beta
 */
export type ArrowQuery = Query & {
    /**
     * How long to wait for the query to complete, in milliseconds. If it doesn't
     * complete in time, the stream fails. If unset or 0, the stream waits until
     * the job completes.
     */
    timeoutMs?: number;
    /**
     * Arrow serialization options sent on `jobs.query`, `ReadRows`, and
     * `CreateReadSession`, such as `picosTimestampPrecision`. Buffer compression
     * isn't supported.
     */
    arrowSerializationOptions?: ArrowSerializationOptions;
};
/**
 * [Beta] Arrow serialization options for
 * {@link BigQuery#createQueryArrowStream}.
 *
 * @beta
 */
export type ArrowSerializationOptions = bigquery.IArrowSerializationOptions;
/**
 * Loads `apache-arrow` and the optional `@google-cloud/bigquery-storage`
 * (>= 6.3.0) package, verifying the latter's version.
 *
 * `apache-arrow` is a regular dependency, so its version is guaranteed by
 * `package.json`. It is loaded lazily so that only Arrow callers pay for it.
 *
 * @private
 */
export declare function checkArrowDependencies(requireFn?: NodeRequire): {
    arrow: ArrowModule;
    storage: StorageModule;
};
/**
 * Returns the shared `BigQueryReadClient` for a `BigQuery` instance, creating
 * it lazily on first use with the `BigQuery` client's credentials, universe
 * domain, and gRPC keepalive settings.
 *
 * @private
 */
export declare function getStorageReadClient(bq: BigQuery, storage: StorageModule): BigQueryReadClient;
/**
 * Creates a 0-row `RecordBatch` that preserves the provided Arrow `Schema`.
 *
 * @private
 */
export declare function createEmptyRecordBatch(arrow: ArrowModule, schema: Schema): RecordBatch;
/**
 * Decodes serialized Arrow IPC schema and record batch bytes into `RecordBatch`
 * objects, emitting a single 0-row `RecordBatch` (preserving `schema` when
 * present) if no record batches are present.
 *
 * @private
 */
export declare function decodeArrowPayload(arrow: ArrowModule, serializedSchema?: Uint8Array | string, serializedRecordBatch?: Uint8Array | string): RecordBatch[];
/**
 * Executes a query and returns a stream of `apache-arrow` `RecordBatch` objects.
 *
 * @private
 */
export declare function createQueryArrowStream_(bq: BigQuery, query?: ArrowQuery | string): ArrowRecordBatchStream;
export {};