factual-api 0.5 → 1.0.0

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## v1.0.0
+* fully documented
+* crosswalk(<factual_id>).only('yelp')
+
+## v0.5
+* big refactoring from Rudy
+* ready for releasing
+
 ## v0.3
 * return hash instead of objects
 * removing facets

data/README.md

@@ -1,71 +1,401 @@
-# Introduction
+# About
 
 This is the Factual supported Ruby driver for [Factual's public API](http://developer.factual.com/display/docs/Factual+Developer+APIs+Version+3).
 
-# Installation
+This API supports queries to Factual's Read, Schema, Crosswalk, and Resolve APIs. Full documentation is available on the Factual website:
 
-    gem 'factual-api'
-    require 'factual'
-    factual = Factual.new(YOUR_KEY, YOUR_SECRET)
+*   [Read](http://developer.factual.com/display/docs/Factual+Developer+APIs+Version+3): Search the data
+*   [Schema](http://developer.factual.com/display/docs/Core+API+-+Schema): Get table metadata
+*   [Crosswalk](http://developer.factual.com/display/docs/Places+API+-+Crosswalk): Get third-party IDs
+*   [Resolve](http://developer.factual.com/display/docs/Places+API+-+Resolve): Enrich your data and match it against Factual's
+
+This driver is supported via the [Factual Developer Group](https://groups.google.com/group/factual_developers)
+
+# Overview
+
+## Basic Design
+
+The driver allows you to create an authenticated handle to Factual. With a Factual handle, you can send queries and get results back.
+
+Queries are created using the Factual handle, which provides a fluent interface to constructing your queries. 
+
+````ruby
+# You can chain the query methods, like this:
+factual.table("places").filters("region" => "CA").search("sushi", "sashimi")
+  .geo("$circle" => {"$center" => [34.06021, -118.41828], "$meters" => 5000})
+  .sort("name").page(2, :per => 10)
+````
+
+Results are returned as Ruby Arrays of Hashes, where each Hash is a result record.
+
+## Setup
+
+The driver's gems are hosted at [Rubygems.org](http://rubygems.org). You can install the factual-api gem as follows:
+
+`````bash
+$ gem install factual-api
+`````
+
+Once the gem is installed, you can use it in your Ruby project like:
+
+````ruby
+require 'factual'
+factual = Factual.new("YOUR_KEY", "YOUR_SECRET")
+````
   
-# Examples
+## Simple Read Examples
+
+`````ruby
+# Return entities from the Places dataset with names beginning with "starbucks"
+factual.table("places").filters("name" => {"$bw" => "starbucks"}).rows
+````
+
+`````ruby
+# Return entity names and non-blank websites from the Global dataset, for entities located in Thailand
+factual.table("global").select(:name, :website)
+  .filters({"country" => "TH", "website" => {"$blank" => false}})
+````
+
+`````ruby
+# Return highly rated U.S. restaurants in Los Angeles with WiFi
+factual.table("restaurants-us")
+  .filters({"locality" => "los angeles", "rating" => {"$gte" => 4}, "wifi" => true}).rows
+````
+
+## Simple Crosswalk Example
+
+````ruby
+# Concordance information of a place
+FACTUAL_ID = "110ace9f-80a7-47d3-9170-e9317624ebd9"
+query = factual.crosswalk(FACTUAL_ID)
+query.rows
+````
+
+## Simple Resolve Example
+
+````ruby
+# Returns resolved entities as an array of hashes
+query = factual.resolve("name" => "McDonalds",
+                        "address" => "10451 Santa Monica Blvd",
+                        "region" => "CA",
+                        "postcode" => "90025")
+
+query.first["resolved"]   # true or false
+query.rows                # all candidate rows
+````
+
+## More Read Examples
+
+````ruby
+# 1. Specify the table Global
+query = factual.table("global")
+````
+
+````ruby
+# 2. Filter results in country US
+query = query.filters("country" => "US")
+````
+
+````ruby
+# 3. Search for "sushi" or "sashimi"
+query = query.search("sushi", "sashimi")
+````
+
+````ruby
+# 4. Filter by geolocation
+query = query.geo("$circle" => {"$center" => [34.06021, -118.41828], "$meters" => 5000})
+````
+
+````ruby
+# 5. Sort it 
+query = query.sort("name")            # ascending 
+query = query.sort_desc("name")       # descending
+query = query.sort("address", "name") # sort by multiple columns
+````
+
+````ruby
+# 6. Page it
+query = query.page(2, :per => 10)
+````
+
+````ruby
+# 7. Finally, get response in a hash or array of hashes
+query.first    # return one row
+query.rows     # return many rows
+````
+
+````ruby
+# 8. Returns total row counts that matches the criteria
+query.total_count
+````
+
+# Read API
+
+## All Top Level Query Parameters
+
+<table>
+  <col width="33%"/>
+  <col width="33%"/>
+  <col width="33%"/>
+  <tr>
+    <th>Parameter</th>
+    <th>Description</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <td>filters</td>
+    <td>Restrict the data returned to conform to specific conditions.</td>
+    <td><tt>query = query.filters("name" => {"$bw" => "starbucks"})</tt></td>
+  </tr>
+  <tr>
+    <td>get total row count</td>
+    <td>returns the total count of the number of rows in the dataset that conform to the query.</td>
+    <td><tt>query.total_count</tt></td>
+  </tr>
+  <tr>
+    <td>geo</td>
+    <td>Restrict data to be returned to be within a geographical range based.</td>
+    <td>(See the section on Geo Filters)</td>
+  </tr>
+  <tr>
+    <td>limit</td>
+    <td>Limit the results</td>
+    <td><tt>query = query.limit(12)</tt></td>
+  </tr>
+  <tr>
+    <td>page</td>
+    <td>Limit the results to a specific "page".</td>
+    <td><tt>query = query.page(2, :per => 10)</tt></td>
+  </tr>
+  <tr>
+    <td>search (across entity)</td>
+    <td>Full text search across entity</td>
+    <td>
+      Find "sushi":<br><tt>query = query.search("sushi")</tt><p>
+      Find "sushi" or "sashimi":<br><tt>query = query.search("sushi", "sashimi")</tt><p>
+      Find "sushi" and "santa" and "monica":<br><tt>query.search("sushi santa monica")</tt>
+    </td>
+  </tr>
+  <tr>
+    <td>search (across field)</td>
+    <td>Full text search on specific field</td>
+    <td><tt>query = query.filters({"name" => {"$search" => "cafe"}})</tt></td>
+  </tr>
+  <tr>
+    <td>select</td>
+    <td>Specifiy which fields to include in the query results.  Note that the order of fields will not necessarily be preserved in the resulting response due to the nature Hashes.</td>
+    <td><tt>query = query.select(:name, :address, :locality, :region)</tt></td>
+  </tr>
+  <tr>
+    <td>sort</td>
+    <td>The field (or fields) to sort data on, as well as the direction of sort.<p>
+        Sorts ascending by default, but supports both explicitly sorting ascending and descending, by using <tt>sort_asc</tt> or <tt>sort_desc</tt>.
+        Supports $distance as a sort option if a geo-filter is specified.<p>
+        Supports $relevance as a sort option if a full text search is specified either using the q parameter or using the $search operator in the filter parameter.<p>
+        By default, any query with a full text search will be sorted by relevance.<p>
+        Any query with a geo filter will be sorted by distance from the reference point.  If both a geo filter and full text search are present, the default will be relevance followed by distance.</td>
+    <td><tt>query = query.sort("name")</tt><br>
+    <tt>query = query.sort_desc("$distance")</tt>
+    <tt>query = query.sort_asc("name").sort_desc("rating")</tt></td>
+  </tr>
+</table>
+
+## Row Filters
+
+The driver supports various row filter logic. For example:
+
+`````ruby
+# Returns records from the Places dataset with names beginning with "starbucks"
+factual.table("places").filters("name" => {"$bw" => "starbucks"}).rows
+````
+
+### Supported row filter logic
+
+<table>
+  <tr>
+    <th>Predicate</th>
+    <th width="25%">Description</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <td>$eq</td>
+    <td>equal to</td>
+    <td><tt>query = query.filters("region" => {"$eq" => "CA"})</tt></td>
+  </tr>
+  <tr>
+    <td>$neq</td>
+    <td>not equal to</td>
+    <td><tt>query = query.filters("region" => {"$neq" => "CA"})</tt></td>
+  </tr>
+  <tr>
+    <td>search</td>
+    <td>full text search</td>
+    <td><tt>query = query.search("sushi")</tt></td>
+  </tr>
+  <tr>
+    <td>$in</td>
+    <td>equals any of</td>
+    <td><tt>query = query.filters("region" => {"$in" => ["CA", "NM", "NY"]})</tt></td>
+  </tr>
+  <tr>
+    <td>$nin</td>
+    <td>does not equal any of</td>
+    <td><tt>query = query.filters("region" => {"$nin" => ["CA", "NM", "NY"]})</tt></td>
+  </tr>
+  <tr>
+    <td>$bw</td>
+    <td>begins with</td>
+    <td><tt>query = query.filters("name" => {"$bw" => "starbucks"})</tt></td>
+  </tr>
+  <tr>
+    <td>$nbw</td>
+    <td>does not begin with</td>
+    <td><tt>query = query.filters("name" => {"$nbw" => "starbucks"})</tt></td>
+  </tr>
+  <tr>
+    <td>$bwin</td>
+    <td>begins with any of</td>
+    <td><tt>query = query.filters("name" => {"$bwin" => ["starbucks", "coffee", "tea"]})</tt></td>
+  </tr>
+  <tr>
+    <td>$nbwin</td>
+    <td>does not begin with any of</td>
+    <td><tt>query = query.filters("name" => {"$nbwin" => ["starbucks", "coffee", "tea"]})</tt></td>
+  </tr>
+  <tr>
+    <td>$blank</td>
+    <td>test to see if a value is (or is not) blank or null</td>
+    <td><tt>query = query.filters("tel" => {"$blank" => true})</tt><br>
+        <tt>query = query.filters("website" => {"$blank" => false})</tt></td>
+  </tr>
+  <tr>
+    <td>$gt</td>
+    <td>greater than</td>
+    <td><tt>query = query.filters("rating" => {"$gt" => 7.5})</tt></td>
+  </tr>
+  <tr>
+    <td>$gte</td>
+    <td>greater than or equal</td>
+    <td><tt>query = query.filters("rating" => {"$gte" => 7.5})</tt></td>
+  </tr>
+  <tr>
+    <td>$lt</td>
+    <td>less than</td>
+    <td><tt>query = query.filters("rating" => {"$lt" => 7.5})</tt></td>
+  </tr>
+  <tr>
+    <td>$lte</td>
+    <td>less than or equal</td>
+    <td><tt>query = query.filters("rating" => {"$lte" => 7.5})</tt></td>
+  </tr>
+</table>
+
+### AND
+
+Filters can be logically AND'd together. For example:
+
+````ruby
+# name begins with "coffee" AND tel is not blank
+query = query.filters({ "$and" => [{"name" => {"$bw" => "coffee"}}, {"tel" => {"$blank" => false}}] })
+````
+
+### OR
+
+Filters can be logically OR'd. For example:
+
+````ruby
+# name begins with "coffee" OR tel is not blank
+query = query.filters({ "$or" => [{"name" => {"$bw" => "coffee"}}, {"tel" => {"$blank" => false}}] })
+````
+
+### Combined ANDs and ORs
+
+You can nest AND and OR logic to whatever level of complexity you need. For example:
+
+````ruby
+# (name begins with "Starbucks") OR (name begins with "Coffee")
+# OR
+# (name full text search matches on "tea" AND tel is not blank)
+query = query.filters({ "$or" => [ {"$or" => [ {"name" => {"$bw" => "starbucks"}},
+                                               {"name" => {"$bw" => "coffee"}}]},
+                                   {"$and" => [ {"name" => {"$search" => "tea"}},
+                                                {"tel" => {"$blank" => false}} ]} ]})
+````
+
+# Crosswalk
+
+The driver fully supports Factual's Crosswalk feature, which lets you "crosswalk" the web and relate entities between Factual's data and that of other web authorities.
+
+(See [the Crosswalk Blog](http://blog.factual.com/crosswalk-api) for more background.)
+
+## Simple Crosswalk Example
+
+````ruby
+# Get all Crosswalk data for a Place with a specific FactualID
+factual.crosswalk("110ace9f-80a7-47d3-9170-e9317624ebd9").rows
+````
+
+## Supported Crosswalk Options
+
+### only
+
+You can specify which namespaces you want, like this:
+
+````ruby
+# Get Crosswalk data for only yelp and facebook for a Place with a specific FactualID
+factual.crosswalk("110ace9f-80a7-47d3-9170-e9317624ebd9").only(:yelp, :facebook).rows
+````
+
+This will generally return 1 record per requested namespace.
+
+### limit
 
-## Quick Sample 
+You can limit the amount of Crosswalk results you get back, like this:
 
-    # Returns Places with names beginning with "Star"
-    factual.table("places").filters("name" => {"$bw" => "Star"}).rows
+````ruby
+# Get only 3 Crosswalk results for a Place with a specific FactualID
+factual.crosswalk("110ace9f-80a7-47d3-9170-e9317624ebd9").limit(3).rows
+````
 
-## Read (with all features)
+# Resolve
 
-    # 1. Specify the table Global
-    query = factual.table("global")
+The driver fully supports Factual's Resolve feature, which lets you start with incomplete data you may have for an entity, and get potential entity matches back from Factual.
 
-    # 2. Filter results in country US (For more filters syntax, refer to [Core API - Row Filters](http://developer.factual.com/display/docs/Core+API+-+Row+Filters))
-    query = query.filters("country" => "US")
+Each result record will include a confidence score (<tt>"similarity"</tt>), and a flag indicating whether Factual decided the entity is the correct resolved match with a high degree of accuracy (<tt>"resolved"</tt>).
 
-    # 3. Search for "sushi" or "sashimi" (For more search syntax, refer to [Core API - Search Filters](http://developer.factual.com/display/docs/Core+API+-+Search+Filters))
-    query = query.search("sushi", "sashimi")
+For any Resolve query, there will be 0 or 1 entities returned with <tt>"resolved"=true</tt>. If there was a full match, it is guaranteed to be the first record in the response Array.
 
-    # 4. Filter by Geo (For more geo syntax, refer to [Core API - Geo Filters](http://developer.factual.com/display/docs/Core+API+-+Geo+Filters))
-    query = query.geo("$circle" => {"$center" => [34.06021, -118.41828], "$meters" => 5000})
+(See [the Resolve Blog](http://blog.factual.com/factual-resolve) for more background.)
 
-    # 5. Sort it 
-    query = query.sort("name")            # ascending 
-    query = query.sort_desc("name")       # descending
-    query = query.sort("address", "name") # sort by multiple columns
+## Simple Resolve Examples
 
-    # 6. Page it
-    query = query.page(2, :per => 10)
+````ruby
+# Returns resolved entities as an array of hashes
+query = factual.resolve("name" => "McDonalds",
+                        "address" => "10451 Santa Monica Blvd",
+                        "region" => "CA",
+                        "postcode" => "90025")
 
-    # 7. Finally, get response in a hash or array of hashes
-    query.first    # return one row
-    query.rows     # return many rows
+query.first["resolved"] # true or false
+query.rows              # all candidate rows
+````
 
-    # 8. Returns total row counts that matches the criteria
-    query.total_count
+# Geo Filters
 
-    # You can chain the query methods, like this
-    factual.table("places").filters("region" => "CA").search("sushi", "sashimi").geo("$circle" => {"$center" => [34.06021, -118.41828], "$meters" => 5000}).sort("name").page(2, :per => 10).rows
+You can query Factual for entities located within a geographic area. For example:
 
-## Crosswalk
+````ruby
+query = query.geo("$circle" => {"$center" => [34.06021, -118.41828], "$meters" => 5000})
+````
 
-    # Concordance information of a place
-    FACTUAL_ID = "110ace9f-80a7-47d3-9170-e9317624ebd9"
-    query = factual.crosswalk(FACTUAL_ID)
-    query.rows
+# Schema
 
-## Resolve
+You can query Factual for the detailed schema of any specific table in Factual. For example:
 
-    # Returns resolved entities as an array of hashes
-    query = factual.resolve("name" => "McDonalds",
-                    "address" => "10451 Santa Monica Blvd",
-                    "region" => "CA",
-                    "postcode" => "90025")
+````ruby
+# Returns a hash of metadata for the table named "global", including an array of fields
+factual.table("global").schema
+````
 
-    query.first.resolved # true or false
-    query.rows           # resolved rows
 
-## Schema
 
-    # Returns a hash of table metadata, including an array of fields
-    factual.table("global").schema

data/lib/factual.rb

@@ -1,22 +1,24 @@
 require 'oauth'
 require 'factual/api'
-require 'factual/query'
+require 'factual/query/table'
+require 'factual/query/resolve'
+require 'factual/query/crosswalk'
 
 class Factual
   def initialize(key, secret)
-    @api = Factual::API.new(generate_token(key, secret))
+    @api = API.new(generate_token(key, secret))
   end
 
-  def crosswalk(factual_id)
-    Query.new(@api, :crosswalk, "places/crosswalk", :factual_id => factual_id)
+  def table(table_id_or_alias)
+    Query::Table.new(@api, "t/#{table_id_or_alias}")
   end
 
-  def resolve(values)
-    Query.new(@api, :resolve, "places/resolve", :values => values)
+  def crosswalk(factual_id)
+    Query::Crosswalk.new(@api, :factual_id => factual_id)
   end
 
-  def table(table_id_or_alias)
-    Query.new(@api, :read, "t/#{table_id_or_alias}")
+  def resolve(values)
+    Query::Resolve.new(@api, :values => values)
   end
 
   private

data/lib/factual/api.rb

@@ -5,7 +5,7 @@ class Factual
   class API
     API_V3_HOST        = "http://api.v3.factual.com"
     DRIVER_VERSION_TAG = "factual-ruby-driver-1.0"
-    PARAM_ALIASES      = { :search => :q }
+    PARAM_ALIASES      = { :search => :q, :sort_asc => :sort }
 
     def initialize(access_token)
       @access_token = access_token
@@ -23,17 +23,13 @@ class Factual
     private
 
     def handle_request(action, path, params)
-      response = make_request(path, params)
-      json    = response.body
-      payload = JSON.parse(json)
-
+      payload = JSON.parse(make_request(path, params).body)
       raise StandardError.new(payload["message"]) unless payload["status"] == "ok"
-
       payload["response"]
     end
 
     def make_request(path, params)
-      url     = "#{API_V3_HOST}/#{path}?#{query_string(params)}"
+      url = "#{API_V3_HOST}/#{path}?#{query_string(params)}"
       headers = { "X-Factual-Lib" => DRIVER_VERSION_TAG }
 
       @access_token.get(url, headers)

data/lib/factual/query/base.rb

@@ -0,0 +1,49 @@
+class Factual
+  module Query
+    class Base
+      include Enumerable
+
+      def initialize(api, params)
+        @api = api
+        @params = params
+      end
+
+      attr_reader :action, :path, :params
+
+      def each(&block)
+        rows.each { |row| block.call(row) }
+      end
+
+      def last
+        rows.last
+      end
+
+      def [](index)
+        rows[index]
+      end
+
+      def rows
+        response["data"]
+      end
+
+      def total_rows
+        response["total_row_count"]
+      end
+
+      def schema
+        @schema ||= @api.schema(self)
+      end
+
+      private
+
+      def form_value(args)
+        args = args.map { |arg| arg.is_a?(String) ? arg.strip : arg }
+        args.length == 1 ? args.first : args.join(',')
+      end
+
+      def response
+        @response ||= @api.execute(self)
+      end
+    end
+  end
+end

data/lib/factual/query/crosswalk.rb

@@ -0,0 +1,19 @@
+require 'factual/query/base'
+
+class Factual
+  module Query
+    class Crosswalk < Base
+      def initialize(api, params = {})
+        @path = "places/crosswalk"
+        @action = :crosswalk
+        super(api, params)
+      end
+
+      [:factual_id, :only, :limit, :include_count].each do |param|
+        define_method(param) do |*args|
+          self.class.new(@api, @params.merge(param => form_value(args)))
+        end
+      end
+    end
+  end
+end

data/lib/factual/query/resolve.rb

@@ -0,0 +1,19 @@
+require 'factual/query/base'
+
+class Factual
+  module Query
+    class Resolve < Base
+      def initialize(api, params = {})
+        @path = "places/resolve"
+        @action = :resolve
+        super(api, params)
+      end
+
+      [:values, :include_count].each do |param|
+        define_method(param) do |*args|
+          self.class.new(@api, @params.merge(param => form_value(args)))
+        end
+      end
+    end
+  end
+end

data/lib/factual/query/table.rb

@@ -0,0 +1,42 @@
+require 'factual/query/base'
+
+class Factual
+  module Query
+    class Table < Base
+      DEFAULT_LIMIT = 20
+
+      def initialize(api, path, params = {})
+        @path = path
+        @action = :read
+        super(api, params)
+      end
+
+      [:filters, :search, :geo, :sort, :select, :limit, :offset, :include_count].each do |param|
+        define_method(param) do |*args|
+          Table.new(@api, @path, @params.merge(param => form_value(args)))
+        end
+      end
+
+      def sort_asc(*args)
+        columns = args.map { |column| "#{column}" }
+        Table.new(@api, @path, @params.merge(:sort => columns.join(',')))
+      end
+
+      def sort_desc(*args)
+        columns = args.map { |column| "#{column}:desc" }
+        Table.new(@api, @path, @params.merge(:sort => columns.join(',')))
+      end
+
+      def page(page_number, paging_options = {})
+        limit = (paging_options[:per] || paging_options["per"] || DEFAULT_LIMIT).to_i
+        limit = DEFAULT_LIMIT if limit < 1
+
+        page_number = page_number.to_i
+        page_number = 1 if page_number < 1
+
+        offset = (page_number - 1) * limit
+        Table.new(@api, @path, @params.merge(:limit => limit, :offset => offset))
+      end
+    end
+  end
+end

metadata

@@ -2,33 +2,55 @@
 name: factual-api
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: "0.5"
+  version: 1.0.0
 platform: ruby
 authors: 
 - Rudiger Lippert
 - Forrest Cao
-- Aaron Crow
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2012-01-19 00:00:00 +08:00
+date: 2012-01-25 00:00:00 +08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: oauth
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.4.4
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.0
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
-  version_requirements: *id001
+  version_requirements: *id003
 description: Factual's official Ruby driver for the Factual public API.
 email: 
-- aaron@factual.com
+- rudy@factual.com
+- forrest@factual.com
 executables: []
 
 extensions: []
@@ -37,7 +59,10 @@ extra_rdoc_files: []
 
 files: 
 - lib/factual/api.rb
-- lib/factual/query.rb
+- lib/factual/query/base.rb
+- lib/factual/query/crosswalk.rb
+- lib/factual/query/resolve.rb
+- lib/factual/query/table.rb
 - lib/factual.rb
 - README.md
 - CHANGELOG.md
@@ -55,7 +80,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      version: "0"
+      version: 1.8.6
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 

data/lib/factual/query.rb

@@ -1,105 +0,0 @@
-class Factual
-  class Query
-    include Enumerable
-
-    DEFAULT_LIMIT = 20
-    VALID_PARAMS = {
-      :read      => [ :filters, :search, :geo, :sort, :select, :limit, :offset ],
-      :resolve   => [ :values ],
-      :crosswalk => [ :factual_id ],
-      :schema    => [ ],
-      :any       => [ :include_count ]
-    }
-
-    def initialize(api, action, path, params = {})
-      @api = api
-      @action = action
-      @path = path
-      @params = params
-      @response = nil
-      @schema = nil
-      validate_params
-    end
-
-    # Attribute Readers
-    attr_reader :action
-
-    [:path, :params].each do |attribute|
-      define_method(attribute) do
-        instance_variable_get("@#{attribute}").clone
-      end
-    end
-
-    # Response Methods
-    def each(&block)
-      rows.each { |row| block.call(row) }
-    end
-
-    def last
-      rows.last
-    end
-
-    def [](index)
-      rows[index]
-    end
-
-    def rows
-      (@response ||= @api.execute(self))["data"].clone
-    end
-
-    def total_rows
-      (@response ||= @api.execute(self))["total_row_count"]
-    end
-
-    def schema
-      (@schema ||= @api.schema(self)).clone
-    end
-
-    # Query Modifiers
-    VALID_PARAMS.values.flatten.uniq.each do |param|
-      define_method(param) do |*args|
-        args  = args.collect{|arg| arg.is_a?(String) ? arg.strip : arg }
-        value = (args.length == 1) ? args.first : args.join(',')
-
-        new_params = @params.clone
-        new_params[param] = value
-
-        Query.new(@api, @action, @path, new_params)
-      end
-    end
-
-    def sort_desc(*args)
-      columns = args.map { |column| "#{column}:desc" }
-
-      new_params = @params.clone
-      new_params[:sort] = columns.join(',')
-
-      Query.new(@api, @action, @path, new_params)
-    end
-
-    def page(page_number, paging_options = {})
-      limit = (paging_options[:per] || paging_options["per"] || DEFAULT_LIMIT).to_i
-      limit = DEFAULT_LIMIT if limit < 1
-
-      page_number = page_number.to_i
-      page_number = 1 if page_number < 1
-
-      new_params = @params.clone
-      new_params[:limit] = limit
-      new_params[:offset] = (page_number - 1) * limit
-
-      Query.new(@api, @action, @path, new_params)
-    end
-
-    private
-
-    # Validations
-    def validate_params
-      @params.each do |param, val|
-        unless (VALID_PARAMS[@action] + VALID_PARAMS[:any]).include?(param)
-          raise StandardError.new("InvalidArgument #{param} for #{@action}")
-        end
-      end
-    end
-  end
-end