API Reference

Writing Data

Adding, Setting, Removing Property Values

To add a value to a non-unique property of an existing node, use "connect" : "insert". For example, to add a name in a particular language to a topic, use something like this:

{
  "id":   "/en/united_states",
  "name": {
    "value" : "美国",
    "lang" : "/lang/zh",
    "connect" : "insert"
  }
}

If the property is unique, such as the date of birth property (nobody is born more than once), then use "connect" : "update". Any existing property value is first removed before the new value is set.

If you are unsure whether a property is unique or not, and don't bother to find out, use "connect" : "replace". This option acts like "connect" : "insert" if the property is non-unique and like "connect" : "update" if it is unique.

To remove a property value (unset it), use "connect" : "delete", e.g.,

{
  "id":   "/en/united_states",
  "name": {
    "value" : "美国",
    "lang" : "/lang/zh",
    "connect" : "delete"
  }
}

Connecting and Disconnecting Nodes

Connecting one node to another is much like setting a property value. You can use the same "connect" directive. For example, to say that Barack Obama was born in Honolulu, we can connect the two topics /en/barack_obama and /en/honolulu with the /people/person/place_of_birth property as follows:

{
  "id": "/en/barack_obama",
  "/people/person/place_of_birth" : {
    "id" : "/en/honolulu",
    "connect" : "update"
  }
}

The outer query node identifies the source of the link, and the inner node identifies the target.

To disconnect (remove the link), use "connect" : "delete".

Creating New Nodes

To create a new graph node, possibly a topic of discourse, use "connect" : "unless_exists". For example, in order to create a new node about the film "The Good, The Bad, and The Ugly", run this query:

{
  "create": "unless_exists",
  "name":   "The Good, The Bad, and The Ugly",
  "type":   "/film/film",
  "id":     null,
  "guid":   null
}

To process this query, the MQL query engine first ignores the "create" directive and run the query as if it were a read query (rather than a write query). If the query has any result, then the data of that result ("id" and "guid" in this case) is returned. Otherwise, a new graph node is created, and the constraints of the query ("name" and "type" in this case) are used to initialize the node, and then the missing data ("id" and "guid") is returned. Either way, you'll get an ID and a GUID back.

If you don't want the MQL query engine to check for existing matching result, then use "create" : "unconditional". Use this option with care, as it can create several graph nodes for the same concept that later need to be merged together. The most common use for "create" : "unconditional" is for creating CVTs and mediator nodes, which we will discuss subsequently.

Creating and Then Connecting

Sometimes you want to create a new node and connect it to an existing node in one shot. For example, we can create a topic for Malia Ann Obama, if such a topic doesn't yet exist, and connect that topic to Barack Obama's topic in one query:

{
  "id": "/en/barack_obama",
  "/people/person/children": {
    "name": "Malia Ann Obama",
    "type": "/people/person",
    "create": "unless_exists"
  }
}

Note that we only use "create". There is no need to use "connect" because the outer query node already specifies to the MQL query engine the connection we want to make between the two topics.

Sometimes, the topic to create is very unique to the other topic. For example, if there were already someone named "Malia Ann Obama", then

  • either she is the "Malia Ann Obama" daughter of Barack Obama, and their topics are already connected,
  • or she is another person named "Malia Ann Obama" and their topics are not connected.

In such case, you should use "create" : "unless_connected" instead:

{
  "id": "/en/barack_obama",
  "/people/person/children": {
    "name": "Malia Ann Obama",
    "type": "/people/person",
    "create": "unless_connected"
  }
}

This option checks not just for a topic with name "Malia Ann Obama" and typed /people/person, but it also checks that that topic is already connected to /en/barack_obama. Even if there is already a topic named "Malia Ann Obama" and typed /people/person, if that topic is not already connected to /en/barack_obama, a new node still gets created.

Creating Compound Value Type (CVT) and Mediator Nodes

CVT and mediator nodes can be created and connected like regular nodes. Here is a query that creating a /film/performance mediator node and connect it to the film, the actor, and the character; it also creates a new character node if that hasn't existed yet:

{
  "id": "/en/the_dark_knight",
  "/film/film/starring": {
    "create": "unconditional",
    "type": "/film/performance",
    "actor": {
      "id": "/en/heath_ledger",
      "connect": "insert"
    },
    "character": {
      "name": "The Joker",
      "type": "/film/film_character",
      "create": "unless_connected"
    }
  }
}

Developer Tools: