---
url: /mosaic/api/core/coordinator.md
---
# Coordinator

The Mosaic coordinator manages queries for Mosaic clients.
Internally, the coordinator includes a query manager that maintains a queue of query requests that are issued through a database [connector](./connectors).
The coordinator also manages *filter groups*: collections of clients that share the same [`filterBy`](./client#filterby) selection. The coordinator responds to selection changes and provides coordinated updates to all linked clients.
Where possible, the coordinator also applies optimizations, such as caching and building optimized indices for filter groups involving supported aggregation queries.

## coordinator {#coordinator-global}

`coordinator()`

Get the default global coordinator instance.

## constructor

`new Coordinator(connector, options)`

Create a new Mosaic Coordinator to manage all database communication for clients and handle selection updates. Accepts a database *connector* and an *options* object:

* *logger*: The logger to use, defaults to `console`.
* *cache*: Boolean flag to enable/disable query caching (default `true`), or a cache object such as `lruCache({ maxBytes })` to use a custom budget. See [Query cache](#query-cache).
* *ipc*: Arrow IPC extraction options used when decoding `"arrow"` query results. If unspecified, date and timestamp values are extracted as JavaScript `Date` objects. Setting new options on the query manager clears the query cache.
* *consolidate* Boolean flag to enable/disable query consolidation (default `true`).
* *preagg*: Pre-aggregation options object. The *enabled* flag (default `true`) determines if pre-aggregation optimizations should be used when possible. The *schema* option (default `'mosaic'`) indicates the database schema in which materialized view tables should be created for pre-aggregated data.

## Query cache

`lruCache(options)`

Create the least-recently-used query cache the coordinator uses by default. The budget counts the Arrow IPC bytes returned by the connector, and a result larger than the budget is not cached. Supports the following *options*:

* *maxBytes*: The maximum number of bytes to retain (default 256 MiB).

A custom cache object must implement `get(key)`, `set(key, value, bytes)`, `clear()`, and `bytes()`, where `bytes()` returns the total bytes currently charged to the cache.

## databaseConnector

`coordinator.databaseConnector(connector)`

Get or set the [*connector*](./connectors) used by the coordinator to issue queries to a backing data source.

## connect

`coordinator.connect(client)`

Connect a [*client*](./client) to this coordinator.
Upon connection, the [client lifecycle](/core/) will initiate.
If the client exposes a `filterBy` selection, the coordinator will handle updates to the client when the selection updates.

## disconnect

`coordinator.disconnect(client)`

Disconnect the [*client*](./client) from the coordinator and remove all update handling.

## logger

`coordinator.logger(logger)`

Get or set the coordinator's logger.
The logger defaults to the standard JavaScript `console`.
A logger instance must support `log`, `info`, `warn`, and `error` methods.
If set to `null`, logging will be suppressed.

## clear

`coordinator.clear(options)`

Resets the state of the coordinator. Supports the following *options*:

* *clients*: A Boolean flag (default `true`) indicating if all current clients should be disconnected.
* *cache*: A Boolean flag (default `true`) indicating if the query cache should be cleared.

## exec

`coordinator.exec(query, options)`

Request a *query* and return a request Promise that resolves when the query is complete.
No query result will be returned.
The input *query* should produce a SQL query upon string coercion.

The supported *options* are:

* *priority*: A value indicating the query priority, one of: `Priority.High`, `Priority.Normal` (the default), or `Priority.Low`.

## query

`coordinator.query(query, options)`

Request a *query* and return a request Promise that resolves when the query is complete.
An Arrow table will be returned.
The input *query* should produce a SQL query upon string coercion.

The supported *options* are:

* *cache*: A Boolean flag (default `true`) indicating if the query result should be cached.
* *priority*: A value indicating the query priority, one of: `Priority.High`, `Priority.Normal` (the default), or `Priority.Low`.

Any additional options will be passed through to the backing database.

## prefetch

`coordinator.prefetch(query, options)`

Request a *query* to prefetch the results for later use, and return a request Promise that resolves when the query is complete. This method accepts the same *options* as [`query()`](#query), except that the *cache* flag will always be true and the *priority* flag will always be `Priority.Low`.

If prefetch requests are no longer needed, the [`cancel`](#cancel) method can be used to drop any queued but not yet issued queries.

## cancel

`coordinator.cancel(requests)`

Cancel the provided query *requests*, a list of one or more request Promise instances returned by earlier `exec`, `query`, or `prefetch` calls.

## updateClient

`coordinator.updateClient(client, query, priority)`

Initiate a *client* update for a given *query* and *priority* (default `Priority.Normal`), and return a Promise that resolves when the query is complete.
The [`client.queryPending()`](./client#querypending) method will be invoked, followed by [`client.queryResult()`](./client#queryresult) or [`client.queryError()`](./client#queryerror) upon completion.

::: warning
This method is used internally, application code should *not* call this method directly.
:::

## requestQuery

`coordinator.requestQuery(client, query)`

Request a query update for the provided *client*.
If the *query* argument is provided, [`updateClient()`](#updateclient) is invoked.
Otherwise, the client [`update()`](./client#update) method is called immediately.

::: warning
This method is used internally, application code should *not* call this method directly.
:::