Documents

Ids

The id of a document can be any string, slashes are allowed - only the mqtt wildcards # and + may not occur in the id. As the intended use of mqttDB is to manage metadata that belongs to MQTT topics I suggest to just use the topic that is described by the document as id.

Create or overwrite a document

To create or overwrite a document with the id hue/light/livingroom you have to publish on the topic $db/set/hue/light/livingroom. The payload has to be a JSON object, e.g. {"type": "light", "name": "hue light livingroom"}. As soon as the document was created the document itself is published retained on the topic $db/doc/hue/lights/livingroom.

Get a document

By default all documents are published with retain flag set to true, so you just have to subscribe to e.g. $db/doc/hue/lights/livingroom and you will receive the document.

If you set the --retain-disable command line option the documents are not published retained, so just subscribing to their topic will deliver you the document only if it changes - but not immediately after subscribing to it. To trigger a publication of the document you can then publish to e.g. $db/get/doc/hue/lights/livingroom.

Extend a document

By publishing to $db/extend/<document-id> the payload gets merged with the content of an existing document. Example: doc1 is {"type":"foo", "name": "bar"}. After publishing {"name": "moo", "bla": "blubb"} on $db/extend/doc1 it will have the content {"type":"foo", "name": "moo", "bla": "blubb"}.

Deletion of documents

To delete the document from the previous example just publish an empty string payload on $db/set/hue/lights/livingroom.

Property Access

Via the topic $db/prop/<document-id> you have the possibility to set, create or delete particular properties of a document. The payload has to be a JSON object with the attributes method, prop, and val.

Examples Payloads:

• {"method":"set", "prop": "name", "val": "new name!"}
• {"method":"create", "prop": "name", "val": "start name!"}
  In contrast to the set method create won't overwrite existing properties.
• {"method":"del", "prop": "name"}

Property dot notation

You can use dot notation for prop to access nested properties. Dots in the property name and the backslash have to be escaped by backslash. Example:

{
  "prop1": {
    "nested-prop": 1
  },
  "prop.with.dots.in.name": 2
}

• To access nested-prop use prop: "prop1.nested-prop".
• To access prop.with.dots.in.name use prop: "prop\.with\.dots\.in\.name".

Internal properties

These properties are set on all documents by mqttDB, they can't be changed or deleted.

_id

The documents id.

_rev

The documents revision. Just a counter that gets incremented on every change of the document.

---

Proceed to Views.