A FlatSQL broad-phase catalog over the sites of one
PackedEntityBlock.
Why tiles and not rows
One FlatSQL row per site was MEASURED at 387 bytes of heap with no index,
500 with one and 603 with three (200,000 rows, four-byte row stubs, with
getStorageBytes reporting only 52 B/row). A million sites is
387-603 MB before a single Entity exists - larger than this whole
layer's budget. A row per occupied TILE is 3.1 B/site measured, and it keeps
the semantic that matters: the SQL statement names candidates and never
decides containment, exactly as an R-Tree prefilter does for ordinary
catalog rows, and Analysis owns the exact phase afterwards.
Why not the R-Tree shadow table
flatsql@1.4.5 parses only a bare single-table
FROM - FROM "t" p and every JOIN fail with
SQL parse error: unsupported FROM target, measured - and ships
no R-Tree module, so _rtree_<table> cannot exist against
this pin for ANY caller, packed or ordinary. The tile table delivers the
same broad-phase semantic in statements the pin does execute.
| Name |
Type |
Description |
block |
PackedEntityBlock
|
The block whose sites become rows. |
options |
object
|
optional
Options.
| Name |
Type |
Default |
Description |
descriptor |
object
|
|
optional
The descriptor the block was built from,
used for its geodetic source when it has one. |
level |
number
|
8
|
optional
Tile level; the grid is 2^level squared. |
table |
string
|
|
optional
Table name; defaults to a unique name. |
attributes |
object
|
|
optional
Queryable attribute columns. |
|
Members
Row order: order[row] is the block SLOT of that row, and the
rows of one tile are contiguous.
Methods
The columns FlatSQL actually parsed out of the schema.
Returns:
The column names.
Releases the FlatSQL table. The typed arrays go with the catalog.
Runs a statement against the tile table.
| Name |
Type |
Description |
sql |
string
|
The statement. |
Returns:
{columns, rows}, rows aligned to columns.
Turns a tile-table result into the row ranges it names.
Returns:
Flat [firstRow, rowCount, ...] pairs.
A registered result value for one site.
| Name |
Type |
Description |
name |
string
|
The result column. |
slot |
number
|
The block slot. |
Returns:
The value.
The result columns registered so far.
Returns:
The names.
The row a slot occupies.
Built on first use, four bytes per site, and only for callers that ask a
site what its row is - the query path goes the other way and needs nothing.
| Name |
Type |
Description |
slot |
number
|
The block slot. |
Returns:
The row, or -1.
Registers a result column computed by an analysis kernel.
The values are readable as entity.properties[name] on a
materialized site and through PackedEntityCatalog#resultAt. This is
the hand-back half of PackedEntityBlock#batchView: a kernel is given
a contiguous batch and gives back a column, and there is never a second
representation of the answer.
| Name |
Type |
Description |
name |
string
|
The column name. |
values |
TypedArray
|
One value per ROW of rowIds, or per
site when rowIds is omitted. |
rowIds |
Uint32Array
|
optional
The rows the values belong to. |