[Developers] MQL Lite (was newbie: simple question)

[Tom Morris]

On Thu, Feb 26, 2009 at 3:49 PM, R. Pito Salas <rps at salas.com> wrote:

> It could be that my confusion came from not knowing the basics of types,
> properties, and all the other core ideas.

If you don't understand object type systems in general and Freebase's
object type system (aka schema) in particular, you're going to have a
hard time, so that's the first place to start.  But if you know SQL,
you can think of the type as the table that you're going to query and
the property names as its columns.  Domains (the /location in
/location/country) are just ways to group types together.

> Another thing that often is very thoughtful collection of specific,
> annotated examples designed to teach MQL.
> Take your example:
>
> {"capital":null, "type":"/location/country", "name":"Peru"}
>
> Can you tease that apart? What's with the 'null? What's with the "type":"
> "/location/country"? So annotating the examples are also a good pedagogical
> tool.

The main thing to understand about MQL is that it's a query-by-example
language.  Basically you give it an object template with the
information that you know and empty spots for the things that you'd
like filled in.  Another stumbling block could be the object syntax
since its a common structure for Python and Javascript, but relatively
unknown in some other languages.  Think of the colon-separated pairs
as key:value pairs.

So, the annotated query is - find all objects which match the template:

  {"name" : "Peru",                     # with the name 'peru' (case
insensitive)
    "type"  : "/location/country",   # which are countries (i.e. not
that hot new bar called "Peru")
    "capital" : null,                        # fill in this slot with
the capital
    }

If I want to know more things, I just added their property names with
empty placeholders.  If they're not unique (ie might return multiple
values), my placeholder needs to be an empty list instead of just a
null value.  Here's the same query with some additional properties:

  {
    "capital" : null,
    "iso_alpha_3" : null,        # give me the three letter ISO country code
    "languages_spoken" : [], # and a list of the languages spoken
    "name" : "Peru",
    "official_language" : [],    # as well as a list of the official languages
    "type" : "/location/country"
  }

Note that although the property name is 'official_language,' singular,
it can return multiple values.  The only way to really know is to
examine the schema for the type that you are interested in
(/location/country in this case).

Try these queries out by pressing F8 on any freebase.com web page,
scrolling down to the bottom, clicking "Query Editor" (yes, it's well
hidden) and then pasting the query in and pressing "Read>>>".
Alternatively, just follow this link
http://www.freebase.com/tools/queryeditor?q=[{"capital":null,"iso_alpha_3":null,"languages_spoken":[],"name":"Peru","official_language":[],"type":"/location/country"}]&read=1

You should see the following results

  {
    "capital" : "Lima",
    "iso_alpha_3" : "PER",
    "languages_spoken" : [
      "Spanish",
      "Omagua language"
    ],
    "name" : "Peru",
    "official_language" : [
      "Aymara language",
      "Quechua",
      "Spanish"
    ],
    "type" : "/location/country"
  }

If I wanted to do more with the languages than just display their
names, I could ask for their ids and then use those to do additional
queries.  For example, I could find other countries where Omagua is
spoken or find out what other languages it's related to.

Start with some simple queries and play around a little bit.  It won't
take that long to get oriented and figure out what's what.  As you
need to do more advanced things, make frequent reference to the MQL
Cookbook that Shawn mentioned.  There are a number of things that are
non-obvious about more advanced queries that are covered in the
Cookbook (e.g. the use of "optional" : "forbidden" to tag things for
exclusion).

Tom

p.s. One of my favorite things for exploring is type schemas is "*" :
[{}]  Add this to any query to see all the property values of the
results dumped as objects, so you can see what types they are, what
properties they contain, etc.