DbTable

Defined in: js-api/src/data.ts:173

Structured write access to one database table, obtained via Db.table. All operations return a MutationResult; the matching fine-grained saved-connection privilege (DataConnection.AddRows for insert, ChangeValues for update, RemoveRows for delete, AddRows+ChangeValues for upsert) and per-provider write capability are enforced server-side (unsupported operations reject with a structured capability error, never a 500). An operation that fails as a whole (rolled back, nothing applied) REJECTS the returned promise with the SQL error; per-row errors under allOrNothing: false resolve with errors/errorCount in the MutationResult. Values are always sent as bound parameters — never interpolated SQL.

where conditions (update/delete) are equality by value, plus string patterns for text columns (e.g. contains foo). Numeric/date range grammar (> 5, 10-20) in where is phase B.

Constructors

Constructor

new DbTable(connectionId, tableName): DbTable

Defined in: js-api/src/data.ts:174

Parameters

Parameter	Type
connectionId	string
tableName	string

Returns

DbTable

Properties

Property	Modifier	Type	Defined in
connectionId	readonly	string	js-api/src/data.ts:174
tableName	readonly	string	js-api/src/data.ts:174

Methods

delete()

delete(spec): Promise<MutationResult>

Defined in: js-api/src/data.ts:204

Deletes the rows matching spec.where (same where semantics as update). An empty where requires allowFullTable: true.

Parameters

Parameter	Type
spec	{ allowFullTable?: boolean; where: Record<string, any>; }
spec.allowFullTable?	boolean
spec.where	Record<string, any>

Returns

Promise<MutationResult>

---

insert()

insert(rows, options?): Promise<MutationResult>

Defined in: js-api/src/data.ts:180

Inserts rows from a DataFrame (bulk) or an array of row objects. An object[] is converted to a typed DataFrame at the API boundary: each column's type is inferred by scanning all of its values, Date/dayjs values become a real datetime column, and nulls are preserved (a genuine null lands as SQL NULL). A mixed or all-null column throws.

Parameters

Parameter	Type
rows	DataFrame | object[]
options	{ allOrNothing?: boolean; errorOnDuplicate?: boolean; }
options.allOrNothing?	boolean
options.errorOnDuplicate?	boolean

Returns

Promise<MutationResult>

---

update()

update(spec): Promise<MutationResult>

Defined in: js-api/src/data.ts:197

Updates the columns in spec.set on the rows matching spec.where. where is equality by value (string values may use string patterns, e.g. contains foo); numeric/date range grammar is phase B.

Parameters

Parameter	Type
spec	{ set: Record<string, any>; where: Record<string, any>; }
spec.set	Record<string, any>
spec.where	Record<string, any>

Returns

Promise<MutationResult>

---

uploadAs()

uploadAs(df, options?): Promise<MutationResult>

Defined in: js-api/src/data.ts:221

Creates the table from the DataFrame's own schema and bulk-loads [df] into it, in one operation (v1 mode is implicitly create; a future replace extends the options). The table must not already exist. Columns map dg type → native type (all nullable, no keys or indexes — for keys, run grok.data.db.ddl(...).createTable(...) first, then a plain insert). Requires provider DDL+write support (Postgres, MySQL/MariaDB, MSSQL, Oracle) and the DataConnection.CreateTable privilege. A failed load REJECTS the returned promise; on providers without transactional DDL (MySQL, Oracle) the CREATE commits first, so a failed load leaves an empty table — the leftover note rides in the rejection message, and the result's plan.transactionalDdl says which contract applies.

With dryRun: true, nothing executes: the result's plan.statements carries the exact CREATE TABLE SQL derived from the DataFrame.

Parameters

Parameter	Type
df	DataFrame
options	{ dryRun?: boolean; }
options.dryRun?	boolean

Returns

Promise<MutationResult>

---

upsert()

upsert(rows, options): Promise<MutationResult>

Defined in: js-api/src/data.ts:187

Inserts or updates rows, matching existing rows on options.keys. An object[] is typed the same way as insert.

Parameters

Parameter	Type
rows	DataFrame | object[]
options	{ allOrNothing?: boolean; keys: string[]; }
options.allOrNothing?	boolean
options.keys	string[]

Returns

Promise<MutationResult>