FQL
From Facebook Developers Wiki
Facebook Query Language, or FQL, allows you to use a SQL-style interface to more easily query the same Facebook social data that you can access through other Facebook API methods (assuming your application has access!).
Contents |
Rationale
FQL is a way to query the same Facebook data you can access through the other API functions, but with a SQL-style interface. In fact, many of the normal API calls are simple wrappers for FQL queries. All of the usual privacy checks are still applied. A typical query looks something like this:
| SELECT name, pic FROM user WHERE uid=211031 OR uid=4801660 |
So, with all that said, why would you use FQL? The key advantages of using FQL over our more traditional API methods are as follows:
- Condensed XML reduces bandwidth and parsing costs. Instead of getting all of the information available about a large set of items, you can get just the fields you want for only the set of items matching a specific condition. You can request the specific set of information by adding constraints to the WHERE clause and only listing certain fields in the SELECT clause.
- More complex requests can reduce the number of requests necessary. Often the data that you are trying to get depends upon the results of a previous method call. For example, with the traditional API, to get the names of a person's friends, you first call friends.get and then pass the result directly back in to users.getInfo. Now you can just execute one FQL query that uses a subquery to get the set of friends - thus reducing an extra trip back and forth, and all of the latency associated with it.
- Provides a single consistent, unified interface for all of your data. Instead of having to learn numerous different methods that each have their own idiosyncrasies, you can make all of your requests with one function that has a consistent return type. Additionally, if you do need to call any of the traditional methods, the return XML is very similar, so the switching cost is negligible.
- It's fun! Check out the examples available at Sample FQL Queries and then try playing around with it in the test console - you can do some cool stuff with it!
The Query Language
Hopefully, you're now convinced that FQL may be useful to you. How do you use it? If you already know SQL, it should be pretty straightforward. Queries are of the form SELECT [fields] FROM [table] WHERE [conditions] (you can also optionally add on ORDER BY and LIMIT clauses that work like they do in MySQL). Unlike SQL, the FROM clause in FQL can contain only a single table. In the SELECT or WHERE clauses you can use the IN keyword to do subqueries (as in the examples in fql.query and Sample FQL Queries), but the subqueries cannot reference variables in the outer query's scope.
Another key restriction is that your query must be indexable. You cannot, for example, just specify WHERE 1 as your entire WHERE clause - in general your query must be limited to working on a specific, enumerable set of IDs (the FQL Tables show which columns are indexable). If you do not satisfy this requirement you will get back an error code 604.
FQL introduces a way of dealing with columns which are themselves structures or arrays (for example, the "education_history" column of the "user" table, which contains an array of education_info structures, or the "current_location" column of the user table which is a location structure). You can reference the structures as a whole, or you can filter them down to only a single field within the structure using dots.
For example, you can do:
| SELECT education_history, current_location |
to get the full structures. Or you can do:
| SELECT education_history.name, current_location.zip |
to get individual fields in those structures.
This is particularly useful in WHERE clauses. For example:
| WHERE "Stanford" IN education_history.name OR current_location.zip = 07079 |
Note: The last example is not indexable and would also need an additional constraint about the user ID.
The easiest way to learn FQL is to experiment with it. We encourage you to try out your own queries in the test console. If you are unsure about what is happening in a WHERE clause, keep in mind that any legal expression in that clause is also legal in the SELECT clause, so you can add things into that clause to get some insight into how our query evaluator is working.
Be Careful with Derived Attributes
A given query returns a maximum of one derived attribute when using JSON as the return format. If 3 derived attributes are requested, the first two are ignored and the last one is returned with the name anon.
For example, the FQL:
| SELECT "aa", "bb", "cc", uid FROM user |
Is effectively this in SQL:
| SELECT "cc" AS anon, uid FROM user |
If you use XML as the return type, all requested derived attributes get returned with the name anon.
Another difference between JSON and XML formats is that the order of the requested attributes is preserved in XML but not JSON.
For More Information
For more details, see:
