MQL tutorial: simple read queries

Author: Skud

1 Oct

MQL, the Metaweb Query Language, is what we use to talk to any Metaweb database such as Freebase. It’s the guts of any Metaweb API, such as mjt or my own Metaweb CPAN module for Perl, but you can also use it standalone in the Query Editor.

I want to run a series of tutorials on MQL, taking a cookbook approach. Essentially, as I learn stuff, I’ll post it here in tutorial form.

Today’s topic: a simple “read” query

First step, open up the Query Editor in your browser. The empty box on the left is where you type your MQL. Then you click “Read” and the response will show up on the right.

Here’s a simple query to cut and paste:

{
  "query":[{
    "type":"/people/person",
    "name":null
   }]
}

This query is asking for a list of all objects of type “/people/person”, and saying that we want to know their names. The overall format of the query uses the JavaScript Object Notation, or JSON. For the most part, the format consists of name/value pairs, and some syntax for grouping lists of those pairs together.

Let’s take our example and break it down further.

“query”:[{ ... }]

All MQL queries need this wrapper around them, to group the query parameters together.

(If you’re using an API rather than the Query Editor, you may also need another envelope around this; see the API docs for details.)

“type”:”/people/person”

Here we limit our search results by the type of object we’re interested in. The type is expressed in the form “domain/type”, which is how the system refers to types under the hood. If you’re not sure of the underlying system name for a type, you can find it by browsing the Data page and getting to the type you want, then looking at the URL. The last two segments of the URL will be the domain and type, eg. “http://www.freebase.com/view/filter/people/person”

“name”:null

This says, “We want to know the name, but we don’t have any particular constraints on it.” So the results we get will list all the names of every object returned.

Now you can click the “read >>” button and see the results. It should look something like this:

  "code":"/api/status/ok",
  "result":[{
    "name":"Jack Abramoff",
    "type":"/people/person"
  },{
    "name":"Bob Ney",
    "type":"/people/person"
  },{
    "name":"David Safavian",
    "type":"/people/person"
  },{
    "name":"Kåre Kristiansen",
    "type":"/people/person"
  },

… and so on. You can click on different views, eg. “Tree View”, “JSON View”, etc. The one I’ve pasted is the JSON view.

Try this

So that’s the most basic form of query. Now you can try some queries of your own:

Try searching other types, eg. “location/location” or “internet/website”.
Try adding adding the “id” field to your query: "id":null
Try limiting the output: "limit":10
Try sorting the output: "sort":"name"

What I’ve covered in this tutorial corresponds roughly to the most basic parts of section 3 of the API docs. If you want to read more, that’s where to do it.