@mosaicajs/client¶

@mosaicajs/client is the headless part of the TypeScript client. It talks to a Mosaica server and holds the state of a map, and leaves the drawing to other code. It has two layers. MosaicaClient is a thin HTTP client with one method per viewer and session route, and it keeps no state between calls. The store, which createStore makes, is built on it: you tell the store where the camera is, what to filter and which layers to draw, and it fetches, caches and composes the data. It publishes the result as projections: read-only snapshots of one part of the map's state each, such as marks, the points to draw, or view, the counts for the current view. MosaicaLayer in @mosaicajs/deck, the elements in @mosaicajs/components and the hooks in @mosaicajs/react all draw from a store, and your own code can read its projections too.

flowchart LR
  server["Mosaica server"] <--> client["MosaicaClient"]
  client <--> store["Store"]
  app["Your app"] -- "camera, filters, layers" --> store
  store -- "projections" --> draw["MosaicaLayer, components, your code"]

Control is a separate client for the server's control plane, which declares, ingests, deletes and publishes data. It sends an operator credential or an API key, so it belongs in a back end or a script. RecordsRead is the paged read of items or artifacts that both MosaicaClient and the store return.

The rest of the package is helpers for the store: building the filter drafts and member_of clauses it takes, listing which layers it can draw and colour by, converting coordinates, choosing palettes and formatting counts.

Store¶

The store is the client-side state of a map. You give it the camera position, filters and layer settings, and it fetches, caches and composes the data. It publishes the result as Projections, read-only snapshots of one part of the map's state each. Read a projection with get or projections, and hear of changes with subscribe.

Every count, artifact and record the store publishes covers only what the viewer may see. Methods that need the server's metadata (/v1/meta) wait for it to load.

A store holds data for one viewer. To show the map to a different viewer, call Store.clear or create a new store. The store calls authorise only to renew its token, so if authorise starts returning another viewer's token without a clear, the previous viewer's data stays on screen until the store has an answer under the renewed token. The store also discards what it holds and loads again when the server's data is compacted or rebuilt.

Properties¶

Property	Modifier	Type	Description
`budget`	`readonly`	`number`	How many marks the store aims to draw. Set by `budget` in the options or by `setBudget`.
`clusterBudget`	`readonly`	`number` \| `null`	The most artifacts a `nested` or `dag` layer is drawn with, or `null` for no limit. Set by `artifacts.budget` in the options or by `setClusterBudget`.
`projections`	`readonly`	`Projections`	The current value of every projection. The store replaces this object's fields as they change, so read a field each time you need it instead of keeping it.

Methods¶

basemapWorld()¶

basemapWorld(): Promise\<ArrayBuffer>

Fetch the world outline for a basemap (MosaicaClient.basemapWorld). The outline is the same for every viewer, so the stores on a page that use one server share one download. A failed fetch is not kept, so the next call tries again.

browse()¶

browse(req: Omit\<BrowseRequest, "view" | "filters"> & object): Promise\<BrowsePage>

Read one page of a layer's hierarchy: its roots, an artifact's children and parents, or the results of a name search. Each row carries its count of visible items. An artifact the store has not been served returns an empty page.

Parameters¶

Parameter	Type	Description
`req`	`Omit`\<`BrowseRequest`, `"view"` \| `"filters"`> & `object`	The page to read. `filters` defaults to Store.requestFilters, so the counts match the map's; pass `null` to count without filters. `view` defaults to the current view.

Throws¶

MosaicaError if the server refuses the request, for example with 422 for an unknown layer.

clear()¶

clear(): void

Forget the current viewer, so the map can be shown to another. The store drops its token, its metadata, everything it has fetched, the member_of clauses, the region and the selection, and abandons every request in flight. It publishes empty projections with status as idle, then asks authorise for a new token and loads again. A store created with a fixed token keeps it.

The filters, layers, colouring, point columns, current view and camera are kept. Any that name a view, layer or column the new metadata does not list are dropped, and if the current view is not listed the store opens on the first one.

The store does the same by itself, keeping its token, when the server reports that the viewer's identity has changed.

clearSelection()¶

clearSelection(): void

Clear the picked item, the opened artifact and their refusals. A pick or open still in flight is not shown. Publishes selection.

dataXY()¶

dataXY(worldX: number, worldY: number): [number, number]

Convert a world position to the current view's data coordinates. World space runs from 0 to WORLD_SIZE on each axis across the view's extent.

Throws¶

Error if /v1/meta has not loaded.

describe()¶

describe(id: bigint): Promise\<Record\<string, unknown> | null>

Fetch one item's fields for a hover. Each id is fetched once and the answer kept. Resolves to null if the request was refused. Publishes nothing; Store.pick opens a card.

dispose()¶

dispose(): void

Stop every timer and request. Closes the client if the store created it; a client passed as client is left for you to close.

extentOf()¶

extentOf(artifactId: bigint): [number, number, number, number] | null

A served artifact's box in the current view's data coordinates, [x0, y0, x1, y1]. null if the artifact is not in artifacts.served or has no box.

forgetSuggestions()¶

forgetSuggestions(column: string): void

Stop fetching suggestions for column and drop its page and error. Call it when a search box is emptied or removed.

frame()¶

frame(): Quantisation | null

The extent the current view's positions are quantised against, in data coordinates. null until /v1/meta has loaded.

get()¶

get\<K extends keyof Projections>(name: K): Projections[K]

The current value of one projection.

heldTitle()¶

heldTitle(column: string, key: string): string | null | undefined

The title Store.titleOf has already fetched, without a request. null if the value has no title. undefined if none is held, including while a lookup is in flight and after a refusal.

items()¶

items(req: StoreItemsRequest, signal?: AbortSignal): Promise\<RecordsRead\<ItemsHead>>

Read the items that match the map's filters, one page at a time. This is MosaicaClient.items with the store's token, view and filters filled in. It resolves when the first page's header arrives; call next() on the result for each page, as an Arrow table. Pages are fetched only as you ask for them.

const read = await store.items({fields: ['title'], pageRows: 50, count: true, inView: true});
const first = await read.next(); // read.head.matched counts every match
const second = await read.next(); // the next 50

A read keeps the filters it started with, so start a new one after the filters change. With inView, a call made before the map has set the camera or a region has been selected waits for one, then reads that area.

Parameters¶

Parameter	Type	Description
`req`	`StoreItemsRequest`	The read. `view` and `filters` default to the store's; see StoreItemsRequest.
`signal?`	`AbortSignal`	Aborts the read.

Throws¶

MosaicaError if the server refuses the first request. Error if inView is set with a view other than the current one. A DOMException named AbortError if the store is disposed while the call waits for the camera, or signal's reason if it is aborted.

needShape()¶

needShape(id: bigint): void

Fetch one artifact's outline into artifacts.shapes, simplified for the current zoom. Map tiles carry only each artifact's centre and box. A shape is fetched at most once, so this can be called on every pointer move.

openArtifact()¶

openArtifact(id: bigint): Promise\<void>

Fetch one artifact's details and publish them as selection.artifact, clearing selection.item. Its full-detail shape goes into artifacts.shapes. If the request is refused, the refusal is published as selection.artifactRefusal and the promise still resolves. An artifact the viewer cannot reach is refused the same as one that does not exist.

pick()¶

pick(id: bigint): Promise\<void>

Fetch one item's record and publish it as selection.item. An opened artifact stays open. If the request is refused, the refusal is published as selection.itemRefusal and the promise still resolves. An item the viewer cannot see is refused as unknown, the same as one that does not exist.

refresh()¶

refresh(): void

Fetch the current view again, as after a refusal. The artifacts are fetched afresh, and the points wherever the held tiles do not cover the view.

requestFilters()¶

requestFilters(): FilterExpr | null

The filter expression the store sends with every request: the filter controls, the member_of clauses and the selected region, combined with all_of. Controls and clauses set to highlight are not included. null when nothing is set. Artifact ids in the expression are decimal strings, so it can be serialised as JSON.

select()¶

select(shape: SelectionShape | null): void

Select a region, or clear the selection with null or a lasso of fewer than three points. The region becomes part of every request's filters, so the map is fetched again. Publishes region.

setAggregate()¶

setAggregate(id: string, spec: AggregateSpec | null): void

Keep a live aggregate of the current view under id, published in the aggregates projection. Pass null to drop it.

The aggregate counts what the map counts (Store.requestFilters). spec.without leaves one column's filter out, so a filter control can still show the values its own clause excludes; spec.withoutMembersOf does the same for a layer's member_of clauses. spec.subject: 'view' limits the counts to the area in view, and 'visible' ignores the filters and counts everything the viewer may see.

The store asks again whenever the filters, highlight, selected region or view change, and for a view aggregate once the camera comes to rest. Each call sends a new request, so call it when the spec changes, not on every render.

Example¶

A field card's histogram of `year`, in view and over everything the filters match,

each leaving out the card's own clause, and the field's figures:

const bins: Grouping = {count: true, by: {field: 'year', bins: 24, sample: 100_000}};
store.setAggregate('year:subject', {groupings: [bins], subject: 'view', without: 'year', highlighted: true});
store.setAggregate('year:match', {groupings: [bins], without: 'year'});
store.setAggregate('year:summary', {groupings: [{summary: ['year']}], subject: 'visible'});

setArtifactColours()¶

setArtifactColours(colours: ChosenColours): void

Give particular artifacts their own colours, keyed by layer and then by mosaica_id. Every other artifact keeps its palette colour. Each call replaces the last, and an empty map clears them. Publishes artifacts.colours and artifacts.overrides.

setBudget()¶

setBudget(budget: number): void

Set how many marks the store aims to draw on screen in every view, and fetch the map again. Anything but a positive finite number is ignored.

setClusterBudget()¶

setClusterBudget(budget: number | null): void

Limit every nested and dag layer to at most budget artifacts by drawing ancestors in place of their descendants. null removes the limit. The store fetches the affected layers again, and any aggregate that ranks a layer at cut: 'drawn'. Anything but a positive whole number or null is ignored.

setColourBy()¶

setColourBy(column: string | null): void

Colour points by a declared column, by a layer's clusters with cluster:<layer> for a layer colourLayers lists, or all alike with null. Publishes legend. Colouring by a layer fetches its artifacts and labels without drawing them. A layer that cannot colour leaves the points uniform. Points already held are fetched again with the new column.

setCurrentView()¶

setCurrentView(id: string): void

Switch to view id. An id meta.views does not list is ignored. Called before /v1/meta has loaded, it sets the view to open with.

Between views that share an extent, the camera and the selected region carry over and the new view draws what it already holds at once. A view with another extent drops both, and the next setView sets the camera. A switch clears the marks, the tiles, the typeahead pages and the fetched shapes, and publishes status as loading.

setFilters()¶

setFilters(draft: FilterDraft): void

Replace the filter controls with draft. Publishes filters and fetches the map again.

setLayers()¶

setLayers(names: string[]): void

Draw the artifacts of these layers, each together with the layers it is linked to by depends_on (layerClosure). Pass [] to draw none. Filter layers are ignored. Publishes artifacts.

setMembers()¶

setMembers(clauses: readonly MemberClause[]): void

Replace the member_of clauses, which keep the map to items inside or outside given artifacts: a card's "filter to this" and "outside this", or the nodes ticked in a hierarchy panel. Pass the whole list; withMember and withoutMember build it. Publishes filters.members and fetches the map again.

setPalette()¶

setPalette(palette: PaletteName): void

Colour clusters from palette. Publishes artifacts.colours and artifacts.palette. A name PALETTES does not list is ignored. Changing to a palette of a different size fetches the artifacts again.

setPointColumns()¶

setPointColumns(id: string, columns: readonly string[]): void

Ask for extra render columns on every point on behalf of id, such as the fields a hover reads from Band.scalars. The server sends only the render columns that have been asked for here or by setColourBy and setSizeBy. Pass [] to withdraw id's request. Names that are not render columns of the current view are ignored. Adding a column fetches the held points again, and they stay drawn until the new ones arrive. The request applies to every view.

setSizeBy()¶

setSizeBy(column: string | null, options?: object): void

Size points by a declared number column, or give every point the same size with null. With rank: true points are sized by rank instead of value. Publishes legend, whose domains and missing fill in from the points drawn. A column that is not a rendered number column sizes nothing.

Parameters¶

Parameter	Type
`column`	`string` \| `null`
`options?`	{ `rank?`: `boolean`; }
`options.rank?`	`boolean`

setView()¶

setView(input: ViewInput): void

Tell the store where the camera is. Call it whenever the camera moves. The store waits briefly for the camera to settle, then fetches what the view needs and publishes each frame as it is composed.

Call Signature¶

subscribe(fn: Listener): () => void

Call fn whenever any projection changes. An error thrown by fn is logged to the console and does not stop the other subscribers.

Returns¶

A function that unsubscribes fn.

() => void

Call Signature¶

subscribe\<K extends keyof Projections>(name: K, fn: (value: Projections[K]) => void): () => void

Call fn with the new value whenever projection name changes. It is not called with the current value; use get for that. An error thrown by fn is logged to the console and does not stop the other subscribers.

Returns¶

A function that unsubscribes fn.

() => void

suggest()¶

suggest(column: string, q: string, verb: ClauseVerb): void

Fetch typeahead suggestions for the category column column that match q, for a control set to verb. The page lands in filters.suggestions[column], each value with its count in the current view, and an error lands in filters.suggestErrors[column].

Under filter, the counts leave out the column's own clause, so each shows what choosing that value as well would add. Under highlight they use every filter, so a value the filters exclude counts 0.

Calls are debounced by 120 ms. The store fetches the suggestions again when the filters or the region change, until Store.forgetSuggestions is called. A request the server sheds is retried up to five times before the error is backpressure.

titleOf()¶

titleOf(column: string, key: string): Promise\<string | null>

The display title of key, a value of the category column column. Resolves to null if the value has no title, if column is not a category column a filter can name, or if the request was refused. Every value of a public vocabulary has its title. A value of a derived vocabulary has one only if the viewer may see an item that carries it. Titles are kept once fetched, and lookups made together go as one request.

Example¶

The title of an opened item's archive

map.addEventListener('mosaica-itemopen', async (e) => {
  const title = await store.titleOf('archive', String(e.detail.record.fields.archive));
});

AggregateSpec¶

AggregateSpec = object

A live aggregate for Store.setAggregate: the groupings to count, which items to count, and optionally a set to compare with. The store fills in the request's filters from its own filters and selected region.

Properties¶

Property	Type	Description
`groupings`	`AggregateSpecGrouping`[]	The groupings. The result has one table for each, in the same order.
`highlighted?`	`boolean`	Whether to count only the items that also match the store's highlight, so each count matches the viewport's `highlighted` count. Defaults to `false`. Has no effect when nothing is highlighted.
`reference?`	`FilterExpr` \| `"visible"`	A set to compare each count with: `'visible'` for every item the viewer may see in the view, or a filter expression. With it, each table also has `reference_count` and `lift` columns. Unset means no comparison.
`subject?`	`"match"` \| `"view"` \| `"visible"`	Which items to count. `match`, the default, counts the items that match the store's filters and selected region. `view` counts the same items within the area in view: the selected region if there is one, otherwise the camera's box; it is fetched again once the camera has rested for 250 ms, and `reference` is limited to the same area. `visible` counts every item the viewer may see in the view, wherever the camera is, and sends no filters, so `without`, `withoutMembersOf` and `highlighted` have no effect.
`without?`	`string`	A column whose filter control is left out of the counts, keyed as in the FilterDraft. A filter control uses this to keep counting the values its own clause excludes. The other controls, the `member_of` clauses and the selected region still apply.
`withoutMembersOf?`	`string`	A layer whose `member_of` clauses are left out of the counts, so a control that lists the layer's artifacts keeps counting the ones its clauses exclude. Other layers' clauses and the selected region still apply.

AggregateSpecGrouping¶

AggregateSpecGrouping = Omit\<Grouping, "by"> & object

One grouping in an AggregateSpec. The same as a Grouping, except that a layer grouping's cut and paletteSize can be 'drawn' to use the map's current values. cut: 'drawn' ranks a nested or dag layer's artifacts at the cut the map currently draws, under the cluster budget (Store.setClusterBudget). paletteSize: 'drawn' returns each artifact's slot in the palette the map colours clusters from (Store.setPalette). Both are read when each request is sent.

Type Declaration¶

Name	Type	Description
`by?`	`Exclude`\<`AggregateBy`, { `layer`: `string`; }> \| `DrawnLayerBy`	As Grouping.by, except that a layer's `cut` and `paletteSize` may be `'drawn'`.

DrawnLayerBy¶

DrawnLayerBy = Extract\<AggregateBy, { layer: string; }> extends infer B ? B extends object ? Omit\<B, "cut" | "paletteSize"> & object : never : never

A layer grouping in an AggregateSpecGrouping. cut and paletteSize may be 'drawn', meaning the cut and palette size the map draws that layer with.

ProjectionName¶

ProjectionName = keyof Projections

The name of one of the store's projections, such as marks or filters. A map projection (how a view's coordinates are laid out) is named by a different type, ViewInfo['projection'].

Projections¶

Projections = object

The store's projections, by name. A projection is a read-only snapshot of one part of the map's state, such as the points to draw (marks) or the filters in force (filters). When one changes the store replaces it with a new object, so comparing by identity tells you whether it changed. Store.subscribe reports each replacement.

Properties¶

Property	Type	Description
`aggregates`	`AggregatesProjection`	Each aggregate registered with Store.setAggregate, by its id.
`artifacts`	`ArtifactsProjection`	The artifacts served for the drawn layers, with their colours and shapes.
`filters`	`FiltersProjection`	The filter controls, the expressions composed from them, the `member_of` clauses and the typeahead.
`legend`	`LegendProjection`	The legend of the colour and size columns.
`marks`	`MarksProjection`	The marks on screen, for a renderer.
`meta`	`Meta` \| `null`	The `/v1/meta` the store read or was given. `null` until it has loaded, and again after Store.clear or a change of the viewer's identity, until the store has read it again.
`region`	`RegionProjection` \| `null`	The selected region and its counts, or `null` while nothing is selected.
`replica`	`ReplicaProjection`	How much the store's tile cache holds.
`selection`	`SelectionProjection`	The picked item and the opened artifact.
`status`	`StatusProjection`	Whether the current view's map is loading, shown, empty or refused.
`tiles`	`TilesProjection`	The tiles of the frame on screen.
`view`	`ViewProjection`	The current view's id, the frame on screen and the frame's counts.

StoreItemsRequest¶

StoreItemsRequest = Omit\<ItemsRequest, "view" | "filters"> & object

The request Store.items takes: an ItemsRequest whose view and filters default to the store's, with inView to read only the area in view.

Type Declaration¶

Name	Type	Description
`filters?`	`FilterExpr` \| `null`	Defaults to Store.requestFilters, so the read returns the items the map counts as matching. `null` reads every item the viewer may see.
`inView?`	`boolean`	Read only the area the in-view counts cover: the selected region if there is one, otherwise the camera's box. Current view only.
`view?`	`string`	The view to read. Defaults to the current view.

StoreOptions¶

StoreOptions = object

Options for createStore. Pass viewerUrl or client, and token or authorise. A store with neither token nor authorise sends no credentials, which only an open server (serve.open) accepts.

Properties¶

Property	Type	Description
`artifacts?`	`object`	How the drawn layers' artifacts are fetched, in tiles 128 to 256 pixels across.
`artifacts.budget?`	`number`	The starting cluster budget (Store.setClusterBudget). By default there is no limit.
`artifacts.heldTiles?`	`number`	How many tiles of artifacts to keep per view. Defaults to `4096`.
`artifacts.perTile?`	`number`	The most artifacts one level shows in a tile, largest first. Defaults to 50, or to `meta.selection.maxArtifactsPerTile` if that is lower, and the server refuses a larger value.
`authorise?`	`TokenSupplier`	A function that returns a viewer token. The store calls it at the start and again before the token expires; see TokenSupplier.
`budget?`	`number`	How many marks the store aims to draw on screen. Defaults to DEFAULT_BUDGET.
`client?`	`MosaicaClient`	A MosaicaClient to send requests through, such as one shared between stores. By default the store creates one from `viewerUrl` and `clientOptions`. You close a client you pass in; Store.dispose closes only one the store created.
`clientOptions?`	`Omit`\<`MosaicaClientOptions`, `"viewerUrl"`>	Options for the client the store creates, such as `headers`, `fetch` or `decoder`. Ignored if `client` is given.
`meta?`	`Meta`	A `/v1/meta` response you have already fetched, so the store need not fetch it again. It must have been fetched with this viewer's token.
`palette?`	`PaletteName`	The palette clusters are coloured from (see PaletteName). Defaults to `tableau10`.
`prefetch?`	`boolean`	Whether to fetch ahead while the camera is still: the tiles around the view and one zoom level deeper. Defaults to `true`.
`replica?`	`Pick`\<`ReplicaOptions`, `"cacheBytes"` \| `"cache"` \| `"revalidateAfterMs"` \| `"onPhase"`>	The tile cache, which every view shares. `cacheBytes` is the most it holds, evicting the tiles drawn least recently; it defaults to 512 MiB. `cache: false` holds nothing, so every camera move makes a request, which is useful for measuring the cache. `revalidateAfterMs` is how long the store may answer the camera from the cache alone before it asks the server whether the counts have changed; it defaults to `60000`. `onPhase(kind, ms, n)` reports how long each step inside the cache took, for instrumentation.
`token?`	`string`	A viewer token, used for every request and never renewed. Takes precedence over `authorise`.
`view?`	`string`	The view to open with. Defaults to the first view in `meta.views`.
`viewerUrl?`	`string`	The viewer server's base URL, as for MosaicaClientOptions.viewerUrl. An empty string means the page's own origin. Required unless `client` is given.

TokenSupplier¶

TokenSupplier = () => Promise\<{ expiresAt: number; token: string; }>

A function that returns a viewer token and its expiry, expiresAt in seconds since the Unix epoch, as MosaicaClient.login and MosaicaClient.authorise return them. Return Infinity as expiresAt for a token that does not expire.

The store renews the token 30 seconds before it expires, or halfway through a lifetime shorter than a minute. It is also called if the server rejects a token that had worked with 401, as after a restart. Concurrent requests share one call. If the function rejects, the request waiting for the token fails. To change viewer, call Store.clear.

Returns¶

Promise\<{ expiresAt: number; token: string; }>

ViewInput¶

ViewInput = object

The camera position, as Store.setView takes it.

Properties¶

Property	Type	Description
`bbox`	[`number`, `number`, `number`, `number`]	The area the canvas shows, `[x0, y0, x1, y1]` in the current view's data coordinates. It may be clamped to the view's extent, as `viewInputOf` in `@mosaicajs/deck` clamps it.
`height`	`number`	The canvas height in pixels.
`width`	`number`	The canvas width in pixels.
`zoom`	`number`	The camera's zoom, as deck.gl's `OrthographicView` counts it: `2 ** zoom` pixels per world unit, so at 0 the 512-unit world is 512 pixels wide. It is passed separately because a clamped `bbox` does not give the true zoom.

DEFAULT_BUDGET¶

const DEFAULT_BUDGET: 250000 = 250_000

How many marks a store aims to draw on screen when StoreOptions.budget is not given.

createStore()¶

createStore(options: StoreOptions): Store

Create a store and start loading the server's metadata (/v1/meta), unless options.meta provides it. If the server refuses, status is published as refused, and the store tries again on the next call that needs the metadata or when authorise supplies a new token.

Throws¶

Error if options has neither viewerUrl nor client.

Projections¶

ArtifactTable¶

A table of the artifacts the store holds, each numbered with a small integer called an ordinal. Points refer to artifacts by ordinal (BandMembership), and a renderer looks ordinals up here to find the artifact and its colour. Read it from ArtifactsProjection.table; only the store writes to it.

An ordinal is an unsigned 32-bit integer, with NO_ORDINAL for none. Once the store no longer holds an artifact, its ordinal is freed and may be given to another artifact.

Properties¶

Property	Modifier	Type	Description
`live`	`readonly`	`number`	How many ordinals are in use.
`range`	`readonly`	`number`	One more than the highest ordinal assigned: the size a lookup texture indexed by ordinal needs.
`version`	`readonly`	`number`	A number that changes whenever the table does. A value derived from the table is up to date while this is unchanged. Compare it for equality only.

Methods¶

changesSince()¶

changesSince(version: number): ArtifactTableChange[] | null

Every change since version, oldest first, so you can update a colour map or lookup texture instead of rebuilding it.

Returns¶

ArtifactTableChange[] | null

The changes, [] if version is current, or null if the table no longer has them (for example if version is from before the table was last cleared). On null, rebuild from liveEntries().

entry()¶

entry(ordinal: number): ArtifactEntry | null

The artifact with this ordinal, or null if the ordinal is 0, freed or never assigned.

liveEntries()¶

liveEntries(): object[]

Every ordinal in use, with its artifact.

ordinalOf()¶

ordinalOf(layer: string, mosaicaId: bigint): number

The ordinal of an artifact, or NO_ORDINAL if the table does not hold it.

resolve()¶

resolve(ordinal: number, served: object, maxLevel?: number): number

Find the ordinal itself or its nearest ancestor that is in served, by following parent links. Use it to colour a point by the artifact drawn at the current cut. On a dag layer it follows the first parent at each step.

Parameters¶

Parameter	Type	Description
`ordinal`	`number`	The ordinal to start from, such as a point's entry in BandMembership.ordinals.
`served`	{ `has`: (`ordinal`: `number`) => `boolean`; }	The ordinals drawn at the current cut, such as a set of ordinals or a colour map.
`served.has`	(`ordinal`: `number`) => `boolean`	Whether an ordinal is drawn at the current cut.
`maxLevel?`	`number`	The level to colour at: the walk skips ancestors in `served` whose `rung` is deeper than this. By default it stops at the first one in `served`.

Returns¶

number

The ordinal found, or NO_ORDINAL if the walk runs out of known parents.

AggregateEntry¶

AggregateEntry = object

The state of one aggregate registered with Store.setAggregate.

Properties¶

Property	Type	Description
`palette`	`PaletteName` \| `null`	The palette the slots in `result` refer to. `null` if there is no result or no grouping asked for palette slots.
`refusal`	`Refusal` \| `null`	Why the last request failed, or `null`.
`result`	`AggregateResult` \| `null`	The latest answer, kept while the next request loads. `null` before the first answer, after a refusal, after a view switch, and after Store.clear or a change of the viewer's identity. For a histogram with a `sample`, the table's `sample` says whether the counts were scaled up from a sample.
`status`	`"loading"` \| `"retrying"` \| `"shown"` \| `"refused"`	`loading` while a request is in flight, or while a `view` aggregate waits for the camera to rest. `retrying` while the server is busy (`429` or `503`) and the store waits to ask again. `shown` once the answer has arrived, and `refused` if the request failed.
`summaries`	readonly (`ReadonlyMap`\<`string`, `FieldSummary`> \| `null`)[]	One entry per grouping, in order: the figures for each field the grouping lists under `summary`, keyed by field name, or `null` for a grouping without `summary`. Empty if there is no result.
`view`	`string` \| `null`	The view `result` was counted in, or `null` if there is no result.

AggregatesProjection¶

AggregatesProjection = ReadonlyMap\<string, AggregateEntry>

The aggregates projection: each aggregate registered with Store.setAggregate, by its id.

ArtifactEntry¶

ArtifactEntry = object

One artifact in an ArtifactTable.

Properties¶

Property	Type	Description
`centroid`	readonly [`number`, `number`] \| `null`	The artifact's centroid in 32-bit grid units (GRID32), or `null` if not known.
`layer`	`string`	The artifact's layer.
`mosaicaId`	`bigint`	The artifact's `mosaica_id`.
`paletteSize`	`number` \| `null`	The palette size `slot` refers to, or `null` if `slot` is not known.
`parentOrdinals`	readonly `number`[]	The ordinals of the artifact's parents, in ascending `mosaica_id` order. Only parents that arrived in the same response as the artifact are listed, so the list may be empty even if the artifact has parents. A tree has at most one parent; a `dag` layer may have several.
`rung`	`number`	The artifact's level: the declared level on a layer with levels, the depth of its parent chain on a tree, and `0` on a flat layer.
`slot`	`number` \| `null`	The artifact's slot in the palette, or `null` if not known. Its colour depends only on this and `paletteSize`, so it can be coloured even when the current view has not served it.

ArtifactsProjection¶

ArtifactsProjection = object

The artifacts projection: the artifacts of the layers being drawn, with their colours and shapes. An artifact is one element of a layer, such as a cluster or a region. Artifacts the viewer may not see are absent.

Properties¶

Property	Type	Description
`attached`	`ReadonlyMap`\<`bigint`, `string`>	Text attached to artifacts, such as a clustering's topic labels, keyed by the artifact it belongs to. artifactName uses it to name the artifacts in `served` and `colourServed`.
`colours`	`ReadonlyMap`\<`number`, `Rgba`>	The colour of each artifact in `table`, by ordinal. It covers more than `servedOrdinals`, because a band fetched at a coarser cut names other artifacts and its points take their colours.
`colourServed`	`Artifact`[]	If points are coloured by a layer (`setColourBy('cluster:<layer>')`), that layer's artifacts, whether or not it is drawn. Otherwise empty.
`coverage`	`object`	Whether the bands in view can colour their points by the layers in use. Both counts are `0` unless `status` is `shown` and a layer is in use.
`coverage.current`	`number`	How many bands in view can colour every point by each layer in use.
`coverage.stale`	`number`	How many bands in view cannot, and are being fetched again.
`held`	`number`	How many artifacts the store holds, including those kept from earlier answers.
`layer`	`string` \| `null`	The first layer drawn, or `null` if none is.
`layers`	`string`[]	Every layer drawn, including those linked by `depends_on` (layerClosure) and excluding filter layers. A layer used only to colour points is not listed.
`lineage`	`ServedLineage`	The parent-child links between the artifacts in `served`.
`overrides`	`ChosenColours`	The colours set with Store.setArtifactColours, which `colours` uses in place of the palette's.
`palette`	`PaletteName`	The palette set with Store.setPalette. Each colour in `colours` comes from the palette its slot was served under, so after a change of palette the colours follow as the artifacts are fetched again.
`refusal`	`Refusal` \| `null`	Why the request was refused while `status` is `refused`, otherwise `null`.
`served`	`Artifact`[]	The artifacts of the drawn layers for the current camera.
`servedOrdinals`	`ReadonlySet`\<`number`>	The ordinals of the artifacts in `served`.
`shapes`	`ReadonlyMap`\<`bigint`, `Shape`>	Artifact outlines by `mosaicaId`: those fetched by Store.needShape, simplified for the zoom, and those fetched by Store.openArtifact, at full detail. Draw an artifact with no entry as its `box`. Emptied by a view switch and by Store.clear.
`status`	`ArtifactChannelState`[`"status"`]	`idle` before the first answer and while no layer is drawn. `loading` while a request is in flight. `shown` when `served` is up to date with the camera. `refused` when the request was refused, in which case `served` is empty.
`table`	`ArtifactTable`	The artifact table, shared by every view. A band's membership columns hold ordinals, and the table turns them into artifacts.
`version`	`number`	A number that increases each time `served` is replaced.

ArtifactTableChange¶

ArtifactTableChange = object

A change to one ordinal, as ArtifactTable.changesSince reports it.

named: the ordinal was assigned to an artifact. Only that ordinal's own derived values change.
placed: the artifact's centroid or palette slot arrived or changed, so its colour and those of every ordinal that resolves through it may change.
linked: a parent was set on an existing artifact, so its descendants may resolve differently.
freed: the ordinal was released and may be reused.

Properties¶

Property	Type	Description
`kind`	`"named"` \| `"placed"` \| `"linked"` \| `"freed"`	What changed.
`ordinal`	`number`	The ordinal that changed.

Band¶

Band = object

The points the store holds for one tile, in ascending mosaica_id order as the server sent them, with the tile's counts. Per-point arrays are in the same order as ids. A tile with no matching points has a band with no points, which carries the counts and draws nothing.

Properties¶

Property	Type	Description
`bytes`	`number`	An estimate of the bytes the band occupies, counted against the cache's `cacheBytes`.
`capUsed`	`number`	The most points per tile (`k`) the band was fetched with.
`columnsAsked?`	readonly `string`[] \| `null`	The render columns the band's request asked for, or absent or `null` if it asked for all of them.
`contentKey`	`string`	Identifies the version of the data the band was answered from (ViewportResponse.contentKey). It changes when items may have been added, when a deletion, suppression or lift applies, and when the server restarts. A band with an older content key may still be drawn until the store has fetched the tile again.
`depth`	`number`	The tile's depth, 0 to 16.
`heldBelow`	`bigint`	One more than the highest `mosaica_id` in `ids`, or `0n` for a band with no points.
`highlightBits`	`Uint8Array` \| `null`	One byte per point: `1` if the point matches the highlight, `0` if not. `null` if no highlight was set, in which case every point is drawn at full strength.
`highlighted`	`bigint`	How many of `matched` also match the highlight. Equal to `matched` when none is set.
`identityKey`	`string`	Identifies the set of items the viewer may see in this view when the band was fetched (ViewportResponse.identityKey). It changes when the session belongs to a different viewer and when the dataset is rebuilt or compacted; the store then drops every band and fetches again.
`ids`	`BigUint64Array`	Each point's `mosaica_id`, ascending.
`layersAsked?`	readonly `string`[] \| `"all"`	The layers the band's request asked for. A layer listed here with no entry in `membership` has none of the band's points. Absent if not known.
`matched`	`bigint`	How many of `visible` match the filters.
`membership`	`Record`\<`string`, `BandMembership`>	For each layer in use when the band was fetched, the artifact each point belongs to. A layer missing here was either not in use when the band was fetched (see `layersAsked`), or none of the band's points belong to it.
`positions`	`Float32Array`	Each point's position in deck.gl world space, as interleaved `x` and `y`.
`prefix`	`bigint`	The tile's Morton prefix at `depth`.
`scalars`	`Record`\<`string`, `ScalarColumn`>	The render columns fetched for these points, by name. See Store.setPointColumns for how to ask for more.
`served`	`number`	How many points the server sent for this tile at this depth. Equal to `ids.length` unless the cache has since dropped some of them to save memory.
`touchedAt`	`number`	When the request that fetched the band started, in milliseconds from `performance.now()`.
`visible`	`bigint`	How many items the viewer may see in the tile.
`x`	`number`	The tile's column index at `depth`.
`y`	`number`	The tile's row index at `depth`.

BandMembership¶

BandMembership = object

Which artifact of one layer each point in a Band belongs to.

Properties¶

Property	Type	Description
`distinct`	`Uint32Array`	The distinct non-zero ordinals in `ordinals`, in ascending order.
`ordinals`	`Uint32Array`	Each point's artifact, as an ordinal in the ArtifactTable, or `0` if the point belongs to no artifact of the layer.

ComposedTile¶

ComposedTile = object

One tile in a Composition: what one band contributes to the frame.

Properties¶

Property	Type	Description
`counts`	{ `highlighted`: `bigint`; `matched`: `bigint`; `served`: `number`; `visible`: `bigint`; } \| `null`	The server's counts for the tile, or `null` for a stand-in. `visible` is how many items the viewer may see in the tile, `matched` how many of those match the filters, `highlighted` how many of those match the highlight, and `served` how many points were sent.
`depth`	`number`	The band's depth, which may differ from the frame's.
`drawn`	`number`	How many marks the tile draws. For an exact tile this is its `served` count.
`exact`	`boolean`	`true` if the marks are the points the server sent for this tile at the frame's depth. `false` for a stand-in, and for a tile whose counts have arrived before its points, which draws nothing.
`prefix`	`bigint`	The tile's address: its Morton prefix at `depth`.

Composition¶

Composition = object

The frame on screen, as ViewProjection.composition holds it: which bands to draw. Exact bands are the server's answer for the frame's tiles at its depth. Stand-ins are points from other depths, drawn until the exact bands arrive, and carry no counts. A renderer builds its draw buffers from these bands.

Properties¶

Property	Type	Description
`depth`	`number`	The tile depth the frame is drawn at, 0 to 16.
`exact`	`Band`[]	The exact bands.
`exactDrawn`	`number`	How many marks the exact bands draw.
`exactServed`	`number`	The sum of the exact bands' `served` counts. Equal to `exactDrawn` in every published frame.
`provisional`	`number`	How many stand-in marks are on screen. It does not count items.
`standIn`	`StandInPiece`[]	The stand-ins, coarsest first. Stand-ins from deeper bands are thinned to the density of the frame's depth, and none covers a tile an exact band covers.
`standInStale`	`boolean`	`true` if the stand-ins were kept from an earlier frame when new exact bands arrived. The next full composition replaces them.
`tiles`	`ComposedTile`[]	One entry per exact band and per stand-in.
`version`	`number`	The tile cache's version when the frame was composed or last refreshed. Compare it for equality only.
`visibleInView`	`number`	The sum of the exact bands' `visible` counts: how many items the viewer may see in those tiles.

Domain¶

Domain = object

The range of a number column's values among the marks drawn, for a colour ramp. It is taken from the drawn marks, so it covers only what the viewer can see. It widens as marks arrive and does not narrow until the store is cleared, so panning does not recolour the map. LegendProjection.domains holds one per column.

Properties¶

Property	Type	Description
`max`	`number`	The largest finite value drawn.
`min`	`number`	The smallest finite value drawn.

FieldSummary¶

FieldSummary = object

Summary figures for one number or timestamp field, over every item the viewer may see in the view.

Properties¶

Property	Type	Description
`max`	`number` \| `bigint` \| `null`	The largest finite value, typed as `min` is.
`mean`	`number` \| `null`	The mean of the finite values, in milliseconds since the Unix epoch for a timestamp field. `null` if `values` is 0.
`min`	`number` \| `bigint` \| `null`	The smallest finite value: a `bigint` for an integer field, a number for a float field, and milliseconds since the Unix epoch for a timestamp field. `null` if `values` is 0.
`missing`	`bigint`	How many items have no value.
`values`	`bigint`	How many items have a finite value.

FiltersProjection¶

FiltersProjection = object & SuggestState

The filters projection: the filter controls, the expressions built from them, the member_of clauses and the typeahead suggestions.

Type Declaration¶

Name	Type	Description
`draft`	`FilterDraft`	The controls as `setFilters` last set them. Until then, one empty control per filterable column (emptyDraft).
`expr`	`FilterExpr` \| `null`	The expression built from the controls set to `filter`, or `null` if there are none. It leaves out the `member_of` clauses and the region; Store.requestFilters includes them.
`highlight`	`FilterExpr` \| `null`	The expression built from the controls set to `highlight`, or `null` if there are none. It leaves out `member_of` clauses set to highlight, which requests still include.
`members`	`MemberClause`[]	The `member_of` clauses as `setMembers` last set them.

InViewCounts¶

InViewCounts = object

Counts over the area in view: the selected region if there is one, otherwise the camera's box. The frame's counts in ViewProjection cover whole tiles, which extend past the box; these cover the area exactly. They are fetched once the camera has rested for 250 ms, and again when the filters, highlight or selection change.

Properties¶

Property	Type	Description
`highlighted`	`Masked`	How many of `matched` also match the highlight. Equal to `matched` when none is set.
`matched`	`Masked`	How many of `visible` match the filters.
`shown`	`number`	How many of the frame's marks lie in the area.
`status`	`"loading"` \| `"shown"` \| `"refused"`	`loading` while new counts are being fetched, with the previous counts kept until they arrive. `shown` once they have arrived, and `refused` if the request was refused.
`visible`	`Masked`	How many items the viewer can see in the area.

LegendProjection¶

LegendProjection = object

The legend projection: what the points are coloured and sized by, and what a legend needs to explain it. It builds up from the marks drawn: names and palette ranks for a category column, a range for a number column, and for the size column whether any point has no value. Colouring by a layer (cluster:<layer>) adds nothing here. Store.clear empties it but keeps colourBy and sizeBy.

Properties¶

Property	Type	Description
`categories`	`Record`\<`string`, `CategoryValue`[]>	The codes drawn for each category column, with their names.
`categoryErrors`	`Record`\<`string`, `Refusal`>	For each category column whose names could not be fetched, why. The store does not ask again until it is cleared.
`colourBy`	`string` \| `null`	What the points are coloured by, as `setColourBy` last set it: a column, `cluster:<layer>`, or `null` for one colour.
`domains`	`Record`\<`string`, `Domain`>	The range of values drawn for each number column. It widens as marks arrive and does not narrow.
`missing`	`Record`\<`string`, `boolean`>	For the column sized by, whether any point drawn had no finite value. Such points are drawn as rings.
`ranks`	`Record`\<`string`, `Ranks`>	Palette ranks for each category column, by code. Values are ranked by how many items with that value the viewer may see across the whole view, most first, so a value gets the same colour each time the same data is loaded. If the server refuses that count, codes are ranked by how often they appear among the marks drawn. A rank does not change once given. A code is drawn in the unmapped colour until its rank arrives.
`samples`	`Record`\<`string`, `ValueSample`>	A sample of the values drawn, for a column sized by rank.
`sizeBy`	`string` \| `null`	The number column the points are sized by, as `setSizeBy` last set it, or `null` for one size.

MarksProjection¶

MarksProjection = object

The marks projection: the points to draw. Points arrive in bands; a band is one tile's points.

Properties¶

Property	Type	Description
`bands`	`Composition`[`"exact"`]	The bands of the frame's own tiles.
`count`	`Count`	How many marks `bands` draws (`shown`) out of the frame's `visible` count (`total`).
`standIn`	`Composition`[`"standIn"`]	Stand-ins, coarsest first: points from bands at another depth, drawn where the frame's own tiles have not arrived yet. Each draws its band's `indices`, or else its first `limit` points.

PresentedStatus¶

PresentedStatus = "idle" | "loading" | "retrying" | "shown" | "empty" | "refused"

What the map is showing, as StatusProjection.status reports it.

idle: nothing has been requested yet.
loading: a request for the view is in flight.
retrying: the server answered 429 or 503, and the store will ask again.
shown: a frame is on screen, and its counts are meaningful.
empty: no points in view match the filters (or the viewer may see none).
refused: the request failed, so nothing is known about what is in view.

Ranks¶

Ranks = Record\<number, number>

A category column's palette rank for each category code. A code keeps its rank until the store is cleared, so panning does not recolour the map. LegendProjection.ranks holds one per column and says how codes are ranked.

Refusal¶

Refusal = object

Why a request failed, as the store's projections report it.

Properties¶

Property	Type	Description
`code`	`string`	The MosaicaError's `code`, or `fetch-failed` for any other error.
`detail`	`string`	The MosaicaError's `detail`, or the error's message for any other error.
`status`	`number` \| `null`	The HTTP status, or `null` if the error has none.

RegionProjection¶

RegionProjection = object

The region projection: the selected region and its counts. It is null while nothing is selected.

Properties¶

Property	Type	Description
`held`	`object`	The marks drawn inside the region.
`held.count`	`number`	How many marks are drawn inside the region in all.
`held.ids`	`BigUint64Array`	The `mosaica_id`s of up to REGION_HELD_LIMIT marks inside the region.
`held.positions`	`Float32Array`	Their world positions, as interleaved `x` and `y`.
`matched`	`Masked`	How many items inside the region match the filters, from ViewProjection.inView. Until those counts arrive, it is estimated from the frame and may not be exact. Zero while `status` is not `shown`.
`refusal`	`Refusal` \| `null`	Why the request was refused while `status` is `refused`, otherwise `null`.
`served`	`Count`	How many marks are drawn inside the region (`shown`) out of `matched` (`total`).
`shape`	`SelectionShape`	The region as passed to Store.select.
`status`	`"loading"` \| `"shown"` \| `"refused"`	`loading` after the selection or the filters change, until new counts arrive; then `shown`. `refused` if the request was refused.
`verdict`	`RegionVerdict` \| `null`	How the server counted the region: exactly, or over the tiles covering it at a stated depth. `null` until the server has said.
`visible`	`Masked` \| `null`	How many items inside the region the viewer can see, from ViewProjection.inView. Until those counts arrive it is estimated from the frame, or `null` if other filters are set. `null` while `status` is not `shown`.

ReplicaProjection¶

ReplicaProjection = object

The replica projection: how much the store's tile cache holds.

Properties¶

Property	Type	Description
`bands`	`number`	Bands held for the current view. A band is one tile's points.
`bytes`	`number`	Bytes held across every view, limited by the `replica.cacheBytes` option.
`lastPlan`	{ `fetched`: `number`; `held`: `number`; } \| `null`	For the last frame planned from scratch: how many of its tiles were already in the cache (`held`) and how many had to be fetched (`fetched`). `null` before the first such frame and after `clear`.
`points`	`number`	Points held for the current view.
`views`	`number`	How many views hold any band.

SelectionProjection¶

SelectionProjection = object

The selection projection: the picked item and the opened artifact, for showing in a card. An id the viewer may not see is refused in the same way as one that does not exist.

Properties¶

Property	Type	Description
`artifact`	{ `detail`: `ArtifactDetail`; `id`: `bigint`; } \| `null`	The artifact last fetched by Store.openArtifact: its `mosaica_id` and its detail. `null` before one is opened and after a refusal.
`artifactRefusal`	`Refusal` \| `null`	Why the last `openArtifact` was refused, or `null`.
`item`	{ `detail`: `ItemDetail`; `id`: `bigint`; } \| `null`	The item last fetched by Store.pick: its `mosaica_id` and its record. `null` before a pick, after a refused pick, and after Store.openArtifact succeeds.
`itemRefusal`	`Refusal` \| `null`	Why the last pick was refused, or `null`.

SelectionShape¶

SelectionShape = ({ bbox: [number, number, number, number]; kind: "box"; } | { kind: "lasso"; points: [number, number][]; } | { id: bigint; kind: "artifact"; }) & object

A region to select with Store.select: a box or a lasso in the current view's data coordinates, or an artifact's shape. While it is selected, the map and its counts are limited to the region.

box: bbox is [x0, y0, x1, y1], with the corners in either order.
lasso: points are the polygon's vertices; the last joins back to the first. A lasso with fewer than three points clears the selection.
artifact: id is the artifact's mosaica_id, and the region is its published shape.

Type Declaration¶

Name	Type	Description
`outside?`	`boolean`	Whether to select everything outside the shape instead. Defaults to `false`.

ServedLineage¶

ServedLineage = object

The parent-child links among the artifacts in ArtifactsProjection.served, built from their parentIds. Only links between served artifacts are included, so an artifact whose parent was not served is a root here. On a dag layer a child is listed under each served parent. The links change as the camera moves and as the cluster budget changes.

Properties¶

Property	Type	Description
`byId`	`Map`\<`bigint`, `Artifact`>	Every served artifact, by `mosaicaId`.
`childrenOf`	`Map`\<`bigint`, `Artifact`[]>	Each parent's served children, by the parent's `mosaicaId`. A parent with none has no entry.
`linked`	`boolean`	Whether there are any links. `false` for a flat layer, and for a tree drawn at a single level.
`roots`	`Artifact`[]	The served artifacts that have no served parent.

StandInPiece¶

StandInPiece = object

A stand-in in a Composition: points from a band at another depth, drawn where the frame's own tiles have not arrived yet.

Properties¶

Property	Type	Description
`band`	`Band`	The band to draw from.
`indices`	`number`[] \| `null`	Indices into the band's points to draw, in order, or `null` to draw its first points.
`limit`	`number`	How many points to draw: the first `limit` of `indices`, or of the band if `indices` is `null`.

StatusProjection¶

StatusProjection = object

The status projection: whether the current view's map is loading, shown, empty or refused. Use it for a status line or an overlay.

Properties¶

Property	Type	Description
`expired`	`boolean`	Whether the viewer's session has ended and a new token is needed: the refusal is `expired-token`, or `bad-credential` for a token the store has already used successfully.
`refusal`	`Refusal` \| `null`	Why the request was refused while `status` is `refused`, otherwise `null`. A `5xx` from something other than the Mosaica server, such as a gateway's `504`, has the code `http-error`.
`retrying`	`boolean`	Whether `status` is `retrying`.
`sessionWarm`	`boolean`	Whether the map has shown a frame or drawn marks since the store was created or last cleared.
`stale`	`boolean`	Whether the server's data has changed since the frame on screen was fetched, so its counts may be out of date. It clears when a newer frame is drawn. Pass it to formatCount and formatMasked as `stale`.
`status`	`PresentedStatus`	`idle` before the first request and after Store.clear. `loading` while a request is in flight, or after a view switch until the new view draws. `retrying` while the server is busy (`429`) or starting (`503`) and the store waits to ask again. `shown` when a frame has arrived. `empty` when no items the viewer may see in view match the filters. `refused` when the request or the read of `/v1/meta` was refused; it says nothing about whether any items exist. The counts are meaningful only while the status is `shown`.
`unreachable`	`boolean`	Whether the server cannot be reached: a request failed to connect, or a proxy in front of the server answered `502`. The store keeps trying, with growing intervals of up to 30 s, and clears the flag and fetches the map again when the server answers. It is always `false` for a store created with a `client`.

SuggestionPage¶

SuggestionPage = object

A page of typeahead suggestions for one category column, from Store.suggest.

Properties¶

Property	Type	Description
`more`	`boolean`	Whether there are more matches than the page holds.
`q`	`string`	The text the suggestions match.
`total`	`number` \| `null`	How many items the counts are out of, for showing a value's share, or `null` if the server did not say.
`values`	`SuggestValue`[]	The matching values, each with its count of items the viewer can see.
`verb`	`ClauseVerb`	Whether the control that asked is set to filter or highlight. Under `filter` the counts leave out the column's own clause; under `highlight` they use every filter.

SuggestState¶

SuggestState = object

The typeahead suggestions for category columns, part of the filters projection. Store.suggest fills it.

Properties¶

Property	Type	Description
`suggestEpoch`	`number`	A number that changes when every page and error is dropped, at a view switch and at Store.clear. A control can compare it to tell that its page was dropped.
`suggestErrors`	`Record`\<`string`, `Refusal`>	Why the latest request for a column failed, in place of its page. If the server is still busy after five retries, the code is `backpressure`.
`suggestions`	`Record`\<`string`, `SuggestionPage`>	The latest page of suggestions for each column.

TilesProjection¶

TilesProjection = object

The tiles projection: the tiles that make up the frame on screen.

Properties¶

Property	Type	Description
`tiles`	`Composition`[`"tiles"`]	One entry per tile drawn, with its address, mark count and the server's counts.

ValueSample¶

ValueSample = object

A uniform sample of a number column's values among the marks drawn, for sizing points by rank. A value's rank is where it falls among values. The marks are themselves a sample, so a rank is an estimate. LegendProjection.samples holds one per column sized by.

Properties¶

Property	Type	Description
`seen`	`number`	How many marks with a finite value the sample was drawn from. It grows with each new sample, so it tells one sample from the next.
`values`	readonly `number`[]	Up to 1024 finite values drawn uniformly from the marks seen, in ascending order.

ViewProjection¶

ViewProjection = object

The view projection: the current view, the frame on screen and its counts. A frame is what the map draws for one camera position: the tiles that cover the view at one depth. The frame's counts cover those whole tiles; inView has counts over the exact area in view.

Properties¶

Property	Type	Description
`composition`	`Composition` \| `null`	The composed frame on screen, or `null` before the view's first frame.
`depth`	`number`	The tile depth of the frame, or `0` before the first frame.
`highlighted`	`Masked`	How many of `matched` also match the highlight. Equal to `matched` when no highlight is set; use `highlighting` to tell whether one is.
`highlighting`	`boolean`	Whether a highlight was set when this frame was drawn.
`id`	`string`	The current view's id, from `meta.views`. It is `''` until `/v1/meta` has loaded. Compare it with the previous value to detect a view switch.
`inView`	`InViewCounts` \| `null`	Counts over the area in view, or `null` before the first have arrived.
`matched`	`Masked`	How many of `visible` match the filters (Store.requestFilters). Equal to `visible` when no filter is set.
`provisional`	`number`	How many stand-in marks are on screen. Stand-ins are points from another depth, drawn while the frame's own tiles load.
`served`	`Count`	How many marks the server sent for the frame (`shown`) out of `visible` (`total`).
`visible`	`Masked`	How many items the viewer can see in the frame's tiles.

NO_ORDINAL¶

const NO_ORDINAL: 0 = 0

The ordinal 0, which means no artifact.

REGION_HELD_LIMIT¶

const REGION_HELD_LIMIT: 500 = 500

The most marks RegionProjection.held lists in ids and positions. Its count counts them all.

Counts¶

Count¶

Count = object

How many marks are drawn out of how many items there are, such as 1,204 of 29,935. The map draws a sample of the items, so the two usually differ. The store publishes one as view.served, marks.count and region.served. Show shown with total, since shown alone reads as the size of the set.

Properties¶

Property	Type	Description
`exact`	`boolean`	Whether the figures are exact. `false` before anything has arrived and while a region waits for its counts, and formatCount then returns an empty string.
`shown`	`number`	How many marks were drawn.
`total`	`number`	How many items the marks were drawn from, counting only items the viewer may see.

FormatOptions¶

FormatOptions = object

Options for formatCount and formatMasked.

Properties¶

Property	Type	Description
`compact?`	`boolean`	Whether to shorten figures of a thousand or more to one decimal place, such as `16.8M` for 16,822,190. Defaults to `false`.
`locale?`	`string`	The locale for thousands separators, as `Number.prototype.toLocaleString` takes it. Defaults to `en-GB`.
`stale?`	`boolean`	Whether the figure is out of date (`status.stale` in the store). A stale figure formats as an empty string. Defaults to `false`.

Masked¶

Masked = object

A count of items the viewer may see, such as visible, matched and highlighted in the view projection, or a region's counts.

Properties¶

Property	Type	Description
`exact`	`boolean`	Whether `value` is exact. A region's count is an estimate if the server counted the tiles covering the region instead of the region itself. Counts for a region selected with `outside` are always estimates. formatMasked shows an estimate with `≈`.
`value`	`number`	The count.

NO_COUNT¶

const NO_COUNT: Count

The Count before anything has arrived: zero of zero, not exact.

NO_MASKED¶

const NO_MASKED: Masked

The Masked count before anything has arrived: zero, not exact.

formatCount()¶

formatCount(count: Count, opts?: FormatOptions): string

Format a count as <shown> of <total>, such as 1,204 of 29,935. Returns an empty string if the count is not exact or opts.stale is set.

Returns¶

string

formatMasked()¶

formatMasked(masked: Masked, opts?: FormatOptions): string

Format a masked count as one figure, such as 29,935, or ≈ 29,935 if it is not exact. Returns an empty string if opts.stale is set.

Filters¶

ClauseVerb¶

ClauseVerb = "filter" | "highlight"

What a filter control does with the items it matches.

filter: the map and its counts are limited to the matching items.
highlight: the matching items are drawn at full strength and the rest dimmed.

ColumnDraft¶

ColumnDraft = { expr?: FilterExpr; family: "text"; phrase: boolean; query: string; } | { family: "keyword"; needle: string; op: "eq" | "prefix" | "contains"; } | { family: "category"; keys: string[]; } | { family: "numeric"; gte: number | null; lte: number | null; }

The state of one filter control, with one variant per kind of column. An empty control, such as a blank query or no selected keys, does not filter (isPopulated).

Union Members¶

Type Literal¶

{ expr?: FilterExpr; family: "text"; phrase: boolean; query: string; }

A text search for query, parsed by textTerms. phrase says whether the column supports phrases. If expr is set, it is sent in place of the query until the control is cleared; use it to filter by an expression a query cannot produce.

Type Literal¶

{ family: "keyword"; needle: string; op: "eq" | "prefix" | "contains"; }

Match needle against the whole value (eq), its start (prefix) or any part (contains).

Type Literal¶

{ family: "category"; keys: string[]; }

Match any of the selected category keys. A key the viewer may not see matches nothing, the same as a key that does not exist.

Type Literal¶

{ family: "numeric"; gte: number | null; lte: number | null; }

Match values between inclusive bounds in the column's own units. null leaves a side open.

FilterDraft¶

FilterDraft = object

The state of a filter panel: its filter controls and its highlight controls, each keyed by column name. Pass it to Store.setFilters. A column may have a control in both, so you can limit the map to some values and highlight a few of those. The highlight applies within what the filters keep. emptyDraft creates one, and composeFilters turns it into filter expressions.

Properties¶

Property	Type	Description
`filter`	`Record`\<`string`, `ColumnDraft`>	The filter controls. emptyDraft creates one per filterable column.
`highlight`	`Record`\<`string`, `ColumnDraft`>	The highlight controls.

FilterExpr¶

FilterExpr = { all_of: FilterExpr[]; } | { any_of: FilterExpr[]; } | { none_of: FilterExpr[]; } | { region: RegionOperand; } | { member_of: MemberOfOperand; } | { mosaica_id: MosaicaIdOperand; } | {[column: string]: FilterOperator; }

A filter expression, as the viewer routes take it.

Each node has exactly one key: a column name mapped to a FilterOperator, region, member_of, mosaica_id, or one of the combinators all_of, any_of and none_of. all_of: [] matches every item and any_of: [] matches none. none_of matches every visible item that none of its branches matches, including items with no value in the column. The server refuses with 422 a node with two keys, an unknown column, an operator the column does not take, or nesting deeper than the deployment allows.

A value that does not exist and a value the viewer cannot see both match nothing, with the same response.

FilterOperator¶

FilterOperator = { eq: string | number | boolean | bigint; } | { in: (string | number | bigint)[]; } | { prefix: string; } | { contains: string; } | { match: string | { minimum_should_match?: number; query: string; }; } | { phrase: string; } | { range: { gt?: number | bigint | string; gte?: number | bigint | string; lt?: number | bigint | string; lte?: number | bigint | string; }; }

One column's condition, with exactly one key.

A category takes its key (a string) or its code (a number), and a keyword takes exact strings. A numeric column takes numbers, and range takes at least one bound and at most one per side. An integer or timestamp column also takes a bigint, which stays exact above 2^53. A timestamp takes microseconds since the Unix epoch, a date ('2020-01-01', midnight UTC) or a date-time with an offset ('2020-01-01T09:30:00Z'). A text column takes match or phrase.

Union Members¶

Type Literal¶

{ eq: string | number | boolean | bigint; }

Type Literal¶

{ in: (string | number | bigint)[]; }

Type Literal¶

{ prefix: string; }

Type Literal¶

{ contains: string; }

Type Literal¶

{ match: string | { minimum_should_match?: number; query: string; }; }

Every word must appear, unless minimum_should_match says how many must.

Type Literal¶

{ phrase: string; }

The words must appear next to each other, in order.

Type Literal¶

{ range: { gt?: number | bigint | string; gte?: number | bigint | string; lt?: number | bigint | string; lte?: number | bigint | string; }; }

MemberClause¶

MemberClause = object

A filter on membership of one artifact, such as a cluster: keep or highlight the items inside it, or those outside it. Pass the list of clauses to Store.setMembers. An artifact can have one filter clause and one highlight clause at the same time.

Properties¶

Property	Type	Description
`artifact`	`bigint`	The artifact's `mosaica_id`.
`label?`	`string`	A name to show for the artifact, such as the one shown by the card or panel that created the clause. It is not sent to the server. The map does not draw a filter layer's artifacts, so this may be the only name available for them.
`layer`	`string`	The artifact's layer.
`outside`	`boolean`	Whether the clause selects the items outside the artifact instead of its members.
`verb`	`ClauseVerb`	Whether the clause filters or highlights.

MemberOfOperand¶

MemberOfOperand = { artifact: string; layer: string; } | { key: string; layer: string; level?: number; }

The member_of filter: the visible members of one artifact, such as a cluster. It works in filters to narrow the map and in highlight to light it. Name the artifact by its mosaica_id as artifact, which memberOf builds, or by the key it was published under as key, with level on a layer with levels.

A layer the viewer's /v1/meta does not list is refused with 422, and so is a level the layer does not hold. An artifact or a key that does not exist, an artifact of another layer, and one that is suppressed or is not served to the viewer match nothing.

Union Members¶

Type Literal¶

{ artifact: string; layer: string; }

Name	Type	Description
`artifact`	`string`	The artifact's `mosaica_id` as a decimal string, since a JSON number cannot hold every 64-bit id.
`layer`	`string`	The layer's name, as `/v1/meta` lists it.

Type Literal¶

{ key: string; layer: string; level?: number; }

Name	Type	Description
`key`	`string`	The key the artifact was published under. On a layer scoped to a group, the key in the request's view.
`layer`	`string`	The layer's name, as `/v1/meta` lists it.
`level?`	`number`	The level the key is held at; 0 when absent.

MosaicaIdOperand¶

MosaicaIdOperand = { eq: string; } | { in: string[]; }

The mosaica_id filter: the items named by the identifiers responses hand out, as decimal strings, which namedItems builds. An identifier naming nothing, or an item the viewer cannot see, matches nothing.

RegionOperand¶

RegionOperand = { polygon: [number, number][]; space?: "view"; } | { bbox: [number, number, number, number]; space?: "view"; } | { circle: [number, number, number]; space?: "view"; } | { ellipse: [number, number, number, number, number]; space?: "view"; } | { artifact: string; }

The region filter: the items whose position lies inside a shape. Give exactly one of:

polygon: at least three [x, y] vertices, closed automatically. More than selection.maxRegionVertices is refused with 422.
bbox: [x0, y0, x1, y1], edges included.
circle: [cx, cy, r].
ellipse: [cx, cy, a, b, angle_degrees].
artifact: an artifact's mosaica_id as a decimal string, matching its members. An artifact that does not exist, is not served to the viewer, is on another view, or has an authored shape matches nothing.

Coordinates are in the view's data coordinates. A shape with a very long boundary may be answered for a slightly larger area; the response's RegionVerdict says so.

RegionVerdict¶

RegionVerdict = { depth: null; exact: true; } | { depth: number; exact: false; }

Whether a response with a region filter is exact (the x-mosaica-region header). With exact: false, a shape's boundary needed more than selection.maxRegionCells cells, so the answer covers a slightly larger area made of cells at depth depth. It depends only on the shapes, never on the items. With several regions it reports the coarsest.

TextTerms¶

TextTerms = object

One alternative of a text query, as textTerms returns it.

Properties¶

Property	Type	Description
`phrases`	`string`[]	Phrases that must each appear, with their words together and in order.
`words`	`string`[]	Words that must all appear, in any order.

activeCount()¶

activeCount(draft: FilterDraft, verb?: ClauseVerb): number

How many controls are populated, for a panel heading. A column populated as both filter and highlight counts twice. Pass verb to count only one side.

Returns¶

number

composeFilters()¶

composeFilters(draft: FilterDraft, verb?: ClauseVerb): FilterExpr | null

Build the filter expression for one side of a draft: null if no control is populated, the single clause if one is, and all_of over the clauses if several are.

Parameters¶

Parameter	Type	Default value	Description
`draft`	`FilterDraft`	`undefined`	The filter panel's state.
`verb?`	`ClauseVerb`	`'filter'`	Which controls to use. Defaults to `filter`.

Returns¶

FilterExpr | null

emptyDraft()¶

emptyDraft(operands: FilterOperandSet[]): FilterDraft

Create a draft with one empty filter control per filterable column, and no highlight controls. Pass meta.filterOperands. A column gets a control only if it supports the operator the control needs: match for text, in for category and range for numeric. A text control's phrase is set if the column supports phrase. A keyword control starts with whichever of eq, prefix and contains comes first in the column's operands.

A group-scoped column is keyed by its bare name, which works only under a view of its own group or of a group that shares its views. To filter it under another view, key the control as column@key, where key names one of the group's views; the server refuses the bare name there with 422.

Returns¶

FilterDraft

isPopulated()¶

isPopulated(draft: ColumnDraft): boolean

Whether a control filters anything: a text query that is not blank, a keyword that is not empty, at least one category key, or at least one numeric bound.

Returns¶

boolean

memberKey()¶

memberKey(layer: string, artifact: bigint): string

A string key for one artifact, <layer> <artifact>, for a Map or Set. A filter clause and a highlight clause on the same artifact have the same key.

Returns¶

string

memberLeaf()¶

memberLeaf(clause: MemberClause): FilterExpr

Turn a clause into a filter expression: member_of, wrapped in none_of if the clause is outside.

Returns¶

FilterExpr

memberOf()¶

memberOf(layer: string, artifact: bigint | { key: string; level?: number; }): MemberOfOperand

Build the operand of a member_of filter for one artifact, named by its mosaica_id or by the key it was published under. A mosaica_id becomes a decimal string, as the server expects; {key, level} is sent as given, level left out for level 0.

Parameters¶

Parameter	Type
`layer`	`string`
`artifact`	`bigint` \| { `key`: `string`; `level?`: `number`; }

Returns¶

MemberOfOperand

namedItems()¶

namedItems(ids: Iterable\<bigint>): FilterExpr

A filter keeping the items ids name, such as the points a map shows a picture for, so one MosaicaClient.items call reads their fields. Each id is sent as its decimal string.

Returns¶

FilterExpr

textQueryOf()¶

textQueryOf(column: string, expr: FilterExpr, phrase: boolean): string | null

The text query that produces expr on column: the reverse of what a text control sends. Returns null if no query produces exactly that expression, for example if a match contains OR or a quote. Use it to show an expression set from elsewhere in a search box.

Returns¶

string | null

textTerms()¶

textTerms(query: string, phrase?: boolean): TextTerms[]

Parse a text control's query into the alternatives it asks for. Plain words must all appear. Text in double quotes (straight or curly) at the start of a word is a phrase, and an unclosed quote runs to the end. OR in capitals, as a word on its own, separates alternatives, any one of which is enough, so a b OR c matches items with both a and b, or with c. Nothing else is syntax: parentheses, and quotes inside a word, are part of the word. Alternatives with no words or phrases are dropped.

Parameters¶

Parameter	Type	Default value	Description
`query`	`string`	`undefined`	The text typed into the control.
`phrase?`	`boolean`	`true`	Whether the column supports phrase search. With `false`, quoted words are read as plain words. Defaults to `true`.

Returns¶

TextTerms[]

withMember()¶

withMember(clauses: readonly MemberClause[], clause: MemberClause): MemberClause[]

Return clauses with clause added at the end. It replaces any clause on the same artifact with the same verb, and leaves one with the other verb.

Returns¶

MemberClause[]

withMembers()¶

withMembers(expr: FilterExpr | null, clauses: readonly MemberClause[], verb: ClauseVerb): FilterExpr | null

Combine expr with the clauses set to verb, using all_of. Two artifacts combine to the items in both; to show the members of either, use their parent. Returns expr unchanged if no clause is set to verb.

Returns¶

FilterExpr | null

withoutClause()¶

withoutClause(draft: FilterDraft, column: string, verb: ClauseVerb): FilterDraft

Return a copy of draft with column's verb control emptied. The control keeps its kind and keyword operator, and the column's control on the other side is unchanged. Returns draft itself if there is no such control.

Returns¶

FilterDraft

withoutMember()¶

withoutMember(clauses: readonly MemberClause[], layer: string, artifact: bigint, verb: ClauseVerb): MemberClause[]

Return clauses without the clause on this artifact with this verb, if there is one.

Layers and views¶

LayerEntry¶

LayerEntry = object

One entry in a layer picker: a layer and the layers linked to it by depends_on, which are drawn together. For example, a clustering's labels are a separate layer that depends on the clustering, and one entry covers both.

Properties¶

Property	Type	Description
`closure`	`string`[]	`root` and every layer linked to it, as layerClosure gives them. A layer that depends on two roots is in both entries.
`root`	`Layer`	The entry's main layer: one that depends on no other layer in `meta`. A layer whose dependencies the viewer cannot see counts as a root.

CLUSTER_PREFIX¶

const CLUSTER_PREFIX: "cluster:" = 'cluster:'

The prefix that makes a colour setting name a layer instead of a column, as in setColourBy('cluster:topics'), which colours points by the topics layer's clusters.

browsableLayers()¶

browsableLayers(layers: readonly Layer[]): Layer[]

The layers a hierarchy panel can show: every layer with a hierarchy (a hierarchy.kind other than flat) that depends on no other layer.

Returns¶

Layer[]

colourLayers()¶

colourLayers(layers: readonly Layer[]): Layer[]

The layers points can be coloured by with setColourBy('cluster:<layer>'): every layer that is not a filter layer and depends on no other layer. A labels layer depends on the layer it labels, so it is left out.

Returns¶

Layer[]

drawableLayers()¶

drawableLayers(layers: readonly Layer[]): Layer[]

The layers that can be drawn: every layer except filter layers (isFilterLayer).

Returns¶

Layer[]

isFilterLayer()¶

isFilterLayer(layer: Layer): boolean

Whether a layer is a filter layer: one with no computed geometry (computedContent is empty) that depends on no other layer. Its artifacts have counts but nothing to draw, so the store does not draw it. Use its artifacts in member_of clauses, for example from a hierarchy panel.

Returns¶

boolean

layerClosure()¶

layerClosure(layers: readonly Layer[], names: readonly string[]): string[]

The layers in names together with every layer linked to them by depends_on, in either direction and at any distance, each listed once in layers order. Names layers does not list are kept, at the end.

Returns¶

string[]

layerEntries()¶

layerEntries(layers: readonly Layer[]): LayerEntry[]

The entries for a layer picker: one per layer that depends on no other layer in layers, with the layers linked to it, in layers order.

Returns¶

LayerEntry[]

subtreeOf()¶

subtreeOf(lineage: ServedLineage, root: bigint): Set\<bigint>

The mosaicaIds of root and every served artifact below it in lineage. root is included even if lineage does not hold it.

Coordinates and colour¶

ChosenColours¶

ChosenColours = ReadonlyMap\<string, ReadonlyMap\<bigint, Rgba>>

Colours for particular artifacts, to use in place of their palette colours, keyed by layer and then by mosaica_id. Pass it to Store.setArtifactColours.

Palette¶

Palette = object

A palette for colouring clusters, with a title and description for a menu. The server gives each cluster a slot in the palette, chosen so that neighbouring clusters differ, and the cluster takes the colour at that slot.

Properties¶

Property	Type	Description
`colours`	readonly `Rgba`[]	The colours, in slot order.
`description`	`string`	A short description for a menu, such as `8 colours · colour-blind safe`.
`title`	`string`	The palette's name for a menu.

PaletteName¶

PaletteName = "okabe-ito" | "tableau10" | "tableau20" | "kelly"

The name of a palette for colouring clusters: okabe-ito (8 colours that stay distinct under the common forms of colour blindness), tableau10 (10 colours), tableau20 (20 colours in light and dark pairs) or kelly (Kelly's 22 colours of maximum contrast).

Rgba¶

Rgba = readonly [number, number, number, number]

A colour as red, green, blue and alpha bytes, each from 0 to 255.

DEFAULT_PALETTE¶

const DEFAULT_PALETTE: PaletteName = 'tableau10'

The palette a store colours clusters with unless you choose another: tableau10.

GRID32¶

const GRID32: number

The size of the grid that artifact geometry (centroid, box and shapes) is served in: 2^32 units on each axis. Item positions in another view (ItemViewPosition) use the same units, and a point's code interleaves its two 32-bit coordinates, so one cell is 2^16 units. gridToWorld converts to world units.

MAX_DEPTH¶

const MAX_DEPTH: 16 = 16

The deepest tile depth, 16. At depth z the view is divided into 2^z by 2^z tiles, so a depth-16 tile is one cell of the 65,536 by 65,536 grid that positions are stored on.

NEUTRAL¶

const NEUTRAL: Rgba

The grey used for an artifact with no colour of its own, such as one whose palette slot is not known yet.

PALETTES¶

const PALETTES: Readonly\<Record\<PaletteName, Palette>>

The cluster palettes, by name, in the order a menu lists them.

WORLD_SIZE¶

const WORLD_SIZE: 512 = 512

The width and height of the map in deck.gl world units: 512. World space runs from 0 to WORLD_SIZE on each axis.

artifactColour()¶

artifactColour(palette: PaletteName, slot: number | null, chosen?: Rgba): Rgba

A cluster's colour: chosen if given, otherwise the colour at slot in palette. Returns NEUTRAL if slot is null or past the end of the palette.

Returns¶

Rgba

dataToWorldXY()¶

dataToWorldXY(x: number, y: number, q: Quantisation): [number, number]

Convert a point from the view's data coordinates to deck.gl world units. Each axis is scaled separately, so the view's extent becomes a square.

Parameters¶

Parameter	Type	Description
`x`	`number`	The x coordinate, in the view's data coordinates.
`y`	`number`	The y coordinate, in the view's data coordinates.
`q`	`Quantisation`	The view's `quantisation`, from `/v1/meta`.

Returns¶

[number, number]

[x, y] in world units, from 0 to WORLD_SIZE for a point inside the extent.

gridToWorld()¶

gridToWorld(v: number): number

Convert one coordinate of artifact geometry from 32-bit grid units (GRID32) to deck.gl world units.

Returns¶

number

gridToWorldXY()¶

gridToWorldXY(p: readonly [number, number]): [number, number]

Convert an [x, y] point of artifact geometry from 32-bit grid units (GRID32) to deck.gl world units.

Returns¶

[number, number]

lonLatOfCell()¶

lonLatOfCell(cx: number, cy: number, view: ViewInfo, q: Quantisation): [number, number] | null

Convert a stored position to [longitude, latitude] in degrees. Returns null for a view whose projection is none. A point beyond Web Mercator's limit of ±85.0511° latitude was clipped when it was stored, and returns the latitude it was clipped to.

Parameters¶

Parameter	Type	Description
`cx`	`number`	The x position in cells, from 0 to 65,536 across the view: a ViewportResult's `positions`, or a Band's `positions` times `65536 / WORLD_SIZE`.
`cy`	`number`	The y position in cells.
`view`	`ViewInfo`	The view, from `meta.views`. Its projection decides how cells convert to degrees.
`q`	`Quantisation`	The view's `quantisation`.

Returns¶

[number, number] | null

paletteSize()¶

paletteSize(palette: PaletteName): number

How many colours palette has. Requests for palette slots send it as palette_size.

HTTP client¶

MosaicaClient¶

A thin HTTP client for the viewer and session routes, with one method per route. It keeps no state between calls. The store that createStore makes is built on it and adds caching and composition. The viewer methods take a session token as their first argument, and every count and record they return covers only what that session may see.

A method rejects with a MosaicaError if the server refuses the request, and with the fetch error if no server answers. On a viewer route, 403 expired-token means the session has ended, and so does 401 bad-credential for a token that worked before.

No method retries on its own. A server too busy to take a request answers 429 backpressure, and the error's retryAfterS says how many seconds to wait before calling again with the same arguments. MosaicaClient.suggest returns this as {status: 'shed', retryAfterS} instead of rejecting. The store retries for you. Here is a helper that makes five attempts:

async function retrying<T>(call: () => Promise<T>, attempts = 5): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await call();
    } catch (error) {
      if (!(error instanceof MosaicaError) || error.status !== 429 || attempt === attempts) throw error;
      await new Promise((resolve) => setTimeout(resolve, (error.retryAfterS ?? 1) * 1000));
    }
  }
}

const read = await retrying(() => client.items(token, {view: 'papers', fields: ['title', 'year']}));

Constructors¶

Constructor¶

new MosaicaClient(opts: MosaicaClientOptions): MosaicaClient

Methods¶

aggregate()¶

aggregate(token: string, req: AggregateRequest, signal?: AbortSignal, options?: object): Promise\<AggregateResult>

POST /v1/aggregate: exact counts of how the items the viewer may see in a view are distributed, as one table per grouping. It reads every page of every response and joins each table's pages into one Arrow table. AggregateTable lists the columns.

The server works out the viewer's visible set afresh for each response, so a deletion or suppression accepted during a long read applies from the next response. AggregateResult.recomposed says whether that happened.

const {tables} = await client.aggregate(token, {
  view: 'papers',
  filters: {year: {range: {gte: 2020}}},
  groupings: [{count: true}, {count: true, by: {field: 'venue', top: 10}}]
});
console.log(tables[0]!.total, tables[1]!.rows.toArray());

Parameters¶

Parameter	Type	Description
`token`	`string`	-
`req`	`AggregateRequest`	-
`signal?`	`AbortSignal`	-
`options?`	{ `follow?`: `boolean`; }	`follow`: whether to read the responses after the first. Defaults to `true`. With `false` the result holds only the first response's pages, and AggregateResult.next is the cursor to pass back as `cursor` to continue.
`options.follow?`	`boolean`	-

Throws¶

MosaicaError if the server refuses the first request: 404 for an unknown view, 422 for an invalid request, naming the limit if one is exceeded.

Throws¶

PartialAggregate if a later request is refused or a body is cut off. It holds the pages read so far and the cursor to continue from.

Throws¶

Error if a response's trailer does not match its body, and the signal's reason if it aborts.

artifact()¶

artifact(token: string, mosaicaId: bigint, opts: object): Promise\<ArtifactDetail>

POST /v1/artifacts/{mosaica_id}: one artifact's layer, key, count and geometry in a view. The count and the geometry cover only the members the viewer may see. Geometry is in 32-bit grid units (GRID32), and a geometry field is null if the layer does not declare it.

Parameters¶

Parameter	Type	Description
`token`	`string`	-
`mosaicaId`	`bigint`	-
`opts`	{ `signal?`: `AbortSignal`; `view`: `string`; `zoom?`: `number`; }	-
`opts.signal?`	`AbortSignal`	-
`opts.view`	`string`	The view to count and place the artifact in.
`opts.zoom?`	`number`	The zoom to simplify the shape for, rounded down and clamped to 0 to 16. If omitted, the full stored shape is returned.

Throws¶

MosaicaError with the same 404 for an id that names nothing, a point, a suppressed artifact, an artifact below its layer's existence criterion, and an artifact on a layer the viewer cannot reach.

artifacts()¶

artifacts(token: string, req: ArtifactsRequest, signal?: AbortSignal): Promise\<RecordsRead\<ArtifactsHead>>

POST /v1/artifacts: read the artifacts of one layer that the viewer is served, one page at a time, in the same way as MosaicaClient.items.

Throws¶

MosaicaError if the server refuses the first request: 404 for an unknown view, 422 for a malformed filter or a request ArtifactsRequest says is refused, and 429 if too many bulk reads are running.

authorise()¶

authorise(target: AuthoriseTarget, signal?: AbortSignal): Promise\<Session>

POST /session/authorise: start a session on someone's behalf, sending the sessionCredential option. A session for a principal or an OIDC identity carries its terms and its read and write permissions, if it holds them, and the target must hold read. A session for terms holds those terms and read. A term is trimmed, and a term that is empty or holds a control character is dropped. Every session holds public, so naming it changes nothing. Only the operator credential may ask for terms or readAll.

Parameters¶

Parameter	Type	Description
`target`	`AuthoriseTarget`	The local principal to act as, the access token of the OIDC identity to act as, the terms the session holds, or `readAll` for a session that sees every item.
`signal?`	`AbortSignal`	-

Returns¶

Promise\<Session>

The session's token, for the viewer methods, its tokenId, for revoke, and expiresAt, in seconds since the Unix epoch.

Throws¶

MosaicaError if the server refuses: 401 for a credential it does not accept; 403 if the key's principal does not hold authorise-as, the target does not hold read, or a key asks for terms or readAll; 404 if principal names no enabled principal; 422 for an access token it does not accept.

Throws¶

Error if the client has no sessionUrl.

basemapWorld()¶

basemapWorld(token: string, signal?: AbortSignal): Promise\<ArrayBuffer>

GET /v1/basemaps/world: the world outline drawn under a geographic view, with land, coastlines and country borders, in the server's MBW1 encoding.

Throws¶

MosaicaError if the server refuses.

browse()¶

browse(token: string, req: BrowseRequest, signal?: AbortSignal): Promise\<BrowsePage>

POST /v1/artifacts/browse: one page of a layer's hierarchy, following parent and child links regardless of what the map shows. It reads the layer's roots, one artifact's children together with that artifact's parents, or the results of a name search. Each row carries its count of visible members and, if filters is set, its count of matching ones. Rows are ordered by count, highest first, then by mosaica_id, using the matching count if filters is set. To read the next page, pass next back as cursor. It is null on the last page.

A parent is listed only if the viewer is served both ends of the link. A parent the viewer is not served returns an empty page.

Throws¶

MosaicaError if the server refuses: 404 for an unknown view, 422 for an unknown layer, both parent and q, limit: 0 or a malformed filter.

categories()¶

categories(token: string, column: string, opts?: object): Promise\<CategoryValue[]>

GET /v1/categories/{column}: what a category column's codes stand for, each as a code, key and title. With codes, it looks up those codes, in the order given. Without, it lists every value in key order, fetching page after page until the last.

A code missing from the answer is either unknown or a value the viewer may not see, and the server does not say which. Every code on a point this session was served resolves.

Parameters¶

Parameter	Type	Description
`token`	`string`	-
`column`	`string`	The column's name, or `<column>@<key>` for a group-scoped category pinned to one view.
`opts?`	{ `codes?`: readonly `number`[]; `limit?`: `number`; `signal?`: `AbortSignal`; `view?`: `string`; }	-
`opts.codes?`	readonly `number`[]	The codes to look up. If omitted, every value is listed. An empty list returns `[]` without a request.
`opts.limit?`	`number`	The page size when listing. Defaults to, and is capped at, `selection.maxCategoryValues`.
`opts.signal?`	`AbortSignal`	-
`opts.view?`	`string`	The view whose values a group-scoped column lists.

Throws¶

MosaicaError if the server refuses: 404 for a column that is not a category, 422 for a malformed request, such as limit: 0 or a group-scoped column with no view.

close()¶

close(): void

Close the decoder the client created and stop its workers. A decoder passed in as decoder is left open.

item()¶

item(token: string, mosaicaId: bigint, signal?: AbortSignal): Promise\<ItemDetail>

POST /v1/items/{mosaica_id}: one item's full record, its position in each view the viewer may reach, and the labels that let this session see it. ItemDetail describes each field.

Parameters¶

Parameter	Type	Description
`token`	`string`	-
`mosaicaId`	`bigint`	The item's `mosaica_id`, as in a viewport result's `ids`.
`signal?`	`AbortSignal`	-

Throws¶

MosaicaError with 404 for an id that names no item, and the same 404 for an item the viewer may not see.

items()¶

items(token: string, req: ItemsRequest, signal?: AbortSignal): Promise\<RecordsRead\<ItemsHead>>

POST /v1/items: read the items the viewer may see in a view, one page at a time. It resolves when the first response's head (ItemsHead) arrives. Iterate the result for each page as an Arrow table; further pages are fetched as you iterate. RecordsRead says how a read ends.

Throws¶

MosaicaError if the server refuses the first request: 404 for an unknown view, 422 for a malformed filter or a request ItemsRequest says is refused, and 429 if too many bulk reads are running.

login(credential: LoginCredential, signal?: AbortSignal): Promise\<Login>

POST /v1/login: log in and start a session. The principal the credential identifies must hold read. The credential is sent in the body, with no bearer token.

Parameters¶

Parameter	Type	Description
`credential`	`LoginCredential`	One credential: a local principal's name and password, an API key, or an OIDC access token.
`signal?`	`AbortSignal`	-

Returns¶

Promise\<Login>

The session's token, for the viewer methods and logout, and expiresAt, in seconds since the Unix epoch.

Throws¶

MosaicaError if the server refuses: 401 for any credential it does not accept, and 403 if the principal does not hold read.

logout()¶

logout(token: string, signal?: AbortSignal): Promise\<void>

POST /v1/logout: end the session of token.

Throws¶

MosaicaError with 401 or 403 if the session has already ended.

meta()¶

meta(token: string, signal?: AbortSignal): Promise\<Meta>

GET /v1/meta: the deployment's metadata. It lists the views, view groups, columns, filter operands and request limits, and the layers this session may know of. The layers depend on the viewer, so a result applies only to the token it was fetched with.

Throws¶

MosaicaError if the server refuses.

Throws¶

Error if the response lacks a field this client requires, which means the server and the client are from different versions.

revoke()¶

revoke(tokenId: number, signal?: AbortSignal): Promise\<void>

POST /session/revoke: end the session tokenId names. An API key can end a session that a key of its own principal started, and the operator credential can end any session. An id that names no live session is not an error.

Throws¶

MosaicaError if the server refuses: 401 for a credential it does not accept, 403 if the key's principal does not hold authorise-as, and 422 for a malformed request.

Throws¶

Error if the client has no sessionUrl.

suggest()¶

suggest(token: string, column: string, q: string, opts?: object): Promise\<SuggestResult>

GET /v1/categories/{column}/suggest: typeahead for a category column. It returns up to limit values whose key or title, or a word in either, starts with q, ignoring case. Values are ordered by the matched text, and only values the viewer may see are offered. The page repeats q, so you can match a page to its request. With filters the request is a POST.

A 429 is returned as {status: 'shed', retryAfterS, detail} instead of thrown; SuggestResult lists the causes.

Parameters¶

Parameter	Type	Description
`token`	`string`	-
`column`	`string`	As for MosaicaClient.categories.
`q`	`string`	The text typed. An empty string matches every value.
`opts?`	{ `counts?`: `boolean`; `filters?`: `FilterExpr`; `limit?`: `number`; `signal?`: `AbortSignal`; `view?`: `string`; }	-
`opts.counts?`	`boolean`	`true` adds each value's count of the visible items that carry it, and the page's `total`, the number of items the counts cover.
`opts.filters?`	`FilterExpr`	A filter expression, as the viewport takes. The counts then cover only the items in `view` that pass it. It changes nothing else, so a value it excludes is still offered, with count `0`. Requires `view`.
`opts.limit?`	`number`	The page size. Defaults to, and is capped at, `selection.maxSuggestions`.
`opts.signal?`	`AbortSignal`	-
`opts.view?`	`string`	As for `categories`. It is also the view `filters` applies in.

Throws¶

MosaicaError for any other refusal: 404 for a column that is not a category, 422 for a q over 256 bytes, filters without view, or a malformed request.

viewport()¶

viewport(token: string, req: ViewportRequest, opts?: object): Promise\<ViewportResponse>

POST /v1/viewport: the points and counts for one area of a view at one zoom. It returns each tile's counts and a sample of up to k points per tile, each point tagged with the artifacts of the layers layers names. Fields of req you leave unset take the server's defaults: k defaults to meta.selection.kMaxMarks, and the server caps it at selection.maxK. Set k to 0 to fetch only the counts.

Parameters¶

Parameter	Type	Description
`token`	`string`	-
`req`	`ViewportRequest`	-
`opts?`	{ `background?`: `boolean`; `onCounts?`: `CountsSink`; `onPart?`: `PartSink`; `signal?`: `AbortSignal`; }	-
`opts.background?`	`boolean`	Decode on a separate worker, so responses the user is waiting for do not queue behind this one. Defaults to `false`.
`opts.onCounts?`	`CountsSink`	Receives the tiles' counts, and the sub-cells if `underlayOffset` asked for them, as soon as they arrive and before any points. Called at most once. The returned `result` carries the same counts.
`opts.onPart?`	`PartSink`	Receives the points as they arrive, before the body has finished (see PartSink). The returned `result` then carries the counts and no points. Not called when `k` is `0`.
`opts.signal?`	`AbortSignal`	Aborts the request and the reading of its body.

Returns¶

Promise\<ViewportResponse>

The decoded result, the server's timings, the response's keys (identityKey, contentKey, pin, stale, region) and the body's size in bytes.

Throws¶

MosaicaError if the server refuses: 404 for an unknown view, 422 for a malformed request.

Throws¶

Error if the body is malformed or ends before its trailer. Parts already passed to onPart hold whole tiles and remain valid.

viewportArtifacts()¶

viewportArtifacts(token: string, req: ViewportArtifactsRequest, opts?: object): Promise\<ViewportArtifactsResponse>

POST /v1/artifacts/viewport: the artifacts of the named layers in each tile of one area of a view at one zoom. A tile lists the artifacts the viewer is served that have a member it can see inside the tile, at most perTile per level, largest first. An artifact that spans several tiles appears in each, with the same figures. A nested or dag layer is answered for all the tiles together, in one frame that comes first. Fields of req you leave unset take the server's defaults.

Parameters¶

Parameter	Type	Description
`token`	`string`	-
`req`	`ViewportArtifactsRequest`	-
`opts?`	{ `background?`: `boolean`; `onTile?`: `TileSink`; `signal?`: `AbortSignal`; }	-
`opts.background?`	`boolean`	Decode on a separate worker, as for MosaicaClient.viewport.
`opts.onTile?`	`TileSink`	Receives each frame as it arrives, before the body has finished (see TileSink). A frame already passed on remains valid if the body later fails.
`opts.signal?`	`AbortSignal`	Aborts the request and the reading of its body.

Returns¶

Promise\<ViewportArtifactsResponse>

Every frame, the response's keys (identityKey, contentKey, pin, stale, region), the server's timings and the body's size in bytes.

Throws¶

MosaicaError if the server refuses: 404 for an unknown view, 422 for a malformed request or a perTile over selection.maxArtifactsPerTile.

Throws¶

Error if the body is malformed or ends before its trailer.

MosaicaError¶

The error a request rejects with when the server refuses it. It carries the HTTP status and the error code and detail from the server's JSON error body, and its message is "<status> <code>: <detail>". A request that reaches no server rejects with the fetch error instead.

Extends¶

Error

Constructors¶

Constructor¶

new MosaicaError(status: number, code: string, detail: string, retryAfterS?: number | null): MosaicaError

Parameters¶

Parameter	Type	Default value	Description
`status`	`number`	`undefined`	The HTTP status, such as `404` or `422`.
`code`	`string`	`undefined`	The error code from the body: `bad-credential`, `expired-token`, `forbidden`, `unknown`, `conflict`, `contract`, `backpressure`, `fail-closed`, `not-ready` or `gone`. It is `http-error` if the body is not JSON or has no code, as with an error page from a proxy, and then only `status` says what went wrong.
`detail`	`string`	`undefined`	What was wrong, from the body's `detail`, or the HTTP status text if the body has none.
`retryAfterS?`	`number` \| `null`	`null`	How many seconds to wait before sending the request again. It is the `Retry-After` header, else the body's `retry_after_s`, else 1, and never less than 1. `null` if the refusal is not a `429` and names no wait.

Overrides¶

Error.constructor

Properties¶

Property	Modifier	Type	Default value	Description
`code`	`readonly`	`string`	`undefined`	The error code from the body: `bad-credential`, `expired-token`, `forbidden`, `unknown`, `conflict`, `contract`, `backpressure`, `fail-closed`, `not-ready` or `gone`. It is `http-error` if the body is not JSON or has no code, as with an error page from a proxy, and then only `status` says what went wrong.
`detail`	`readonly`	`string`	`undefined`	What was wrong, from the body's `detail`, or the HTTP status text if the body has none.
`retryAfterS`	`readonly`	`number` \| `null`	`null`	How many seconds to wait before sending the request again. It is the `Retry-After` header, else the body's `retry_after_s`, else 1, and never less than 1. `null` if the refusal is not a `429` and names no wait.
`status`	`readonly`	`number`	`undefined`	The HTTP status, such as `404` or `422`.

PartialAggregate¶

The error MosaicaClient.aggregate throws when a read stops part of the way, because a response was cut off or the server refused a later request. result holds every whole page read before the stop. Its next is the cursor to pass as cursor to continue without repeating a row, and null there means you must start again from the beginning.

Extends¶

Error

Constructors¶

Constructor¶

new PartialAggregate(why: string, result: AggregateResult, cause?: unknown): PartialAggregate

Parameters¶

Parameter	Type	Description
`why`	`string`	What went wrong, which starts the error's `message`.
`result`	`AggregateResult`	The tables as far as they were read.
`cause?`	`unknown`	The error a later request threw, if that is what stopped the read.

Overrides¶

Error.constructor

Properties¶

Property	Modifier	Type	Description
`refusal`	`readonly`	`MosaicaError` \| `null`	The MosaicaError that refused a later request, or `null` if no refusal stopped the read.
`result`	`readonly`	`AggregateResult`	The tables as far as they were read.
`retryAfterS`	`readonly`	`number` \| `null`	On a `429`, how many seconds the server asked you to wait. `null` if no refusal stopped the read, or if the refusal names no wait.
`status`	`readonly`	`number` \| `null`	The refusal's HTTP status, or `null` if no refusal stopped the read.

RecordsRead¶

A paged read of items or artifacts, as MosaicaClient.items and MosaicaClient.artifacts return it. Iterate it with for await to get each page as an Arrow table. Pages are fetched only as you iterate, and the read asks the server for more until no rows remain. A read that matches no rows yields one empty table that still has the read's columns.

Breaking out of the loop, calling return() or aborting the request's signal stops the read and releases the connection. A return() while a page is awaited ends the read there.

If a response is cut off or the server refuses a follow-up request, the read throws after the last whole page, and cursor is where to resume without repeating a row. To resume, call items or artifacts again with the same request, cursor set to cursor and count left out. A follow-up refused with 429 throws a MosaicaError whose retryAfterS is the wait.

const read = await client.items(token, {view: 'papers', fields: ['title', 'year']});
for await (const page of read) console.log(page.numRows);

Type Parameters¶

Type Parameter	Description
`Head`	ItemsHead or ArtifactsHead.

Implements¶

AsyncIterableIterator\<Table>

Properties¶

Property	Modifier	Type	Description
`head`	`readonly`	`Head`	The first response's head.

Accessors¶

cursor¶

Get Signature¶

get cursor(): string | null | undefined

Where the read continues, after the last page yielded. Before the first page it is the request's own cursor, so undefined means from the beginning. null means no rows remain.

identityKey¶

Get Signature¶

get identityKey(): string

The latest response's identity key for this viewer and view, or an empty string if it had none.

pageEnd¶

Get Signature¶

get pageEnd(): PageEnd | null

The page end that followed the last page yielded, or null before the first page.

region¶

Get Signature¶

get region(): RegionVerdict | null

The latest response's verdict on a region filter, or null if filters has none.

timings¶

Get Signature¶

get timings(): Pick\<Timings, "serverUs" | "admissionUs">

The latest response's server timings, in microseconds: serverUs from admission to the response's head, and admissionUs for admission itself.

trailer¶

Get Signature¶

get trailer(): RecordsTrailer | null

The last response's trailer once the read has ended, or null until then.

Methods¶

[asyncIterator]()¶

[asyncIterator](): this

Returns this read, so that for await can iterate it.

Implementation of¶

AsyncIterableIterator.[asyncIterator]

next()¶

next(): Promise\<IteratorResult\<Table\<any>, undefined>>

The next page, or done once the read has ended.

Throws¶

Error if a response is cut off or its trailer does not match its body.

Throws¶

MosaicaError if the server refuses a follow-up request.

Throws¶

The signal's reason if it aborts.

Implementation of¶

AsyncIterableIterator.next

return()¶

return(): Promise\<IteratorResult\<Table\<any>, undefined>>

Stop the read, release the response being read and request no more.

Implementation of¶

AsyncIterableIterator.return

Decoder¶

Decoder = object

Decodes viewport responses into typed arrays and artifacts for a MosaicaClient. The client's default decoder uses web workers, so decoding does not hold up drawing. inlineDecoder decodes on the calling thread instead, for a test, a script or a runtime without Worker. Pass a decoder as the client's decoder option.

Properties¶

Property	Modifier	Type	Description
`lastWorkerMs`	`readonly`	`number` \| `null`	How long the last decode took inside a worker, in milliseconds, not counting time spent waiting. For a streamed response it is the time of the last frame. `null` for the inline decoder and before the first decode.

Methods¶

close()¶

close(): void

Stop the decoder's workers, if it has any, and reject the decodes still in progress.

decode()¶

decode(bytes: Uint8Array, background?: boolean): Promise\<ViewportResult>

Decode a whole /v1/viewport body. background sends the work to a separate worker, if the decoder has one, so responses the user is waiting for do not queue behind it. Rejects with Error if the body is malformed.

Returns¶

Promise\<ViewportResult>

MosaicaClientOptions¶

MosaicaClientOptions = object

Options for a MosaicaClient.

Properties¶

Property	Type	Description
`decoder?`	`Decoder`	Where responses are decoded. By default the client creates a decoder that uses web workers if it can, and this thread otherwise. You close a decoder you pass in; MosaicaClient.close closes only one the client created.
`fetch?`	typeof `fetch`	A `fetch` to use in place of the global one.
`headers?`	`Record`\<`string`, `string`>	Headers to send on every request. A method's own `authorization` and `content-type` headers take precedence over these.
`onDecode?`	(`ms`: `number`, `bytes`: `number`, `points`: `number`, `workerMs`: `number` \| `null`) => `void`	Called once per `viewport` and `viewportArtifacts` response with decode timings, for instrumentation. `ms` is the time from the response's headers to the decoded result, including reading the body. `bytes` is the body's size and `points` the number of points decoded. `workerMs` is the time a worker spent decoding, summed over the frames of a streamed response, or `null` if the response was decoded on this thread.
`sessionCredential?`	`string`	The credential `authorise` and `revoke` send: an API key whose principal holds `authorise-as`, or the operator credential. It can start a session for any principal, so it is meant for a back end or a script. A browser page can reach the session listener only from an origin listed in `serve.dev_cors_origins`, a development setting. If it is not set, no credential is sent, which only an open server (`serve.open`) accepts.
`sessionUrl?`	`string`	The session listener's base URL. Only `authorise` and `revoke` use it, and they throw if it is not set.
`viewerUrl`	`string`	The viewer server's base URL, such as `https://maps.example.org` or `/mosaica`. A trailing slash is ignored. An empty string sends requests to the page's own origin.

PartSink¶

PartSink = (part: ViewportPart) => void | Promise\<void>

A callback that receives a /v1/viewport response's points as they arrive, so a wide view can be drawn before the whole body has loaded. Pass it as onPart to MosaicaClient.viewport. Parts arrive in the order the server sent them. Each holds whole tiles: their counts and their points, with subCells set to null. If the callback returns a promise, the next part waits until it settles.

Returns¶

void | Promise\<void>

TileSink¶

TileSink = (frame: ViewportArtifactsFrame, keys: object) => void | Promise\<void>

A callback that receives a /v1/artifacts/viewport response's frames as they arrive, with the response's identity and content keys. Pass it as onTile to MosaicaClient.viewportArtifacts. Frames arrive in the order the server sent them. If the callback returns a promise, the next frame waits until it settles.

Parameters¶

Parameter	Type
`frame`	`ViewportArtifactsFrame`
`keys`	{ `contentKey`: `string`; `identityKey`: `string`; }
`keys.contentKey`	`string`
`keys.identityKey`	`string`

Returns¶

void | Promise\<void>

inlineDecoder()¶

inlineDecoder(): Decoder

Create a decoder that runs on the calling thread. background has no effect and lastWorkerMs is always null.

Returns¶

Decoder

setWorkerFactory()¶

setWorkerFactory(factory: (() => Worker) | null): void

Set how the default decoder creates its web workers, for a bundler that cannot load the default worker. By default each worker loads decode.worker.js from beside this module. Vite and webpack bundle it automatically, and it also works unbundled. esbuild does not: either copy the file beside your output or install a factory here. The single-file bundle installs its own factory.

Parameters¶

Parameter	Type	Description
`factory`	(() => `Worker`) \| `null`	A function that creates one worker, called each time a worker is needed. `null` restores the default.

Control plane¶

Control¶

A client for the server's control plane, which changes what a database holds and who may see it. It has one method per control route: declaring columns, views and layers; ingesting, deleting and suppressing items; publishing annotations; flushing and compacting; and managing principals, keys, groups, grants, OIDC providers and sessions. It sends one credential (ControlOptions.credential) and keeps no state between calls. Request bodies are sent as you give them, in the route's own field names: an Arrow IPC stream for ingest, either Arrow or JSON for grow, and JSON for everything else.

Every method resolves to an Answer, including refusals and requests that reached no server, and awaitCompaction to a CompactWait. A call rejects only if its signal aborts, with the signal's reason, or if the onProgress given to compact or awaitCompaction throws.

Writes become visible to viewers at the next publication. The server publishes every ingest.flush_max_age_secs (90 seconds by default), or sooner once ingest.flush_max_items rows (40,000 by default) are buffered. Deletions and suppressions apply at once. Control.flush and the wait option bring the next publication forward.

A busy server answers 429. The call then waits as long as the server asks, between 1 and 30 seconds, and tries again, up to five minutes of waiting in all. After that it returns the 429. A request that reaches no server is returned with status UNANSWERED. ingest first tries once more a second later.

ingest sends a batch id with each request: your batch, or a new random id. The server remembers each accepted batch id with its body. The same body sent again under that id is answered as a replay, with replayed: true and no effect, and a different body under it is refused with 409. The same rows sent in two calls under different ids are processed twice. A row that names its item by mosaica_id or a unique value then finds, in the second call, the item the first created, and changes nothing.

The catalogue methods need admin. Each catalogue change ends the live sessions it could affect, and answers how many in sessions_ended.

Constructors¶

Constructor¶

new Control(options: ControlOptions): Control

Methods¶

addMember()¶

addMember(group: string, principal: string, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

PUT /control/groups/{name}/members/{principal}: add a principal to a group.

awaitCompaction()¶

awaitCompaction(request: number, options?: AwaitCompactionOptions): Promise\<CompactWait>

Wait for compaction request request to be answered, reading Control.compactionRequest about once a second, and resolve with how the wait ended, as CompactWait describes. The wait has no bound of its own: it ends when the request is answered or a reading is refused, and signal is the way to stop it sooner. A reading that reaches no server is read again a second later, so a server that restarts is answered as lost once it is back. onProgress is called with the job of each reading that has one. The call rejects if signal aborts, with its reason, or if onProgress throws, and sends nothing more after either.

changePrincipal()¶

changePrincipal(name: string, change: PrincipalChange, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

PATCH /control/principals/{name}: disable or enable a principal.

changes()¶

changes(items: ChangeItem[], options?: StrictOptions): Promise\<Answer\<ChangesApplied>>

POST /control/changes: delete, suppress or unsuppress items, each named by its match, and artifacts and layers, each named by its mosaica_id. A deletion or suppression applies to every request from the moment it is accepted, without waiting for a publication.

A change that names no item, or two, is listed in refused and the rest are applied. With strict the request is refused at the first such change, with 404 if it names no item and 409 if it names two. Deleting a layer here is refused with 422; use Control.dropLayer. Every change is checked before any is applied, so any other refusal applies nothing.

clearPassword()¶

clearPassword(name: string, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

DELETE /control/principals/{name}/password: remove a principal's password.

compact()¶

compact(options?: CompactOptions): Promise\<CompactAnswer>

POST /control/compact: request a compaction, which removes deleted rows from disc. The answer is 202, sent before the compaction runs, with the request's number in body.request. If no compaction can start until the server restarts, the answer is 503 and no compaction is requested.

Without wait, follow the request with Control.compactionRequest or Control.awaitCompaction. With wait, the call waits with awaitCompaction once the request is accepted, passing it signal and onProgress, and resolves with the 202 and, in waited, how the wait ended, as CompactWait describes. An abort during the wait rejects the call and loses the request's number, so a caller that wants to bound the wait and still follow the request afterwards posts without wait and calls awaitCompaction itself.

compactionRequest()¶

compactionRequest(request: number, options?: CallOptions): Promise\<Answer\<CompactionRequest>>

GET /control/compact/{request}: where one compaction request is, and how it was answered, as CompactionRequest. It needs admin. The HTTP reference describes the route, including the 404 and 410 it answers for a request it no longer knows.

createGroup()¶

createGroup(name: string, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

POST /control/groups: create a group. A name already in use is refused with 409.

createKey()¶

createKey(principal: string, body?: KeyCreate, options?: CallOptions): Promise\<Answer\<IssuedKey>>

POST /control/principals/{name}/keys: issue an API key. The whole key is returned only in this answer.

createPrincipal()¶

createPrincipal(name: string, kind: "person" | "service", options?: CallOptions): Promise\<Answer\<CatalogueChange>>

POST /control/principals: create a principal with no password, key, term or permission. A name already in use is refused with 409.

createView()¶

createView(group: string, key: string, body: object, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

PUT /control/views/{group}/{key}: create a view in group from the roster record in body. An unknown group is refused with 404. If a live view already holds the key with this record, the answer is 200 with that view. With a different record it is 409. A dropped view's key may be used again, and the new view starts empty.

declareAttribute()¶

declareAttribute(body: object, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

PUT /control/attributes: declare one attribute column, named in the body. Batches sent after the answer may carry it. The answer is 201 if the column is new, 200 if the name already has this declaration, and 409 if it has a different one. A column declared with render: true is available on every point drawn. A point stored before the declaration has no value for it until a batch gives it one.

unique: true means no two items may hold the same value. It is the one field you can change on an existing column. The answer then waits while the column's index is built, and is 409, naming up to ten of the values, if more than one item holds a value. unique: false drops the index and keeps the values.

declareLayer()¶

declareLayer(declaration: object, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

PUT /control/layers: declare one annotation layer. The answer is 201 with the layer's name and mosaica_id, or 200 with the existing layer's if a layer of that name already has exactly this declaration. A different declaration under an existing name, or one that breaks the deployment's rules, is refused with 422 saying why. A layer past the last layer space, or with more levels than a space holds, is refused with 409. A dropped layer's name may be declared again.

declareShards()¶

declareShards(body: object, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

PUT /control/shards: set the shard size, {size}. When the shard taking new items reaches this size it is sealed and the next one opened. A size at or below that shard's current size seals it at once. The answer is 201 if the size changed, 200 if it was already set, and 422 for a size of zero.

declareView()¶

declareView(name: string, body: object, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

PUT /control/views/{name}: declare one plain view, with no rows yet. The statuses are as for Control.declareViewGroup.

declareViewGroup()¶

declareViewGroup(name: string, body: object, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

PUT /control/view_groups/{name}: declare a view group, with no views yet. The answer is 201 if the group is new and 200 if the name already has this declaration. A different declaration under the name is refused with 409.

declareVocabulary()¶

declareVocabulary(name: string, body: object, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

PUT /control/vocabularies/{name}: declare a vocabulary, the set of values of a category column. A closed vocabulary's values go in the body. The answer is 201 if the vocabulary is new, 200 if the name already has this declaration, in which case the values are added as a page, and 409 if it has a different one.

deleteGroup()¶

deleteGroup(name: string, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

DELETE /control/groups/{name}: delete a group with its grants and memberships.

deletePrincipal()¶

deletePrincipal(name: string, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

DELETE /control/principals/{name}: delete a principal with its password, keys, grants and memberships.

dropLayer()¶

dropLayer(name: string, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

DELETE /control/layers/{name}: drop a layer that declareLayer declared. The name may be declared again, as a new layer that none of the old layer's mosaica_ids name.

dropProvider()¶

dropProvider(name: string, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

DELETE /control/providers/{name}: remove a provider. Every session authorised through it ends.

dropView()¶

dropView(group: string, key: string, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

DELETE /control/views/{group}/{key}: drop a view that createView made, and free its key. Items left with no row in any view are deleted, and the answer's deleted says how many.

endSessions()¶

endSessions(which: SessionsToEnd, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

POST /control/sessions/end: end one session by token_id, or every session of a principal or a provider.

flush()¶

flush(options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

POST /control/flush: bring the next publication forward. The answer is 202, and its publication names the first publication that includes every write sent before the flush. With wait, the answer is held until that publication has happened.

grant()¶

grant(grant: Grant, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

POST /control/grants: grant terms or a permission to a principal or a group. A grant already held changes nothing.

grow()¶

grow(layer: string, body: Uint8Array\<ArrayBufferLike> | GrowRequest, options?: StrictOptions): Promise\<Answer\<MembershipsGrown>>

PATCH /control/layers/{name}/artifacts: add a page of members to artifacts the layer already holds, or with a rank change a content's generating set, and fill in parts the artifacts lack. Refused members of members and leaving are listed in refused as for publish, or with strict refuse the request. A part that differs from the one held is refused with 409, and that refusal applies nothing.

Parameters¶

Parameter	Type	Description
`layer`	`string`	-
`body`	`Uint8Array`\<`ArrayBufferLike`> \| `GrowRequest`	A `Uint8Array` is sent as an Arrow IPC stream, anything else as JSON. The Arrow form has one row per artifact: `key` as `utf8`, `members` as a list of structs whose fields are the member table's columns, and optionally `view` and `access`, with `level` in the schema's metadata.
`options?`	`StrictOptions`	-

ingest()¶

ingest(body: Uint8Array, options?: RowOptions): Promise\<RowAnswer>

POST /control/ingest: insert or update items from one page of rows, given as an Arrow IPC stream. A row names an item by its mosaica_id and the values of any unique columns it carries. A row that names no item creates one at its position. A row whose values all equal what the item already stores changes nothing. A row that names an item with no row in this view, and changes nothing else, adds the item to the view. Any other row edits the item, which keeps its mosaica_id.

A column left out keeps the item's stored value, and a null clears it. A row without coordinates changes only the columns it carries. A row that only places its item in an annotation changes the annotation, and the item counts as unchanged.

A row is refused if its values name two items, its mosaica_id names no item, or it names an item or sets a unique value that an earlier row of the page does. A refused row is listed in refused with its reason, its mosaica_id in the answer is null, and the other rows are stored. With strict the page is refused with 409 at the first refused row, and nothing is stored. IngestResponse describes the answer.

limits()¶

limits(options?: CallOptions): Promise\<Record\<string, unknown>>

The limits object from Control.status: the caps each write route puts on rows, items and body bytes, one object per route. {} if the status request failed.

listGroups()¶

listGroups(options?: CallOptions): Promise\<Answer\<{ groups: GroupRecord[]; }>>

GET /control/groups: every local group, in body.groups.

listKeys()¶

listKeys(principal: string, options?: CallOptions): Promise\<Answer\<{ keys: KeyRecord[]; }>>

GET /control/principals/{name}/keys: a principal's API keys, without their secrets, in body.keys.

listPrincipals()¶

listPrincipals(options?: CallOptions): Promise\<Answer\<{ principals: PrincipalRecord[]; }>>

GET /control/principals: every local principal, in body.principals.

listProviders()¶

listProviders(options?: CallOptions): Promise\<Answer\<{ providers: ProviderRecord[]; }>>

GET /control/providers: every OIDC provider, declared through the API or in mosaica.toml, in body.providers.

listSessions()¶

listSessions(which?: object, options?: CallOptions): Promise\<Answer\<{ sessions: SessionRecord[]; }>>

GET /control/sessions: live sessions, in body.sessions. Lists all of them, a local principal's (including those started on its behalf), or those authorised through a provider.

Parameters¶

Parameter	Type
`which?`	{ `principal?`: `string`; `provider?`: `string`; }
`which.principal?`	`string`
`which.provider?`	`string`
`options?`	`CallOptions`

publish()¶

publish(layer: string, body: PublishRequest, options?: StrictOptions): Promise\<Answer\<ArtifactsPublished>>

PUT /control/layers/{name}/artifacts: publish artifacts into one level of a layer, each with a first page of members, and return each artifact's mosaica_id. Members, excluded items and a content's generated_from are each a MemberTable. A mosaica_id in a member table must be an item's; an artifact's or a layer's names nothing.

A member that names no item, or two, is left out and listed in refused, and the rest are published. With strict the request is refused at the first such member, with 404 if it names no item and 409 if it names two. A generated_from member that names no item, or two, refuses the request even without strict. A request that creates more artifacts than the level's layer space has ids left for is refused with 409. Any other refusal applies nothing.

putProvider()¶

putProvider(name: string, declaration: ProviderDeclaration, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

PUT /control/providers/{name}: declare a provider, or replace one whole. Replacing a provider ends every session authorised through it. A provider declared in mosaica.toml is refused with 409.

removeMember()¶

removeMember(group: string, principal: string, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

DELETE /control/groups/{name}/members/{principal}: remove a principal from a group.

revokeGrant()¶

revokeGrant(grant: Grant, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

POST /control/grants/revoke: revoke terms or a permission. Revoking a grant that is not held changes nothing.

revokeKey()¶

revokeKey(prefix: string, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

DELETE /control/keys/{prefix}: revoke an API key. Every session started with it ends.

setPassword()¶

setPassword(name: string, password: string, options?: CallOptions): Promise\<Answer\<CatalogueChange>>

PUT /control/principals/{name}/password: set a principal's password. A password shorter than the configured minimum is refused with 422.

showGroup()¶

showGroup(name: string, options?: CallOptions): Promise\<Answer\<GroupRecord>>

GET /control/groups/{name}: one group, or 404.

showPrincipal()¶

showPrincipal(name: string, options?: CallOptions): Promise\<Answer\<PrincipalRecord>>

GET /control/principals/{name}: one principal, or 404.

showProvider()¶

showProvider(name: string, options?: CallOptions): Promise\<Answer\<ProviderRecord>>

GET /control/providers/{name}: one provider, or 404.

status()¶

status(options?: CallOptions): Promise\<Answer\<ControlStatus>>

GET /control/status: the running database's state, as JSON in body. It includes the publication counter, the write executor, caches, admission, compaction, shards and the write limits. overlay counts the item deletions and suppressions that no compaction has removed yet.

vocabularyValues()¶

vocabularyValues(name: string, body: object, options?: WriteOptions): Promise\<Answer\<Record\<string, unknown>>>

PATCH /control/vocabularies/{name}/values: add one page of {key, title?} values to a vocabulary. No value is removed, and a title given for an existing key replaces its title. An unknown vocabulary is refused with 404. For a derived vocabulary, the answer to a writer without write-all leaves out added, existing and titles.

Returns¶

Promise\<Answer\<Record\<string, unknown>>>

AddressRow¶

AddressRow = object & object

Names one item by its mosaica_id, the values of its unique fields, or both, keyed by column. A unique field's value is a string for a keyword. For an integer it is a number or a string of decimal digits, and for a timestamp it may also be a date, or a date-time with an offset, as a string. null names nothing. Every value given must name the same item, and a row that names no item, or two, is refused. A key that is neither mosaica_id nor a unique field is ignored and listed in the answer's ignored_columns.

Type Declaration¶

Name	Type	Description
`mosaica_id?`	`string` \| `null`	The item's `mosaica_id`, a string of decimal digits.

Answer¶

Answer\<B extends object = Record\<string, unknown>> = object & ({ body: B; ok: true; } | { body: Record\<string, unknown>; ok: false; })

The result of a Control call. Every response, including a refusal, is returned as an Answer. None is thrown. If ok is true, body is the route's response, B. Otherwise it is the refusal, with error and detail.

Type Parameters¶

Type Parameter	Default type
`B` extends `object`	`Record`\<`string`, `unknown`>

Type Declaration¶

Name	Type	Description
`attempts`	`number`	How many times the request was sent, including retries.
`seconds`	`number`	Seconds from the first attempt to the answer, including waits between attempts.
`status`	`number`	The HTTP status, or UNANSWERED if no server answered.
`text`	`string`	The response body as text. If no server answered, a sentence naming the URL and the error.

ArtifactsPublished¶

ArtifactsPublished = PublicationAck & object

The answer to publish.

Type Declaration¶

Name	Type	Description
`artifacts`	`object`[]	One per artifact, in the order sent, with its `mosaica_id`. If the key was already held, it is the existing artifact's id. `null` for an artifact refused as `label_not_held`.
`created`	`number`	Artifacts the request created.
`filled`	`number`	Parts filled in on artifacts that already existed.
`ignored_columns`	`string`[]	Member table columns that are neither `mosaica_id` nor a unique field, which were ignored.
`joined`	`number`	Memberships added, to new and existing artifacts alike.
`refused`	`RefusedMember`[]	The refused members, which the artifacts were published without, and the artifacts refused as `label_not_held`. Empty with `strict`.
`shapes?`	`ShapeReport`[]	Present if the request carried a shape or authored shape content.
`without_content`	`number`	How many of those have no content, on a layer that declares some.

Attachment¶

Attachment = object

The artifact another is attached to, such as the cluster a label names. The target must already exist, on a layer that the attached artifact's layer names in depends_on.

Properties¶

Property	Type	Description
`key`	`string`	The target's key.
`layer`	`string`	The target's layer.
`level?`	`number`	The target's level. Defaults to 0.

AwaitCompactionOptions¶

AwaitCompactionOptions = CallOptions & object

Options for Control.awaitCompaction.

Type Declaration¶

Name	Type	Description
`onProgress()?`	(`record`: `Progress`) => `void`	Called with the `job` of each reading that has one: the compaction serving the request while it is pending, and the compaction that answered it at the last reading. A compaction shorter than a second can begin and end between two readings, so the last record can be the only one.

CallOptions¶

CallOptions = object

Options every Control method takes.

Properties¶

Property	Type	Description
`signal?`	`AbortSignal`	Aborts the call, during a request or a wait between attempts. The call then rejects with the signal's reason.

CatalogueChange¶

CatalogueChange = object

The answer to every catalogue change. A change ends every live session whose terms or permissions it could change.

Properties¶

Property	Type	Description
`sessions_ended`	`number`	How many live sessions the change ended.

ChangeItem¶

ChangeItem = object

One change in a Control.changes request, in the route's own field names.

Properties¶

Property	Type	Description
`match`	`AddressRow`	The item to change. Several changes in one request may name the same item.
`op`	`"delete"` \| `"suppress"` \| `"unsuppress"`	`delete` removes the item from every response, and a later compaction removes its rows. `suppress` hides it from every response until `unsuppress` lifts the suppression. Both apply from the moment the request is accepted.

ChangesApplied¶

ChangesApplied = PublicationAck & object

The answer to changes.

Type Declaration¶

Name	Type	Description
`accepted`	`number`	How many changes were applied.
`ignored_columns`	`string`[]	The `match` keys that are neither `mosaica_id` nor a unique field, which were ignored.
`refused`	`RefusedRow`[]	The refused changes, in the order sent. Empty with `strict`.

CompactAccepted¶

CompactAccepted = object

The body of the answer to compact.

Properties¶

Property	Type	Description
`request`	`number`	The request's number, which Control.compactionRequest and Control.awaitCompaction take.

CompactAnswer¶

CompactAnswer = Answer\<CompactAccepted> & object

The answer to compact. Its status and body are those of POST /control/compact.

Type Declaration¶

Name	Type	Description
`waited?`	`CompactWait`	With `wait`, how the wait ended. Absent without `wait`, and where the request was not accepted.

CompactionAnswer¶

CompactionAnswer = object

How a compaction request was answered, the answer of a CompactionRequest, in the route's own field names. The fields after ok are null except where the outcome is refused.

Properties¶

Property	Type	Description
`detail`	`string` \| `null`	What the gate means and what to do about it, in a sentence.
`first`	`number`	The first of the requests answered together with this one.
`gate`	`string` \| `null`	The gate that refused a shard, one of the names in `compaction.fold_refusals_by_gate`.
`had_bytes`	`number` \| `null`	For a memory or disc refusal, what the host had, in bytes.
`last`	`number`	The last of the requests answered together with this one.
`need_bytes`	`number` \| `null`	For a memory or disc refusal, what the compaction needs, in bytes.
`ok`	`boolean`	Whether the request succeeded, as the server decided it.
`outcome`	`CompactionOutcome`	How the requests were answered.
`shard`	`number` \| `null`	The shard refused, or `null` where the request was refused for the whole node.

CompactionOutcome¶

CompactionOutcome = "compacted" | "nothing_to_do" | "refused" | "failed"

How the server answered a compaction request, as GET /control/compact/{request} in the HTTP reference defines each value.

CompactionRequest¶

CompactionRequest = object & ({ answer: null; answered: false; } | { answer: CompactionAnswer; answered: true; })

The body of Control.compactionRequest: one compaction request, pending or answered, in the route's own field names. answer is null while answered is false.

Type Declaration¶

Name	Type	Description
`job`	`Progress` \| `null`	While the request is pending, the record of the compaction serving it, or `null` where none is serving it yet. Once it is answered, the last record of the compaction that answered it, or `null` where none ran.
`request`	`number`	The request's number.

CompactionRequests¶

CompactionRequests = object

compaction.requests in ControlStatus.

Properties¶

Property	Type	Description
`accepted`	`number`	The number of the latest request this run of the server gave.
`answered`	`number`	The highest request number that has been answered.

CompactOptions¶

CompactOptions = AwaitCompactionOptions & object

Options for Control.compact.

Type Declaration¶

Name	Type	Description
`wait?`	`boolean`	Once the request is accepted, wait for its answer with Control.awaitCompaction, and return how the wait ended in the answer's `waited`. Defaults to `false`.

CompactWait¶

CompactWait = { answer: CompactionAnswer; ended: "answered"; job: Progress | null; ok: boolean; } | { ended: "lost" | "gone" | "unread"; ok: false; read: Answer\<CompactionRequest>; }

How Control.awaitCompaction ended. ok is true only where the request was answered and the answer's ok is true. A reading that reached no server does not end the wait, which reads again a second later.

answered: the request was answered, and answer and job are as Control.compactionRequest served them.
lost: a reading was answered 404, because the server restarted after the request was made and the request was lost with it. Ask again.
gone: a reading was answered 410, because the server no longer keeps the request's answer.
unread: a reading was refused with any other status, such as 403 for a credential without admin, or 503 for a request still pending when the server stopped applying writes.

In the last three, read is the reading that ended the wait.

Union Members¶

Type Literal¶

{ answer: CompactionAnswer; ended: "answered"; job: Progress | null; ok: boolean; }

Name	Type	Description
`answer`	`CompactionAnswer`	How the request was answered, as served.
`ended`	`"answered"`	-
`job`	`Progress` \| `null`	The record of the compaction that answered the request, as served, or `null` where none ran.
`ok`	`boolean`	The answer's `ok`, as served.

Type Literal¶

{ ended: "lost" | "gone" | "unread"; ok: false; read: Answer\<CompactionRequest>; }

Name	Type	Description
`ended`	`"lost"` \| `"gone"` \| `"unread"`	-
`ok`	`false`	-
`read`	`Answer`\<`CompactionRequest`>	The reading of `GET /control/compact/{request}` that ended the wait.

ControlOptions¶

ControlOptions = object

Options for a Control.

Properties¶

Property	Type	Description
`controlUrl`	`string`	The control listener's base URL. A trailing slash is ignored.
`credential?`	`string`	The credential sent as the bearer token on every request: the operator credential, an API key or an OIDC access token. Writes, `flush` and `compact` need `write`. Declarations and drops need `write-all` as well. `status` and the catalogue methods need `admin`. A writer without `write-all` writes only within its terms. If it is not set, no credential is sent, which only an open server (`serve.open`) accepts.
`fetch?`	typeof `fetch`	A `fetch` to use in place of the global one.
`headers?`	`Record`\<`string`, `string`>	Headers to send on every request. The headers a method sets itself take precedence: `authorization`, `content-type`, and on `ingest` `x-mosaica-batch-id` and `x-mosaica-view`.

ControlStatus¶

ControlStatus = Record\<string, unknown> & object

The body of Control.status. The fields that say how far the running jobs have gone are typed, and the rest are left as unknown.

Type Declaration¶

Name	Type	Description
`compaction`	`Record`\<`string`, `unknown`> & `object`	The compactions.
`jobs`	`Progress`[]	The record of the flush and of the compaction running, each where one is, and empty when neither is.

Grant¶

Grant = object

One grant or revocation. Set exactly one of principal and group, and exactly one of term, terms and permission.

Properties¶

Property	Type	Description
`group?`	`string`	The group the grant is made to.
`permission?`	`Permission`	A permission, which says what the grantee may do.
`principal?`	`string`	The local principal the grant is made to.
`term?`	`string`	One term, which says what the grantee may see. `public` and an empty term are refused.
`terms?`	`string`[]	Many terms, granted or revoked as one change. One refused term refuses them all.

GroupRecord¶

GroupRecord = object

A local group.

Properties¶

Property	Type	Description
`members`	`string`[]	The principals in the group.
`name`	`string`	The group's name.
`permissions`	`Permission`[]	The permissions granted to the group, which each member holds.
`terms`	`string`[]	The terms granted to the group, which each member holds.

GrowingArtifact¶

GrowingArtifact = object

One artifact in a GrowRequest, named by the key it was published under. Parts the artifact lacks are filled in. A row with only a key changes nothing.

Properties¶

Property	Type	Description
`access?`	`string`[] \| `null`	The artifact's access labels.
`attached_to?`	`Attachment` \| `null`	The artifact this one is attached to.
`bbox?`	`number`[] \| `null`	As in PublishedArtifact.
`circle?`	`number`[] \| `null`	As in PublishedArtifact.
`content?`	`object`[]	Contents by rank. A content given at a rank that holds none, because it was withdrawn or is past the last, is added as a new content at the next free rank.
`ellipse?`	`number`[] \| `null`	As in PublishedArtifact.
`key`	`string`	The key the artifact was published under.
`leaving?`	`MemberTable` \| `null`	Members leaving a generating set, applied after the joins. Requires `rank`.
`members?`	`MemberTable` \| `null`	Members joining.
`parent?`	`string`[]	Parent keys.
`rank?`	`number` \| `null`	Without `rank`, `members` join the artifact's membership. With it, `members` and `leaving` change the generating set of the content at this rank. A content's rank is its position among the artifact's contents, and it keeps its number when an earlier content is withdrawn.
`space?`	`"view"` \| `"wgs84"` \| `null`	This row's coordinate space for authored shape content, overriding the request's `default_space`.
`view?`	`string` \| `null`	The key of the view the artifact belongs to, as in PublishedArtifact.
`wkt?`	`string` \| `null`	As in PublishedArtifact.

GrowRequest¶

GrowRequest = object

The JSON body of Control.grow.

Properties¶

Property	Type	Description
`artifacts`	`GrowingArtifact`[]	The artifacts, at least one.
`default_space?`	`"view"` \| `"wgs84"`	As in PublishRequest.
`level?`	`number`	As in PublishRequest.

IngestResponse¶

IngestResponse = PublicationAck & object

The answer to ingest. Refused rows are not counted.

Type Declaration¶

Name	Type	Description
`added`	`number`	Rows that added an item they named to the batch's view.
`clamped`	`number`	Rows whose coordinates lay outside the view's extent, stored on its edge.
`clipped`	`number`	Rows whose coordinates lay outside the projection's domain, stored on the frame's edge.
`created`	`number`	Rows that named no item and created one.
`edited`	`number`	Rows that edited an item they named.
`joined`	`number`	Memberships the batch's layer columns added.
`minted`	`number`	Artifacts the batch's layer columns created.
`mosaica_ids`	(`string` \| `null`)[]	One per row, in the order sent: the `mosaica_id` of the item the row created or named, or `null` if the row was refused.
`over_bound`	`number`	Rows creating an item whose labels index it under more than 4,096 keys. These rows are stored.
`over_bound_rows`	`number`[]	The positions of the first 100 of those rows.
`refused`	`RefusedRow`[]	The refused rows, with reasons. Empty with `strict`, which refuses the whole batch instead.
`replayed?`	`true`	Present if this body was already accepted under this batch id, in which case nothing was written.
`rows`	`number`	Rows the batch carried.
`unchanged`	`number`	Rows that named an item and changed nothing.

IssuedKey¶

IssuedKey = object

An API key as createKey issues it.

Properties¶

Property	Type	Description
`key`	`string`	The whole key, `msk_<prefix>_<secret>`. It is returned only here, once.
`prefix`	`string`	The key's public identity, which listing and revoking use.

JobKind¶

JobKind = "build" | "ingest" | "flush" | "compaction"

The kind of job a Progress record describes.

JobState¶

JobState = "running" | "finished" | "failed"

Whether a job is running, has finished or has failed. A failed job's record keeps the step it stopped in.

KeyCreate¶

KeyCreate = object

The body of createKey.

Properties¶

Property	Type	Description
`expires_at?`	`number`	When the key and every session authorised with it end, in seconds since the Unix epoch. If omitted, the key does not expire.
`permissions?`	`Permission`[]	The key's own permissions, narrower than its principal's. If omitted, it holds its principal's.

KeyRecord¶

KeyRecord = object

An API key as listKeys lists it, without its secret.

Properties¶

Property	Type	Description
`created_at`	`number`	When it was issued, in seconds since the Unix epoch.
`expires_at`	`number` \| `null`	When it stops being accepted, in seconds since the Unix epoch, or `null` for never.
`permissions`	`Permission`[] \| `null`	Its own permissions, narrower than its principal's, or `null` if it holds its principal's.
`prefix`	`string`	The key's public identity, which revoking takes.
`principal`	`string`	The principal it authenticates.

MembershipsGrown¶

MembershipsGrown = PublicationAck & object

The answer to grow.

Type Declaration¶

Name	Type	Description
`artifacts`	`object`[]	One per artifact, in the order sent. `withdrawn` is the rank of a content the row withdrew by emptying its generating set. For a row refused as `label_not_held`, `mosaica_id` is `null` and every count is 0.
`ignored_columns`	`string`[]	Member table columns that are neither `mosaica_id` nor a unique field, which were ignored.
`refused`	`RefusedMember`[]	The refused members, which the artifacts were grown without, and the rows refused as `label_not_held`. Empty with `strict`.
`shapes?`	`ShapeReport`[]	Present if the request filled in authored shape content.

MemberTable¶

MemberTable = object & object

Several items as columns of equal length, one row per item, keyed by mosaica_id and unique field names. Each cell is as in an AddressRow, or null if that column does not name the row's item. {} holds no items. Columns of different lengths are refused with 422. A column that is neither mosaica_id nor a unique field is ignored and listed in ignored_columns.

Type Declaration¶

Name	Type	Description
`mosaica_id?`	(`string` \| `null`)[]	Each row's `mosaica_id`, a string of decimal digits.

Permission¶

Permission = "read" | "write" | "authorise-as" | "admin" | "read-all" | "write-all"

What a principal may do. Its terms, which say what it may see, are granted separately.

read: start a session for itself and make viewer requests with it.
write: ingest, delete, suppress and annotate within its own terms, and flush and compact.
authorise-as: start sessions for other principals.
admin: read the server's status, and manage principals, keys, groups, grants, providers and sessions.
read-all: with read, see every item and satisfy every label.
write-all: with write, write across all items, declare columns, vocabularies, layers, views, view groups and shards, and drop layers and views.

Each permission is granted on its own: admin does not imply read or write.

PrincipalChange¶

PrincipalChange = object

The body of changePrincipal.

Properties¶

Property	Type	Description
`disabled`	`boolean`	`true` ends the principal's sessions and refuses each of its credentials.

PrincipalRecord¶

PrincipalRecord = object

A local principal, as the catalogue holds it. Passwords and key secrets are never returned.

Properties¶

Property	Type	Description
`disabled`	`boolean`	Whether its credentials are refused.
`groups`	`string`[]	The groups it is a member of.
`has_password`	`boolean`	Whether a password is set.
`kind`	`"person"` \| `"service"`	A person or a service.
`name`	`string`	The principal's name, which every other verb takes.
`permissions`	`Permission`[]	The permissions granted to the principal directly.
`terms`	`string`[]	The terms granted to the principal directly.

Progress¶

Progress = object

How far a long-running job has gone, as /control/status serves it in jobs and in compaction.last_job, and Control.compactionRequest in job. A job is a fixed list of phases, each of which runs one or more steps, and a step that processes a known number of things counts them. An optional field is absent from the record, never null.

Properties¶

Property	Type	Description
`context?`	`string`	Which part of the step is running, such as `shard 3`. Absent when the step has one part with no name of its own.
`done?`	`number`	How much of the step is done, in `unit`. Absent, with `total` and `unit`, for a step that counts nothing.
`elapsed_s`	`number`	Seconds since the job began.
`eta_s?`	`number`	Seconds until `done` reaches `total` at `rate`, for the step only. Absent where `rate` is absent or zero.
`job`	`JobKind`	The kind of job.
`phase`	`ProgressPhase`	The phase the job is in.
`rate?`	`number`	Units per second over the last 20 seconds of the step. Absent for a step that counts nothing and for one younger than two seconds.
`rss_bytes`	`number`	The resident memory of the process running the job when the record was taken, in bytes.
`state`	`JobState`	Whether the job is running, finished or failed.
`step`	`string`	The step's stable name, such as `postings` for a compaction or `rows` for a flush.
`step_elapsed_s`	`number`	Seconds since the step began.
`step_id`	`number`	Which step this is. It stays the same while the step's count or context changes, and no other step begun in the same process has it, so a record whose `step_id` differs from the last one read begins a new step.
`total?`	`number`	The count `done` is going towards.
`unit?`	`ProgressUnit`	What `done` and `total` count.

ProgressPhase¶

ProgressPhase = object

A phase of a job: its position among the job's phases, counted from 1, and its name.

Properties¶

Property	Type	Description
`index`	`number`	The phase's position, from 1.
`name`	`string`	The phase's name, for a person, such as `Indexing records`.
`of`	`number`	How many phases the job has.

ProgressUnit¶

ProgressUnit = "items" | "rows" | "pairs" | "terms" | "bytes"

What a step's done and total count.

ProviderDeclaration¶

ProviderDeclaration = object

An OIDC provider as putProvider declares it.

Properties¶

Property	Type	Description
`audience`	`string`	The `aud` its tokens must hold.
`claim_rules?`	`object`[]	Each turns a claim's values into terms, such as `{claim: 'groups[*]', template: '{value}'}`.
`issuer`	`string`	The `iss` its tokens carry.
`jwks_url`	`string`	Where its signing keys are published: `https`, or `http` to a loopback address.
`role_mappings?`	`object`[]	Each gives an identity whose `claim` holds exactly `value` the terms and permissions of the local `group`.

ProviderRecord¶

ProviderRecord = Required\<ProviderDeclaration> & object

An OIDC provider as the catalogue lists it.

Type Declaration¶

Name	Type	Description
`name`	`string`	The provider's name.
`read_only`	`boolean`	`true` if it is declared in `mosaica.toml`, so the API cannot change or remove it.

PublicationAck¶

PublicationAck = object

The publication at which a write becomes visible to viewers.

Properties¶

Property	Type	Description
`publication`	`number`	The number of the first publication that includes the write.
`visible?`	`boolean`	With `wait`, whether that publication had happened before the answer was sent.

PublishedArtifact¶

PublishedArtifact = object

One artifact in a PublishRequest, in the route's own field names. Its members come from members or excluding. An artifact with attached_to may have neither, and then covers its target's members.

Properties¶

Property	Type	Description
`access?`	`string`[] \| `null`	The artifact's own access labels. `null` or `[]` means none.
`attached_to?`	`Attachment` \| `null`	The artifact this one is attached to.
`bbox?`	`number`[] \| `null`	`[min_x, min_y, max_x, max_y]`, on a layer whose `shape` is `bbox`.
`circle?`	`number`[] \| `null`	`[cx, cy, r]`, on a layer whose `shape` is `circle`.
`content?`	`object`[]	Supplied content, ranked from most specific: one value per supplied content the layer declares, and in `generated_from` the items it was made from, if the content requires them.
`ellipse?`	`number`[] \| `null`	`[cx, cy, a, b, angle_degrees]`, on a layer whose `shape` is `ellipse`.
`excluding?`	`MemberTable` \| `null`	The view's items to leave out, so the membership is every other item in the view. Refused together with `members`.
`key?`	`string` \| `null`	The publisher's key, unique within the level. You need it to name the artifact as a parent or an attachment target, or to grow it.
`members?`	`MemberTable` \| `null`	The members. `{}` is an empty membership.
`parent?`	`string`[]	Parent keys, each already held or published earlier in the request.
`space?`	`"view"` \| `"wgs84"` \| `null`	This artifact's coordinate space, overriding the request's `default_space`.
`view?`	`string` \| `null`	The key of the view the artifact belongs to. Required on a layer scoped to a view group, and refused on any other.
`wkt?`	`string` \| `null`	A WKT polygon or multipolygon, on a layer whose `shape` is `polygon`.

PublishRequest¶

PublishRequest = object

The body of Control.publish.

Properties¶

Property	Type	Description
`artifacts`	`PublishedArtifact`[]	The artifacts, at least one.
`default_space?`	`"view"` \| `"wgs84"`	The coordinate space of shapes on artifacts that do not set `space`: `view` for the view's own coordinates, `wgs84` for degrees. Defaults to `view`.
`level?`	`number`	The level the artifacts go into. Defaults to 0.

RefusalReason¶

RefusalReason = "names_two_items" | "unknown_mosaica_id" | "names_no_item" | "one_item_twice" | "one_value_twice" | "value_held" | "label_not_held"

Why a row was refused.

names_two_items: the row's values name more than one item.
unknown_mosaica_id: its mosaica_id names no live or suppressed item.
names_no_item: its values name no item, in a request that does not create items.
one_item_twice: an earlier row of the batch names the same item.
one_value_twice: an earlier row of the batch sets the same unique value.
value_held: the row would give an item a unique value that an item outside the writer's terms already holds.
label_not_held: the row, or an artifact in publish or grow, sets an access label the writer's terms do not satisfy.

Only ingest gives one_item_twice, one_value_twice and value_held.

RefusedMember¶

RefusedMember = object

A member that was refused, so the artifact was published or grown without it. Without list and row, it is a whole artifact refused as label_not_held, for which nothing was written.

Properties¶

Property	Type	Description
`artifact`	`number`	The artifact's position in the request, from 0.
`list?`	`"members"` \| `"excluding"` \| `"leaving"`	The member table the member was in.
`reason`	`RefusalReason`	Why it was refused.
`row?`	`number`	The member's row in that table, from 0.

RefusedRow¶

RefusedRow = object

A row that was refused, with the reason.

Properties¶

Property	Type	Description
`reason`	`RefusalReason`	Why it was refused.
`row`	`number`	The row's position in the request, from 0.

RowAnswer¶

RowAnswer = Answer\<IngestResponse> & object

The answer to ingest, with the batch id the request carried.

Type Declaration¶

Name	Type	Description
`batch`	`string`	The batch id the request was sent with. Pass it as `batch` to send the same body again, which the server answers as a replay if it accepted the body the first time.

RowOptions¶

RowOptions = StrictOptions & object

Options for ingest.

Type Declaration¶

Name	Type	Description
`batch?`	`string`	The batch id, sent in `x-mosaica-batch-id`. Defaults to a new random id for each call. Pass the `batch` of an earlier RowAnswer to send its body again.
`view?`	`string`	The view the rows belong to, sent in `x-mosaica-view`. Required if the database has more than one view. An unknown view is refused with `404`.

SessionRecord¶

SessionRecord = object

A live session.

Properties¶

Property	Type	Description
`api_key`	`string` \| `null`	The prefix of the API key it was authorised with, or `null`.
`created_at`	`number`	When it started, in seconds since the Unix epoch.
`expires_at`	`number`	When it ends at the latest, in seconds since the Unix epoch.
`minted_by`	`string` \| `null`	The principal that started it with `authorise-as`, or `null`.
`permissions`	`Permission`[]	What the session may do: `read`, and `write` if its principal holds it. A session from `login` also carries `read-all` and `write-all` if the principal holds them.
`principal`	`string` \| `null`	The local principal, or `null` for an OIDC identity.
`provider`	`string` \| `null`	The provider an OIDC identity was accepted by, or `null`.
`subject`	`string` \| `null`	The OIDC identity's `sub`, or `null`.
`token_id`	`number`	The session's id, which `endSessions` takes. It cannot be used as a credential.

SessionsToEnd¶

SessionsToEnd = { token_id: number; } | { principal: string; } | { provider: string; }

Which sessions endSessions ends: one session by id, or every session of a principal or a provider.

ShapeReport¶

ShapeReport = object

How one artifact's shape was fitted to each view of its layer.

Properties¶

Property	Type	Description
`content?`	`number`	The rank of the authored shape content this reports on. Absent for the artifact's own shape.
`key`	`string` \| `null`	The artifact's key.
`views`	`object`[]	One entry per view of the layer.

StrictOptions¶

StrictOptions = WriteOptions & object

Options for a write whose rows name items: ingest, changes, publish and grow.

Type Declaration¶

Name	Type	Description
`strict?`	`boolean`	`true` refuses the whole request at its first refused row, and nothing is written. Otherwise the server applies the rows it accepts and lists each refused one in the answer's `refused`.

WriteOptions¶

WriteOptions = CallOptions & object

Options for a write.

Type Declaration¶

Name	Type	Description
`wait?`	`boolean`	Wait until the write is visible to viewers before answering. The server brings the next publication forward and holds its answer until then, or until `serve.visible_wait_max_secs` passes; the answer's `visible` says which. Sent as `wait=visible`. Defaults to `false`.

UNANSWERED¶

const UNANSWERED: 0 = 0

The status of an Answer when the request reached no server. It is not an HTTP status.

Meta¶

ArrowType¶

ArrowType = "bool" | "u8" | "u16" | "u32" | "u64" | "i8" | "i16" | "i32" | "i64" | "f32" | "f64" | "timestamp_us" | "utf8" | "keyword" | "text"

A declared column's storage type. timestamp_us is microseconds since the Unix epoch. keyword is a short string matched exactly and text is prose searched by word. Neither string type is sent with points; read them with MosaicaClient.item. utf8 cannot be declared.

CategoryDescriptor¶

CategoryDescriptor = object

Marks an integer column as a category. Points carry a category as an integer code, and this object is the only sign that a column is one. The codes are random and their order means nothing, so do not colour them on a continuous scale. MosaicaClient.categories turns codes into values.

Properties¶

Property	Type	Description
`kind`	`"declared"` \| `"discovered"`	`declared`: the value set is fixed, and a write with an unknown key is refused. `discovered`: a new key gets a code when it is first written.
`visibility`	`"derived"` \| `"public"`	`public`: every viewer is offered every value. `derived`: a viewer is offered only the values held by at least one item they can see.
`vocabulary`	`string`	The name of the value set the codes refer to. Columns that share a vocabulary share its keys, codes and titles, so one palette serves them all. Which values are visible is decided per column.

ComputedProperty¶

ComputedProperty = "centroid" | "box"

A geometry an artifacts request can ask for. Read an artifact's outline with MosaicaClient.artifact.

DeclaredScalar¶

DeclaredScalar = object

A declared column with one value per item.

Properties¶

Property	Type	Description
`analyser`	`string` \| `null`	For a `text` column, its analyser as `<name>/<version>`; otherwise `null`.
`arrowType`	`ArrowType`	The column's storage type.
`category`	`CategoryDescriptor` \| `null`	How the column works as a category, or `null` if it is not one.
`homes`	(`"rendered"` \| `"value_column"` \| `"record"`)[]	Where MosaicaClient.items reads the value from: `rendered` (the view's point columns), `value_column` (a per-item column) or `record` (the record store). A column held only in `record` reads fastest in `stored` order.
`index`	`boolean`	Whether the column has a filter index. A column with none of `render`, `index` and `unique` can be read on an item but not filtered on.
`name`	`string`	The column's name, which filters, `/v1/categories/{column}` and `ViewportResult.scalars` use.
`render`	`boolean`	Whether points can carry the column in a viewport response, which is what lets it colour or size them. A missing value arrives as null, or as code `0` in a category. A column without `render` can still be filterable (see Meta.filterOperands) and is returned by MosaicaClient.item.
`unique`	`boolean`	Whether every item holds a different value. A unique column takes `eq` and `in` filters, which find items by value, even without `render` or `index`.

FilterOperandSet¶

FilterOperandSet = object

A column you can filter on, and how. Build filter controls from these. family says which control fits: a category has a list of values (MosaicaClient.categories), a keyword takes typed text, a text column is searched by words, and a numeric one by range.

Properties¶

Property	Type	Description
`column`	`string`	The column or family name a filter uses.
`family`	`"category"` \| `"keyword"` \| `"text"` \| `"numeric"`	The column's filter family, which decides its operators.
`operands`	`string`[]	The operators the column accepts: `eq` and `in` for a category; `eq`, `in`, `prefix` and `contains` for a keyword; `eq`, `in` and `range` for a number; `match` and `phrase` for text. A unique column with neither `render` nor `index` takes only `eq` and `in`.
`scope?`	`object`	The view group, if the column is group-scoped. In a view of that group, or of a group that shares its views, a filter names the column plainly and reads the value for the request's view. In any other view it must name a view as `column@key`, or the request is refused with `422`.
`scope.group`	`string`	-

Layer¶

Layer = object

An annotation layer, such as a clustering or a set of boundaries, as /v1/meta lists it. A layer the viewer cannot reach is not listed. The entry does not say how many artifacts the layer holds.

Properties¶

Property	Type	Description
`computedContent`	`string`[]	The geometry computed per request from the members the viewer can see: any of `centroid`, `box` and `hull`.
`depsOn`	`string`[]	The layers whose artifacts this layer's artifacts attach to, as topic labels attach to clusters. Usually empty.
`hierarchy`	`object`	How artifacts relate. `flat`: no hierarchy. `nested`: a tree of parent links, with no levels. `dag`: like `nested`, but a child may have several parents. `stacked`: independent levels. `tiered`: levels whose artifacts sit inside those of the level above. With `pruneChildren`, a parent and its child that both qualify serve only the child, unless a request's `artifactBudget` asks for more detail.
`hierarchy.kind`	`"flat"` \| `"nested"` \| `"dag"` \| `"stacked"` \| `"tiered"`	-
`hierarchy.pruneChildren`	`boolean`	-
`levels`	`object`[]	The layer's levels, each with its number, title and `zoom`: the `[min, max]` tile depths at which it is shown by default, or `null` for every depth. Empty for a `nested` or `dag` layer.
`membership`	`"enumerated"` \| `"spatial"` \| `"attribute"`	How an artifact's members are decided: `enumerated`, a stored list; `spatial`, the items inside its shape; `attribute`, the items holding one value of a column. An attribute layer arrives as `{attribute: <column>}`, which this type does not declare.
`name`	`string`	The layer's name, which requests use.
`shape`	`ShapeKind` \| `null`	The kind of outline the layer draws, or `null` if it draws none. A `derived` outline is the hull of the members the viewer can see, so it differs between viewers; do not reuse it for another viewer. A `predicate` or `authored` outline is the same for everyone.
`suppliedContent`	`string`[]	The types of publisher-supplied content each artifact carries, in the order of Artifact.content.
`title`	`string` \| `null`	The layer's display title, or `null` if it has none.
`version`	`number`	A number that changes when the layer's access rule is edited.
`views`	`string`[]	The views the layer appears in that the viewer can reach.

MapProjection¶

MapProjection = "web_mercator" | "equirectangular" | "gall_isographic" | "none"

The map projection that placed a view's positions. See ViewInfo.projection.

Meta¶

Meta = object

The server's description of what the viewer can use, from GET /v1/meta: views, columns, filterable columns, annotation layers and request limits. It lists only what the viewer can reach, so do not show one viewer's Meta to another.

Properties¶

Property	Type	Description
`apiVersion`	`number`	The viewer API's version, `1`.
`bundleFormat`	`number`	The bundle format version the server opened.
`declaredScalars`	`DeclaredScalar`[]	The columns with one value per item, in declaration order.
`filterOperands`	`FilterOperandSet`[]	The columns you can filter on, with their operators. Build filter controls from this list. It differs from Meta.declaredScalars: a filterable column need not arrive with the points, and a column that arrives with them need not be filterable.
`groups`	`ViewGroup`[]	The view groups the viewer can reach.
`layers`	`Layer`[]	The annotation layers the viewer can reach.
`maxTilesPerRequest`	`number`	The most tiles one viewport request may cover; more is a `422`.
`scopedScalars`	`ScopedScalar`[]	The group-scoped columns the viewer can reach.
`selection`	`object`	How many points the server selects per tile, and the deployment's request limits.
`selection.kMaxMarks`	`number`	The most points one tile serves, and the default `k`.
`selection.kMin`	`number`	The fewest points a tile serves if it has that many.
`selection.maxAggregateBins`	`number`	The largest `bins` of an aggregate grouping.
`selection.maxAggregateCells`	`number`	The most cells an aggregate grouping's `cells` may cover.
`selection.maxAggregateGroupings`	`number`	The most groupings one MosaicaClient.aggregate request may have.
`selection.maxAggregateNamed`	`number`	The most `values` or `artifacts` an aggregate grouping may name.
`selection.maxAggregateTop`	`number`	The largest `top` of an aggregate grouping.
`selection.maxArtifactsPerTile`	`number`	The largest `perTile` a MosaicaClient.viewportArtifacts request may ask for.
`selection.maxBrowseRows`	`number`	The page size of MosaicaClient.browse, and its largest.
`selection.maxCategoryValues`	`number`	The page size of MosaicaClient.categories, and its largest. A shorter page is the last.
`selection.maxK`	`number`	The largest `k` a request can ask for. A tile serves at most `min(k, maxK, kMaxMarks)` points.
`selection.maxPageBytes`	`number`	The most bytes in one page of MosaicaClient.items or MosaicaClient.artifacts, before compression. A single larger row is sent on its own.
`selection.maxPageRows`	`number`	The most rows in one page of MosaicaClient.items or MosaicaClient.artifacts.
`selection.maxRegionCells`	`number`	The most boundary cells a `region` may use. A larger shape is still answered, for a slightly larger area, and RegionVerdict says so.
`selection.maxRegionVertices`	`number`	The most vertices a `region` polygon may have; more is a `422`.
`selection.maxShapeVertices`	`number`	The most vertices a published shape may have.
`selection.maxSuggestions`	`number`	The default and largest `limit` of MosaicaClient.suggest.
`selection.maxSuggestionWalk`	`number`	The most values one suggestion request examines before it stops and answers `more: true`.
`selection.maxSuggestSetEntities`	`number`	Up to this many visible items, suggestions come only from values the viewer can see. Above it, `more` may mean the search reached `maxSuggestionWalk`.
`selection.maxUnderlayOffset`	`number`	The largest `underlayOffset` a viewport request may ask for.
`selection.thetaTargetMarks`	`number`	The number of points an unfiltered request aims to serve in an average occupied tile. A filtered request serves every match up to the per-tile limit.
`views`	`ViewInfo`[]	The views the viewer can reach: views in no group first, then each group's in creation order. Asking for any other view is a `404`.

Quantisation¶

Quantisation = object

The extent of a view's data coordinates. Positions are stored as 32-bit grid units on each axis: 0 at the minimum and the top of the grid at the maximum, which is inclusive.

Properties¶

Property	Type	Description
`xMax`	`number`	The largest x, in data coordinates.
`xMin`	`number`	The smallest x, in data coordinates.
`yMax`	`number`	The largest y, in data coordinates.
`yMin`	`number`	The smallest y, in data coordinates.

ScopedScalar¶

ScopedScalar = object

A group-scoped column: a family with one column per view of a view group, so an item can hold a different value in each view. Absent from /v1/meta if the viewer cannot reach the group.

Properties¶

Property	Type	Description
`analyser`	`string` \| `null`	For a `text` family, its analyser as `<name>/<version>`; otherwise `null`.
`arrowType`	`ArrowType`	The storage type, as on a DeclaredScalar.
`category`	`CategoryDescriptor` \| `null`	How the family works as a category, or `null` if it is not one.
`index`	`boolean`	Whether the family has a filter index. Meta.filterOperands lists the families you can filter on.
`name`	`string`	The family's name. A filter uses it, pinned to a view if needed (see FilterOperandSet.scope).
`render`	`boolean`	Whether points carry the column in a viewport response. Only views listed in views carry it.
`scope`	`object`	The view group whose views each have a column of this family.
`scope.group`	`string`	-
`views`	`string`[]	The views the viewer can reach whose points carry this column: the group's own views, and the same keys in any group that shares them. A view created on a running service appears once a flush has written its values.

ShapeKind¶

ShapeKind = "derived" | "predicate" | "authored"

The kind of outline a layer draws: derived, the hull of the members the viewer can see; predicate, the shape that decides a spatial layer's membership; authored, a shape the publisher supplied. See Layer.shape.

TileScheme¶

TileScheme = "xyz"

A basemap tile scheme. The only one is xyz, the z/x/y scheme slippy-map tile servers use. See ViewInfo.tileScheme.

ViewGroup¶

ViewGroup = object

A view group: many views of the same kind, such as one layout per year. A request names one of its views, never the group.

Properties¶

Property	Type	Description
`membersOf`	`string` \| `null`	The group whose keys this group's views use, if this group is a second layout over another group's views; otherwise `null`.
`name`	`string`	The group's name.
`title`	`string` \| `null`	The group's display title, or `null` if it has none.
`views`	`string`[]	The ids of the group's views the viewer can reach, as `<group>:<key>`, in creation order.

ViewInfo¶

ViewInfo = object

A view, one 2D layout of the items, as /v1/meta lists it. Use its projection fields to choose a basemap, and lonLatOfCell to turn a position into longitude and latitude.

Properties¶

Property	Type	Description
`displayName`	`string`	The view's display name. For a view in a group it is the id.
`id`	`string`	The view's id, which requests use: the view's name, or `<group>:<key>` for a view in a group.
`projection`	`MapProjection`	The map projection that placed the positions, or `none` if the view is not a map.
`quantisation`	`Quantisation`	The extent of this view's data coordinates. Each view has its own.
`roster`	`ViewRoster` \| `null`	The view's place in its group, or `null` if it is in no group.
`tile`	{ `x`: `number`; `y`: `number`; `z`: `number`; } \| `null`	The tile the view covers, or `null` if `tileScheme` is `null`.
`tileScheme`	`TileScheme` \| `null`	`xyz` if the view lines up with slippy-map tiles, so raster tiles can be drawn under the points; otherwise `null`. Only a `web_mercator` view can line up.
`worldAspect`	`number` \| `null`	The width-to-height ratio to draw the world at: `1` for `web_mercator`, `2cos φ₁` for `equirectangular` and `gall_isographic` (φ₁ being the standard parallel), and `null` for `none`.

ViewMetadataValue¶

ViewMetadataValue = { type: "bool"; value: boolean; } | { type: "int"; value: number; } | { type: "float"; value: number; } | { type: "text"; value: string; } | { type: "timestamp_us"; value: number; }

One metadata value of a view, such as the date a snapshot was taken. timestamp_us is microseconds since the Unix epoch. Metadata describes the view as a whole and cannot be filtered on.

ViewRoster¶

ViewRoster = object

A view's place in its group. The view's id is <group>:<key>. The group's views are ordered as ViewGroup.views lists them, in creation order. To move between views, step through that list; keys are your own strings and need not sort in order.

Properties¶

Property	Type	Description
`group`	`string`	The group's name.
`key`	`string`	The view's key within its group.
`metadata`	`Record`\<`string`, `ViewMetadataValue`>	The view's metadata, one entry per name the group declares. Empty in a group that borrows another group's keys; read the metadata there.

Requests and responses¶

AggregateBy¶

AggregateBy = { field: string; top: number; } | { field: string; values: string[]; } | { bins: number; field: string; range?: [number | bigint | string, number | bigint | string]; sample?: number; } | { cut?: AggregateCut; layer: string; level?: number; paletteSize?: number; top: number; } | { artifacts: bigint[]; layer: string; level?: number; paletteSize?: number; }

How a grouping divides items into groups. There are three kinds:

A category column, as its top values by count or the values you name. The column needs index or render, or a derived vocabulary.
An annotation layer, as its top artifacts by count or the artifacts you name. level is required on a layer with several levels and refused on one with one level. paletteSize (2 to 32) gives each artifact its Artifact.slot. On a nested or dag layer, top requires a cut, and lists the artifacts MosaicaClient.viewportArtifacts would draw for it. A cut on any other layer is a 422.
A number or timestamp column in bins, as a histogram. The column needs index or render.

Pin a group-scoped column outside its group as <field>@<key>. A named value or artifact the viewer cannot see gets no row.

For a histogram, range cuts [lower, upper] into bins equal bins; bounds may be numbers, bigints, or for a timestamp, dates or date-times as in a filter. Without a range, the server picks round edges that cover every visible item in the view, in at most bins bins, so they stay the same as the filters and the map change. With sample, a set more than about 64 times larger than sample is counted from about sample of its items and the counts are scaled up; a smaller set is counted exactly. AggregateTable.sample says which happened. A histogram cannot have cells, and its table is always one page.

AggregateCells¶

AggregateCells = object

Divides each group into map cells at depth. Depths 0 to 16 are the map's tiles at that zoom, and 17 to 32 are finer.

Properties¶

Property	Type	Description
`area?`	[`number`, `number`, `number`, `number`]	The area, `[x0, y0, x1, y1]` in the view's data coordinates. Only the cells it touches are listed, each counted whole. Unset covers the whole view. At most `meta.selection.maxAggregateCells` cells.
`depth`	`number`	The cell depth, `0` to `32`.

AggregateCut¶

AggregateCut = object

The map position a nested or dag layer is drawn at, as in ViewportArtifactsRequest. It covers at most meta.maxTilesPerRequest tiles.

Properties¶

Property	Type	Description
`bbox`	[`number`, `number`, `number`, `number`]	The area, `[x0, y0, x1, y1]` in the view's data coordinates.
`budget?`	`number`	The most artifacts to draw. Unset means no limit.
`zoom`	`number`	The tile depth, `0` to `16`.

AggregateRequest¶

AggregateRequest = object

The request MosaicaClient.aggregate sends: summary tables over the visible items in view, such as counts per category, a histogram, or counts per map cell. Each Grouping gives one table. A field you leave unset takes the server's default.

Properties¶

Property	Type	Description
`compression?`	`"zstd"`	As for ItemsRequest.compression.
`cursor?`	`string`	A previous result's AggregateResult.next, to continue the same request.
`filters?`	`FilterExpr`	The items to count. Unset counts every visible item in `view`.
`groupings`	`Grouping`[]	The tables to compute, at most `meta.selection.maxAggregateGroupings`.
`pageRows?`	`number`	As for ItemsRequest.pageRows.
`pages?`	`number`	As for ItemsRequest.pages.
`reference?`	`FilterExpr`	A second set to compare each count with, from the same visible items. `{}` is every visible item. With it, each table with `count` also gains `reference_count` and `lift` columns.
`view`	`string`	The view to count in. Items with no position in it are not counted.

AggregateResult¶

AggregateResult = object

What MosaicaClient.aggregate returns.

Properties¶

Property	Type	Description
`identityKey`	`string`	The identity key for the viewer and view (see ViewportResponse.identityKey), or empty if the response had none.
`next`	`string` \| `null`	Where to continue the read, or `null` once every table is complete.
`recomposed`	`boolean`	Whether the data changed between pages, so the tables mix counts from before and after the change.
`region`	`RegionVerdict` \| `null`	Whether the `region` filters in `filters` or `reference` were answered exactly; `null` if there were none.
`tables`	`AggregateTable`[]	One table per grouping, in the order of `groupings`.

AggregateSample¶

AggregateSample = object

How a histogram with a sample was counted.

Properties¶

Property	Type	Description
`items`	`number`	How many items of the set were counted.
`referenceItems`	`number` \| `null`	How many items of the reference set were counted, or `null` without a `reference`.
`sampled`	`boolean`	Whether the counts are scaled up from a sample. `false` if every item was counted.

AggregateTable¶

AggregateTable = object

One table of AggregateResult.tables.

The rows are an Arrow table whose columns depend on the grouping, in this order:

group, with by: listed for a named or top group, rest for the items in no listed group, and none for the items with no value.
key and title, with by: the value's key and title, or the artifact's mosaica_id and name. title is present for a layer, or for a column whose vocabulary has titles. Both are null for rest and none.
slot, with by on a layer: the artifact's colour index, or null without paletteSize and on rest and none.
lower and upper, with bins, in place of key and title: the bin's edges. A bin holds values from lower up to upper, and the last bin includes its upper. An edge is a bigint on an integer field, a number on a float field or if a range bound is fractional, and a timestamp in milliseconds, as Arrow reads it, on a timestamp field.
cell, with cells: the cell's Morton prefix, as a bigint.
count, with count. With a reference too, reference_count and lift, which is null if either count it divides by is 0.
The field figures' columns, as Grouping describes.

Properties¶

Property	Type	Description
`grouping`	`number`	The table's index in the request's `groupings`.
`groups`	`number` \| `null`	How many groups have an item in the set, before the cut to `top` or the named list; `null` without `by`.
`referenceTotal`	`number` \| `null`	How many items are in the reference set, or `null` without a `reference`.
`rows`	`Table`	The rows, from every page read.
`sample`	`AggregateSample` \| `null`	How a histogram with a `sample` was counted; otherwise `null`.
`total`	`number`	How many items are in the set.

Artifact¶

Artifact = object

One annotation artifact, such as a cluster, a boundary or a topic label, as MosaicaClient.viewportArtifacts serves it.

Counts and geometry cover only the members the viewer can see, so two viewers can get different figures for the same mosaicaId. They cover members outside the current view too, so they do not change as the map moves. An artifact the viewer may not see is left out of the response.

Properties¶

Property	Type	Description
`box`	[`number`, `number`, `number`, `number`] \| `null`	The bounding box of the visible members, `[minX, minY, maxX, maxY]` in 32-bit grid units; `null` as for `centroid`.
`centroid`	[`number`, `number`] \| `null`	The centre of the visible members, in 32-bit grid units (gridToWorldXY converts it). `null` if the layer does not declare it or the request's `computed` left it out.
`content`	`string`[]	The publisher's content, such as label text, one entry per type in the layer's Layer.suppliedContent. If the artifact has several descriptions for different access levels, this is the one the viewer qualifies for.
`highlighted`	`boolean` \| `null`	Whether any visible member in the frame's tiles matches both the filter and the highlight, or `null` with no highlight.
`key`	`string` \| `null`	The publisher's key for the artifact, or `null` if it has none.
`layer`	`string`	The artifact's layer.
`maskedCount`	`bigint`	How many of the artifact's members the viewer can see.
`matched`	`boolean` \| `null`	Whether any visible member in the frame's tiles matches the request's filter, or `null` with no filter. The filter changes nothing else about the artifact. The points you hold are a sample, so do not work this out from them.
`mosaicaId`	`bigint`	The artifact's `mosaica_id`, the same for every viewer.
`parentIds`	`bigint`[]	The artifact's parents in the same frame, in ascending order. A `dag` layer may give several, and the first is always the same one. Empty for a root, for a flat layer, and when the parent is not served to the viewer; treat all three as a root.
`rung`	`number`	The level to draw the artifact at: its declared level on a `stacked` or `tiered` layer, its depth in the tree on a `nested` or `dag` layer (a root is `0`), and `0` on a flat layer. Use this rather than counting `parentIds`.
`slot`	`number` \| `null`	The artifact's colour index, below the request's `paletteSize`, or `null` without one. Slots are chosen so that neighbouring artifacts differ, and stay the same at any zoom, area, budget or filter.
`target`	`bigint` \| `null`	The `mosaicaId` of the artifact this one attaches to, as a topic label attaches to its cluster, or `null`. An attached artifact is served only with its target. It takes `matched` and `highlighted` from its target. Its `maskedCount` counts its own members, or its target's if it has none, so it is not the number to show beside a label.

ArtifactDetail¶

ArtifactDetail = object

One artifact, as MosaicaClient.artifact returns it. Its count and geometry match what the viewport serves for it in the same view. It does not list the members.

Properties¶

Property	Type	Description
`box`	[`number`, `number`, `number`, `number`] \| `null`	The bounding box of the visible members, `[minX, minY, maxX, maxY]` in 32-bit grid units; `null` if the layer does not declare it.
`centroid`	[`number`, `number`] \| `null`	The centre of the visible members, in 32-bit grid units; `null` if the layer does not declare it.
`key`	`string` \| `null`	The publisher's key for the artifact, or `null` if it has none.
`layer`	`string`	The artifact's layer.
`maskedCount`	`bigint`	How many of the artifact's members the viewer can see in the requested view.
`shape`	`Shape` \| `null`	The artifact's outline, or `null` if its layer draws none. A predicate or authored outline is simplified for the call's `zoom`, or sent whole without one.

ArtifactsHead¶

ArtifactsHead = object

The head of a MosaicaClient.artifacts response, as RecordsRead.head.

Properties¶

Property	Type	Description
`matched`	`number` \| `null`	How many of those have a visible member that matches the filter, or `null` unless the request set `count`.
`pageRows`	`number`	The page size used.
`served`	`number` \| `null`	How many artifacts the request selects, or `null` unless the request set `count`.

ArtifactsRequest¶

ArtifactsRequest = object

The request MosaicaClient.artifacts sends: every artifact of layer served to the viewer, as pages of Arrow rows ordered by level and then by publication order. A field you leave unset takes the server's default.

Each page's columns are mosaica_id (uint64), then the fields in the order named, then matched_count (uint64) if the request has filters.

Properties¶

Property	Type	Description
`compression?`	`"zstd"`	As for ItemsRequest.compression.
`count?`	`boolean`	Put the ArtifactsHead.served and ArtifactsHead.matched counts in the head. A `422` with `cursor`. MosaicaClient.artifacts sends it on the first request only.
`cursor?`	`string`	As for ItemsRequest.cursor.
`fields`	(`"key"` \| `"level"` \| `"parents"` \| `"target"` \| `"masked_count"` \| `"content"` \| `"centroid"` \| `"box"` \| `"shape"` \| `"slot"`)[]	The properties to return, each once. `centroid` gives the columns `centroid_x` and `centroid_y`, and `box` gives `box_x_min`, `box_y_min`, `box_x_max` and `box_y_max`, in the view's coordinates. `shape` is a WKB `MultiPolygon`. `slot` needs ArtifactsRequest.paletteSize. A repeated property is a `422`.
`filters?`	`FilterExpr`	Only the artifacts with a visible member that matches, and a `matched_count` column.
`ids?`	`bigint`[]	Only these artifacts, such as the ones that tag a point. An id not served to the viewer gives no row.
`keepUnmatched?`	`boolean`	With `filters`, return every artifact, with a `matched_count` of zero for those with no match.
`layer`	`string`	A layer `/v1/meta` lists. Any other is a `422`.
`level?`	`number`	Only the artifacts at this level. A `422` on a layer with one level, or past its last level.
`pageRows?`	`number`	As for ItemsRequest.pageRows.
`pages?`	`number`	As for ItemsRequest.pages.
`paletteSize?`	`number`	As for ViewportArtifactsRequest.paletteSize. Without it the `slot` column is null.
`parent?`	`bigint`	Only the children of this artifact. A `422` with `q`.
`q?`	`string`	Only the artifacts whose key or first text contains this, ignoring case. A `422` with `parent`.
`view`	`string`	The view the counts and geometry are taken in.

AuthoriseTarget¶

AuthoriseTarget = { principal: string; } | { accessToken: string; } | { terms: string[]; } | { readAll: true; }

Who MosaicaClient.authorise creates a session for.

Union Members¶

Type Literal¶

{ principal: string; }

Name	Type	Description
`principal`	`string`	A local principal, by name.

Type Literal¶

{ accessToken: string; }

Name	Type	Description
`accessToken`	`string`	An OIDC identity, by the access token its provider issued.

Type Literal¶

{ terms: string[]; }

Name	Type	Description
`terms`	`string`[]	A set of terms, for a session that belongs to no principal and has `read` permission only. Only the operator credential may ask for one. Each term is trimmed, and a term that is empty or holds a control character is dropped. Every session holds `public`, so naming it changes nothing.

Type Literal¶

{ readAll: true; }

Name	Type	Description
`readAll`	`true`	A superuser session with `read` and `read-all`, which sees every item and satisfies every label, including items added after it was created. Deletions and suppressions still apply. Only the operator credential may ask for one.

BrowsePage¶

BrowsePage = object

One page of MosaicaClient.browse.

Properties¶

Property	Type	Description
`artifacts`	`BrowseRow`[]	The page's rows.
`next`	`string` \| `null`	The cursor for the next page, or `null` if this is the last.
`parents`	`BrowseRow`[]	In the children form, the parent's own parents; otherwise `[]`.

BrowseRequest¶

BrowseRequest = object

The request MosaicaClient.browse sends: one page of a layer's artifacts by hierarchy, whatever the map shows. It has three forms:

Roots, with neither parent nor q: the artifacts with no parent served to the viewer.
Children, with parent: its children, and its own parents in BrowsePage.parents. On a dag layer a child appears under each of its parents.
Search, with q: the artifacts whose key or BrowseRow.name contains q, ignoring case.

Giving both parent and q is a 422. Rows are ordered by matchedCount if filters is set, otherwise by maskedCount, then by mosaicaId.

Properties¶

Property	Type	Description
`cursor?`	`string`	The previous page's BrowsePage.next.
`filters?`	`FilterExpr` \| `null`	A filter. Each row then carries `matchedCount` and the page is ordered by it. The same rows are served, including those with a `matchedCount` of zero.
`layer`	`string`	The layer to browse. A layer `/v1/meta` does not list, or one whose artifacts attach to another layer's, is a `422`.
`level?`	`number`	The level to browse on a `stacked` or `tiered` layer. On any other layer, or for a level the layer does not have, it is a `422`.
`limit?`	`number`	The page size. Defaults to `selection.maxBrowseRows` and is capped at it; `0` is a `422`.
`paletteSize?`	`number`	As for ViewportArtifactsRequest.paletteSize: each row then carries a BrowseRow.slot.
`parent?`	`bigint`	The parent whose children to list, by `mosaica_id`. An artifact that does not exist, belongs to another layer, is suppressed or is not served to the viewer gives an empty page.
`q?`	`string`	Text to search for in each artifact's key or BrowseRow.name, ignoring case.
`view`	`string`	The view the counts are taken in.

BrowseRow¶

BrowseRow = object

One row of a browse page.

Properties¶

Property	Type	Description
`childCount`	`number`	How many children of this artifact are served to the viewer. `0` for a leaf, and on a `flat` or `stacked` layer.
`key`	`string` \| `null`	The publisher's key for the artifact, or `null` if it has none.
`maskedCount`	`bigint`	How many of the artifact's members the viewer can see. Filters do not change it.
`matchedCount`	`bigint` \| `null`	How many of those members match the request's filter, or `null` with no filter.
`mosaicaId`	`bigint`	The artifact's `mosaica_id`.
`name`	`string` \| `null`	A name to show: the artifact's first supplied text, or if it has none, the text of an artifact attached to it, such as a cluster's topic label. `null` if neither has text.
`parentIds`	`bigint`[]	The artifact's parents that are served to the viewer, in ascending order.
`rung`	`number`	The artifact's level: its declared level on a `stacked` or `tiered` layer, its depth in the tree on a `nested` or `dag` layer, and `0` on a flat layer.
`slot`	`number` \| `null`	As for Artifact.slot: `null` if the request had no `paletteSize`.

CategoryValue¶

CategoryValue = object

One category value: what a code stands for, and how to show it.

Properties¶

Property	Type	Description
`code`	`number`	The integer code that points carry for this value. Never `0`, which means no value.
`key`	`string`	The value's key, which filters use. Show it if there is no title.
`title`	`string` \| `null`	The value's display title, or `null` if none was written. Values of a discovered vocabulary have none.

CountsSink¶

CountsSink = (counts: ViewportCounts) => void

Receives a viewport response's counts as soon as they arrive; see ViewportCounts.

Returns¶

void

Grouping¶

Grouping = object

One table of an aggregate: how to divide the items into rows, and which figures each row holds. by divides them into groups and cells into map cells; with both, each group is divided into cells. Name at least one figure; {count: true} alone counts the whole set.

The field figures (values, missing, min, max, mean and summary) each take a list of number or timestamp columns declared with index or render, and add one column per field named <figure>_<field>. They are computed over every visible item in the view, so they cannot be combined with by, cells, filters or reference, and their table has one row. All figures are exact; min, max and mean are null if the field has no values. values_ and missing_ columns are bigint; min_ and max_ are typed as a histogram's edges, and mean_ is a timestamp on a timestamp field and a number otherwise.

Properties¶

Property	Type	Description
`by?`	`AggregateBy`	Divide the items into groups. Unset treats them as one group.
`cells?`	`AggregateCells`	Divide each group into map cells. Unset keeps each group whole.
`count?`	`true`	Add a `count` column: the items in each row.
`max?`	`string`[]	Add `max_<field>`: the largest finite value.
`mean?`	`string`[]	Add `mean_<field>`: the mean of the finite values, rounded to the microsecond on a timestamp.
`min?`	`string`[]	Add `min_<field>`: the smallest finite value.
`missing?`	`string`[]	Add `missing_<field>`: how many items hold no value.
`summary?`	`string`[]	Add all five figures for each field.
`values?`	`string`[]	Add `values_<field>`: how many items hold a finite value.

ItemDetail¶

ItemDetail = object

One item's record, as MosaicaClient.item returns it.

Properties¶

Property	Type	Description
`fields`	`Record`\<`string`, `unknown`>	The item's values, by column name. Numbers are JavaScript numbers, so a 64-bit integer above 2^53 loses precision. A category value is its key. A column with no value is left out.
`labels`	`string`[]	Why the viewer can see the item: the parts of its access labels the viewer satisfies, sorted. Each entry is a term the viewer holds, `public`, or a conjunction the viewer satisfies, written as terms joined by `&` (such as `staff&uk`). It does not give the item's full labels. It can be empty.
`scoped`	`Record`\<`string`, `Record`\<`string`, `unknown`>>	The item's group-scoped values, by family name and then by view key, such as `{mood: {'2026-Q1': 'calm'}}`. Meta.scopedScalars gives each family's group. Views the viewer cannot reach are left out, and so is a `text` family, which has no per-item value.
`views`	`ItemViewPosition`[]	The item's position in each view it is in that the viewer can reach, sorted by id. An item in no view at all is a `404`.

ItemsHead¶

ItemsHead = object

The head of a MosaicaClient.items response, as RecordsRead.head.

Properties¶

Property	Type	Description
`matched`	`number` \| `null`	How many of those match the filter, or `null` unless the request set `count`.
`order`	`"map"` \| `"stored"`	The order of the rows.
`pageRows`	`number`	The page size used.
`visible`	`number` \| `null`	How many items in the view the viewer can see, or `null` unless the request set `count`.

ItemsRequest¶

ItemsRequest = object

The request MosaicaClient.items sends: every visible item in view that matches filters, as pages of Arrow rows. A field you leave unset takes the server's default.

Each page's columns are mosaica_id (uint64), then the fields in the order named, then mosaica:x and mosaica:y with position, mosaica:labels with labels, and mosaica:matched with keepUnmatched. A missing value is null. A category is a dictionary column of its keys, with a dictionary per page, so compare keys rather than dictionary indices across pages.

Properties¶

Property	Type	Description
`compression?`	`"zstd"`	Compress each page with zstd. The client decodes either form.
`count?`	`boolean`	Put the ItemsHead.visible and ItemsHead.matched counts in the head. A `422` with `cursor`. MosaicaClient.items sends it on the first request only.
`cursor?`	`string`	A previous response's cursor, to continue the read.
`fields`	`string`[]	The columns to return, by name, each once. Pin a group-scoped column outside its group as `<field>@<key>`. `[]` returns `mosaica_id` alone. An unknown or repeated name is a `422`.
`filters?`	`FilterExpr`	A filter. Only matching items are returned, unless `keepUnmatched` is set.
`keepUnmatched?`	`boolean`	Return every visible item, with a `mosaica:matched` column saying which match `filters`.
`labels?`	`boolean`	Return `mosaica:labels` (`list<utf8>`): the parts of each item's labels the viewer satisfies, as ItemDetail.labels gives them.
`order?`	`"map"` \| `"stored"`	`map` orders rows by their place on the map. `stored` orders them as the record store holds them, which is faster for columns held only there. Unset keeps the cursor's order, or lets the server choose. An order different from the cursor's is a `422`.
`pageRows?`	`number`	Rows per page, at most `meta.selection.maxPageRows`, which is the default. `0` is a `422`.
`pages?`	`number`	The most pages one response may carry. Unset carries as many as the server's limits allow; `0` is a `422`.
`position?`	`boolean`	Return each item's position as `mosaica:x` and `mosaica:y` (`float64`) in the view's coordinates, such as degrees on a geographic view.
`view`	`string`	The view to read. Items with no position in it are not returned.

ItemViewPosition¶

ItemViewPosition = object

Where one view places an item. See ItemDetail.views.

Properties¶

Property	Type	Description
`id`	`string`	The view's id.
`x`	`number`	The item's x in that view's 32-bit grid units (ViewInfo.quantisation). Each view has its own extent, so the same item has a different position in each.
`y`	`number`	The item's y, in the same units as `x`.

Login¶

Login = object

A session, as MosaicaClient.login returns it.

Properties¶

Property	Type	Description
`expiresAt`	`number`	When the session expires, in seconds since the Unix epoch. It is no later than the server's `token_max_lifetime` after the request, nor than the expiry of the API key or access token used to create it. A change to the catalogue can end it sooner.
`token`	`string`	The bearer token every viewer route takes. It is a credential.

LoginCredential¶

LoginCredential = { password: string; principal: string; } | { apiKey: string; } | { accessToken: string; }

The credential MosaicaClient.login sends: a password, an API key or an OIDC access token.

Union Members¶

Type Literal¶

{ password: string; principal: string; }

Name	Type	Description
`password`	`string`	Its password.
`principal`	`string`	A local principal's name.

Type Literal¶

{ apiKey: string; }

Name	Type	Description
`apiKey`	`string`	An API key, `msk_<prefix>_<secret>`.

Type Literal¶

{ accessToken: string; }

Name	Type	Description
`accessToken`	`string`	An OIDC access token issued by a declared provider.

MatchSpan¶

MatchSpan = object

Where a suggestion matched the query, so you can highlight the match. start and len count Unicode code points, which differ from JavaScript string indices for characters such as emoji; index Array.from(text) to be exact.

Properties¶

Property	Type	Description
`field`	`"key"` \| `"title"`	The field that matched. For a value with no title it is `key`.
`len`	`number`	The match's length in code points.
`start`	`number`	The code point the match starts at.

MembershipColumn¶

MembershipColumn = object

One layer's membership column. See ViewportResult.membership.

Properties¶

Property	Type	Description
`ids`	`BigUint64Array`	The artifacts' `mosaica_id`s, in the order first seen.
`index`	`Uint16Array` \| `Uint32Array`	Per point, `0` if no artifact holds it, otherwise `1 + d`, where `ids[d]` is the artifact. A `Uint16Array` for at most 65,535 points.

PageEnd¶

PageEnd = object

Sent after each page of an items or artifacts read.

Properties¶

Property	Type	Description
`endedBy`	`"rows"` \| `"bytes"` \| `"time"` \| `"end"`	Why the page ended. `rows`: it holds `pageRows` rows. `bytes`: the next row would have taken it past `meta.selection.maxPageBytes`. `time`: the response ran out of time and ends after this page. `end`: no rows remain.
`next`	`string` \| `null`	The cursor to continue after this page, or `null` if no rows remain.

RecordsTrailer¶

RecordsTrailer = object

Sent at the end of an items or artifacts response.

Properties¶

Property	Type	Description
`endedBy`	`"end"` \| `"pages"` \| `"budget_bytes"` \| `"budget_time"` \| `"deadline"`	Why the response ended. `end`: no rows remain. `pages`: it carried the request's `pages`. `budget_bytes` and `budget_time`: it reached the server's size or time limit. `deadline`: the stream timed out.
`next`	`string` \| `null`	The cursor to continue from, or `null` if no rows remain.
`pages`	`number`	How many pages the response carried, including an empty one.
`rows`	`number`	How many rows the response carried.
`streamUs`	`number`	How long the response took on the server, in microseconds, including time spent waiting for the client.

ScalarColumn¶

ScalarColumn = ScalarValues & object

One render column's values for a response's points, in point order. The values are a typed array you can pass to a GPU attribute without copying. Whether the column is a category is on DeclaredScalar.category.

Type Declaration¶

Name	Type	Description
`present?`	`Uint8Array` \| `null`	Per point, `1` if it has a value and `0` if not, in which case `values[i]` is a meaningless zero. Missing or `null` if every point has a value. A category uses code `0` for no value.

ScalarValues¶

ScalarValues = { arrowType: "bool"; values: boolean[]; } | { arrowType: "utf8"; values: string[]; } | { arrowType: "u8"; values: Uint8Array; } | { arrowType: "u16"; values: Uint16Array; } | { arrowType: "u32"; values: Uint32Array; } | { arrowType: "u64"; values: BigUint64Array; } | { arrowType: "i8"; values: Int8Array; } | { arrowType: "i16"; values: Int16Array; } | { arrowType: "i32"; values: Int32Array; } | { arrowType: "i64"; values: BigInt64Array; } | { arrowType: "f32"; values: Float32Array; } | { arrowType: "f64"; values: Float64Array; } | { arrowType: "timestamp_us"; values: BigInt64Array; }

A column's storage type and its values. 64-bit integers and timestamp_us (microseconds since the Unix epoch) are bigint arrays.

Session¶

Session = Login & object

A session created by MosaicaClient.authorise.

Type Declaration¶

Name	Type	Description
`tokenId`	`number`	The session's id, which MosaicaClient.revoke takes. It is not a credential.

Shape¶

Shape = [number, number][][][]

An artifact's outline: a list of parts, each a list of rings, each a list of [x, y] vertices in 32-bit grid units. A part's first ring is its outer boundary and the others are holes. A derived hull has one part per separate group of visible members, and no holes.

The outline is simplified for the zoom it was requested at and may be off by up to a cell. To know whether a point is a member, use ViewportResult.membership.

SubCell¶

SubCell = object

One cell of the density underlay (ViewportRequest.underlayOffset).

Properties¶

Property	Type	Description
`cell`	`bigint`	The cell's Morton prefix at depth `zoom + underlayOffset`.
`count`	`bigint`	How many items in the cell the viewer can see. Never `0`: empty cells are left out.

SuggestPage¶

SuggestPage = object

One page of suggestions from MosaicaClient.suggest.

Properties¶

Property	Type	Description
`column`	`string`	The column, as the request spelt it.
`more`	`boolean`	`true` if there may be more matches: the page filled, or the server examined `selection.maxSuggestionWalk` values. There is no next page; a longer query narrows the list.
`q`	`string`	The query as the request sent it, so you can match a page to its request.
`region?`	`RegionVerdict`	Whether the counts are exact, if the request's `filters` had a `region` and it asked for counts.
`total?`	`number`	How many items the counts are taken over, so a value's share is `count / total`. Present only if the request set `counts: true`.
`values`	`SuggestValue`[]	The matching values the viewer can see, ordered by the matched text.

SuggestResult¶

SuggestResult = object & SuggestPage | { detail: string | null; retryAfterS: number; status: "shed"; }

What MosaicaClient.suggest returns: status: 'ok' with the page, or status: 'shed' if the server was too busy (429). A shed request may be sent again after retryAfterS seconds, and detail gives the server's reason. A viewer can have one suggestion request running at a time, so the usual cause is that the previous one has not finished.

SuggestValue¶

SuggestValue = object

One suggested category value, with where it matched and, if asked for, a count.

Properties¶

Property	Type	Description
`code`	`number`	The value's code. Never `0`.
`count?`	`number`	How many visible items hold this value, in the request's view and matching its `filters` if it gave them. Present only if the request set `counts: true`.
`key`	`string`	The value's key.
`match`	`MatchSpan`	Where the query matched.
`title`	`string` \| `null`	The value's display title, or `null` if none was written.

TileCounts¶

TileCounts = object

One tile's exact counts of the items the viewer can see. The served points are a sample of the matched ones, so show served alongside matched or visible.

Properties¶

Property	Type	Description
`highlighted`	`bigint`	How many of `matched` also match the request's `highlight`, whether served or not. Equal to `matched` with no highlight.
`matched`	`bigint`	How many of `visible` match the request's filter; equal to `visible` with no filter.
`served`	`bigint`	How many points the response carries for the tile.
`tile`	`bigint`	The tile's Morton prefix at the request's `zoom`.
`visible`	`bigint`	How many items in the tile the viewer can see. Filters do not change it.

Timings¶

Timings = object

The server's timings for one response.

Properties¶

Property	Type	Description
`admissionUs`	`number`	Microseconds the request waited to be admitted (`x-mosaica-admission-us`), or `0` if the header is missing.
`serverUs`	`number`	Microseconds from admission to the server's first write (`x-mosaica-server-us`), or `0` if the header is missing. It does not cover the rest of the stream.
`stageNs`	`number`[] \| `null`	Per-stage timings in nanoseconds, or `null`. The server sends them only if it was built with the `bench-timing` feature and `serve.stage_timing` is on.

ViewportArtifactsFrame¶

ViewportArtifactsFrame = object

One frame of a MosaicaClient.viewportArtifacts response, passed to its onTile callback as it arrives.

Properties¶

Property	Type	Description
`artifacts`	`Artifact`[]	The artifacts with a visible member in the tile, at most `perTile` per layer and level, largest `maskedCount` first.
`tile`	`bigint` \| `null`	The tile this frame answers, as its Morton prefix at the request's `zoom`. `null` for the treed frame, and for an empty frame of a `bbox` request.
`treed`	`boolean`	Whether this is the treed frame, which holds the `nested` and `dag` layers' artifacts for the whole area, cut to the request's `budget`. It comes first, and is left out if it would be empty.

ViewportArtifactsRequest¶

ViewportArtifactsRequest = object

The request MosaicaClient.viewportArtifacts sends: the artifacts of the named layers in each tile of an area. Give exactly one of bbox and tiles. A field you leave unset takes the server's default.

Properties¶

Property	Type	Description
`bbox?`	[`number`, `number`, `number`, `number`]	The area, as for ViewportRequest.bbox.
`budget?`	`number`	The most artifacts to serve from the `nested` and `dag` layers named, using ancestors in place of their descendants. Unset means no limit.
`computed?`	`ComputedProperty`[]	Which geometry each artifact carries: any of `'centroid'` and `'box'`. Unset gives what the layer declares, and `[]` gives none. A geometry the layer does not declare is left out. Read an artifact's outline with MosaicaClient.artifact.
`filters?`	`FilterExpr` \| `null`	A filter, answered as each artifact's Artifact.matched. It changes nothing else.
`highlight?`	`FilterExpr` \| `null`	An expression to highlight, answered as each artifact's Artifact.highlighted.
`layers?`	`string`[] \| `"all"`	The layers to answer for, as for ViewportRequest.layers. Unset or `[]` is none.
`levels?`	`number`[] \| `"all"`	Which levels of each layer to answer for, as for ViewportRequest.levels.
`paletteSize?`	`number`	The number of colours in your palette, from 2 to 32. Each artifact then carries a Artifact.slot. Outside that range the request is a `422`.
`perTile`	`number`	The most artifacts one level serves in one tile, largest first. Required, and at most `selection.maxArtifactsPerTile`; more is a `422`.
`stamp?`	`string` \| `null`	As for ViewportRequest.stamp.
`tiles?`	`bigint`[]	The tiles to answer, in place of `bbox`, as for ViewportRequest.tiles. Each gets one frame.
`view`	`string`	A view id from Meta.views. Any other view is a `404`.
`zoom`	`number`	The tile depth to answer at, `0` to `16`.

ViewportArtifactsResponse¶

ViewportArtifactsResponse = object

What MosaicaClient.viewportArtifacts returns.

Properties¶

Property	Type	Description
`bytes`	`number`	The size of the response body, in bytes.
`contentKey`	`string`	As for ViewportResponse.contentKey.
`frames`	`ViewportArtifactsFrame`[]	Every frame in order: the treed frame if there is one, then one per tile.
`identityKey`	`string`	As for ViewportResponse.identityKey.
`pin`	`string` \| `null`	As for ViewportResponse.pin.
`region`	`RegionVerdict` \| `null`	As for ViewportResponse.region.
`stale`	`boolean`	As for ViewportResponse.stale.
`timings`	`Timings`	The server's timings. `stageNs` is always `null`.

ViewportCounts¶

ViewportCounts = object

A viewport response's counts, passed to a CountsSink. The server sends the counts before any point, so you can show them first.

Properties¶

Property	Type	Description
`contentKey`	`string`	As for ViewportResponse.contentKey.
`identityKey`	`string`	As for ViewportResponse.identityKey.
`subCells`	`SubCell`[] \| `null`	The density underlay, or `null` if the request asked for none.
`tiles`	`TileCounts`[]	Every tile's counts, in the response's tile order.

ViewportPart¶

ViewportPart = object

Part of a viewport response, passed to a PartSink as it arrives so you can draw points before the whole response has loaded. A part holds whole tiles, listed in result.tiles; its subCells is null.

Properties¶

Property	Type	Description
`columnsAsked?`	readonly `string`[] \| `null`	As for ViewportResponse.columnsAsked.
`contentKey`	`string`	As for ViewportResponse.contentKey.
`identityKey`	`string`	As for ViewportResponse.identityKey.
`layersAsked?`	readonly `string`[] \| `"all"`	As for ViewportResponse.layersAsked.
`result`	`ViewportResult`	The part's points, with the tiles they cover.

ViewportRequest¶

ViewportRequest = object

The request MosaicaClient.viewport sends: the points and counts for an area of the map. Give exactly one of bbox and tiles. A field you leave unset takes the server's default.

Properties¶

Property	Type	Description
`artifactBudget?`	`number`	The most artifacts a `nested` or `dag` layer tags points with. The server meets it by using ancestors in place of their descendants. Unset means no limit; other layers ignore it.
`bbox?`	[`number`, `number`, `number`, `number`]	The area, as `[x0, y0, x1, y1]` in the view's data coordinates with `x0 <= x1` and `y0 <= y1`. The response covers every tile at depth `zoom` that the box touches.
`filters?`	`FilterExpr` \| `null`	The filter, or `null` for none. It narrows which points are served and each tile's `matched` count. It does not change `visible` or the response's `identityKey`, so drop the points you hold yourself when the filter changes.
`highlight?`	`FilterExpr` \| `null`	An expression to highlight, or `null` for none. It does not change which points are served. It adds a `highlighted` count to each tile and a flag to each point, for the items that match both `filters` and `highlight`. Combine several highlights with `any_of` or `all_of`.
`k?`	`number`	The most points each tile serves. Defaults to `selection.kMaxMarks`, and is capped at `selection.maxK` and `selection.kMaxMarks`. `0` asks for counts only. Keep it the same as the map zooms in, or points already drawn drop out.
`layers?`	`string`[] \| `"all"`	The annotation layers to tag points with: each adds a column saying which of its artifacts holds each point (ViewportResult.membership). Unset or `[]` is none and `'all'` is every layer the viewer can reach. Unknown names are ignored. The artifacts themselves come from MosaicaClient.viewportArtifacts.
`levels?`	`number`[] \| `"all"`	Which levels of each named layer tag the points. Unset uses the levels whose `zoom` range covers the request's `zoom`, or every level if none declares a range. `'all'` is every level, `[]` is none, and a level a layer does not have is ignored.
`pointRows?`	`"full"` \| `"highlight"` \| readonly `string`[]	Which columns each point carries. `'full'`, the default, is every `render` column. A list names the `render` columns to carry, and `[]` gives the position alone; any other name is a `422`. `'highlight'` gives only each point's `mosaica_id` and highlight flag, for when only the highlight has changed; once ViewportResponse.stale is `true`, ask for the columns again. Without a `highlight`, `'highlight'` is answered as `'full'`. The same points are served whichever you choose.
`stamp?`	`string` \| `null`	The ViewportResponse.pin of the response on screen, so the server can report whether the data has changed since (ViewportResponse.stale).
`tiles?`	`bigint`[]	The tiles at depth `zoom` to answer, in place of `bbox`, as Morton prefixes (the tile's position code). They are answered in the order given, without duplicates. Leave out the tiles you already hold.
`underlayOffset?`	`number`	Also return exact visible counts for the cells `underlayOffset` levels below `zoom`, as ViewportResult.subCells, to draw a density underlay. `0` or unset returns none. Above `selection.maxUnderlayOffset`, past depth 16, or over the deployment's cell limit, the request is a `422`.
`view`	`string`	A view id from Meta.views. Any other view is a `404`.
`zoom`	`number`	The tile depth to answer at, `0` to `16`.

ViewportResponse¶

ViewportResponse = object

What MosaicaClient.viewport returns.

Properties¶

Property	Type	Description
`bytes`	`number`	The size of the response body, in bytes.
`columnsAsked?`	readonly `string`[] \| `null`	The `render` columns the request asked for in ViewportRequest.pointRows, or `null` if it did not name any.
`contentKey`	`string`	Identifies the version of the data the response was answered from: its entity tag (`etag`), without quotes. It changes when items may have been added, when a deletion, suppression or lift applies, and when the server restarts. You may still draw a tile cached under an older content key; to refresh it, list it in ViewportRequest.tiles.
`identityKey`	`string`	Identifies the set of items the viewer may see in this view (`x-mosaica-identity-key`). It is derived from the viewer's access terms, the view and the dataset, so it changes when the session belongs to a viewer with different access and when the dataset is rebuilt or compacted. When it changes, discard what you cached under the old key.
`layersAsked?`	readonly `string`[] \| `"all"`	The layers the request named in ViewportRequest.layers. A named layer with no column in ViewportResult.membership tags no point.
`pin`	`string` \| `null`	The version of the data this response was computed from (`x-mosaica-pin`), or `null` if the header is missing. Send it back as ViewportRequest.stamp to learn whether the data has changed. Shortly after a write, it can still name the previous version, and the new items are not yet visible. Deletions and suppressions apply at once.
`region`	`RegionVerdict` \| `null`	Whether the request's `region` filters were answered exactly, or `null` if it had none.
`result`	`ViewportResult`	The decoded response. If the call was given a part sink, the points went there and this result's per-point arrays are empty.
`stale`	`boolean`	Whether the data has changed since the request's `stamp`, or `false` if no stamp was sent. It changes whenever the server flushes, merges or compacts data, even if nothing the viewer can see changed. It is advisory: nothing expires while it is `true`.
`timings`	`Timings`	The server's timings.

ViewportResult¶

ViewportResult = object

A decoded viewport response: per-tile counts and the served points. The per-point arrays are all in the order of ids.

Properties¶

Property	Type	Description
`codes`	`BigUint64Array`	Each point's 64-bit Morton code, its two 32-bit grid coordinates interleaved. Shifting right by `64 - 2z` gives the tile at depth `z` that holds it.
`highlighted`	`Uint8Array` \| `null`	One byte per point: `1` if it matches the request's `highlight`, otherwise `0`. `null` with no highlight.
`ids`	`BigUint64Array`	Each point's `mosaica_id`.
`membership`	`Record`\<`string`, `MembershipColumn`>	One column per layer the request named in `layers` that tags any point, by layer name. Each gives, per point, the deepest artifact of the layer that holds it; see MembershipColumn. MosaicaClient.artifacts with `ids` reads those artifacts.
`pointsProjection`	`"full"` \| `"highlight"`	`'highlight'` if the points came with only `ids` and `highlighted` (asked for with `pointRows: 'highlight'` and a `highlight`); you then match the flags to the points you hold by `mosaica_id`. Otherwise `'full'`.
`positions`	`Float64Array`	Interleaved x, y per point in cell space, `[0, 65536)` per axis, with a fraction for the position inside the cell.
`scalars`	`Record`\<`string`, `ScalarColumn`>	The `render` columns the request asked for in `pointRows`, by column name.
`subCells`	`SubCell`[] \| `null`	The density underlay's cells if the request set `underlayOffset`; otherwise `null`.
`tiles`	`TileCounts`[]	One entry per tile with anything visible to the viewer, in the response's tile order.
`world`	`Float32Array`	The same positions in world space, `[0, 512)` per axis (WORLD_SIZE): cell space divided by 128. This is the space the renderer draws in.

Artifacts¶

artifactName()¶

artifactName(a: Pick\<Artifact, "content" | "mosaicaId"> | Pick\<BrowseRow, "mosaicaId" | "name">, attached?: ReadonlyMap\<bigint, string>): string | null

What to call an artifact: its own first supplied text, else the text of the artifact attached to it (a clustering's topic label) in attached, else null. An empty text counts as none. A key such as hdb-2422486 is never used. Pass attached from ArtifactsProjection.attached.

Parameters¶

Parameter	Type	Default value
`a`	`Pick`\<`Artifact`, `"content"` \| `"mosaicaId"`> \| `Pick`\<`BrowseRow`, `"mosaicaId"` \| `"name"`>	`undefined`
`attached?`	`ReadonlyMap`\<`bigint`, `string`>	`NONE`

Returns¶

string | null

@mosaicajs/client¶

Store¶

Store¶

Properties¶

Methods¶

basemapWorld()¶

browse()¶

Parameters¶

Throws¶

clear()¶

clearSelection()¶

dataXY()¶

Throws¶

describe()¶

dispose()¶

extentOf()¶

forgetSuggestions()¶

frame()¶

get()¶

heldTitle()¶

items()¶

Parameters¶

Throws¶

needShape()¶

openArtifact()¶

pick()¶

refresh()¶

requestFilters()¶

select()¶

setAggregate()¶

Example¶

setArtifactColours()¶

setBudget()¶

setClusterBudget()¶

setColourBy()¶

setCurrentView()¶

setFilters()¶

setLayers()¶

setMembers()¶

setPalette()¶

setPointColumns()¶

setSizeBy()¶

Parameters¶

setView()¶

subscribe()¶

Call Signature¶

Returns¶

Call Signature¶

Returns¶

suggest()¶

titleOf()¶

Example¶

AggregateSpec¶

Properties¶

AggregateSpecGrouping¶

Type Declaration¶

DrawnLayerBy¶

ProjectionName¶

Projections¶

Properties¶

StoreItemsRequest¶

Type Declaration¶

StoreOptions¶

Properties¶

TokenSupplier¶

Returns¶

ViewInput¶

Properties¶

DEFAULT_BUDGET¶

createStore()¶

Throws¶

Projections¶

ArtifactTable¶

Properties¶

Methods¶

changesSince()¶

Returns¶

entry()¶

liveEntries()¶

ordinalOf()¶