1# MQL Guide
2
3## General
4
5Cayley's MQL implementation is a work-in-progress clone of [Freebase's MQL API](https://developers.google.com/freebase/mql/). At the moment, it supports very basic queries without some of the extended features. It also aims to be database-agnostic, meaning that the schema inference from Freebase does not (yet) apply.
6
7Every JSON Object can be thought of as a node in the graph, and wrapping an object in a list means there may be several of these, or it may be repeated. A simple query like:
8
9```json
10[{
11  "id": null
12}]
13```
14
15Is equivalent to all nodes in the graph, where "id" is the special keyword for the value of the node.
16
17Predicates are added to the object to specify constraints.
18
19```json
20[{
21  "id": null,
22  "some_predicate": "some value"
23}]
24```
25
26Predicates can take as values objects or lists of objects (subqueries), strings and numbers (literal IDs that must match -- equivalent to the object {"id": "value"}) or null, which indicates that, while the object must have a predicate that matches, the matching values will replace the null. A single null is one such value, an empty list will be filled with all such values, as strings.
27
28## Keywords
29
30* `id`: The value of the node.
31
32## Reverse Predicates
33
34Predicates always assume a forward direction. That is,
35
36```json
37[{
38  "id": "A",
39  "some_predicate": "B"
40}]
41```
42
43will only match if the quad
44```
45A some_predicate B .
46```
47
48exists. In order to reverse the directions, "!predicates" are used. So that:
49
50```json
51[{
52  "id": "A",
53  "!some_predicate": "B"
54}]
55```
56
57will only match if the quad
58```
59B some_predicate A .
60```
61exists.
62
63## Multiple Predicates
64
65JSON does not specify the behavior of objects with the same key. In order to have separate constraints for the same predicate, the prefix "@name:" can be applied to any predicate. This is slightly different from traditional MQL in that fully-qualified http paths may be common predicates, so we have an "@name:" prefix instead.
66
67
68```json
69[{
70  "id": "A",
71  "@x:some_predicate": "B",
72  "@y:some_predicate": "C"
73
74}]
75```
76
77Will only match if *both*
78
79```
80A some_predicate B .
81A some_predicate C .
82```
83
84exist.
85
86This combines with the reversal rule to create paths like ``"@a:!some_predicate"``
87