Type References

Determines how the grid treats this column.

• "measure" — stored as a number (INTEGER or DOUBLE in SQL). The grid can aggregate it (sum, avg, etc.) and reports numeric domain ranges (min/max) for filtering.
• "dimension" — used for grouping, pivoting, and labeling rows. Stored as VARCHAR (or TIMESTAMP if subtype is "temporal"). Filtering returns distinct categorical values.

Optional refinement that controls SQL type casting and filtering behavior. See SchemaSubtype.

Format string that tells the SQL engine how to parse date/time values from raw strings. Only used when subtype is "temporal".

Uses strptime format codes — e.g. "%Y-%m-%d" parses "2024-03-15", "%m/%d/%Y %H:%M" parses "03/15/2024 14:30".

Aggregate function for measures. Defaults to "sum" if not specified. See AggregateFn.

Cardinality hint for dimensions: "low" for few unique values, "high" for many. Upstream consumers can use this to pick appropriate UI — e.g. a dropdown for low cardinality vs. a search input for high cardinality.

The column name as it appears in the data source.

Optional human-readable label for rendering in headers.

Start row index in the data source (inclusive). The caller is responsible for converting any logical row to a row index in the data source. All pages overlapping the [startRow, endRow) range that are not already cached are fetched in parallel.

End row index in the data source (exclusive).

Path into the group hierarchy. When groupBy is set, data is organized in nested groups. Expanding a group progressively loads its child pages. groupPath represents which expanded path to fetch from - empty [] for top level, ["USA"] for children of "USA", ["USA", "California"] for children of California under USA.

Columns that form the grouping hierarchy (e.g. ["country", "state"]). When set, the data source returns aggregated group rows instead of individual rows. Each level in groupBy becomes a nesting level - the first column forms the top-level groups, the second forms sub-groups within each expanded parent, and so on. groupPath determines which level is being fetched.

Columns to include in the output.

Sort instructions. Array is ordered by priority (multi-sort) - first entry is the primary sort. See SortEntry.

Filter conditions. Multiple filters are combined with AND - all must match. See ScalarFilter.

Agent-defined metadata configuration. Core does not interpret this field — it passes it through to the metadata plumber.

Column to sort by.

Sort direction. "noop" means this entry is inactive.

When absent, rows are sorted by the value of field directly. When present, field identifies which group to sort and by specifies a measure column whose aggregated value determines the order. For example, { field: "country", direction: "desc", by: "revenue" } sorts country groups by their total revenue descending.

Always "scalar" for scalar filters.

Column to filter on.

Set to "date" for date-part filters (year, month, etc).

Comparison operator.

Value to compare against. Shape depends on op - array for in/not_in/between, scalar for others, null for empty/notEmpty.

Which part of the date to extract before comparing. See DatePart.

Number of rows per page.

Maximum number of fetched pages to keep in memory before the farthest page is evicted. This is how larger-than-memory datasets are supported - only a bounded window of pages is held in the browser at any time.

Column-major data arrays. Each inner array holds all values for one column. For example, 3 rows with columns [name, age] is stored as [["Alice", "Bob", "Carol"], [30, 25, 28]].

Total number of rows.

Raw metadata columns extracted from the query. Keys are metadata aliases (e.g. "__meta__email__null"), values are column-major arrays aligned with rowData rows. Populated when a metadata resolver contributes expressions to the getData query.

Column-major row data, or null if the page has not been fetched yet.

The starting row index in the data source for this page. Physical index refers to the actual row position in the source data, as opposed to logical index which is the position the renderer displays. These differ when virtualization or lazy loading is active - only a subset of physical rows may be loaded, and the renderer maps them to logical positions.

Number of rows this page covers.

Map from local row index to its ExpandedGroup. When expand(groupPath) is called, an entry is added here for that row with expanded: true and child pages populated. When collapse(groupPath) is called, expanded is set to false but the entry and its child data remain cached for fast re-expansion.

Page-scoped metadata (rows + cells) in page-local coordinates. Evicted with data when the page is evicted.

Whether this group is currently expanded. false means collapsed but child data is still cached.

Total number of child rows in this group.

Child PageNodes holding the group's row data.

Defines the row axis. Pass a plain string, an operator tree (AxisExpr), or an AxisConfig to include dimensional projection.

Defines the column axis. Same types as rows.

Filters applied globally to both axes before aggregation. Supports ScalarFilter and TupleFilter. Multiple filters are combined with AND.

Controls the ordering of row facet values. Each SortEntry can sort by the dimension value itself (by absent) or by a measure's aggregated value (by set to a measure field). direction: "noop" keeps the natural order.

Agent-defined metadata configuration. Core does not interpret this field — it passes it through to the metadata plumber's resolver and reshaper.

Values to expand at this level. "*" expands all values; an array expands only the listed values.

Projection for the next level down. Only applies to values matched by open. If absent, expansion stops at this level.

Tree describing the dimensional grouping structure. See DimSpec.

Flat list of measures to aggregate. Each has a field, aggregation function, and optional filters.

Sort instructions for row dimension values. When present, only covers row dimension fields.

Column name of the measure field.

Aggregation function to apply. See AggregateFn. Defaults to "sum" if not specified in the schema.

Optional ScalarFilters applied to this measure before aggregation.

Column names in order: dimension columns first, then measure columns.

Column-major data. data[i] holds all values for columns[i]. All inner arrays have the same length (the row count).

Metadata columns extracted separately from the main data. Keys are metadata aliases (e.g. "__meta__profit_pct"), values are column-major arrays aligned with the main data rows.

Always "facet".

Column names to query values for.

"distinct" returns unique values per field independently. "group" returns observed combinations across fields.

Optional pre-filters to narrow the values returned (e.g. only show countries within a selected region).

Always "tuple" for tuple filters.

Columns that form the tuple (e.g. ["region", "country"]).

"in" includes matching tuples; "not_in" excludes them.

Array of tuples to match. Each inner array has one value per field, in the same order as fields.

Total number of rows in the viewmodel (not just the slice).

Total number of columns in the viewmodel (not just the slice).

Number of rows in this slice.

Number of columns in this slice.

Column facet values for the sliced columns, transposed from the viewmodel's storage. The viewmodel stores facets as colFacets[level][colIndex]; the slice transposes them to columnFacets[colIndex][level] (grouped per column).

Example - viewmodel with 2 levels, 4 columns:

colFacets = [["Q1","Q1","Q2","Q2"], ["revenue","cost","revenue","cost"]]

Slice for columns 1-2:

columnFacets = [["Q1","cost"], ["Q2","revenue"]]

Absent when the slice is empty.

Column-major data for the sliced range: data[colIndex][rowIndex]. Absent when the slice is empty.

Row facet values for the sliced rows, transposed from the viewmodel's storage. The viewmodel stores row facets as rowFacets[level][rowIndex]; the slice transposes them to rowFacets[rowIndex][level] (grouped per row). null means the value is the same as the row above (for merge/span rendering).

Example - viewmodel with 2 levels, 3 rows:

rowFacets = [["Europe",null,"North America"], ["Germany","France",null]]

Slice for rows 0-2:

rowFacets = [["Europe","Germany"], [null,"France"], ["North America",null]]

Row facet values for the sliced rows. Group rows have a string label (e.g. "USA"); data/leaf rows have null. Single level, so no transposition - same shape as the viewmodel's storage.

Unpacked row metadata for the sliced rows. See FlatRowMeta.

Sets a value under namespace and key.

Returns all key-value pairs under namespace, or undefined if the namespace does not exist.

Clears a single key within namespace, or the entire namespace if key is omitted.

Height in pixels used for data rows when no VTrackDef.cellHeight override is set. Default: 19.

Width in pixels used as the initial column width before auto-sizing measures actual content. Default: 50.

Number of extra rows and columns rendered beyond the visible viewport in each direction. Higher values reduce blank flashes during fast scrolling but increase DOM node count. Default: 2.

When true, column facet cells render a drag handle on the right edge for interactive column resizing. Double-click the handle to auto-fit to content width. Default: true.

Fixture classes to instantiate on each edge of the grid. The layout creates one instance per class and positions them in array order. See Fixtures.

Name of the theme to apply. The layout resolves the theme via getTheme(name) and sets CSS custom properties on the grid container. Default: "light".

Controls how column widths update on scroll. "max-seen" keeps the widest measurement seen so far (columns only grow). "dynamic" re-measures every frame (columns can shrink when wide content scrolls out). Default: "max-seen".

Debounce interval in milliseconds for the viewDataEmpty event. Prevents flooding the data source with fetch requests during fast scrolling. Default: 150.

2D grid of aggregated values. data[col][row] holds the value at column position col and row position row. null means no data exists for that cell (the combination was not observed in the source data).

Column facet levels. Each inner array holds values for one facet level. For cross("quarter", concat("revenue", "cost")), this has two dimension levels (quarter) plus a measure-name level.

Row facet levels. Same structure as columnFacets but for the row axis. Absent when the row axis has no dimensions.

Facet metadata such as projection state for each facet level.

The original schema passed to the data model.

Metadata for value cells, facets, and headers. Merged into the ViewModel on construction and updateData.

Column-major data arrays for the visible rows. Each inner array holds all values for one column - e.g. 3 rows with columns [name, age] is [["Alice", "Bob", "Carol"], [30, 25, 28]]. This data is always contiguous (no gaps) - only pages that form a contiguous block around the current scroll position are included. Column-major layout supports large datasets efficiently as the renderer can access and iterate a single column array without touching other columns.

Column header labels. The layout uses this to render hierarchical column headers - each level is an array of labels. For standard tables, there is only one level and all columns are leaf-level headers.

Row facet values. When groupBy is active, some rows are group rows (showing a group label like "USA") and others are data/leaf rows. Group rows have their group value here (e.g. "USA"); leaf/data rows have null. The renderer uses this to display group row labels in a separate facet column on the left, visually distinguishing group headers from data rows. Only present when groupBy is non-empty.

Packed row metadata byte array encoding depth, isLeaf, and isExpanded per row.

Renderer options forwarded from setViewModelOptions.

DataSchema definitions.

Total number of rows the data source has, including expanded children. This is larger than the rows in data since pages are lazy loaded - only a contiguous subset is present in data. The renderer uses this for scrollbar sizing and virtual scroll calculations.

Number of rows in the data source that precede the returned data block. Since pages are lazy loaded, the page cache can have holes - only a contiguous block around the current scroll position is included in data. offsetTop tells the renderer how many rows come before this block, so it can position the rendered rows correctly within the full virtual scroll area.

Metadata for value cells, facets, and headers. Merged into the ViewModel on construction and updateData.