gridcn2.0.0
Contracts

Query layer reference

The column map options, the operators per column kind, the request limits, and the error codes of the query layer.

This page lists the exact rules of the query layer.

PartWhere
Column optionsColumn map
Operators and valuesOperators
Bounds of a requestLimits
Error codesErrors
Differences from the clientClient differences

Column map

defineColumnMap(columns, { tieBreaker }) returns the map. Each column sets type or kind. A number column also sets numeric.

OptionMeaningDefault
typetext, number, checkbox, select, date, url, or longText. url and longText behave as text.Required
kindThe behavior of a custom cell type: text, number, checkbox, select, or date.From type
numericThe stored number type: int2, int4, int8, float, or decimal.Required on number
scaleDecimal places of a decimal column. A column with scale returns decimal strings.None
fieldThe physical column name when it differs from the id.The id
primaryKeyThe final sort key. At most one column.false
serverOnlyNever selected, filtered, sorted, searched, or aggregated for the client. rowScope can use it.false
searchableQuick search covers the column. At most 16 columns.false
filterable, sortablefalse rejects a filter or a sort on the column.true
requiredThe column is NOT NULL.false
caseSensitiveText tests compare case. A filter row with matchCase: true, which the grid sets for a matchCase column, compares case on any text column.false
keepBlankTextA stored empty string is a value, not empty.false
timeA date column that holds instants. Day filters use local days.false
storageHow a date column stores instants: native, iso-text, epoch-ms, or epoch-s.native
nativeThe PostgreSQL type of a text or select column: enum or uuid.None
choicesThe values of a select column. A native enum needs them.None
aggregateThe reducer of the flat totals: sum, avg, min, max, or count.None
operatorsCustom operators: { id, label, input }. input is none, single, range, or list.None

A table without a primary key passes tieBreaker, a list of unique columns that are not null and not serverOnly. The sort of every request ends with the primary key or the tie-breaker.

Operators

OperatorNumberDateCheckboxSelectText
contains, notContains, startsWith, endsWithRefusedRefusedRefusedAllowedAllowed
equals, notEquals, empty, notEmptyAllowedAllowedAllowedAllowedAllowed
gt, gte, lt, lte, isBetweenAllowedAllowedRefusedRefusedAllowed
isAnyOf, isNoneOfAllowedAllowedAllowedAllowedAllowed

A native enum or uuid column refuses the ordering operators.

The layer reads an empty value before it checks the kind of the column:

Operator with an empty valueResult
equalsThe empty rows
notEqualsThe rows that are not empty
contains, startsWith, endsWithEvery row
notContains, gt, gteNo row
lt, lteThe rows that are not empty
isAnyOf with no entryNo row
isNoneOf with no entryEvery row

An empty entry in a list stands for the empty rows. isAnyOf ["a", ""] matches a and the empty rows.

A value that cannot parse never fails the request. A positive test matches no row. notEquals matches every row. A day on a time column matches from the local midnight to the next one in timeZone.

Import rows

parseImportRows(input, { columns, limits }) reads the body of an import request, { rows: Record<string, unknown>[] }. It returns { rows, rejected }.

  • A request over maxImportRows rows throws a QueryError. So does a row that is not an object, a key that is not a mapped column, or a serverOnly key.
  • A value over maxValueLength, or a number text over maxNumberLength, throws limit-exceeded.
  • A value that does not fit its column kind is a refusal. A missing value in a required column is one too. The row stays out of rows, and rejected names it as { rowIndex, columnId, code, message }. message is English. code names the reason, such as "required" or "not-a-number". IMPORT_REFUSAL_MESSAGES lists every code. A route maps the code to its own language.
  • rows holds the parsed values. A number stays a number, or becomes canonical text when it came as text. A date is YYYY-MM-DD, an instant is ISO text, and a blank value is null.

An import check route answers { rejected }. The save route inserts rows. Pass maxBodyBytes to handleGridRequest for an import route. The default is 512 KiB.

Limits

Set limits on the factory to change a bound. A request over a bound fails with limit-exceeded or invalid-value. The defaults accept every spec that URL state and saved views restore.

LimitDefault
maxFilterNodes128
maxFilterLeaves64
maxSorts64
maxValueLength1000
maxNumberLength40
maxListLength1000
maxTreeListValues5000
maxTreeStringBytes262144
maxSearchLength500
maxValueQueryLength128
maxPageSize1000
maxOffsetNone
maxColumnIds10000
maxImportRows10000
maxGroupLevels4
maxGroupKeyLength1024
maxGroupAggregates32

A group nests one group at most. A deeper group fails with limit-exceeded. With maxOffset, a start above the bound fails with offset-too-deep.

Group answer

A request with groupBy and childKind: "groups" resolves a GroupsAnswer: groups, groupCount, and, at the top level, totalRowCount. Each group holds key, childCount, totalRowCount, and aggregates keyed by column id. A reducer with no counted value gives null. fetchRows has the type Promise<RowsAnswer | GroupsAnswer>. A capabilities.groupBy of false answers unsupported. A group page with a text key longer than maxGroupKeyLength fails with limit-exceeded at spec.groupBy.<columnId>. The bound never goes above 1,024, which is what the grid accepts.

Errors

The query layer throws QueryError with a code and a path. The path holds field names and indices, never request text. handleGridRequest answers { error, path }.

CodeStatusMeaning
invalid-request400The body has the wrong shape.
unknown-column400The column is not in the map, or is serverOnly.
unknown-operator400The operator is not built in and the column does not declare it.
operator-not-allowed400The operator does not fit the kind of the column, or the column is not filterable or sortable.
invalid-value400A value is over its length, or a range does not match the page.
limit-exceeded400The tree or a list is over a bound, or a group key is over maxGroupKeyLength.
offset-too-deep400start is above maxOffset.
unsupported501The request asks for a pivot, or the adapter cannot group.
payload-too-large413The body is over maxBodyBytes.

Client differences

TopicClientServer
Case foldingJavaScript lower casePostgreSQL by collation, SQLite for ASCII only
Text orderLocale compareDatabase collation
Number equalityText equalityNumeric equality
Blank sortingEmpty values lastNULL last, empty text not moved
Quick searchMarks matches and keeps every rowNarrows the result to the substring
Day filter on a timestampText orderLocal day in timeZone
Group deeper than 2The grid drops the grouplimit-exceeded

On this page