My article "Use Facebook Connect to Bring Your Application to Millions of Users" described how you can connect your web application with Facebook through the Facebook Connect API. Then, in "Publish Your Application Stories to Facebook," I explained how you can easily post messages to Facebook newsfeeds and users' walls. Today we'll focus on simple data mining[md]what can you learn about your user and her friends once the user has authenticated your application.
Facebook provides a rich set of API calls that you can use (the Facebook Connect category in the Facebook wiki has more than 100 articles). These API calls provide a variety of functions, including functions that you need in order to find your user's friends, her groups, her friend lists, the links she has published, and numerous other details.
Fortunately, you don't have to study all these API calls. All the information you might need can be retrieved from Facebook by using Facebook Query Language (FQL). Its grammar is pretty close to the MySQL grammar, so you should be able to use FQL almost immediately if you're familiar with any SQL dialect.
Before jumping into sample FQL queries, let's review a few FQL limitations:
- The only data-manipulation clause implemented in FQL is the SELECT clause. Inserts and updates are not supported; you have to use API calls if you want to modify Facebook data structures.
- FQL doesn't support table joins. You could use a WHERE field IN (select-set) construct to fetch information from a table based on contents of another table, but you cannot use the JOIN clause.
- All FQL queries must have a WHERE condition that references an indexable column. (Indexable columns are clearly marked in the descriptions of individual FQL tables.) For example, you can select user data based on user ID (or any combination of user ID and other columns), but not based solely on the user's favorite books.
- The only other clauses that can be used with the SELECT clause are ORDER (which sorts the results) and LIMIT (which limits the number of rows in the result set).
Testing FQL Queries
If you're not completely at ease with FQL, you should test your queries with the Facebook API Test Console, which is part of the Facebook developers' tools.
You might want to test your queries within the scope of the Test application, but it's better if you select your own application (notice the blue oval in Figure 1) when you want to test application-specific queries. For example, you could test whether a friend of the user has already connected his or her Facebook account with your application.
After selecting the application and the returned data format, you have to select the API call (select fql.query, marked with a green oval in Figure 1) and enter the actual FQL query. We'll start with the simple SELECT * FROM user query, which quickly returns an error message: You cannot use the SELECT * format, but rather have to list the fields that interest you.
A quick consultation with the user table documentation gives us the list of potential columns. We'll use just the first name, the last name, and the information as to whether the user has already connected with our application. Here's the revised FQL query:
SELECT first_name,last_name,is_app_user FROM user
Unfortunately, it returns this very uninformative error message:
Parser error: unexpected end of query.
A quick look into the FQL grammar confirms that the WHERE condition is mandatory; we cannot perform a query without it.
Assuming that we'd like to see who uses our application, we might try the following query:
SELECT first_name,last_name,is_app_user FROM user WHERE is_app_user = 1
Yet again we're rejected, this time with the following error message:
Your statement is not indexable. The WHERE clause must contain an indexable column. Such columns are marked with * in the tables linked from http://wiki.developers.facebook.com/index.php/FQL_Tables.
The only indexable columns in the user table are the user ID (uid), full name (name) and username, so we have to know one of these in order to get the user data. Let's try to get the data based on the full name:
SELECT uid,first_name,last_name,is_app_user FROM user WHERE name = 'John Doe'
The FQL query finally returns the results; now you can switch into JSON format to inspect the data (see Figure 2).