Facebook Query Language (FQL) Overview

Facebook Query Language, or FQL, enables you to use a SQL-style interface to query the data exposed by the Graph API. It provides advanced features not available in the Graph API.

For detailed FQL Table information, check out the FQL Reference.

Example

Runs the query "SELECT uid2 FROM friend WHERE uid1=me()"

GET /fql?q=SELECT+uid2+FROM+friend+WHERE+uid1=me()&access_token=...

Read

You can issue a HTTP GET request to /fql?q=query where query can be a single fql query or a JSON-encoded dictionary of queries.

Query

Queries are of the form SELECT [fields] FROM [table] WHERE [conditions]. Unlike SQL, the FQL FROM clause can contain only a single table. You can use the IN keyword in SELECT or WHERE clauses to do subqueries, but the subqueries cannot reference variables in the outer query's scope. Your query must also be indexable, meaning that it queries properties that are marked as indexable in the documentation below.

FQL can handle simple math, basic boolean operators, AND or NOT logical operators, and ORDER BY and LIMIT clauses. ORDER BY can contain only a single table.

For any query that takes a uid, you can pass me() to return the logged-in user. For example:

SELECT name FROM user WHERE uid = me() 

Other functions that are available are now(), strlen(), substr() and strpos().

Here's an example of a subquery that fetches all user information for the active user and friends:

SELECT uid, name, pic_square FROM user WHERE uid = me()
OR uid IN (SELECT uid2 FROM friend WHERE uid1 = me())

Multi-query

Evaluates a series of FQL (Facebook Query Language) queries in one call and returns the data at one time.

This method takes a JSON-encoded dictionary called ''queries'' where the individual queries use the exact same syntax as a simple query. However, this method allows for more complex queries to be made. You can fetch data from one query and use it in another query within the same call. The WHERE clause is optional in the latter query, since it references data that’s already been fetched. To reference the results of one query in another query within the same call, specify its name in the FROM clause, preceded by #.

For example, say you want to get some data about a user attending an event. Normally, you’d have to perform two queries in a row, waiting for the results of the first query before running the second query, since the second query depends on data from the first one. But with fql.multiquery, you can run them at the same time, and get all the results you need, giving you better performance than running a series of fql.query calls. First, you need to get the user ID and RSVP status of each attendee, so you’d formulate the first query – query1 – like this:

"query1":"SELECT uid, rsvp_status FROM event_member WHERE eid=12345678"

Then to get each attendee’s profile data (name, URL, and picture in this instance), you’d make a second query – query2 – which references the results from query1. You formulate query2 like this:

"query2":"SELECT name, url, pic FROM profile WHERE id IN (SELECT uid FROM #query1)"

Sample

Here's a sample for running fql query

<?php
  $app_id = 'YOUR_APP_ID';
  $app_secret = 'YOUR_APP_SECRET';
  $my_url = 'POST_AUTH_URL';

  $code = $_REQUEST["code"];

 // auth user
 if(empty($code)) {
    $dialog_url = 'https://www.facebook.com/dialog/oauth?client_id=' 
    . $app_id . '&redirect_uri=' . urlencode($my_url) ;
    echo("<script>top.location.href='" . $dialog_url . "'</script>");
  }

  // get user access_token
  $token_url = 'https://graph.facebook.com/oauth/access_token?client_id='
    . $app_id . '&redirect_uri=' . urlencode($my_url) 
    . '&client_secret=' . $app_secret 
    . '&code=' . $code;

  // response is of the format "access_token=AAAC..."
  $access_token = substr(file_get_contents($token_url), 13);

  // run fql query
  $fql_query_url = 'https://graph.facebook.com/'
    . 'fql?q=SELECT+uid2+FROM+friend+WHERE+uid1=me()'
    . '&access_token=' . $access_token;
  $fql_query_result = file_get_contents($fql_query_url);
  $fql_query_obj = json_decode($fql_query_result, true);

  // display results of fql query
  echo '<pre>';
  print_r("query results:");
  print_r($fql_query_obj);
  echo '</pre>';

  // run fql multiquery
  $fql_multiquery_url = 'https://graph.facebook.com/'
    . 'fql?q={"all+friends":"SELECT+uid2+FROM+friend+WHERE+uid1=me()",'
    . '"my+name":"SELECT+name+FROM+user+WHERE+uid=me()"}'
    . '&access_token=' . $access_token;
  $fql_multiquery_result = file_get_contents($fql_multiquery_url);
  $fql_multiquery_obj = json_decode($fql_multiquery_result, true);

  // display results of fql multiquery
  echo '<pre>';
  print_r("multi query results:");
  print_r($fql_multiquery_obj);
  echo '</pre>';
?>