Importing CSV

You can load rows into a table from a CSV file or an Excel workbook, either in the console or from a handler. Both use the same import engine, and it works the same way in each:

• Nothing is written until the whole file checks out. Every cell is coerced and checked against the column that will hold it first: enum membership, string length, integer range, decimal scale, JSON validity, NOT NULL.
• A bad value is an error, never a guess. It is reported by spreadsheet line and column. It is never silently truncated, replaced with a default, or swapped for a "close" value.
• References and scope follow the API's rules. A reference is a _uid holding the referenced row's uid, every imported row gets a fresh uid, and a file can never set org_id.

An import from a handler is an ordinary governed write: rows go in through the same path as a create, so the table's create permission, its switched-off operations, your database quota and organization scoping all apply, and each row is a change event that realtime subscribers receive. An import in the console is you, the app's owner, editing your own data, like adding rows by hand in the table editor.

In the console

{ "line": 412, "column": "status", "value": "Pending", "message": "'Pending' is not one of: received, matched, approved, paid, disputed, on_hold" }

From a handler

sdk.importCsv runs the same engine inside a handler, so you can offer imports in your own app. Pair a dry run with a commit, the way the console does:

export default async function importInvoices(data = {}, ctx) {
  const { sdk } = ctx;

  const options = {
    table: "invoices",
    csv: data.csv, // or csvBase64
    mapping: { "Invoice #": "invoice_number", "Vendor": "vendor_uid", "Total": "amount" },
    defaults: { currency: "USD" },
    onError: "abort",
  };

  // 1. Validate everything, write nothing.
  const preview = await sdk.importCsv({ ...options, dryRun: true });
  if (preview.errorRowCount > 0 || preview.missingRequiredColumns.length > 0) {
    return { ok: false, errors: preview.errors, missing: preview.missingRequiredColumns };
  }

  // 2. Commit.
  const result = await sdk.importCsv(options);
  return { ok: true, imported: result.imported };
}

The options:

A dry run returns the resolved mapping, the headers, rowCount, errorRowCount, the first errors, previewRows (coerced) and missingRequiredColumns. A commit returns imported and skippedRows. Under onError: "abort", skippedRows is always 0, because a bad row raises instead, so a partial import is never mistaken for a complete one.

Importing needs the handler's sdk:import capability. Inside sdk.withTransaction, a failed import rolls back with everything else.

Errors

Duplicates are not skipped quietly. A row that collides with a unique column fails the insert, and onError: "skip" covers values a column cannot store, not collisions, so de-duplicate the file before importing.

Next