<div><p> Your First Query
================

To access the wealth of data in Freebase, you need to query Freebase much like you would query a conventional database. There are a few differences though:

* You typically query a conventional database using SQL, but you query Freebase using _MQL_, which stands for Metaweb Query Language and we pronounce "mickle".
* You typically process results from a SQL query through ODBC, JDBC, or some other database access layer, but results from a MQL query comes to you as [JSON](http://www.json.org/) and the intermediate access layer is HTTP.
* You typically query a conventional database only in the back-end of your web application, but you can query Freebase from both the back-end and the front-end (or even solely from the front-end!) of your web application.

Don't worry if these differences don't make a lot of sense. You'll soon understand them as you start to query Freebase more often for your own use.

However, if you don't know JSON, then you should definitely [learn about it here](http://www.json.org/) before continuing.


Conceptualizing How the Data is Stored
--------------------------------------

Before we dive into using MQL to query Freebase, let's first start with a conceptual understanding of how the data is stored. Consider the topic about New York City. Freebase.com provides 2 ways to view this topic:

* [the concise, beautified, read-only way](http://www.freebase.com/view/en/new_york), intended for the general public
* [the verbose editable way](http://www.freebase.com/edit/topic/en/new_york), intended for data enthusiasts who care to edit the data

Of course, there are other ways to show the same data, less pretty and more "raw", like so:

</p><table><tr><th>Property</th>
    <th>Value(s)</th>
  </tr><tr><td>id</td>
    <td>/en/new_york</td>
  </tr><tr><td>guid</td>
    <td>#9202a8c04000641f80000000002f8906</td>
  </tr><tr><td>name</td>
     <td>New York City</td>
  </tr><tr><td>/location/location/containedby</td>
    <td>
      <ul><li>New York</li>
        <li>United States</li>
      </ul></td>
  </tr><tr><td>/location/place_with_neighborhoods/neighborhoods</td>
    <td>
      <ul><li>Silver Beach</li>
        <li>Tudor City</li>
        <li>Times Square</li>
        <li>etc.</li>
      </ul></td>
  </tr><tr><td colspan="2">A lot more properties are omitted for brevity.</td>
  </tr></table>


Going one step further in the "raw" direction, we can present the same data in JSON, like so
  
&gt;     {
&gt;       "id" : "/en/new_york",
&gt;       "guid" : "#9202a8c04000641f80000000002f8906",
&gt;       "name" : "New York City",
&gt;       "/location/location/containedby" : [
&gt;         "New York",
&gt;         "United States"
&gt;       ],
&gt;       "/location/place_with_neighborhoods/neighborhoods" : [
&gt;         "Silver Beach",
&gt;         "Tudor City",
&gt;         "Times Square"
&gt;       ]
&gt;     }

This JSON representation can help you conceptualize how the data is stored in Freebase, although it isn't really stored as JSON.


Filling in The Blanks
---------------------

The JSON representation above also serves to explain the query language MQL. Say you have found out the ID of the New York City topic to be `/en/new_york` and you wish to find the topic's GUID, name, what geographic regions contain it, and its neighborhoods. Then you need to write the same JSON as above, except that you leave blanks for the data that you don't know and wish to retrieve:

&gt;     {
&gt;       "id": "/en/new_york",
&gt;       "guid": null,
&gt;       "name": null,
&gt;       "/location/location/containedby": [],
&gt;       "/location/place_with_neighborhoods/neighborhoods": []
&gt;     }
  
`null`s and empty arrays `[]` both serve as blanks to be filled in. A `null` stands for a single value, and an empty array `[]` stands for a list of values. What you have written is a valid MQL query. When you dispatch this query to Freebase, Freebase fills in the blanks and returns the resulting JSON back to you:

&gt;     {
&gt;       "id": "/en/new_york",
&gt;       "guid": "#9202a8c04000641f80000000002f8906",
&gt;       "name": "New York City",
&gt;       "/location/location/containedby": [
&gt;         "New York",
&gt;         "United States"
&gt;       ],
&gt;       "/location/place_with_neighborhoods/neighborhoods": [
&gt;         "Arrochar",
&gt;         "Annadale",
&gt;         "Arden Heights",
&gt;         ...
&gt;       ]
&gt;     }
  
Putting the query and its result side-by-side illustrates the fill-in-the-blank concept:
  
<table><tr><th>Query</th>
    <th>Result</th>
  </tr><tr><td>
<pre>{
  "id": "/en/new_york",
  "guid": null,
  "name": null,
  "/location/location/containedby": [
  
  
  ],
  "/location/place_with_neighborhoods/neighborhoods": [
  
  
  
  
  ]
}</pre>
    </td>
    <td>
<pre>{
  "id": "/en/new_york",
  "guid": "#9202a8c04000641f80000000002f8906",
  "name": "New York City",
  "/location/location/containedby": [
    "New York",
    "United States"
  ],
  "/location/place_with_neighborhoods/neighborhoods": [
    "Arrochar",
    "Annadale",
    "Arden Heights",
    ...
  ]
}</pre>    
    </td>
  </tr></table>

&gt; Try it out yourself:
&gt; 
&gt; * Copy and paste the query above into [the Query Editor](http://www.freebase.com/app/queryeditor) or simply [click on this permanent link](http://tinyurl.com/kqrylf)
&gt; * Click the Run button in the Query Editor and look over the results in the output pane on the right. Note that the Query Editor displays the query result wrapped inside another Javascript object literal that contains meta information such as the success/error code of the query execution.

The key point is this:
  
&gt; A MQL query is expressed in JSON, and the results to a MQL query is also expressed in JSON. Conceptually, Freebase processes the query by taking the query JSON and filling in the blanks in order to produce the result JSON.

In the next section of this Getting Started guide, we'll walk you through all the steps of formulating a query as well as explain more MQL concepts.

 </div>