fql-workbench

A FQL Workbench tool

npm install fql-workbench
17 downloads in the last week
69 downloads in the last month

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

npm loves you