Facebook released the Data Store API Beta a few months ago, but I hadn’t had a chance to try it out until recently. There are many blog posts discussing the merits of its implementation, but I felt it would be useful to post a quick how-to guide to using it. The Data Store API uses an Object metaphor, which is much different than the table metaphor used by most other databases. However, the mapping between the two models is pretty simple.
Facebook has also made it much easier to work with the Data Store with the Data Store Admin tool added to the Developer page beside each application. This tool lets you create and edit the schema for the database and do FQL queries against it. You can do the same things programmatically, but sometimes it is nice to have a visual editor.
Note: All operations involving schema management can only be done by the developers of the application and will fail with a FacebookRestClientException of 200 – Permission error if done in the context of another user. So, it would be best to move this type of operation to an Admin-only page or do it via the Admin tool.
Another thing to note is that each application gets its own Data Store space, so multiple applications cannot share the same database. The Data Store API has Object Types, Objects and Associations. I will go over each one and show how it maps to the Table metaphor, then do a quick example of creating a table, adding a row and getting its values.
Object Types
Object Types represent Tables and their Properties represent Columns. You create an Object Type like this:
$facebook->api_client->data_createObjectType("tablename");
You add properties or Columns like this:
// 1 for integer,2 for string (max. 255 characters), 3 for text blob (max. 64kb)
$facebook->api_client->data_defineObjectProperty("tablename", "columnname", 3);
Once you have created an Object Type, you can then create instances of it or Rows. You only need to create an Object Type once, although you can create many different Object Types if you need many different tables
Objects
Objects represent Rows in the Table. You set the values of the properties to set the value of a Column. You can create or update an existing Object, if you have its id. You can create a new Object and set its properties at the same time like this:
$objectID = $facebook->api_client->data_createObject("tablename", array("columname" => "$value") );
or update an object like this:
//pass true to overwrite the properties, or false to merge in
$objectID = $facebook->api_client->data_updateObject($objectID, array("columname" => "$value"), true );
Once you have rows, you can fetch an array of the properties like this:
$properties = $facebook->api_client->data_getObject($objectID);
Associations
Creating Objects is easy, but, as you can see above, you need the objectID to get an Object. Where do you get that from? Associations.
An Association is a link between two ids. You can use it to link the current user or page to an objectId, and then get the properties for that object.
After you create a new object, you need to create the association using the objectID you get back like this:
$facebook->api_client->data_setAssociation( "user_to_row", $userID, $objectID );
Then you can retrieve the objectID any time by getting it out of the association for the current user:
$objects = $facebook->api_client->data_getAssociatedObjects( "user_to_row", $userID, true );
// There is only a single row for this objectID
if( isset($objects) && isset($objects[0]) ) {
// id2 holds the object id
$objectID = $objects[0]["id2"];
}
Example
The example below defines a Table schema, adds a Row and then uses an Association to get the values.
//Create the table
$facebook->api_client->data_createObjectType("description");
$facebook->api_client->data_defineObjectProperty("description", "text", 3);
$facebook->api_client->data_defineAssociation( "user_to_row", 1, array("alias" => "user_id"), array("alias" => "row_id") );
//Add a row
$text = "All work and no play makes John unhappy";
$rowID = $facebook->api_client->data_createObject("description", array("text" => "$text") );
$facebook->api_client->data_setAssociation( "user_to_row", $userID, $rowID );
//Fetch the row value
$objects = $facebook->api_client->data_getAssociatedObjects( "user_to_row", $userID, true );
// There is only a single row for this objectID
if( isset($objects) && isset($objects[0]) ) {
// id2 holds the object id
$objectID = $objects[0]["id2"];
}
$description = $facebook->api_client->data_getObjectProperty( $objectID, "text" );
echo "The description for is $description";
Error Handling
You will notice that there is none above. However, many of these calls are likely to throw one of the following:
FacebookAPIErrorCodes::API_EC_DATA_OBJECT_NOT_FOUND FacebookAPIErrorCodes::API_EC_DATA_OBJECT_ALREADY_EXISTS FacebookAPIErrorCodes::API_EC_PERMISSION
so it makes sense to put each call into a try\catch block.
Summary
The Facebook Data Store API is still in Beta, so don’t expect it to work all of the time. However, it is a nice way to eliminate the need for any external database support for your application. You can find more information about the Data Store API here and a nice set of wrapper classes here.
(Updated based on alvin's comments)