fql-workbench

FQLWorkbench ============ #### A workbench for Facebook's FQL ### Step 1 - Install ``` $ sudo npm install fql-workbench -g ``` ### Step 2 - Start the daemon ``` $ fql daemon ``` ### Step 3 - Connect (Local/remote) ``` $ fql connect -h/--host [host] -p/--port [port] -i/--id [id] -s/--secret [secret] -u/--uid [uid] (optional) -U/--user (optional) ``` ### Step 4 - Play All output is yaml output. ``` fql> SELECT uid, username, first_name, last_name, name, sex, is_app_user FROM user WHERE uid = :uid; ... - uid: 543985131 username: joseph.werle first_name: Joseph last_name: Werle name: 'Joseph Werle' sex: male is_app_user: false Query took 0.087 seconds to execute. fql> ``` ### Aliases The following aliases are available within the query: ``` :id - App ID :secret - App Secret :accessToken - The access token generated by the app id and secret :uid - The UID supplied by the -u or --uid flag. :me - If the -U or --user flag was supplied then the value of this variable is the uid supplied by the -u or --uid flag ``` ### Commands The following commands are available at the command line interface ``` :help <command> - Displays usage on a given command :print <string> - Prints a string to the buffer :exit - Exits the session :describe <table> - Shows a table definition ``` ### Help Using :help ``` fql> :help ... ':help <command> - Displays usage on a given command' fql> :help print ... ':print <string> - Prints a string to the buffer' fql> :help describe ... ':describe <table> - Shows a table definition' fql> ``` ### Tab Completion There is tab completion for the support query syntax. Tables, fields, permissions coming soon. ``` fql> sele select fql> select name fr from fql> select name from user w where fql> select name from user where uid = :uid ... - name: 'Joseph Werle' Query took 0.082 seconds to execute. fql> ``` ### Exiting You can leave the session in a few ways. ``` fql> :exit ... $ ``` or ``` Query took 0.081 seconds to execute. fql> exit Exiting... ``` ### Using commands ``:print`` ``` fql> :print :uid ... '543985131' fql> :print :id ... '459902834061249' fql> ``` ``:show tables`` ``` fql> :show tables ... Fetching tables from http://developers.facebook.com/docs/reference/fql/ tables: - album - application - apprequest - checkin - comment - comments_info - connection - cookies - developer - domain - domain_admin - event - event_member - family - friend - friend_request - friendlist - friendlist_member - group - group_member - insights - like - link - link_stat - location_post - mailbox_folder - message - note - notification - object_url - offer - page - page_admin - page_blocked_user - page_fan - page_global_brand_child - page_milestone - permissions - permissions_info - photo - photo_src - photo_tag - place - privacy - privacy_setting - profile - profile_pic - profile_view - question - question_option - question_option_votes - review - standard_friend_info - standard_user_info - status - stream - stream_filter - stream_tag - subscription - thread - translation - unified_message - unified_thread - unified_thread_action - unified_thread_count - url_like - user - video - video_tag ``` ``:describe`` or ``:desc`` ``` fql> :describe insights ... name: insights fields: object_id: { name: object_id, type: { type: int }, indexable: true, description: 'The object for which you are retrieving metrics.' } metric: { name: metric, type: { type: string }, indexable: true, description: 'The usage data to retrieve.' } end_time: { name: end_time, type: { type: int }, indexable: true, description: "The end of the period during which the metrics were collected,\nexpressed as a unix time (which should always be midnight, Pacific Daylight Time)\nor using the function end_time_date() which takes a date string in 'YYYY-MM-DD' format.\nNote: If the unix time provided is not midnight, Pacific Daylight Time, your query may return an empty resultset.\nExample: To obtain data for the 24-hour period starting on September 15th at 00:00 (i.e. 12:00 midnight)\nand ending on September 16th at 00:00 (i.e. 12:00 midnight),\nspecify 1284620400 as the end_time and 86400 as the period.\n\nNote: end_time should not be specified when querying lifetime metrics." } period: { name: period, type: { type: int }, indexable: true, description: "The length of the period during which the metrics were collected,\nexpressed in seconds as one of 86400 (day), 604800 (week),\n2592000 (month) or 0 (lifetime) or using the function period(),\nwhich takes one of the strings day, week, month or lifetime.\n\nNote: Each metric may not have all periods available." } value: { name: value, type: { type: mixed }, indexable: false, description: 'The value of the requested metric.' } permissions: - access_token - read_insights ``` Filter the output of a :describe call ``` fql> :desc user perms ... Fetching table definition for user http://developers.facebook.com/docs/reference/fql/user name: user permissions: - user_likes - user_education_history - user_work_history - user_religion_politics - user_about_me - user_notes - user_status - user_online_presence - email - user_birthday - user_hometown - user_relationships - user_relationship_details - user_activities - user_interests - user_location - user_website ``` Filter user table to show fields and filter the output to only show the type ``` fql> :desc user fields:type ... Fetching table definition for user http://developers.facebook.com/docs/reference/fql/user name: user fields: uid: int username: string first_name: string middle_name: string last_name: string name: string pic_small: string pic_big: string pic_square: string pic: string affiliations: array profile_update_time: time timezone: int religion: string birthday: string birthday_date: string devices: array sex: string hometown_location: array meeting_sex: array meeting_for: array relationship_status: string significant_other_id: uid political: string current_location: array activities: string interests: string is_app_user: bool music: string tv: string movies: string books: string quotes: string about_me: string hs_info: array education_history: array work_history: array notes_count: int wall_count: int status: string has_added_app: bool online_presence: string locale: string proxied_email: string profile_url: string email_hashes: array pic_small_with_logo: string pic_big_with_logo: string pic_square_with_logo: string pic_with_logo: string pic_cover: array allowed_restrictions: string verified: bool profile_blurb: string family: array website: string is_blocked: bool contact_email: string email: string third_party_id: string name_format: string video_upload_limits: array games: string work: array education: array sports: array favorite_athletes: array favorite_teams: array inspirational_people: array languages: array likes_count: int friend_count: int mutual_friend_count: int can_post: bool ``` Describing a single field in a table ``` fql> :describe insights field:metric ... name: insights fields: metric: { name: metric, type: { type: string }, indexable: true, description: 'The usage data to retrieve.' } ``` Filtering meta information on a field ``` fql> :describe insights field:metric.description ... name: insights fields: metric: 'The usage data to retrieve.' fql> :describe insights field:metric.type ... name: insights fields: metric: { type: string } fql> desc user field:username.type,username.name,username.description,pic.type ... name: user fields: username: [{ type: string }, username, 'The username of the user being queried.'] pic: [{ type: string }] ``` Describing tables that do not exist ``` fql> :desc like ... Fetching table definition for like http://developers.facebook.com/docs/reference/fql/like - 'Unsupported table.' ``` Getting more output from a filter ``` fql> :desc insights fields:type,description ... name: insights fields: object_id: { type: int, description: '''The object for which you are retrieving metrics.''' } metric: { type: string, description: '''The usage data to retrieve.''' } end_time: { type: int, description: '"The end of the period during which the metrics were collected,\nexpressed as a unix time (which should always be midnight, Pacific Daylight Time)\nor using the function end_time_date() which takes a date string in ''YYYY-MM-DD'' format.\nNote: If the unix time provided is not midnight, Pacific Daylight Time, your query may return an empty resultset.\nExample: To obtain data for the 24-hour period starting on September 15th at 00:00 (i.e. 12:00 midnight)\nand ending on September 16th at 00:00 (i.e. 12:00 midnight),\nspecify 1284620400 as the end_time and 86400 as the period.\n\nNote: end_time should not be specified when querying lifetime metrics."' } period: { type: int, description: '"The length of the period during which the metrics were collected,\nexpressed in seconds as one of 86400 (day), 604800 (week),\n2592000 (month) or 0 (lifetime) or using the function period(),\nwhich takes one of the strings day, week, month or lifetime.\n\nNote: Each metric may not have all periods available."' } value: { type: mixed, description: '''The value of the requested metric.''' } ``` ### Examples Query your own data ``` fql> SELECT name FROM user WHERE uid = :uid ... - name: 'Joseph Werle' ``` Query data about a Facebook page ``` fql> SELECT name, page_id, username, description, page_url FROM page WHERE username = 'facebook'; ... - name: Facebook page_id: 20531316728 username: facebook description: page_url: 'http://www.facebook.com/facebook' Query took 0.103 seconds to execute. fql> ``` SELECT * ``` fql> select * from user where uid = :uid ... - uid: 543985131 username: joseph.werle first_name: Joseph middle_name: last_name: Werle name: 'Joseph Werle' pic_small: 'http://profile.ak.fbcdn.net/hprofile-ak-ash4/273334_543985131_475654434_t.jpg' pic_big: 'http://profile.ak.fbcdn.net/hprofile-ak-ash4/273334_543985131_475654434_n.jpg' pic_square: 'http://profile.ak.fbcdn.net/hprofile-ak-ash4/273334_543985131_475654434_q.jpg' pic: 'http://profile.ak.fbcdn.net/hprofile-ak-ash4/273334_543985131_475654434_s.jpg' affiliations: [] profile_update_time: null timezone: null religion: null birthday: null birthday_date: null devices: null sex: male hometown_location: null meeting_sex: null meeting_for: null relationship_status: null significant_other_id: null political: null current_location: null activities: interests: is_app_user: false music: tv: movies: books: quotes: null about_me: null hs_info: null education_history: [] work_history: [] notes_count: null wall_count: null status: null has_added_app: false online_presence: null locale: en_US proxied_email: null profile_url: null email_hashes: [] pic_small_with_logo: 'http://external.ak.fbcdn.net/safe_image.php?d=AQBqN7ykEVtkBj8a&url=http%3A%2F%2Fprofile.ak.fbcdn.net%2Fhprofile-ak-ash4%2F273334_543985131_475654434_t.jpg&logo&v=5' pic_big_with_logo: 'http://external.ak.fbcdn.net/safe_image.php?d=AQCJdVZedb1KWG1D&url=http%3A%2F%2Fprofile.ak.fbcdn.net%2Fhprofile-ak-ash4%2F273334_543985131_475654434_n.jpg&logo&v=5' pic_square_with_logo: 'http://external.ak.fbcdn.net/safe_image.php?d=AQDy8oj7Jkur4m27&url=http%3A%2F%2Fprofile.ak.fbcdn.net%2Fhprofile-ak-ash4%2F273334_543985131_475654434_q.jpg&logo&v=5' pic_with_logo: 'http://external.ak.fbcdn.net/safe_image.php?d=AQBLIlCy5KXvtmFo&url=http%3A%2F%2Fprofile.ak.fbcdn.net%2Fhprofile-ak-ash4%2F273334_543985131_475654434_s.jpg&logo&v=5' pic_cover: null allowed_restrictions: null verified: null profile_blurb: null family: [] website: null is_blocked: null contact_email: null email: null third_party_id: GmFMcou46KWeiU_Kg4ByPNQODS8 name_format: '{first} {last}' video_upload_limits: null games: work: [] education: [] sports: [] favorite_athletes: [] favorite_teams: [] inspirational_people: [] languages: [] likes_count: null friend_count: null mutual_friend_count: null can_post: false ``` Multi Query ``` fql> #user SELECT uid, username, name, first_name, last_name FROM user WHERE uid = :uid; #profile SELECT uid, username, name FROM #user ... - name: user fql_result_set: [{ uid: 543985131, username: joseph.werle, name: 'Joseph Werle', first_name: Joseph, last_name: Werle }] - name: profile fql_result_set: [{ uid: 543985131, username: joseph.werle, name: 'Joseph Werle' }] Query took 0.08 seconds to execute. fql> ``` Query app metric data ``` fql> SELECT metric, value FROM insights WHERE object_id = :id AND metric = 'application_active_users' AND end_time=end_time_date('2011-06-26') AND period=period('month') ... - metric: application_active_users value: 434 Query took 0.144 seconds to execute. fql> ``` ``` fql> SELECT metric, value FROM insights WHERE object_id = :id AND metric = 'application_like_adds' AND end_time=end_time_date('2011-06-26') AND period=period('month') ... - metric: application_like_adds value: 87 Query took 0.125 seconds to execute. fql> ``` Copyright and license --------------------- Copyright 2012 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at: http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - - - fql-workbench copyright 2012 joseph.werle@gmail.com