SkySpark by SkyFoundry

28. Grids


Grids are two-dimensional tabular representations of tagged entities. We use grids as the core data model to serialize haystack tagged data over HTTP using the Rest API.


Fantom APIs:

Axon APIs:


A grid is composed of:

Metadata is just a list of tags as name value pairs as specified by the tag model. Grid level metadata allows us to specify tags about the entire grid.

Columns and rows are used to model a list of Haystack tagged entities. Columns are computed by the union of all unique tag names in a list of entities. Each column is composed of a programmatic name which must be a valid tag name. Columns may also specify metadata using tags. The dis column tag may be used to provide a human friendly display name for the column (since the programmatic name will likely be camel case).

Rows are used to model the list of tagged entities. Rows are composed of a cell for each column in the grid. Each cell must be a valid tag kind scalar value or may be null/sparse if the row doesn't have a value for a given column.


Consider three haystack entities which model sites:

id: @site-a
dis: "Site A"
area: 45000ft²

id: @site-b
dis: "Site B"

id: @site-c
dis: "Site C"
area: 62000ft²
phone: "(804) 555-1234"

Our three entities all have an id, dis, and site tags. In addition two have the area tag, and one has a phone tag. To combine these three entities into a grid we end up with five columns and three rows:

id       dis       site  area      phone
-------  -------   ----  --------  ------
@site-a  "Site A"  ✓     45000ft²
@site-b  "Site B"  ✓
@site-c  "Site C"  ✓     62000ft²  "(804) 555-1234"

Note the columns are union of all tags shared by the entities. Because not every entity shares the same columns, we have sparse or null cells. We could further add grid level or column level meta.