Appearance

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. The coordinator also manages filter groups: collections of clients that share the same 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()

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.
  • 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 used by the coordinator to issue queries to a backing data source.

connect ​

coordinator.connect(client)

Connect a client to this coordinator. Upon connection, the client lifecycle 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 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(), 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 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() method will be invoked, followed by client.queryResult() or 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() is invoked. Otherwise, the client update() method is called immediately.

WARNING

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