FQL

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

You can execute FQL queries by fetching https://api.facebook.com/method/fql.query?query=QUERY. You can specify a response format as either XML or JSON with the format query parameter.

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.

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(). There is also a rand() which can be used in conjunction with ORDER BY (ie ORDER BY rand()).

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())

Here's an example of using the NOT operator in FQL queries. This fetches the members of an event who are not the current user and not friends with the current user:

SELECT uid, name FROM user WHERE uid IN (
  SELECT uid FROM event_member WHERE eid=209798352393506
)
AND NOT (uid=me())
AND NOT (uid IN (
  SELECT uid1 FROM friend WHERE uid2=me()
))

For more information, check out the tables below, most of which have sample queries demonstrating their use. Also check out the Performance Guide for tips on optimizing your FQL.

FAQ

How do I get 10 random friends?

You can get a random selection by using order by rand() in your query. Here's how to get 10 random friends of the current user: select uid2 from friend where uid1 = me() order by rand() limit 10

Tables

album

Query this table to return information about a photo album.

application

Query this table to return read-only properties about an application.

checkin

Query this table to return information about a checkin. By default, this query returns the last 20 checkins and returns a maximum of 500 checkins.

comment

Query this table to obtain comments associated with one or more fb:comments/Feed story comment XIDs.

comments_info

The comments_info FQL table. Query this table to obtain XIDs for fb:comments objects associated with an application ID.

connection

Query this table to return a user's friends and the Facebook Pages to which the user is connected.

cookies

Query this table to return information about a cookie.

developer

Query this table to return the application IDs for which the specified user is listed as a developer in the Developer application.

domain

The domain table provides a read-only mapping between domain names and ids.

domain_admin

this is the page_admin table of

event

Query this table to return information about an event.

event_member

Query this table to return information about a user's status for an event.

family

Query this table to return detailed information about a user's family.

friend

Query this table to determine whether two users are linked together as friends.

friend_request

Query this table either to determine which users have sent friend requests to the logged-in user or to query whether a friend request has been sent from the logged-in user to a specific user.

friendlist

Query this table to return any friend lists owned by the specified user.

friendlist_member

Query this table to determine which users are members of a friend list.

group

Query this table to return information about a group.

group_member

Query this table to return information about the members of a group.

insights

The insights table contains statistics about applications, pages and domains

like

Query this table to return the user IDs of users who like a given Facebook object (video, note, link, photo, or photo album).

link

Query this table to return the links the current user has posted.

link_stat

Query this table to return detailed information from your Facebook Share implementation.

mailbox_folder

Query this table to return information about a user's Inbox folders.

message

Query this table to return information about messages in a thread.

metrics

Query this table to retrieve metrics about your application.

note

Query this table to return the notes the current user has written or to return details for a particular note.

notification

Query this table to get the notifications for the current session user, that is, any notification that appears on http://www.facebook.com/notifications.php.

object_url

Query this table to return information about a URL in the Open Graph

page

Query this table to return information about a Facebook Page.

page_admin

Query this table to return information about the admin of a Facebook Page.

page_fan

Query this table to return information about the fan of a Facebook Page.

permissions

Query this table to return the extended permissions the current user has granted to the application.

permissions_info

Query this table to return more descriptive information about extended permissions.

photo

Query this table to return information about a photo.

photo_src

Query this table to return different size versions of a photo.

photo_tag

Query this table to return information about a photo tag.

place

Query this table to return information about a place.

privacy

Query this table to return a user's privacy setting for a given object_id.

profile

Query this table to return certain (typically publicly) viewable information from a user's profile or Facebook Page that is displayed in a story.

review

Query this table to obtain reviews associated with an application, a user or both.

standard_friend_info

Query this table to determine whether two users are linked together as friends.

standard_user_info

Query this table to return standard information about a user, for use when you need analytic information only.

status

Query this table to return one or more of a user's statuses.

stream

Query this table to return posts from a user's stream or the user's profile.

stream_filter

Query this table to return a filter_key that can be used to query the stream FQL table, as seen through any content filters the user has available on Facebook.

stream_tag

Query this table to return associations between users or Facebook Pages and the items they tag in status posts.

thread

Query this table to return information about message threads in a user's Inbox.

translation

Query this table to return the native strings (original, untranslated text in your application interface) and the translated strings for your application.

unified_message

This table can be used to access information about messages in the new Facebook messaging system.

unified_thread

This table can be used to access information about threads in the new Facebook messaging system.

unified_thread_action

This table should be used to access information about subscribe and unsubscribe actions performed on a thread in the new Facebook messaging system.

unified_thread_count

This table should be used to access information about the number of threads in a folder in the new Facebook messaging system.

user

Query this table to return detailed information from a user's profile.

video

Query this table to return information about a video.

video_tag

Query this table to return information about a video tag.