import type { Column } from "./columns.ts";
import type { Block } from "./index.ts";
import type { ColumnDef } from "./types.ts";
/**
 * Brand keyed in the global symbol registry so `isRecordBatch` recognizes
 * instances across separate module copies (ESM vs CJS, source vs bundled dist).
 * Plain `instanceof` fails the moment two copies of this class coexist; the
 * brand survives because `Symbol.for` returns one symbol process-wide.
 */
declare const RECORD_BATCH_BRAND: unique symbol;
/** Options for materializing row data. */
export interface MaterializeOptions {
    /** Convert bigint values (Int64, UInt64, Int128, etc.) to strings. */
    bigIntAsString?: boolean;
}
/**
 * A Row object is a Proxy that lazily accesses column data.
 *
 * Performance note: Each `row.field` access goes through a Proxy trap and
 * Map lookup. For hot loops, prefer:
 * - `batch.toArray()` for full materialization
 * - `batch.getColumn(name)` + column iteration for columnar access
 * - `batch.getAt(rowIndex, colIndex)` for direct value access
 */
export type Row = Record<string, unknown> & {
    /** Materialize row to a plain object. */
    toObject(options?: MaterializeOptions): Record<string, unknown>;
    /** Materialize row to a plain array in column order. */
    toArray(options?: MaterializeOptions): unknown[];
};
/**
 * RecordBatch provides an ergonomic, virtual view over columnar ClickHouse data.
 * Matches Apache Arrow terminology - a single batch of records with shared schema.
 */
export declare class RecordBatch implements Iterable<Row> {
    readonly columns: ColumnDef[];
    readonly columnData: Column[];
    readonly rowCount: number;
    readonly decodeTimeMs?: number;
    /** @internal */ nameToIndex: Map<string, number>;
    private _columnNames;
    constructor(block: Block);
    static from(block: Block): RecordBatch;
    /** Prototype-level brand; see RECORD_BATCH_BRAND. */
    get [RECORD_BATCH_BRAND](): true;
    /**
     * Identity-independent RecordBatch check. Prefer this over `instanceof` for
     * dispatching on user-supplied data: it stays correct when the batch was
     * created by a different copy of this module (ESM/CJS or source/dist split).
     */
    static isRecordBatch(value: unknown): value is RecordBatch;
    get length(): number;
    get numCols(): number;
    get schema(): ColumnDef[];
    get columnNames(): string[];
    /** Get column by name. */
    getColumn(name: string): Column | undefined;
    /** Get column by index. */
    getColumnAt(index: number): Column | undefined;
    /** Get value at specific row and column index. Allocation-free. */
    getAt(rowIndex: number, colIndex: number): unknown;
    /** Get row at index (returns a lazy Proxy). */
    get(index: number, options?: MaterializeOptions): Row;
    /** Iterate over rows lazily. Default iterator creates new proxies per row (safe to store/collect). */
    [Symbol.iterator](): Iterator<Row>;
    /** Materialize all rows to plain objects. */
    toArray(options?: MaterializeOptions): Record<string, unknown>[];
    /** For JSON.stringify(table). */
    toJSON(): Record<string, unknown>[];
}
/**
 * Builder for constructing RecordBatches row-by-row.
 * Grows dynamically - no upfront capacity required.
 */
export declare class RecordBatchBuilder {
    private schema;
    private builders;
    private _rowCount;
    private finished;
    constructor(schema: ColumnDef[], expectedRows?: number);
    get rowCount(): number;
    /** Append a row (values in column order). Coerces values to correct types. */
    appendRow(values: unknown[]): this;
    /** Finalize and return an immutable RecordBatch. */
    finish(): RecordBatch;
}
/**
 * Create a RecordBatch from row data.
 * Accepts arrays, sync iterables/generators, or async iterables/generators.
 * Returns Promise<RecordBatch> for async iterables.
 *
 * @example
 * // From array
 * batchFromRows(schema, [[1, "a"], [2, "b"]]);
 *
 * // From generator
 * batchFromRows(schema, function*() { yield [1, "a"]; }());
 *
 * // From async generator
 * await batchFromRows(schema, async function*() { yield [1, "a"]; }());
 */
export declare function batchFromRows(schema: ColumnDef[], rows: unknown[][] | Iterable<unknown[]>, expectedRows?: number): RecordBatch;
export declare function batchFromRows(schema: ColumnDef[], rows: AsyncIterable<unknown[]>, expectedRows?: number): Promise<RecordBatch>;
export declare function validateColumnLengths(columnData: readonly Column[], columnNames?: readonly string[], expectedRowCount?: number): number;
/**
 * Create a RecordBatch from pre-built Column objects.
 * Schema is inferred from the columns.
 *
 * @example
 * batchFromCols({
 *   id: getCodec("UInt32").fromValues([1, 2, 3]),
 *   name: getCodec("String").fromValues(["a", "b", "c"]),
 * });
 */
export declare function batchFromCols(columns: Record<string, Column>): RecordBatch;
/** Data that can be sent as an external table (shared by HTTP and TCP clients). */
export type ExternalTableData = RecordBatch | Iterable<RecordBatch> | AsyncIterable<RecordBatch>;
export {};
//# sourceMappingURL=table.d.ts.map