Views

What are Views?

With views you can...

• Filter the documents in your database to find those relevant for a specific purpose.
• Extract data from your documents and present it in a specific order.
• Build indexes to find documents by any value or structure that resides in them.
• Make all sorts of calculations on the data in your documents.

This is loosely inspired by CouchDB and MapReduce, but this is not a "real" MapReduce implementation - we're not talking about "Big Data" here.

Create Views

Views are created by publishing a JSON object containing a map function body, an optional reduce function body and an optional MQTT wildcard filter to the $db/query/<view-id> topic. The map and reduce functions can be any valid Javascript code, if you want to add something to the view you have to call the emit() function. In the map function this refers to the document, the function is then executed once per document to compose the view. After the map function was applied to all documents the optional reduce function is called and can work on the result. The reduce function gets the result array of the map execution in the variable result and has to use the return statement.

See Detailed View Examples.

Beside the possibility to select documents with a map script you can also use the property filter to pre-filter documents through a MQTT wildcard match on their id. Example payload for a view that includes only documents with ids starting with hue/lights: {"filter": "hue/lights/#", "map": "return this._id"}

Get a View

By default all views are published with retain flag set to true, so you just have to subscribe to $db/view/<view-id> and you will receive the view.

If you set the --retain-disable command line option the views are not published retained, so just subscribing to their topic will deliver you the view only if it changes - but not immediately after subscribing to it. To trigger a publication of a specific view you can then publish to $db/get/view/<view-id>.

Javascript

The map and reduce scripts are executed in a sandbox, so you don't have access to Node.js globals like e.g. require, process or console. Apart from that you can use all Javascript features that Node.js provides.

Besides the emit() function the sandbox also provides an api object containing a few functions that can also be used by the map and reduce scripts. See the Sandbox Documentation.

The documents in the workers are frozen, so no change on the database contents is possible by the map and reduce scripts.

Delete Views

You can delete a view by publishing an empty string on $db/query/<view-id>.

How Views are Composed

On every change in the database all views are re-composed and mqttDB will publish the updated views.

The views are composed in separate worker processes, mqttDB will by default spawn as many workers as CPU cores are available.

You can adjust a compromise between memory usage and view composing performance by setting a lower/higher number of worker processes. More workers: faster view composition, less workers: lower memory consumption. See a few words about mqttDB Performance also.

---

Proceed to View Examples.