DomainTableClient<TRow, TInsert, TColumn, TExpand, TUpdate>

Defined in: js-api/src/dapi.ts:1286

Row CRUD for one domain table. Reads return only rows and columns the current user can see; writes are validated, permission-checked, and audited server-side. Pass a row interface as TRow for typed reads/writes, and an insert interface as TInsert so insert enforces required columns (grok api-generated clients pass both; see DomainsDataSource.table).

Type Parameters

Type Parameter	Default type
TRow	any
TInsert	DomainRowInsert<TRow>
TColumn extends string	string
TExpand extends object	object
TUpdate	Partial<TRow>

Constructors

Constructor

new DomainTableClient<TRow, TInsert, TColumn, TExpand, TUpdate>(dart, schema, table, options?): DomainTableClient<TRow, TInsert, TColumn, TExpand, TUpdate>

Defined in: js-api/src/dapi.ts:1298

Parameters

Parameter	Type
dart	any
schema	string
table	string
options?	DomainTableClientOptions

Returns

DomainTableClient<TRow, TInsert, TColumn, TExpand, TUpdate>

Properties

Property	Modifier	Type	Defined in
dart	public	any	js-api/src/dapi.ts:1290
schema	readonly	string	js-api/src/dapi.ts:1298
table	readonly	string	js-api/src/dapi.ts:1298

Accessors

filters

Get Signature

get filters(): DomainSavedFiltersClient

Defined in: js-api/src/dapi.ts:1704

Saved filter presets of this table — shareable entities carrying filter panel states.

Returns

DomainSavedFiltersClient

Methods

aggregate()

aggregate<TGroup, TAlias>(spec): Promise<DomainAggregateRow<TGroup | TAlias>[]>

Defined in: js-api/src/dapi.ts:1409

Grouped aggregation over the rows and columns visible to the caller (10k row cap); resolves to result rows named by group column / measure alias. Alias measures with as (and pass literal groupBy) to get typed result keys; without them, cast or use aggregateDf.

Type Parameters

Type Parameter	Default type
TGroup extends string	never
TAlias extends string	never

Parameters

Parameter	Type
spec	DomainAggregateSpec<TColumn, TGroup, TAlias>

Returns

Promise<DomainAggregateRow<TGroup | TAlias>[]>

---

aggregateDf()

aggregateDf(spec): Promise<DataFrame>

Defined in: js-api/src/dapi.ts:1547

aggregate returning a typed d42 DataFrame (10k row cap, both formats).

Parameters

Parameter	Type
spec	DomainAggregateSpec<TColumn>

Returns

Promise<DataFrame>

---

audit()

audit(id): Promise<DomainAuditEntry[]>

Defined in: js-api/src/dapi.ts:1498

Returns the row's audit trail (before/after diffs, in-transaction with each write).

Parameters

Parameter	Type
id	string

Returns

Promise<DomainAuditEntry[]>

---

auditLog()

auditLog(options?): Promise<DomainAuditEntry[]>

Defined in: js-api/src/dapi.ts:1559

Table-wide audit trail, newest first; limit clamps to [1, 1000].

Parameters

Parameter	Type
options?	{ limit?: number; }
options.limit?	number

Returns

Promise<DomainAuditEntry[]>

---

batch()

batch(data, options?): Promise<DomainBatchReport>

Defined in: js-api/src/dapi.ts:1466

Bulk upload: a DataFrame (sent as d42), a CSV string, an array of row objects, or raw bytes (options.format: 'd42' default, 'parquet' converted via the Arrow package). options.mode: 'upsert' merges by the table's business key. Resolves to the batch report; a failure that carries the per-row report (e.g. an allOrNothing abort) resolves with error set, report-less failures reject. Declared many-to-many relations are REJECTED here (the set diff is per row and would defeat the set-based load) — link with insert / update.

Parameters

Parameter	Type
data	string | Uint8Array<ArrayBufferLike> | DataFrame | object[]
options	DomainBatchOptions

Returns

Promise<DomainBatchReport>

---

capabilities()

capabilities(): Promise<DomainTableCapabilities>

Defined in: js-api/src/dapi.ts:1587

Effective DomainTableCapabilities of the CURRENT user on this table: server-truth permission probes on the final securing entity plus the writable-column mirror of column security. Cached per registry generation + user; grant changes made through this client drop the cache automatically, out-of-band changes require DomainsDataSource.invalidateUiCaches. Rejects with a DomainValidationError for unknown tables.

Returns

Promise<DomainTableCapabilities>

---

count()

count(filter?): Promise<number>

Defined in: js-api/src/dapi.ts:1516

Row count under [filter] (condition tree or smart string; omit for the whole table).

Parameters

Parameter	Type
filter?	DomainFilter<TColumn>

Returns

Promise<number>

---

delete()

delete(id): Promise<void>

Defined in: js-api/src/dapi.ts:1475

Soft-deletes a row (engine-enforced cascade/restrict/setnull for declared relations; a restrict reference rejects with a DomainRestrictError).

Parameters

Parameter	Type
id	string

Returns

Promise<void>

---

deleteWhere()

deleteWhere(filter, options?): Promise<DomainDeleteReport>

Defined in: js-api/src/dapi.ts:1487

Soft-deletes up to options.limit (≤1000, default 1000) matching rows you may delete, oldest first, in ONE transaction; referential actions apply per row and a restrict reference rejects the whole call (DomainRestrictError — nothing is deleted). The filter is required — an empty one rejects with a DomainValidationError. Each row runs through the per-row engine (cascade fan-out, audit), so this is not a free bulk sweep: prefer a narrow filter and a modest limit, and loop while hasMore for larger sets. A row already gone by its turn (deleted concurrently, or eaten by an earlier row's cascade) is skipped, not an error.

Parameters

Parameter	Type
filter	DomainFilter<TColumn>
options?	{ limit?: number; }
options.limit?	number

Returns

Promise<DomainDeleteReport>

---

exists()

exists(filter?): Promise<boolean>

Defined in: js-api/src/dapi.ts:1521

True when at least one visible row matches [filter].

Parameters

Parameter	Type
filter?	DomainFilter<TColumn>

Returns

Promise<boolean>

---

facets()

facets<TId, TKind>(spec): Promise<{ facets: { [K in string]: DomainFacetResultOf<TKind> }; }>

Defined in: js-api/src/dapi.ts:1510

Batched facet computation for filter panels: category counts, histograms, min/max, row count, and column profiling in one round trip — counts under all other filters, bounds under the row predicate only (the stable-axis exception; see DomainFacetsSpec). All results respect the row predicate and column security. Resolves to {facets: {<id>: <result>}} — 'categories' results as {categories: DomainFacetCategory[], hasMore}, 'histogram' as {min, max, buckets, totalBuckets, nulls} — buckets counted under the other filters, totalBuckets under the row predicate only (datetime bounds are ISO-8601 strings), 'minMax' as {min, max}, 'count' as {count}, 'plan' as {columns: [{name, distinct, min?, max?}]}.

Type Parameters

Type Parameter	Default type
TId extends string	string
TKind extends DomainFacetKind	DomainFacetKind

Parameters

Parameter	Type
spec	DomainFacetsSpec<TColumn, TId, TKind>

Returns

Promise<{ facets: { [K in string]: DomainFacetResultOf<TKind> }; }>

---

fetchFields()

fetchFields(ids, fields?): Promise<DataFrame>

Defined in: js-api/src/dapi.ts:1542

Rows for [ids] as a typed DataFrame: the 'id' column plus [fields] (default: all visible columns). Chunked client-side at 100k ids; row predicate + column security apply (missing/invisible ids are absent rows). An empty [ids] list short-circuits to an empty ZERO-COLUMN frame — even when [fields] are requested.

Parameters

Parameter	Type
ids	string[]
fields?	TColumn[]

Returns

Promise<DataFrame>

---

first()

first(spec?): Promise<TRow | null>

Defined in: js-api/src/dapi.ts:1526

First matching row or null; shorthand for query({...spec, limit: 1}).

Parameters

Parameter	Type
spec?	DomainQuerySpec<TColumn, keyof TExpand & string>

Returns

Promise<TRow | null>

---

get()

get(id): Promise<TRow>

Defined in: js-api/src/dapi.ts:1416

Fetches one row by id; resolves to null if the row does not exist or is not visible (typed TRow for backward compatibility — guard against null, or use first).

Parameters

Parameter	Type
id	string

Returns

Promise<TRow>

---

getByKey()

getByKey(keyValues): Promise<TRow | null>

Defined in: js-api/src/dapi.ts:1532

Business-key (or any equality-set) lookup; ambiguous or absent → null.

Parameters

Parameter	Type
keyValues	Partial<TRow>

Returns

Promise<TRow | null>

---

grant()

grant(group, permission): Promise<void>

Defined in: js-api/src/dapi.ts:1597

Idempotently grants [permission] on this table to [group] (a group id). Requires Share.

Parameters

Parameter	Type
group	string
permission	DomainPermission

Returns

Promise<void>

---

grants()

grants(): Promise<DomainGrant[]>

Defined in: js-api/src/dapi.ts:1592

Direct permission rows on this table's registry entity. Requires Share.

Returns

Promise<DomainGrant[]>

---

insert()

insert(rows, options?): Promise<DomainInsertResult[]>

Defined in: js-api/src/dapi.ts:1437

Inserts a single row or a small array of rows; resolves to per-row reports ({id, created}, or {status: 'duplicate', existingId} on a business-key match — pass options.errorOnDuplicate to reject duplicates with a DomainValidationError instead, its isDuplicate set). For tables that declare "idempotency": true, pass an idempotencyKey (UUID) row field to make retries safe: a replay returns the existing id with status: 'idempotent-replay'.

A payload may carry declared many-to-many relations as lists of target row ids ({title: 'Crash', labels: [id1, id2]}); the junction rows are written in the same transaction as the row, so a target that is missing or invisible fails the WHOLE row with code: 'not-visible-or-missing'. A row that dedups to an existing one (status: 'duplicate' / 'idempotent-replay') IGNORES its relation values — a replay never mutates the existing row's links. Creating the target and linking it in one shot is a DomainsDataSource.transaction with '$ref' placeholders inside the list. batch does NOT accept relation keys — use insert/update.

Parameters

Parameter	Type
rows	TInsert | TInsert[]
options?	{ errorOnDuplicate?: boolean; }
options.errorOnDuplicate?	boolean

Returns

Promise<DomainInsertResult[]>

---

isWatching()

isWatching(id?): Promise<boolean>

Defined in: js-api/src/dapi.ts:1577

Whether the current user watches the table (or row, when [id] is given).

Parameters

Parameter	Type
id?	string

Returns

Promise<boolean>

---

promote()

promote(id): Promise<{ id: string; promoted: boolean; }>

Defined in: js-api/src/dapi.ts:1493

Creates the entities row for a domain row so it can be individually shared.

Parameters

Parameter	Type
id	string

Returns

Promise<{ id: string; promoted: boolean; }>

---

query()

Call Signature

query(): DomainQueryBuilder<TRow, TColumn, TExpand, TRow, DataFrame>

Defined in: js-api/src/dapi.ts:1377

Bare query() returns an awaitable DomainQueryBuilder (it used to resolve all-defaults rows — await table.query() behaves identically, and everything chains: await table.query().where('sku', '=', key).orderBy('created_on', true).top(5)). Prefer the builder's condition forms and the cond/and/or helpers over template-built filter strings — condition values are bound server-side, so any string value is safe (apostrophes included).

Returns

DomainQueryBuilder<TRow, TColumn, TExpand, TRow, DataFrame>

Call Signature

query(spec): Promise<TRow[]>

Defined in: js-api/src/dapi.ts:1382

Runs a filtered, sorted, paginated query; resolves to an array of row objects (10k row cap). A declared many-to-many relation expands under its own name into a DomainRelationLink[] (expand: ['labels'] → row.labels = [{id, name}, ...], capped at 100, ordered by display name, [] when there are no visible links).

Parameters

Parameter	Type
spec	DomainQuerySpec<TColumn, keyof TExpand & string>

Returns

Promise<TRow[]>

---

queryDf()

queryDf(spec?): Promise<DataFrame>

Defined in: js-api/src/dapi.ts:1402

Runs the same query as query but resolves to a typed DataFrame (d42 wire format, 10M row cap). Columns carry the db property tags (dbPropertySchema/dbPropertyName), .choices, and semantic types; system columns are untagged. 'details:' expand is JSON-only — use query; master expand yields flat '<fk_column>.<name>' columns. A relation expand yields TWO columns: '<relation>' with the display names joined by ', ' (tagged so the grid draws chips) and the hidden companion '~<relation>.id' with the ids in the same order — the ids are the source of truth (see DomainRelationLink).

Parameters

Parameter	Type
spec	DomainQuerySpec<TColumn, keyof TExpand & string>

Returns

Promise<DataFrame>

---

restoreColumnVisibility()

restoreColumnVisibility(column): Promise<void>

Defined in: js-api/src/dapi.ts:1631

Deletes the per-column schema with its grants; the column rejoins the everyone-visible core schema.

Parameters

Parameter	Type
column	TColumn

Returns

Promise<void>

---

restrictColumn()

restrictColumn(column): Promise<{ id: string; name: string; }>

Defined in: js-api/src/dapi.ts:1623

Restricts [column] without granting anyone (inverse: restoreColumnVisibility).

Parameters

Parameter	Type
column	TColumn

Returns

Promise<{ id: string; name: string; }>

---

revoke()

revoke(group, permission?): Promise<void>

Defined in: js-api/src/dapi.ts:1603

Revokes [permission] (or all four when omitted) from [group]. Requires Share.

Parameters

Parameter	Type
group	string
permission?	DomainPermission

Returns

Promise<void>

---

save()

save(row): Promise<TRow>

Defined in: js-api/src/dapi.ts:1649

Insert-or-update by row identity: no id → insert; id → version-checked partial update (uses row.version when present). System columns other than the addressing id/version are stripped from the payload, so spreading a read row is safe. Resolves to the row merged with the new id/version — NB: re-saving an OLD object after a successful save carries its stale version and rejects with a DomainVersionConflictError; keep the resolved row. An id-less save whose business key matches an existing row is a TRUE insert-or-update: the values are applied to the existing row as a versioned update (retried on conflict), so save() never resolves a version-less row. An idempotency-key replay applies nothing — the original insert already did — and resolves the existing row's fresh version (rejects DomainNotFoundError when that row is no longer visible). The unversioned (last-write-wins) update remains available ONLY by deliberately constructing {id} without a version — never as a side effect of a duplicate.

Parameters

Parameter	Type
row	Partial<TRow> & object

Returns

Promise<TRow>

---

shareColumn()

shareColumn(column, group, permission?): Promise<{ id: string; name: string; }>

Defined in: js-api/src/dapi.ts:1615

Restricts [column] to its own single-column property schema and grants [group] View on it — afterwards only grantees (and admins) see the column. Returns the per-column schema {id, name} (a further grants target). Requires Share on the core schema; jsonb columns are managed via their property schema (DomainError). Out of scope on this surface: listing a per-column schema's own grants (keep the returned id), and property-schema grants in general (server-supported; no JS surface yet).

Parameters

Parameter	Type
column	TColumn
group	string
permission?	DomainPermission

Returns

Promise<{ id: string; name: string; }>

---

unwatch()

unwatch(id?): Promise<boolean>

Defined in: js-api/src/dapi.ts:1572

Removes the table (or row, when [id] is given) subscription; resolves to whether the server confirmed the removal.

Parameters

Parameter	Type
id?	string

Returns

Promise<boolean>

---

update()

update(id, values, options?): Promise<DomainUpdateResult>

Defined in: js-api/src/dapi.ts:1455

Partially updates a row; pass options.version (the version the client last read) for optimistic concurrency — the update fails with a DomainVersionConflictError if the row has changed since. Resolves to {id, version} (version increments on every update).

values may also carry declared many-to-many relations as lists of target row ids, with SET-REPLACE semantics over the links you can SEE: the list becomes the visible link set, [] clears it, and an ABSENT relation key leaves the relation untouched. Links whose junction row or target row the caller cannot view are never diffed and therefore never removed — a replace can only destroy links its author knows about, so "the replace didn't remove that label" is the design, not a bug. A relations-only update still bumps the row version, so options.version covers the links too. grok api-generated clients name the relations in their <Table>Update type and pass it as the client's fifth generic; untyped callers keep Partial<TRow>.

Parameters

Parameter	Type
id	string
values	TUpdate
options?	{ version?: number; }
options.version?	number

Returns

Promise<DomainUpdateResult>

---

updateWithRetry()

updateWithRetry(id, mutate, options?): Promise<DomainUpdateResult | null>

Defined in: js-api/src/dapi.ts:1685

Read-modify-write with optimistic retry: fetches the fresh row, applies [mutate], writes with the fresh version; retries on DomainVersionConflictError (maxRetries counts retries after the initial attempt — default 5 retries = up to 6 attempts, no backoff). [mutate] returning null skips the write (resolves null). Rejects DomainNotFoundError when the row is invisible/absent, and DomainError (code 'no-version') when the fresh row carries no version — the write never silently degrades to an unversioned (last-write-wins) update. For multi-op flows (e.g. a guarded transaction), use DG.retryOnVersionConflict directly with the fresh read inside the action.

Parameters

Parameter	Type
id	string
mutate	(fresh) => TUpdate | null
options?	{ maxRetries?: number; }
options.maxRetries?	number

Returns

Promise<DomainUpdateResult | null>

---

upsert()

upsert(row): Promise<{ id: string; status: "inserted" | "updated"; }>

Defined in: js-api/src/dapi.ts:1554

Inserts or merges ONE row by the table's business key (requires businessKey). Rides the batch engine in upsert mode; failures (invalid values, missing business-key column) reject with a DomainValidationError.

Parameters

Parameter	Type
row	TInsert

Returns

Promise<{ id: string; status: "inserted" | "updated"; }>

---

watch()

watch(id?): Promise<boolean>

Defined in: js-api/src/dapi.ts:1566

Subscribes the current user to change notifications for the table (or one row when [id] is given; row watch requires the table's audit trail). Resolves to whether the server confirmed the subscription.

Parameters

Parameter	Type
id?	string

Returns

Promise<boolean>