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.
| Part | Where |
|---|---|
| Column options | Column map |
| Operators and values | Operators |
| Bounds of a request | Limits |
| Error codes | Errors |
| Differences from the client | Client differences |
Column map
defineColumnMap(columns, { tieBreaker }) returns the map. Each column sets type or kind. A number column also sets numeric.
| Option | Meaning | Default |
|---|---|---|
type | text, number, checkbox, select, date, url, or longText. url and longText behave as text. | Required |
kind | The behavior of a custom cell type: text, number, checkbox, select, or date. | From type |
numeric | The stored number type: int2, int4, int8, float, or decimal. | Required on number |
scale | Decimal places of a decimal column. A column with scale returns decimal strings. | None |
field | The physical column name when it differs from the id. | The id |
primaryKey | The final sort key. At most one column. | false |
serverOnly | Never selected, filtered, sorted, searched, or aggregated for the client. rowScope can use it. | false |
searchable | Quick search covers the column. At most 16 columns. | false |
filterable, sortable | false rejects a filter or a sort on the column. | true |
required | The column is NOT NULL. | false |
caseSensitive | Text tests compare case. A filter row with matchCase: true, which the grid sets for a matchCase column, compares case on any text column. | false |
keepBlankText | A stored empty string is a value, not empty. | false |
time | A date column that holds instants. Day filters use local days. | false |
storage | How a date column stores instants: native, iso-text, epoch-ms, or epoch-s. | native |
native | The PostgreSQL type of a text or select column: enum or uuid. | None |
choices | The values of a select column. A native enum needs them. | None |
aggregate | The reducer of the flat totals: sum, avg, min, max, or count. | None |
operators | Custom 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
| Operator | Number | Date | Checkbox | Select | Text |
|---|---|---|---|---|---|
contains, notContains, startsWith, endsWith | Refused | Refused | Refused | Allowed | Allowed |
equals, notEquals, empty, notEmpty | Allowed | Allowed | Allowed | Allowed | Allowed |
gt, gte, lt, lte, isBetween | Allowed | Allowed | Refused | Refused | Allowed |
isAnyOf, isNoneOf | Allowed | Allowed | Allowed | Allowed | Allowed |
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 value | Result |
|---|---|
equals | The empty rows |
notEquals | The rows that are not empty |
contains, startsWith, endsWith | Every row |
notContains, gt, gte | No row |
lt, lte | The rows that are not empty |
isAnyOf with no entry | No row |
isNoneOf with no entry | Every 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
maxImportRowsrows throws aQueryError. So does a row that is not an object, a key that is not a mapped column, or aserverOnlykey. - A value over
maxValueLength, or a number text overmaxNumberLength, throwslimit-exceeded. - A value that does not fit its column kind is a refusal. A missing value in a
requiredcolumn is one too. The row stays out ofrows, andrejectednames it as{ rowIndex, columnId, code, message }.messageis English.codenames the reason, such as"required"or"not-a-number".IMPORT_REFUSAL_MESSAGESlists every code. A route maps the code to its own language. rowsholds the parsed values. A number stays a number, or becomes canonical text when it came as text. A date isYYYY-MM-DD, an instant is ISO text, and a blank value isnull.
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.
| Limit | Default |
|---|---|
maxFilterNodes | 128 |
maxFilterLeaves | 64 |
maxSorts | 64 |
maxValueLength | 1000 |
maxNumberLength | 40 |
maxListLength | 1000 |
maxTreeListValues | 5000 |
maxTreeStringBytes | 262144 |
maxSearchLength | 500 |
maxValueQueryLength | 128 |
maxPageSize | 1000 |
maxOffset | None |
maxColumnIds | 10000 |
maxImportRows | 10000 |
maxGroupLevels | 4 |
maxGroupKeyLength | 1024 |
maxGroupAggregates | 32 |
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 }.
| Code | Status | Meaning |
|---|---|---|
invalid-request | 400 | The body has the wrong shape. |
unknown-column | 400 | The column is not in the map, or is serverOnly. |
unknown-operator | 400 | The operator is not built in and the column does not declare it. |
operator-not-allowed | 400 | The operator does not fit the kind of the column, or the column is not filterable or sortable. |
invalid-value | 400 | A value is over its length, or a range does not match the page. |
limit-exceeded | 400 | The tree or a list is over a bound, or a group key is over maxGroupKeyLength. |
offset-too-deep | 400 | start is above maxOffset. |
unsupported | 501 | The request asks for a pivot, or the adapter cannot group. |
payload-too-large | 413 | The body is over maxBodyBytes. |
Client differences
| Topic | Client | Server |
|---|---|---|
| Case folding | JavaScript lower case | PostgreSQL by collation, SQLite for ASCII only |
| Text order | Locale compare | Database collation |
| Number equality | Text equality | Numeric equality |
| Blank sorting | Empty values last | NULL last, empty text not moved |
| Quick search | Marks matches and keeps every row | Narrows the result to the substring |
| Day filter on a timestamp | Text order | Local day in timeZone |
| Group deeper than 2 | The grid drops the group | limit-exceeded |