Tomás Lin’s Programming Brain Dump

FQL is the query language used in Facebook to access tables and relationships. All the top level calls available within facebook APIs ( such as getFriends() ) are simply wrappers around FQL calls. In this post, I will show you how to use the newly released Adobe Flex / Facebook API to invoke FQL commands.

Intro to FQL

After working with the Facebook API for a while, you’ll become slightly frustrated by the number of calls you need to make in order to get detailed information found across different tables.

Let’s say your requirement is: “Get all the names, sex and profile pictures of the user’s friends”.

Using API objects, you would need to first call a getFriends() command to get all the friends of the user. Then you would have to call getUserInfo() to get the details for each user.

Wouldn’t it be nice if you could just call a magic function that will do all this processing on the server and just return the data that you need?

Fortunately, the Facebook API has a very powerful query language called FQL. FQL allows you to get the data your application needs in one call, and makes your code much simpler.

Instead of the above, I could call the following command:

    SELECT name, sex, pic_square FROM user
    WHERE uid IN ( SELECT uid2 FROM friend WHERE uid1= loggedInUser )

Which will return exactly the fields I need.

Using FQL with the Facebook API

I’ve included a complete example of a FQL shell here: http://tomaslin.googlepages.com/callFql.mxml

You would simply need to replace the “xxx” in the API Key and secret with one from your facebook application.

Here are the juicy bits:

private function invokeFQL( query : String, callback : Function ) : void {
    var call : FacebookCall = fbook.post( new FqlQuery( query ) );
    call.addEventListener(FacebookEvent.COMPLETE, callback );
}

To call FQL, you simply need to create a FqlQuery() object with the query that you need and add a callback. My invokeFQL function passes a callback function, so I can reuse this function like so:

invokeFQL( selectFriendsQuery, selectFriendsCallback )
invokeFQL( selectAlbumsQuery, selectAlbumsCallback )

The callback function looks something like this:

   private function fqlCallBack( e : FacebookEvent ) : void {
      if( !e.success ){
         Alert.show( "Error: " + e.error.reason );
     } else {
        result.text = e.data.rawResult;
     }
   }

This is just like your HTTPService response function. However, since your data does not conform to a standard GetFriendsData object, I recommend just keeping these as XML and use the e4x functionality available in Flex to handle these requests.

Here is an example of a more elaborate callback function would look like

   [Bindable] private var profilePictures : XMLListCollection;
   [Bindable] private var friends : XMLListCollection;    

   private function fqlCallBack( e : FacebookEvent ) : void {
       if( !e.success ){
         Alert.show( "Error: " + e.error.reason );
      } else {
        var results : XML = new XML( e.data.rawResult );
        // extract profile pictures
	namespace fb = "http://api.facebook.com/1.0/";
 	use namespace fb;
        profilePictures = new XMLListCollection( results..pic_square );        // extract users
        friends = new XMLListCollection( results..user );
     }
  }

You would then bind these items to as your dataproviders like so:

     <mx:List id="myphotos" dataProvider="{profilePictures}" itemRenderer="PhotoRenderer"/>

To access individual nodes, you would either call the child element directly, like user.name, or use the dataField or labelFunction functionalities within Flex components to retrieve this data. See Adobe’s Using XML data tutorials for more info.

Tips on Learning and Using FQL

• The Facebook Developer Tools include a console for you to test your FQL commands. Go http://developers.facebook.com/tools.php?api and select fql.query as your method.
• The FQL equivalent of each API call is outlined in the API documentation of each call. For example, friends.get’s FQL call is SELECT uid2 FROM friend WHERE uid1=loggedInUid . Instead of trying to come up with these commands from scratch, build from existing calls and optimize.
• Don’t skim on the documentation. FQL is very well detailed on the Facebook site, I always go back to both the tables reference and the API calls reference to construct the API calls
• Again E4X, the XML format available to Flex applications is perfect for these types of unstructured data.

Happy hacking. Remember to visit Empora.com – Search Your Style.