import { Field } from "apache-arrow";
import { BlobFile as NativeBlobFile } from "./native";
export type BlobInput = {
    data: Buffer | Uint8Array | null;
    uri: string | null;
};
export type BlobOptions = {
    /** Defaults to true. */
    nullable?: boolean;
    /**
     * Max payload bytes kept inline in the data file. Zero is allowed. Must be a
     * safe integer.
     */
    inlineSizeThreshold?: number;
    /**
     * Max payload bytes stored in a packed sidecar before a dedicated file. Must
     * be a positive safe integer.
     */
    dedicatedSizeThreshold?: number;
    /**
     * Max bytes in one packed sidecar before starting another. Must be a positive
     * safe integer.
     */
    packFileSizeThreshold?: number;
};
/**
 * Declares a `lance.blob.v2` column.
 *
 * Query results are descriptors, not payload bytes. Use {@link Table.fetchBlobs}
 * or {@link Table.fetchBlobFiles} to read bytes.
 *
 * @example
 * ```ts
 * import { readFile } from "node:fs/promises";
 * import { Field, Int64, Schema } from "apache-arrow";
 * import { blob, connect } from "@lancedb/lancedb";
 *
 * const db = await connect("./data");
 * const video = await readFile("clip.mp4");
 * const table = await db.createTable(
 *   "videos",
 *   [{ id: 1n, video }],
 *   {
 *     schema: new Schema([
 *       new Field("id", new Int64()),
 *       blob("video"),
 *     ]),
 *   },
 * );
 *
 * const rows = await table.query().select(["id"]).withRowId().toArray();
 * const rowIds = rows.map((row) => row._rowid as bigint);
 * const bytes = await table.fetchBlobs("video", rowIds);
 *
 * const [handle] = await table.fetchBlobFiles("video", rowIds);
 * const size = handle!.size();
 * const header = await handle!.readRange(0n, size < 65536n ? size : 65536n);
 * ```
 */
export declare function blob(name: string, options?: BlobOptions): Field;
/**
 * Checks for the `lance.blob.v2` extension marker. Does not validate the
 * field's storage type.
 */
export declare function isBlobField(field: Field): boolean;
/**
 * A lazy handle to blob bytes. Create one with {@link Table.fetchBlobFiles}.
 *
 * @hideconstructor
 */
export declare class BlobFile {
    private readonly inner;
    private constructor();
    /** @ignore */
    static fromNative(inner: NativeBlobFile): BlobFile;
    /** Returns the blob size in bytes. */
    size(): bigint;
    /**
     * Reads from the cursor and advances the cursor.
     *
     * Reads to the end when `maxBytes` is omitted, or at most `maxBytes` bytes
     * otherwise. Returns an empty buffer at the end of the blob.
     * {@link BlobFile.readRange} does not move the cursor.
     */
    read(maxBytes?: bigint, options?: BlobReadOptions): Promise<Buffer>;
    /**
     * Reads the half-open byte range `[start, end)`.
     *
     * Fails when `end` is past the blob size. Does not move the cursor.
     */
    readRange(start: bigint, end: bigint, options?: BlobReadOptions): Promise<Buffer>;
    /**
     * Reads several half-open byte ranges. Returns one buffer per range, in
     * the order given.
     *
     * Fails when any `end` is past the blob size. Does not move the cursor.
     */
    readRanges(ranges: BlobRange[], options?: BlobReadOptions): Promise<Buffer[]>;
    /** Moves the cursor to `position`, in bytes from the start of the blob. */
    seek(position: bigint): Promise<void>;
    /** Returns the cursor position in bytes. */
    tell(): Promise<bigint>;
    /**
     * Releases the handle. Reads after `close()` fail. Calling it again does
     * nothing.
     */
    close(): Promise<void>;
    /** Returns true after {@link BlobFile.close}. */
    isClosed(): boolean;
}
/** Options for blob reads. */
export type BlobReadOptions = {
    /**
     * Cancels the read. The call rejects with `signal.reason`, and the native
     * read stops, including in-flight requests to a remote table.
     */
    signal?: AbortSignal;
};
/** @ignore */
export declare function runWithSignal<T>(signal: AbortSignal | undefined, run: (signal: AbortSignal | undefined) => Promise<T>): Promise<T>;
/** A half-open byte range `[start, end)` for {@link BlobFile.readRanges}. */
export type BlobRange = {
    start: bigint;
    end: bigint;
};
export declare function coerceBlobValue(value: unknown): BlobInput | null;