DomainQuery

Defined in: js-api/src/domains.ts:880

What the user is looking at, as ONE serializable object: the parameters of the platform's DomainQuery function (filters, joins, aggregations, groupBy, orderBy, projection, limit, offset). URL routing, deep links, saved filters, "open in Table View" and data-synced dashboards all serialize exactly this — there is no parallel query-state vocabulary.

const q = new DG.DomainQuery({schema: 'grit', table: 'issue',
  filters: ['status = "open"'], orderBy: ['!created_on'], limit: 100});
const df = await q.run();                                  // recorded run
const url = new URLSearchParams(q.toUrlParams()).toString(); // filters[0]=...&orderBy[0]=...

UI-only state stays out of it. Search text, view mode, the current entity ride separate reserved URL parameters (view=, entity=) that fromUrlParams ignores; if an app needs to carry them together, wrap a DomainQuery in an envelope object — never widen this class.

Constructors

Constructor

new DomainQuery(params): DomainQuery

Defined in: js-api/src/domains.ts:906

Empty and absent lists are the same thing: they normalize to undefined, so toParams / toUrlParams round-trip to an identical object.

Parameters

Parameter	Type
params	DomainQueryParams

Returns

DomainQuery

Properties

Property	Type	Description	Defined in
aggregations?	string[]	Measures ('count', 'avg(amount) as avg_amount') — non-empty means aggregate mode.	js-api/src/domains.ts:894
columns?	string[]	Projection; omit for all viewable columns (select mode only).	js-api/src/domains.ts:884
filters?	string[]	Filter elements, AND-combined: smart-filter grammar strings ('status = "open"'), or the per-element JSON escape hatch (a '{'-prefixed condition node, a '['-prefixed condition sub-group). Values inside a JSON node are bound server-side; a grammar string cannot quote apostrophes, so prefer nodes for arbitrary user values.	js-api/src/domains.ts:890
groupBy?	string[]	Grouping columns — non-empty means aggregate mode.	js-api/src/domains.ts:896
joins?	string[]	Master-FK expands ('<fk_column>'); 'details:' child arrays are rejected.	js-api/src/domains.ts:892
limit?	number	Row cap; toSpec falls back to DOMAIN_QUERY_ROW_LIMIT when unset.	js-api/src/domains.ts:900
offset?	number	Row offset (select mode only).	js-api/src/domains.ts:902
orderBy?	string[]	Sort elements; a '!' prefix means descending.	js-api/src/domains.ts:898
schema	string	-	js-api/src/domains.ts:881
table	string	-	js-api/src/domains.ts:882

Accessors

isAggregate

Get Signature

get isAggregate(): boolean

Defined in: js-api/src/domains.ts:948

Aggregate mode: aggregations or groupBy carries elements. columns and offset are then REJECTED, not ignored — toSpec throws and run gets a 400 from the function.

Returns

boolean

Methods

run()

run(): Promise<DataFrame>

Defined in: js-api/src/domains.ts:970

Runs the query through the platform's DomainQuery function — the reproducible path: the resulting DataFrame carries a creation script, so it refreshes from the Source pane, survives a saved project as a data-synced dashboard, and takes URL parameters (filters[0], ...). Being a normal function run, its result also goes through the platform's default handling: the frame is added to the workspace and OPENED IN A TABLE VIEW, which becomes the current view. Per-caller row and column security applies on every run.

The creation script is recorded only when the user has data history enabled (grok.shell.settings.dataHistory, on by default) — the query itself runs either way, but the frame comes back without .script/.history tags when it is off.

Failures arrive as the function's own error (raw Dart message text), NOT as the typed DomainError family: the function boundary carries no error envelope. Where typed failures matter, run toSpec through queryDf instead.

For a silent read (no history, no workspace entry, no view) pass toSpec to grok.dapi.domains.table('<schema>.<table>').queryDf(...) instead.

Returns

Promise<DataFrame>

---

toParams()

toParams(): DomainQueryParams

Defined in: js-api/src/domains.ts:931

The DomainQuery function's parameter values — the shape DomainView.query reports and run passes to the function.

Returns

DomainQueryParams

---

toSpec()

toSpec(): DomainQuerySpec

Defined in: js-api/src/domains.ts:986

The same query as a REST spec for queryDf/query — the same rows as run, without the recording (the limit is always explicit, so the result never depends on the server default).

Throws for an aggregate query (use run, or aggregateDf with a DomainAggregateSpec), and for several smart-filter grammar elements at once: those are parsed by the function itself, and a bare string inside a REST condition tree means a connector, not a filter.

Returns

DomainQuerySpec

---

toUrlParams()

toUrlParams(): object

Defined in: js-api/src/domains.ts:1029

URL parameters for a deep link, binding one list element per key (filters[0]=status %3D "open") — the platform's list-element binding scheme, so a recorded run's filters[0] can be substituted from the URL. The table address (schema/table) is NOT emitted: it addresses the view, and fromUrlParams takes it back explicitly. Values are raw — encode them (URLSearchParams).

Returns

object

---

fromBuilder()

static fromBuilder(builder): DomainQuery

Defined in: js-api/src/domains.ts:925

The state a DomainQueryBuilder accumulated (see its toQuery).

Parameters

Parameter	Type
builder	DomainQueryBuilder<any>

Returns

DomainQuery

---

fromParams()

static fromParams(params): DomainQuery

Defined in: js-api/src/domains.ts:920

The query behind a view's current state: DG.DomainQuery.fromParams(domainView.query).

Parameters

Parameter	Type
params	DomainQueryParams

Returns

DomainQuery

---

fromUrlParams()

static fromUrlParams(schema, table, params): DomainQuery

Defined in: js-api/src/domains.ts:1049

Rebuilds the query from toUrlParams output (lossless round trip). Keys that are not query parameters — the reserved view= / entity= UI state among them — are ignored; a malformed element index (filters[x]) or a non-integer limit/offset throws instead of degrading to NaN. Element indices are read in ascending order and gaps are closed.

Parameters

Parameter	Type
schema	string
table	string
params	{[key: string]: string; }

Returns

DomainQuery