@terascope/data-mate 2.24.0 → 2.25.1

package/dist/src/teal-frame/TealFrame.js

@@ -0,0 +1,575 @@
+import { SQLDialectName } from '@terascope/types';
+import { DataType } from '@terascope/data-types';
+import { getSQLDialect, groupByClause, quoteIdentifier, quoteLiteral, toSQLSort, wholeNumber } from '@terascope/sql-builder';
+import { appendInTransaction } from './append.js';
+import { getContext } from './database.js';
+import { AppendError } from './errors.js';
+import { createTable, nextTableName } from './table.js';
+import { joinSQL, selectList } from './clauses.js';
+import { readParquetSource } from './sources.js';
+import { assertOrderSafe } from './order-safety.js';
+import { resolveRules } from './export-json.js';
+import * as output from './output.js';
+import { makeRowShapers } from './row-shape.js';
+import { expandValuesSQL } from './expand-values.js';
+import { deepSelectSQL, emptySkippedObjects } from './deep-select.js';
+import { distinctLines, parseLines, writeLines } from './line-stream.js';
+/**
+ * The DuckDB dialect, shared with `@terascope/xlucene-translator`.
+ *
+ * `ORDER BY` and `LIMIT`/`OFFSET` are rendered by the dialect, so a sort built by a frame and
+ * a sort in a statement from `QueryAccess.restrictSQLQuery` place nulls the same way.
+*/
+const dialect = getSQLDialect(SQLDialectName.duckdb);
+/**
+ * A frame whose rows live in DuckDB.
+ *
+ * TealFrame has its own API; it does not wrap or replace `DataFrame`. Its methods fall into
+ * three groups:
+ *
+ * 1. **Compose a statement:** `filter`, `select`, `orderBy`, `limit`, `distinct`, `join`,
+ *    `deepSelect`, `pruneEmptyObjects`, `expandValues` and `removeEmptyRows`. Each returns a
+ *    new frame over one more SQL step. Nothing runs yet.
+ * 2. **Run an existing statement:** `query` (instance) and `fromSQL` (static).
+ * 3. **Consume:** `rows`, `size`, `ndjson`, `writeNDJSON`, `writeParquet`, `listValues` and
+ *    `countEmptyRows`. These execute the statement and produce output.
+ *
+ * `filter` and `select` are clause builders, not a search API: `filter` is the `WHERE` clause
+ * and `select` is the `SELECT` list, just as `orderBy` is the `ORDER BY`. They exist for
+ * callers that build a query one step at a time. For example, `tealFrameAdapter` returns an
+ * expression for one function on one column, and a chain of transforms becomes a chain of
+ * `select` calls that compose into one statement evaluated in a single pass.
+ *
+ * If you already have a complete statement, such as one from `QueryAccess`, pass it to
+ * `query` whole. Rebuilding a restricted statement from `filter` and `select` can drop a
+ * field restriction.
+*/
+export class TealFrame {
+    ctx;
+    config;
+    source;
+    columns;
+    constructor(ctx, config, 
+    /**
+     * Not readonly: `append` may promote a relation to a table, because a frame manages
+     * its own storage. Every other operation returns a new frame and leaves this one
+     * unchanged.
+    */
+    source, columns) {
+        this.ctx = ctx;
+        this.config = config;
+        this.source = source;
+        this.columns = columns;
+    }
+    /** The in-flight promotion of a relation to a table, shared by concurrent appends. */
+    promotion;
+    /** True when the rows are in a real table rather than recomputed per reference. */
+    get isMaterialized() {
+        return this.source.kind === 'table';
+    }
+    /**
+     * True when this frame's rows come out in a defined order.
+     *
+     * Set by `orderBy` and kept by the operators that preserve order. Operations that would
+     * discard the order check it and throw.
+    */
+    get isOrdered() {
+        return this.source.kind === 'relation' && this.source.ordered === true;
+    }
+    /** Refuses an operation that would silently discard an ordering - see `order-safety.ts`. */
+    assertOrderSafe(operation, other) {
+        assertOrderSafe(operation, this.isOrdered || other?.isOrdered === true);
+    }
+    /** A new relation-backed frame over `sql` on the same database. */
+    derive(sql, { config = this.config, columns = this.columns, ordered } = {}) {
+        return new TealFrame(this.ctx, config, { kind: 'relation', sql, ordered }, columns);
+    }
+    /**
+     * SQL naming this frame's rows, usable directly in a `FROM` clause.
+     *
+     * For a materialized frame this is its quoted table name; for a relation it is a
+     * parenthesized subquery, so composed frames reach DuckDB's optimizer as a single
+     * statement.
+    */
+    get from() {
+        return this.source.kind === 'table'
+            ? quoteIdentifier(this.source.table)
+            : `(${this.source.sql})`;
+    }
+    /**
+     * Returns a frame over the rows of a complete SQL statement.
+     *
+     * Use it to run a statement from `QueryAccess.restrictSQLQuery`, which is a finished
+     * `SELECT` that already carries the field restrictions:
+     *
+     * ```ts
+     * const sql = await access.restrictSQLQuery(query, { params: frame.searchParams(size) });
+     * for await (const row of frame.query(sql).rows()) { ... }
+     * ```
+     *
+     * The statement runs only when rows are requested, and it composes with other operations:
+     * `frame.query(sql).limit(10)` is one statement.
+     *
+     * `config` defaults to this frame's config. Pass the right config when the statement's
+     * `SELECT` list produces different fields. If the statement references its source more
+     * than once, materialize this frame first; see `searchParams`.
+     *
+     * @param sql A complete SQL statement.
+     * @param config The field types the statement produces. Defaults to this frame's config.
+     * @param columns The output column names. Defaults to the top-level fields of `config`.
+    */
+    query(sql, config = this.config, columns) {
+        if (!sql.trim()) {
+            throw new TypeError('query requires a SQL statement');
+        }
+        return this.derive(sql, { config, columns: columns ?? columnsOf(config) });
+    }
+    /**
+     * Runs SQL and returns positional rows, with values as DuckDB renders them to JSON. This is
+     * for inspection, not for reading data; use `query(sql).rows()` to read data.
+     *
+     * Unlike `query`, it needs no `DataTypeConfig`, so it can run catalog queries such as
+     * `DESCRIBE`. It also skips the conversion to output values, so it shows what DuckDB
+     * actually stores.
+     *
+     * @internal
+    */
+    rawRows(sql) {
+        return this.ctx.rows(sql);
+    }
+    /**
+     * The `SQLSearchParams` that name this frame as the source of a `QueryAccess` statement.
+     *
+     * A materialized frame reports `table`, which is quoted as an identifier. A relation-backed
+     * frame reports `relation`, its SQL used verbatim.
+     *
+     * Prefer a table when the generated statement may reference its source more than once
+     * (a self-join, a correlated subquery, a `UNION`). Each reference to a relation re-runs the
+     * whole subquery, while a table is read directly. Call `materialize()` first in that case.
+     *
+     * @param size The page size, rendered as `LIMIT`.
+     * @param from The page start, rendered as `OFFSET`.
+    */
+    searchParams(size, from) {
+        const source = this.source.kind === 'table'
+            ? { table: this.source.table }
+            : { relation: this.from };
+        return {
+            ...source,
+            ...(size != null && { size }),
+            ...(from != null && { from }),
+        };
+    }
+    /** The backing table name, when this frame is materialized. */
+    get table() {
+        return this.source.kind === 'table' ? this.source.table : undefined;
+    }
+    /**
+     * Creates an empty frame backed by a new table. This is the usual way to make a frame;
+     * add rows with `append`.
+    */
+    static async create(config, options = {}) {
+        const context = await getContext(options.database);
+        const { table, columns } = await createTable(context, config, options.name);
+        return new TealFrame(context, config, { kind: 'table', table }, columns);
+    }
+    /**
+     * Adds rows to this frame, from parsed records or from Parquet files, and returns the
+     * number of rows added.
+     *
+     * Records are coerced to the frame's field types; Parquet is already typed and is not.
+     *
+     * If the frame is a relation, it is first promoted to a table in place. Frames already
+     * derived from it keep the SQL they captured and are unaffected.
+     *
+     * The append runs in a transaction, so a failed batch leaves the table exactly as it was.
+     * When a table is assembled from many batches, a bad one cannot corrupt those already in it.
+     *
+     * **Finish appending before deriving other frames from this one.** Derived frames read the
+     * table by name, so a later append changes their results too.
+    */
+    async append(source, options = {}) {
+        await this.ensureTable();
+        const table = this.source.kind === 'table' ? this.source.table : '';
+        // on its own connection and in a transaction; see `appendInTransaction`
+        return appendInTransaction(this.ctx.instance, this.config, table, source, options);
+    }
+    /**
+     * Promotes a relation to a table in place, so this frame has storage to append to.
+     *
+     * The promotion is shared, so two concurrent appends do not each create a table and split
+     * the rows between them.
+    */
+    async ensureTable() {
+        if (this.source.kind === 'table')
+            return;
+        this.promotion ??= this.promoteToTable();
+        await this.promotion;
+    }
+    async promoteToTable() {
+        const table = nextTableName('appendable');
+        await this.ctx.run(`CREATE OR REPLACE TABLE ${quoteIdentifier(table)} AS SELECT * FROM ${this.from}`);
+        this.source = { kind: 'table', table };
+    }
+    /**
+     * Creates a frame from parsed JS records, such as Elasticsearch documents.
+     *
+     * Each value is coerced to its field type. In `strict` mode (the default) the first value
+     * that does not fit throws a `CoercionFailureError`, as `DataFrame`'s builder does. In
+     * `lenient` mode the value is stored as null and each failing field is recorded with a count
+     * and an example value.
+     *
+     * If the records cannot be added, the new table is dropped before the error is thrown.
+    */
+    static async fromRecords(config, records, options = {}) {
+        const frame = await TealFrame.create(config, options);
+        try {
+            await frame.append({ records }, { mode: options.mode });
+        }
+        catch (err) {
+            // No frame is returned, so no caller could drop the table; drop it here. A plain
+            // `append` does not do this, because there the caller holds the frame and the
+            // table may hold earlier batches.
+            await frame.destroy();
+            // Unwrapped: nothing survived, so `AppendError`'s context adds nothing, and this
+            // throws what `DataFrame` throws, a `CoercionFailureError`.
+            throw err instanceof AppendError ? err.cause : err;
+        }
+        return frame;
+    }
+    /**
+     * Creates a frame over Parquet files, without coercing their values.
+     *
+     * Parquet carries its own schema, so column types are already enforced; the values are
+     * expected to have been validated when the files were written.
+     *
+     * @param path One path, a list of paths, or a glob. Several files read as one relation.
+    */
+    static async fromParquet(config, path, options = {}) {
+        const context = await getContext(options.database);
+        // relation-backed: Parquet is queried in place, so nothing is copied until rows are
+        // requested. `materialize()` turns it into one table.
+        const sql = `SELECT * FROM ${readParquetSource(path)}`;
+        return new TealFrame(context, config, { kind: 'relation', sql }, columnsOf(config));
+    }
+    /**
+     * Creates a frame over a complete SQL statement whose source is named in the SQL itself,
+     * such as `read_parquet([...])` or an existing table.
+     *
+     * Use the instance method `query()` instead when the statement was built against an
+     * existing frame.
+     *
+     * ```ts
+     * const sql = await access.restrictSQLQuery(query, {
+     *     params: { relation: `read_parquet(${...})`, size: 100 }
+     * });
+     * const frame = await TealFrame.fromSQL(sql, config);
+     * ```
+     *
+     * Nothing runs until rows are requested. The statement is not validated, so any error
+     * comes from DuckDB when it executes.
+    */
+    static async fromSQL(sql, config, options = {}) {
+        if (!sql.trim()) {
+            throw new TypeError('fromSQL requires a SQL statement');
+        }
+        const context = await getContext(options.database);
+        return new TealFrame(context, config, { kind: 'relation', sql }, columnsOf(config));
+    }
+    /**
+     * Copies this frame's rows into a new table and returns a new frame over it. The original
+     * frame is unchanged. A frame that is already a table is returned as is.
+     *
+     * A relation is recomputed every time it is referenced, so materializing pays off when the
+     * relation is expensive and used more than once. For a single use it is slower, and a
+     * cheap relation over a table never needs it.
+    */
+    async materialize(name) {
+        if (this.isMaterialized)
+            return this;
+        const table = nextTableName(name ?? 'materialized');
+        await this.ctx.run(`CREATE OR REPLACE TABLE ${quoteIdentifier(table)} AS SELECT * FROM ${this.from}`);
+        return new TealFrame(this.ctx, this.config, { kind: 'table', table }, this.columns);
+    }
+    /**
+     * Sets the `SELECT` list, returning a new frame.
+     *
+     * Every column-level operation is a projection: applying a transform or validation,
+     * renaming, dropping, or adding a derived column. Chained `select` calls compose into one
+     * statement evaluated in a single pass, where `DataFrame` makes a pass per function.
+     * Expressions may be native SQL or calls to registered UDFs.
+     *
+     * To run a complete statement, use `query` instead.
+     *
+     * @param expressions A map of `{ outputName: sqlExpression }`, or a verbatim `SELECT` list.
+     * @param options The result's config and column names, and an optional `groupBy`. Grouping
+     * an ordered frame throws, because it would discard the order.
+    */
+    select(expressions, options = {}) {
+        const { config = this.config, groupBy } = options;
+        const { list, names } = selectList(expressions, options.columns);
+        if (groupBy?.length)
+            this.assertOrderSafe('select with groupBy');
+        const sql = joinSQL(`SELECT ${list} FROM ${this.from}`, groupByClause(groupBy));
+        return this.derive(sql, { config, columns: names, ordered: this.isOrdered });
+    }
+    /**
+     * Joins another frame, returning a new frame.
+     *
+     * Either side may be a table or a relation. Both sides are aliased (`a` and `b` by
+     * default), because two frames often share column names; write `on` and `select` in terms
+     * of those aliases. `groupBy` lets a join and an aggregation run as one statement.
+     *
+     * Both frames must be in the same database, and neither may be ordered, because a join
+     * does not keep row order.
+    */
+    join(other, options) {
+        if (other.ctx !== this.ctx) {
+            throw new TypeError('join requires both frames to be in the same database:'
+                + ' they are in different databases, so neither can see the other\'s tables');
+        }
+        this.assertOrderSafe('join', other);
+        const { list, names } = selectList(options.select, options.columns);
+        const as = options.as ?? 'a';
+        const otherAs = options.otherAs ?? 'b';
+        const type = (options.type ?? 'inner').toUpperCase();
+        const sql = joinSQL(`SELECT ${list}`
+            + ` FROM ${this.from} AS ${quoteIdentifier(as)}`
+            + ` ${type} JOIN ${other.from} AS ${quoteIdentifier(otherAs)}`
+            + ` ON ${options.on}`, groupByClause(options.groupBy));
+        return this.derive(sql, { config: options.config, columns: names });
+    }
+    /**
+     * Adds a `WHERE` clause, returning a new frame.
+     *
+     * The predicate is raw SQL, so the caller must quote identifiers itself: a field named
+     * `group` needs `filter('"group" = \'y\'')`. To run a complete statement, such as one
+     * from `QueryAccess`, use `query` instead.
+     *
+     * A filter keeps row order, so a sorted frame stays sorted.
+    */
+    filter(predicate) {
+        return this.derive(`SELECT * FROM ${this.from} WHERE ${predicate}`, {
+            ordered: this.isOrdered,
+        });
+    }
+    /**
+     * Removes duplicate rows, comparing every column (`SELECT DISTINCT *`). Returns a new
+     * frame.
+     *
+     * It works on list and object columns, and treats nulls as equal, so rows that are null in
+     * the same column collapse into one.
+     *
+     * `DISTINCT` does not keep row order, so it throws on an ordered frame and its result is
+     * unordered. Remove duplicates first, then sort.
+    */
+    distinct() {
+        this.assertOrderSafe('distinct');
+        return this.derive(`SELECT DISTINCT * FROM ${this.from}`);
+    }
+    /**
+     * Adds an `ORDER BY`, returning a new frame.
+     *
+     * The sort wraps the current relation in a subquery. DuckDB's optimizer flattens the
+     * nesting, so `.orderBy(x).limit(10)` runs as a single top-N query. The order of calls
+     * means what it says:
+     *
+     * | chain | means |
+     * |---|---|
+     * | `.orderBy(x).limit(10)` | the top 10 by x |
+     * | `.limit(10).orderBy(x)` | an arbitrary 10, sorted |
+     * | `.orderBy(x).filter(p).limit(10)` | the top 10 of the matching rows |
+     * | `.orderBy(x).limit(10).filter(p)` | the top 10, then filtered - may yield fewer |
+     *
+     * `select`, `filter` and `limit` may follow a sort. `join`, `distinct` and a grouping
+     * `select` throw on a sorted frame, because they would discard the order. `materialize()`
+     * drops the order, because a table has none.
+     *
+     * Nulls sort as in `DataFrame`: first when ascending, last when descending.
+     *
+     * **Ties are not ordered deterministically.** DuckDB sorts in parallel and is not stable,
+     * so rows with equal sort values can come back in a different order on each run, and
+     * paging over them can repeat or skip rows. `DataFrame` sorts with the stable
+     * `Array#sort`. A caller that pages must end `sort` with a unique field.
+     *
+     * @param sort The sort terms, at least one.
+    */
+    orderBy(sort) {
+        if (sort.length === 0) {
+            throw new TypeError('orderBy requires at least one sort term');
+        }
+        const terms = dialect.orderBy(sort.map(toSQLSort));
+        return this.derive(`SELECT * FROM ${this.from} ORDER BY ${terms}`, { ordered: true });
+    }
+    /**
+     * Adds `LIMIT` and `OFFSET`, returning a new frame.
+     *
+     * Either bound may be given alone; with neither, the frame is returned unchanged, so
+     * optional paging values can be passed straight through.
+     *
+     * Prefer `limit` to stopping early in `rows()`. DuckDB stops reading once an unsorted
+     * limit is satisfied, and for a sorted one keeps only the top `count` rows instead of
+     * sorting everything. Breaking out of `rows()` stops only the JS consumer.
+     *
+     * A limit keeps row order. Note that `size()` on a limited frame counts the page, not the
+     * total; call `size()` on the frame before the limit to get the total.
+     *
+     * @param count The maximum number of rows (`LIMIT`).
+     * @param offset The number of rows to skip (`OFFSET`).
+    */
+    limit(count, offset) {
+        if (count == null && offset == null)
+            return this;
+        // validated here so the error names this method's parameters; the dialect's own
+        // error would name `size` and `from`
+        if (count != null)
+            wholeNumber(count, 'limit\'s count');
+        if (offset != null)
+            wholeNumber(offset, 'limit\'s offset');
+        return this.derive(joinSQL(`SELECT * FROM ${this.from}`, dialect.limitOffset(count, offset)), { ordered: this.isOrdered });
+    }
+    /** Counts the frame's rows. */
+    async size() {
+        return Number(await this.ctx.scalar(`SELECT count(*) FROM ${this.from}`) ?? 0);
+    }
+    /**
+     * Writes the frame to a Parquet file compressed with zstd, for moving data between
+     * processes.
+     *
+     * Parquet's built-in zstd compression is much faster than gzipping JSON output and
+     * produces a smaller file.
+    */
+    async writeParquet(path) {
+        await output.writeParquet(this.ctx, this.from, this.config, path);
+    }
+    /**
+     * Writes the frame to a file as ldjson, one JSON object per line.
+     *
+     * DuckDB writes the file, so rows never become JS objects and this is much faster than
+     * serializing `rows()`.
+     *
+     * The output is byte-identical to `DataFrame.toJSON` with the same `SerializeOptions`,
+     * including ISO 8601 dates and integers past `MAX_SAFE_INTEGER` written as strings. See
+     * `export-json.ts`.
+     *
+     * With no options, null fields and empty objects are omitted (`removeNullFields: true`).
+     * Any explicit `SerializeOptions` flag means exactly what it means to `DataFrame`.
+     *
+     * The promise resolves once the whole file is written. Use `ndjson()` to stream the lines
+     * instead, for example to upload them as they are produced.
+    */
+    async writeNDJSON(path, options = {}) {
+        // removing duplicate rows keeps the first of each in stream order, which a COPY
+        // cannot express, so that option writes through the stream instead
+        if (resolveRules(options).skipDuplicateObjects) {
+            await writeLines(path, this.ndjson(options));
+            return;
+        }
+        await this.ctx.run(`COPY (${output.jsonLinesSQL(this.from, this.config, options)}) TO ${quoteLiteral(path)}`
+            + ' (FORMAT CSV, HEADER false, QUOTE \'\', ESCAPE \'\', DELIMITER \'\u0007\')');
+    }
+    /**
+     * Streams the frame as ldjson lines, byte-identical to what `writeNDJSON` writes.
+     *
+     * DuckDB renders each line, so JavaScript only passes strings along. A caller can upload
+     * the lines as they arrive and never hold the whole result in memory.
+    */
+    ndjson(options = {}) {
+        const lines = this.ctx.streamColumnStrings(output.jsonLinesSQL(this.from, this.config, options));
+        return resolveRules(options).skipDuplicateObjects ? distinctLines(lines) : lines;
+    }
+    /**
+     * Streams the frame's rows as JS objects.
+     *
+     * With `options`, it yields what `DataFrame.rows(true, options)` yields, by parsing the
+     * lines `ndjson(options)` produces. Without options, it yields every column, with a nil
+     * value as `null`.
+     *
+     * There is no `toArray()` or `getColumn()`: the data lives in DuckDB, so column-level work
+     * belongs in SQL, and a result may be too large to hold as an array.
+    */
+    rows(options) {
+        if (options != null)
+            return parseLines(this.ndjson(options));
+        return this.ctx.streamRowObjects(`SELECT * FROM ${this.from}`, makeRowShapers(this.config));
+    }
+    /**
+     * Streams the elements of a list column in the first row, as
+     * `ListVector.getRowIterator(0, true, options)` yields them.
+     *
+     * Useful for a one-row frame whose single list column holds the real result. Each element
+     * is rendered by the same rules as `ndjson(options)`. A nil element is yielded as `null`
+     * under `useNullForUndefined`, as `undefined` otherwise, and skipped under
+     * `skipNilListValues` (or `skipNilObjectValues` for object elements). As in `DataFrame`,
+     * nothing is yielded under `skipEmptyArrays` when the column is empty, and
+     * `skipDuplicateObjects` is not supported.
+    */
+    listValues(column, options = {}) {
+        return output.listValues(this.ctx, this.from, this.config, column, options);
+    }
+    /**
+     * Keeps only the selected fields, as `DataFrame.deepSelect` does. Dotted paths select
+     * fields inside nested objects, and names that do not exist are ignored. See
+     * `deep-select.ts`.
+    */
+    deepSelect(fields) {
+        const { sql, config, columns } = deepSelectSQL(this.from, this.columns, this.config, fields);
+        return this.derive(sql, { config, columns, ordered: this.isOrdered });
+    }
+    /**
+     * Drops every Object column marked `_skip_if_empty` that has no declared child fields left,
+     * typically after `deepSelect`. Decided from the config alone; no rows are read.
+    */
+    pruneEmptyObjects() {
+        const dropped = new Set(emptySkippedObjects(this.config));
+        if (dropped.size === 0)
+            return this;
+        const columns = this.columns.filter((column) => !dropped.has(column));
+        const fields = Object.fromEntries(Object.entries(this.config.fields ?? {})
+            .filter(([name]) => !dropped.has(name.split('.', 1)[0])));
+        const config = { ...this.config, fields };
+        const sql = columns.length
+            ? `SELECT ${columns.map(quoteIdentifier).join(', ')} FROM ${this.from}`
+            : `SELECT * FROM ${this.from} LIMIT 0`;
+        return this.derive(sql, { config, columns, ordered: this.isOrdered });
+    }
+    /**
+     * Expands array fields into one row per element, as the `@expandValues` directive does.
+     * See `expand-values.ts` for the two modes. Row order is kept, and so is a row with nothing
+     * to expand. The expanded fields become `array: false`.
+    */
+    expandValues(fields, options) {
+        const { sql, config } = expandValuesSQL(this.from, this.columns, this.config, fields, options);
+        return this.derive(sql, { config, ordered: this.isOrdered });
+    }
+    /**
+     * Counts the rows where every column is null, as `DataFrame.countEmptyRows` does. A row
+     * holding `{}` or `[]` is not empty, because the stored value is tested, not its JSON form.
+    */
+    async countEmptyRows() {
+        return Number(await this.ctx.scalar(`SELECT count(*) FROM ${this.from} WHERE ${this.emptyRow()}`) ?? 0);
+    }
+    /** Keeps the rows that are not empty, in order, as `DataFrame.removeEmptyRows` does. */
+    removeEmptyRows() {
+        return this.filter(`NOT (${this.emptyRow()})`);
+    }
+    emptyRow() {
+        return this.columns.map((column) => `${quoteIdentifier(column)} IS NULL`).join(' AND ');
+    }
+    /**
+     * Drops the backing table, if this frame has one. A relation has nothing to drop.
+     *
+     * Call it only once no frame derived from this one is still in use, because derived
+     * frames read the table by name.
+    */
+    async destroy() {
+        if (this.source.kind === 'table') {
+            await this.ctx.run(`DROP TABLE IF EXISTS ${quoteIdentifier(this.source.table)}`);
+        }
+    }
+}
+/** A config's top-level columns, as `toDuckDB` lays them out. */
+function columnsOf(config) {
+    return Object.keys(new DataType(config).toDuckDB());
+}
+//# sourceMappingURL=TealFrame.js.map

package/dist/src/teal-frame/TealFrame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TealFrame.js","sourceRoot":"","sources":["../../../src/teal-frame/TealFrame.ts"],"names":[],"mappings":"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"}

package/dist/src/teal-frame/append.d.ts

@@ -0,0 +1,45 @@
+import { DuckDBConnection, DuckDBInstance } from '@duckdb/node-api';
+import { AppendOptions, AppendSource, FrameConfig } from './interfaces.js';
+/**
+ * Loads rows into a frame's table. Used by `TealFrame.append` and `fromRecords`.
+ *
+ * Records arrive as JS objects, are coerced with `coerceToType` (the same function
+ * `DataFrame`'s builder uses) and are appended as typed values, with no JSON round trip.
+ * Because the coercion code is shared, field semantics match `DataFrame` exactly.
+ *
+ * These are free functions because none of them needs the frame. Each takes the append's own
+ * connection (see `appendInTransaction`), the table name and the input.
+*/
+/** Counts a table's rows without throwing. Used while reporting a failure, where a second
+ * error would hide the original one. */
+export declare function countQuietly(connection: DuckDBConnection, table: string): Promise<number | undefined>;
+/**
+ * Appends Parquet files with `INSERT ... BY NAME`.
+ *
+ * Columns are matched by name because a positional `INSERT ... SELECT *` fails when a file's
+ * column order differs from the table's, and separately produced files may not agree on order.
+ *
+ * No coercion is needed: Parquet is typed, and the values were coerced by `fromRecords` when
+ * the file was written.
+*/
+export declare function appendParquet(connection: DuckDBConnection, table: string, paths: string | readonly string[]): Promise<number>;
+/**
+ * Coerces records with `coerceToType` and appends them through a typed DuckDB appender.
+ *
+ * `strict` (the default) throws on the first bad value, as `DataFrame`'s builder does.
+ * `lenient` stores null instead and collects each failing field with a count and an example.
+*/
+export declare function appendRecords(connection: DuckDBConnection, config: FrameConfig, table: string, records: readonly Record<string, unknown>[], options: AppendOptions): Promise<number>;
+/**
+ * Runs one `TealFrame.append` as an atomic transaction on its own connection.
+ *
+ * **The separate connection is required for correctness.** A DuckDB transaction belongs to a
+ * connection, and the shared connection is used by the whole process. If two appends shared it,
+ * the second `BEGIN` would throw, its `ROLLBACK` would discard the first append's rows, and every
+ * later statement would fail with `Current transaction is aborted`.
+ *
+ * With one connection per append, concurrent appends to the same table are safe: DuckDB's MVCC
+ * lets appends proceed without write conflicts.
+*/
+export declare function appendInTransaction(instance: DuckDBInstance, config: FrameConfig, table: string, source: AppendSource, options: AppendOptions): Promise<number>;
+//# sourceMappingURL=append.d.ts.map

package/dist/src/teal-frame/append.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append.d.ts","sourceRoot":"","sources":["../../../src/teal-frame/append.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAmB,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAMrF,OAAO,EACH,aAAa,EAAE,YAAY,EAAmB,WAAW,EAC5D,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;EASE;AAEF;wCACwC;AACxC,wBAAsB,YAAY,CAC9B,UAAU,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAC5C,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU7B;AAED;;;;;;;;EAQE;AACF,wBAAsB,aAAa,CAC/B,UAAU,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAC/E,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;;EAKE;AACF,wBAAsB,aAAa,CAC/B,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC3C,OAAO,EAAE,aAAa,GACvB,OAAO,CAAC,MAAM,CAAC,CA2DjB;AAED;;;;;;;;;;EAUE;AACF,wBAAsB,mBAAmB,CACrC,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,aAAa,GACvB,OAAO,CAAC,MAAM,CAAC,CA2BjB"}