Run FQL Queries

Topics
- Facebook SDK for iOS
Authentication
Data Access
- Fetch User Data
- Run FQL Queries
Sharing & Distribution
Customization
Optimization

FQL, the Facebook Query Language, allows you to use a SQL-style interface to query data exposed by the Graph API. It provides advanced features not available in the Graph API, including batching multiple queries into a single call.

A Graph API call using FQL with HTTP takes the form:

GET /fql?q=<QUERY>

The Facebook SDK for iOS provides methods to make FQL calls. The FBRequestConnection class has a convenience class method: startWithGraphPath:parameters:HTTPMethod:completionHandler: that you can use to make an FQL call with the Graph API. Make use of this method by passing fql as the Graph path parameter and setting q with your FQL query.

This document covers the following topics:

Prerequisites
Sample Overview
Step 1: Add FQL to Fetch Friend Info
Step 2: Add the Friend Display
Troubleshooting

Prerequisites

The code for the starting point for this doc can be found on GitHub. If you haven't done so, clone the how-to samples for the Facebook SDK:

git clone https://github.com/fbsamples/ios-3.5-howtos.git

Then open the Xcode project under the FQLHowTo/Initial folder.

Sample Overview

The completed sample allows users to log in with Facebook and run a query to show a limited set of friends.

After the person logs in, two buttons are shown. One button runs a query that includes a subquery. The second button gets essentially the same information but splits the call up into a multi-query. This shows how you can take data from one query and use it in the second. The completed app allows users to see the same information from the query and multi-query call:

For your reference, the completed sample is also available on GitHub.

Overview of initial code

The initial Xcode project has Facebook Login implemented. It includes all the user interface components you'll need to set up the sample. What's missing is Facebook functionality that you'll add to implement your queries.

The main classes and nib files used in the projects are:

AppDelegate.m: Includes supporting code for Facebook Login implementation.
ViewController.m: Includes FBLoginViewDelegate protocol methods to handle Facebook Login callbacks from the FBLoginView that's instantiated in ViewController.xib. The query buttons are attached to outlets in this class, and the buttons are made visible or hidden depending on whether the user is logged in or logged out. The class initially contains empty methods for each query button's action.
ViewController.xib: Contains an FBLoginView object with the delegate set to the ViewController implementation class. The nib also contains two buttons used to initiate the queries.

Step 1: Add FQL to Fetch Friend Info

In this step, you'll link up the buttons you set up to make the query calls. When you've completed this step you'll know how to make FQL API calls using query and multi-query. In this step, the data you retrieve will simply log to the Xcode console.

The query you're using gets the user's friends, limits results to 25, and returns the id, name and profile picture info:

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

Step 1a: Query

Implement the queryButtonAction: method to make the query FQL call:

- (IBAction)queryButtonAction:(id)sender {
    // Query to fetch the active user's friends, limit to 25.
    NSString *query =
    @"SELECT uid, name, pic_square FROM user WHERE uid IN "
    @"(SELECT uid2 FROM friend WHERE uid1 = me() LIMIT 25)";
    // Set up the query parameter
    NSDictionary *queryParam = @{ @"q": query };
    // Make the API request that uses FQL
    [FBRequestConnection startWithGraphPath:@"/fql"
                                 parameters:queryParam
                                 HTTPMethod:@"GET"
                          completionHandler:^(FBRequestConnection *connection,
                                              id result,
                                              NSError *error) {
        if (error) {
            NSLog(@"Error: %@", [error localizedDescription]);
        } else {
            NSLog(@"Result: %@", result);
        }
    }];
}

Build and run the project to make sure it runs without errors. Tap the ''Login'' button to log in with Facebook. Once you're authenticated, you should see the ''Query'' and ''Multi-query'' buttons. Tap ''Query'' and view the results in the Xcode console.

Step 1b: Multi-query

Implement the multiQueryButtonAction: method to make the multi-query FQL call:

- (IBAction)multiQueryButtonAction:(id)sender {
    // Multi-query to fetch the active user's friends, limit to 25.
    // The initial query is stored in reference named "friends".
    // The second query picks up the "uid2" info from the first
    // query and gets the friend details.
    NSString *query =
    @"{"
    @"'friends':'SELECT uid2 FROM friend WHERE uid1 = me() LIMIT 25',"
    @"'friendinfo':'SELECT uid, name, pic_square FROM user WHERE uid IN (SELECT uid2 FROM #friends)',"
    @"}";
    // Set up the query parameter
    NSDictionary *queryParam = @{ @"q": query };
    // Make the API request that uses FQL
    [FBRequestConnection startWithGraphPath:@"/fql"
                                 parameters:queryParam
                                 HTTPMethod:@"GET"
                          completionHandler:^(FBRequestConnection *connection,
                                              id result,
                                              NSError *error) {
                              if (error) {
                                  NSLog(@"Error: %@", [error localizedDescription]);
                              } else {
                                  NSLog(@"Result: %@", result);
                              }
                          }];
}

Build and run the project to make sure it runs without errors. Once you're authenticated, tap ''Multi-query'' and view the results in the Xcode console. Notice that there are two sets of results: one for the user's friends and one for friend details.

Step 2: Add the Friend Display

In this step, you'll display the friend details when the user taps either the query or multi-query button. Both the query and multi-query buttons will yield the same results visually. So even though you get two results back in the multi-query call, you'll only pull out the friend details. The friend details will be displayed in the table view of a new view controller you'll add. You'll add a new UITableViewController that the FriendViewController class presents modally. This new view controller will also contain a done button to dismiss the friend results view.

Let's assume the friend data looks like this:

{
    name = "Zoran Martinovic";
    "pic_square" = "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-snc4/372099_15150_128454473_q.jpg";
    uid = 15150;
},
    {
    name = "Nick Grudin";
    "pic_square" = "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-ash2/369387_19094_361608391_q.jpg";
    uid = 19094;
},

You'll configure your UITableViewController to handle this input data format.

First, add a view controller for the friend details display, by adding a new file to the project. Select the Objective-C class template, name the class FriendViewController, make it a subclass of UITableViewController and deselect the ''With XIB for user interface'' option:

Open the FriendViewController header file. Then, add a public property to hold the incoming friend data from the main view controller:

@property (strong, nonatomic) NSArray *data;

Open the FriendViewController and implement the UITableView datasource methods to handle the friend data. First, set it up for a single section:

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView
{
    // Return the number of sections.
    return 1;
}

Then, set the number of rows to correspond to the number of incoming friends:

- (NSInteger)tableView:(UITableView *)tableView 
numberOfRowsInSection:(NSInteger)section
{
    // Return the number of rows in the section.
    return [self.data count];
}

Next, set up each row to show the friend's name and profile picture:

- (UITableViewCell *)tableView:(UITableView *)tableView 
cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    static NSString *CellIdentifier = @"Cell";
    UITableViewCell *cell = 
        [tableView dequeueReusableCellWithIdentifier:CellIdentifier];

    if (cell == nil) {
        cell = [[UITableViewCell alloc] 
            initWithStyle:UITableViewCellStyleDefault 
          reuseIdentifier:CellIdentifier];
    }
    cell.textLabel.text = self.data[indexPath.row][@"name"];
    UIImage *image = [UIImage imageWithData:
                      [NSData dataWithContentsOfURL:
                       [NSURL URLWithString:
                        self.data[indexPath.row][@"pic_square"]]]];
    cell.imageView.image = image;

    return cell;
}

Now that you've configured the data display, you'll add a way for users to dismiss the friend display. You can do this using a UIToolbar with a done button that closes the friend display. You'll add the toolbar as a header view in your UITableView instance.

Add a private property for the UIToolbar instance:

@property (strong, nonatomic) UIToolbar *toolbar;

Next, in the viewDidLoad method, create the toolbar at the end of the method:

// Add a toolbar to hold a Done button that will dismiss this view controller
self.toolbar = [[UIToolbar alloc] init];
self.toolbar.barStyle = UIBarStyleDefault;
[self.toolbar setAutoresizingMask:UIViewAutoresizingFlexibleWidth];
[self.toolbar sizeToFit];

UIBarButtonItem *doneButton = [[UIBarButtonItem alloc]
                               initWithBarButtonSystemItem:UIBarButtonSystemItemDone
                               target:self
                               action:@selector(doneButtonPressed:)];

UIBarButtonItem *space = [[UIBarButtonItem alloc]
                          initWithBarButtonSystemItem:UIBarButtonSystemItemFlexibleSpace
                          target:nil
                          action:nil];

self.toolbar.items = [NSArray arrayWithObjects:space, doneButton, nil];

Next, implement the UITableView delegate methods to add the toolbar to the section's view and set the corresponding section's height:

- (UIView *)tableView:(UITableView *)tableView viewForHeaderInSection:(NSInteger)section
{
    return self.toolbar;
}

- (CGFloat)tableView:(UITableView *)tableView heightForHeaderInSection:(NSInteger)section
{
    return self.toolbar.frame.size.height;
}

Then, create a new method called doneButtonPressed: that is invoked when the user presses the done button. This method dismisses the friend display:

- (void)doneButtonPressed:(id)sender
{
    // Dismiss view controller
    [[self presentingViewController] dismissModalViewControllerAnimated:YES];
}

That's all you need to set up the friend display. Now you're ready to link this view to the main view controller. Open the main view controller implementation file and add logic to invoke the friend view controller.

First, import the friend view controller so you can instantiate and present it:

#import "FriendViewController.h"

Next, add a new private helper method that takes the data the friend view controller expects. This method instantiates the friend view controller, sets the friend data and then presents it modally:

- (void) showFriends:(NSArray *)friendData
{
    // Set up the view controller that will show friend information
    FriendViewController *viewController =
    [[FriendViewController alloc] initWithStyle:UITableViewStylePlain];
    viewController.data = friendData;
    // Present view controller modally.
    [self presentViewController:viewController animated:YES completion:nil];
}

Now, modify the queryButtonAction: method to call the newly defined showFriends: method with the correct data. Add the following code after the NSLog statement that logs the FQL result:

NSArray *friendInfo = (NSArray *) result[@"data"];
[self showFriends:friendInfo];

Finally, modify the multiQueryButtonAction: method to also call the showFriends: method with the correct data. Add the following code after the NSLog statement that logs the FQL result:

NSArray *friendInfo =
    (NSArray *) result[@"data"][1][@"fql_result_set"];
[self showFriends:friendInfo];

Build and run the project to make sure it runs without errors. Once you're authenticated, tap ''Query'' and verify that you see your friends' names and profile pictures. Tap the done button to dismiss the friend details display. Tap ''Multi-query'' and verify the results are the same.

Troubleshooting

The Graph API Explorer has an FQL tab that you can use to debug your FQL queries.

This is super helpful if you have any problems with your queries.

Updated 15 hours ago

Topics

Authentication

Data Access

Sharing & Distribution

Customization

Optimization