Fql.multiquery
From Facebook Developer Wiki
Contents |
Description
Evaluates a series of FQL (Facebook Query Language) queries in one call and returns the data at one time.
This method takes a JSON-encoded dictionary called queries where the individual queries use the exact same syntax as a query made with fql.query. However, this method allows for more complex queries to be made. You can fetch data from one query and use it in another query within the same call. The WHERE clause is optional in the latter query, since it references data that’s already been fetched. To reference the results of one query in another query within the same call, specify its name in the FROM clause, preceded by #.
For example, say you want to get some data about a user attending an event. Normally, you’d have to perform two queries in a row, waiting for the results of the first query before running the second query, since the second query depends on data from the first one. But with fql.multiquery, you can run them at the same time, and get all the results you need, giving you better performance than running a series of fql.query calls. First, you need to get the user ID and RSVP status of each attendee, so you’d formulate the first query – query1 – like this:
Then to get each attendee’s profile data (name, URL, and picture in this instance), you’d make a second query – query2 – which references the results from query1. You formulate query2 like this:
This method also has better performance than running a series of fql.query calls with batch.run.
Parameters
| Required | Name | Type | Description | |
| required | api_key | string | The application key associated with the calling application. If you specify the API key in your client, you don't need to pass it with every call. | |
|---|---|---|---|---|
| call_id | float | The request's sequence number. Each successive call for any session must use a sequence number greater than the last. We suggest using the current time in milliseconds, such as PHP's microtime(true) function. If you specify the call ID in your client, you don't need to pass it with every call. | ||
| sig | string | An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application. Facebook computes the signature for you automatically. | ||
| v | string | This must be set to 1.0 to use this version of the API. If you specify the version in your client, you don't need to pass it with every call. | ||
| queries | array | A JSON-encoded dictionary of the queries to perform. The array contains a set of key/value pairs. Each key is a query name, which can contain only alphanumeric characters and optional underscores. Each key maps to a value containing a traditional FQL query. | ||
| optional | session_key | string | The session key of the logged in user. The session key is automatically included by our PHP client. | |
| format | string | The desired response format, which can be either XML or JSON. (Default value is XML.) | ||
| callback | string | Name of a function to call. This is primarily to enable cross-domain JavaScript requests using the <script> tag, also known as JSONP, and works with both the XML and JSON formats. The function will be called with the response passed as the parameter. Warning: If you use JSON as the output format, you may run into problems when selecting multiple fields with the same name or with selecting multiple "anonymous" fields (for example, SELECT 1+2, 3+4 ...). |
Example Requests
The following sample request runs four queries in one fql.multiquery call. The last two queries are built on data returned by other queries made in the call. The user_stream query gets all the recent posts from the user's home page stream. The friends query returns all of that user's friends. The comments query returns every comment made on all the posts returned by the user_stream query. Finally, the actor_info query returns the name and profile picture for every actor (who is a friend of the user) who made a post in the user_stream query and made a comment in the comments query.
Note: In this code, USER_ID must be replaced with an actual numeric Facebook User ID. Also, double quotes must be used for the query names and the queries themselves.
Response
This call returns a dictionary containing a list of query results in either JSON or XML format. The keys returned are the names of the queries made.
As with fql.query, the data returned from each query very closely resembles the returns of other API calls like users.getInfo, as many API functions are simply wrappers for FQL queries.
Example Return XML
Example Return JSON
Error Codes
| Code | Description | |
| 1 | An unknown error occurred. Please resubmit the request. | |
|---|---|---|
| 2 | The service is not available at this time. | |
| 4 | The application has reached the maximum number of requests allowed. More requests are allowed once the time window has completed. | |
| 5 | The request came from a remote address not allowed by this application. | |
| 100 | One of the parameters specified was missing or invalid. | |
| 101 | The API key submitted is not associated with any known application. | |
| 102 | The session key was improperly submitted or has reached its timeout. Direct the user to log in again to obtain another key. | |
| 103 | The submitted call_id was not greater than the previous call_id for this session. | |
| 104 | Incorrect signature. | |
| 601 | Error while parsing FQL statement. | |
| 602 | The field you requested does not exist. | |
| 603 | The table you requested does not exist. | |
| 604 | Your statement is not indexable. | |
| 605 | The function you called does not exist. | |
| 606 | Wrong number of arguments passed into the function. | |
| 614 | Unresolved dependency in multiquery. |
Notes
- At this time, you cannot preload queries with fql.multiquery.
- You can call this method using a session secret, and not the application secret (for example, for a Facebook Connect site or desktop application).
