keen 0.5.0 → 0.6.0

data/.travis.yml

@@ -4,6 +4,7 @@ bundler_args: --without development
 rvm:
   - 1.8.7
   - 1.9.3
+  - 2.0.0
   - jruby-19mode
   - rbx-19mode
 

data/README.md

@@ -37,7 +37,9 @@ environment-based approach because it keeps sensitive information out of the cod
 
 If your environment is set up property, `Keen` is ready go immediately. Publish an event like this:
 
-    Keen.publish("sign_ups", { :username => "lloyd", :referred_by => "harry" })
+```ruby
+Keen.publish("sign_ups", { :username => "lloyd", :referred_by => "harry" })
+```
 
 This will publish an event to the 'sign_ups' collection with the `username` and `referred_by` properties set.
 
@@ -63,33 +65,78 @@ To publish asynchronously, first add
 Next, run an instance of EventMachine. If you're using an EventMachine-based web server like
 thin or goliath you're already doing this. Otherwise, you'll need to start an EventMachine loop manually as follows:
 
-    Thread.new { EventMachine.run }
+```ruby
+Thread.new { EventMachine.run }
+```
 
 The best place for this is in an initializer, or anywhere that runs when your app boots up.
 Here's a good blog article that explains more about this approach - [EventMachine and Passenger](http://railstips.org/blog/archives/2011/05/04/eventmachine-and-passenger/).
 
+And here's a gist that shows an example of [Eventmachine with Unicorn](https://gist.github.com/jonkgrimes/5103321). Thanks to [jonkgrimes](https://github.com/jonkgrimes) for sharing this with us!
+
 Now, in your code, replace `publish` with `publish_async`. Bind callbacks if you require them.
 
-    http = Keen.publish_async("sign_ups", { :username => "lloyd", :referred_by => "harry" })
-    http.callback { |response| puts "Success: #{response}"}
-    http.errback { puts "was a failurrr :,(" }
+```ruby
+http = Keen.publish_async("sign_ups", { :username => "lloyd", :referred_by => "harry" })
+http.callback { |response| puts "Success: #{response}"}
+http.errback { puts "was a failurrr :,(" }
+```
 
 This will schedule the network call into the event loop and allow your request thread
 to resume processing immediately.
 
+### Running queries
+
+The Keen IO API provides rich querying capabilities against your event data set. For more information, see the [Data Analysis API Guide](https://keen.io/docs/data-analysis/).
+
+Unlike event publishing, queries require that an API Key is provided. Just like project ID, we encourage that you set this as an environment variable:
+
+    KEEN_API_KEY=your-api-key
+
+Here's are some examples of querying with the Ruby gem. Let's assume you've added some events to the "purchases" collection.
+
+```ruby
+Keen.count("purchases") # => 100
+Keen.sum("purchases", :target_property => "price")  # => 10000
+Keen.minimum("purchases", :target_property => "price")  # => 20
+Keen.maximum("purchases", :target_property => "price")  # => 100
+Keen.average("purchases", :target_property => "price")  # => 60
+
+Keen.sum("purchases", :target_property => "price", :group_by => "item.id")  # => [{ "item.id": 123, "result": 240 }, { ... }]
+
+Keen.count_unique("purchases", :target_property => "username")  # => 3
+Keen.select_unique("purchases", :target_property => "username")  # => ["bob", "linda", "travis"]
+
+Keen.extraction("purchases")  # => [{ "price" => 20, ... }, { ... }]
+
+Keen.funnel(:steps => [
+  { :actor_property => "username", "event_collection" => "purchases" },
+  { :actor_property => "username", "event_collection" => "referrals" },
+  { ... }])  # => [20, 15 ...]
+```
+
+Many of there queries can be performed with group by, filters, series and intervals. The API response for these is converted directly into Ruby Hash or Array.
+
+Detailed information on available parameters for each API resource can be found on the [API Technical Reference](https://keen.io/docs/api/reference/).
+
 ### Other code examples
 
 #### Authentication
 
 To configure keen-gem in code, do as follows:
 
-    Keen.project_id = 'your-project-id'
+```ruby
+Keen.project_id = 'your-project-id'
+```
 
 You can also configure individual client instances as follows:
 
-    keen = Keen::Client.new(:project_id => 'your-project-id')
+```ruby
+keen = Keen::Client.new(:project_id => 'your-project-id')
+```
 
 #### em-synchrony
+
 keen-gem can be used with [em-synchrony](https://github.com/igrigorik/em-synchrony).
 If you call `publish_async` and `EM::Synchrony` is defined the method will return the response
 directly. (It does not return the deferrable on which to register callbacks.) Likewise, it will raise
@@ -103,15 +150,18 @@ This is useful for situations like tracking email opens using [image beacons](ht
 In this situation, the JSON event data is passed by encoding it base-64 and adding it as a request parameter called `data`.
 The `beacon_url` method found on the `Keen::Client` does this for you. Here's an example:
 
-    keen = Keen::Client.new(:project_id => '12345')
-
-    keen.beacon_url("sign_ups", :recipient => "foo@foo.com")
-    # => "https://api.keen.io/3.0/projects/12345/events/email_opens?data=eyJyZWNpcGllbnQiOiJmb29AZm9vLmNvbSJ9"
+```ruby
+Keen.beacon_url("sign_ups", :recipient => "foo@foo.com")
+  # => "https://api.keen.io/3.0/projects/12345/events/email_opens?data=eyJyZWNpcGllbnQiOiJmb29AZm9vLmNvbSJ9"
+```
 
 To track email opens, simply add an image to your email template that points to this URL.
 
 ### Changelog
 
+##### 0.6.0
++ Added querying capabilities. A big thanks to [ifeelgoods](http://www.ifeelgoods.com/) for contributing!
+
 ##### 0.5.0
 + Removed API Key as a required field on Keen::Client. Only the Project ID is required to publish events.
 + You can continue to provide the API Key. Future features planned for this gem will require it. But for now,

data/lib/keen.rb

@@ -23,7 +23,8 @@ module Keen
 
     def_delegators :default_client, :project_id, :api_key,
                    :project_id=, :api_key=, :publish, :publish_async,
-                   :beacon_url
+                   :beacon_url, :count, :count_unique, :minimum, :maximum,
+                   :sum, :average, :select_unique, :funnel, :extraction
 
     attr_writer :logger
 

data/lib/keen/client.rb

@@ -1,5 +1,8 @@
 require 'keen/http'
 require 'keen/version'
+require 'keen/client/publishing_methods'
+require 'keen/client/querying_methods'
+
 require 'openssl'
 require 'multi_json'
 require 'base64'
@@ -7,6 +10,9 @@ require 'uri'
 
 module Keen
   class Client
+    include Keen::Client::PublishingMethods
+    include Keen::Client::QueryingMethods
+
     attr_accessor :project_id, :api_key
 
     CONFIG = {
@@ -30,12 +36,6 @@ module Keen
       }
     }
 
-    def beacon_url(event_collection, properties)
-      json = MultiJson.encode(properties)
-      data = [json].pack("m0").tr("+/", "-_").gsub("\n", "")
-      "https://#{api_host}#{api_path(event_collection)}?data=#{data}"
-    end
-
     def initialize(*args)
       options = args[0]
       unless options.is_a?(Hash)
@@ -50,64 +50,6 @@ module Keen
         :project_id, :api_key)
     end
 
-    def publish(event_collection, properties)
-      check_configuration!
-      check_event_data!(event_collection, properties)
-
-      begin
-        response = Keen::HTTP::Sync.new(
-          api_host, api_port, api_sync_http_options).post(
-            :path => api_path(event_collection),
-            :headers => api_headers_with_auth("sync"),
-            :body => MultiJson.encode(properties))
-      rescue Exception => http_error
-        raise HttpError.new("Couldn't connect to Keen IO: #{http_error.message}", http_error)
-      end
-      process_response(response.code, response.body.chomp)
-    end
-
-    def publish_async(event_collection, properties)
-      check_configuration!
-      check_event_data!(event_collection, properties)
-
-      deferrable = EventMachine::DefaultDeferrable.new
-
-      http_client = Keen::HTTP::Async.new(api_host, api_port, api_async_http_options)
-      http = http_client.post({
-        :path => api_path(event_collection),
-        :headers => api_headers_with_auth("async"),
-        :body => MultiJson.encode(properties)
-      })
-
-      if defined?(EM::Synchrony)
-        if http.error
-          Keen.logger.warn("Couldn't connect to Keen IO: #{http.error}")
-          raise HttpError.new("Couldn't connect to Keen IO: #{http.error}")
-        else
-          process_response(http.response_header.status, http.response.chomp)
-        end
-      else
-        http.callback {
-          begin
-            response = process_response(http.response_header.status, http.response.chomp)
-            deferrable.succeed(response)
-          rescue Exception => e
-            deferrable.fail(e)
-          end
-        }
-        http.errback {
-          Keen.logger.warn("Couldn't connect to Keen IO: #{http.error}")
-          deferrable.fail(Error.new("Couldn't connect to Keen IO: #{http.error}"))
-        }
-        deferrable
-      end
-    end
-
-    # deprecated
-    def add_event(event_collection, properties, options={})
-      self.publish(event_collection, properties, options)
-    end
-
     private
 
     def process_response(status_code, response_body)
@@ -126,21 +68,12 @@ module Keen
       end
     end
 
-    def api_path(event_collection)
-      "/#{api_version}/projects/#{project_id}/events/#{URI.escape(event_collection)}"
-    end
-
-    def api_headers_with_auth(sync_or_async)
-      api_headers(sync_or_async)
-    end
-
-    def check_configuration!
-      raise ConfigurationError, "Project ID must be set" unless project_id
+    def ensure_project_id!
+      raise ConfigurationError, "Project ID must be set" unless self.project_id
     end
 
-    def check_event_data!(event_collection, properties)
-      raise ArgumentError, "Event collection can not be nil" unless event_collection
-      raise ArgumentError, "Event properties can not be nil" unless properties
+    def ensure_api_key!
+      raise ConfigurationError, "API Key must be set for queries" unless self.api_key
     end
 
     def method_missing(_method, *args, &block)

data/lib/keen/client/publishing_methods.rb

@@ -0,0 +1,111 @@
+module Keen
+  class Client
+    module PublishingMethods
+
+      # @deprecated
+      #
+      # Publishes a synchronous event
+      # @param event_collection
+      # @param [Hash] event properties
+      #
+      # @return the JSON response from the API
+      def add_event(event_collection, properties, options={})
+        self.publish(event_collection, properties, options)
+      end
+
+      # Publishes a synchronous event
+      # See detailed documentation here
+      # https://keen.io/docs/api/reference/#event-collection-resource
+      #
+      # @param event_collection
+      # @param [Hash] event properties
+      #
+      # @return the JSON response from the API
+      def publish(event_collection, properties)
+        ensure_project_id!
+        check_event_data!(event_collection, properties)
+
+        begin
+          response = Keen::HTTP::Sync.new(
+            api_host, api_port, api_sync_http_options).post(
+              :path => api_event_resource_path(event_collection),
+              :headers => api_headers("sync"),
+              :body => MultiJson.encode(properties))
+        rescue Exception => http_error
+          raise HttpError.new("Couldn't connect to Keen IO: #{http_error.message}", http_error)
+        end
+        process_response(response.code, response.body.chomp)
+      end
+
+      # Publishes an asynchronous event
+      # See detailed documentation here
+      # https://keen.io/docs/api/reference/#event-collection-resource
+      #
+      # @param event_collection
+      # @param [Hash] event properties
+      #
+      # @return a deferrable to apply callbacks to
+      def publish_async(event_collection, properties)
+        ensure_project_id!
+        check_event_data!(event_collection, properties)
+
+        deferrable = EventMachine::DefaultDeferrable.new
+
+        http_client = Keen::HTTP::Async.new(api_host, api_port, api_async_http_options)
+        http = http_client.post({
+          :path => api_event_resource_path(event_collection),
+          :headers => api_headers("async"),
+          :body => MultiJson.encode(properties)
+        })
+
+        if defined?(EM::Synchrony)
+          if http.error
+            Keen.logger.warn("Couldn't connect to Keen IO: #{http.error}")
+            raise HttpError.new("Couldn't connect to Keen IO: #{http.error}")
+          else
+            process_response(http.response_header.status, http.response.chomp)
+          end
+        else
+          http.callback {
+            begin
+              response = process_response(http.response_header.status, http.response.chomp)
+              deferrable.succeed(response)
+            rescue Exception => e
+              deferrable.fail(e)
+            end
+          }
+          http.errback {
+            Keen.logger.warn("Couldn't connect to Keen IO: #{http.error}")
+            deferrable.fail(Error.new("Couldn't connect to Keen IO: #{http.error}"))
+          }
+          deferrable
+        end
+      end
+
+      # Returns an encoded URL that will record an event. Useful in email situations.
+      # See detailed documentation here
+      # https://keen.io/docs/api/reference/#event-collection-resource
+      #
+      # @param event_collection
+      # @param [Hash] event properties
+      #
+      # @return a URL that will track an event when hit
+      def beacon_url(event_collection, properties)
+        json = MultiJson.encode(properties)
+        data = [json].pack("m0").tr("+/", "-_").gsub("\n", "")
+        "https://#{api_host}#{api_event_resource_path(event_collection)}?data=#{data}"
+      end
+
+      private
+
+      def api_event_resource_path(event_collection)
+        "/#{api_version}/projects/#{project_id}/events/#{URI.escape(event_collection)}"
+      end
+
+      def check_event_data!(event_collection, properties)
+        raise ArgumentError, "Event collection can not be nil" unless event_collection
+        raise ArgumentError, "Event properties can not be nil" unless properties
+      end
+    end
+  end
+end

data/lib/keen/client/querying_methods.rb

@@ -0,0 +1,199 @@
+module Keen
+  class Client
+    module QueryingMethods
+
+      # Runs a count query.
+      # See detailed documentation here:
+      # https://keen.io/docs/api/reference/#count-resource
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      def count(event_collection, params={})
+        query(__method__, event_collection, params)
+      end
+
+      # Runs a count unique query.
+      # See detailed documentation here:
+      # https://keen.io/docs/api/reference/#count-unique-resource
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   target_property (required)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      def count_unique(event_collection, params)
+        query(__method__, event_collection, params)
+      end
+
+      # Runs a minimum query.
+      # See detailed documentation here:
+      # https://keen.io/docs/api/reference/#minimum-resource
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   target_property (required)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      def minimum(event_collection, params)
+        query(__method__, event_collection, params)
+      end
+
+      # Runs a maximum query.
+      # See detailed documentation here:
+      # https://keen.io/docs/api/reference/#maximum-resource
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   target_property (required)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      def maximum(event_collection, params)
+        query(__method__, event_collection, params)
+      end
+
+      # Runs a sum query.
+      # See detailed documentation here:
+      # https://keen.io/docs/api/reference/#sum-resource
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   target_property (required)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      def sum(event_collection, params)
+        query(__method__, event_collection, params)
+      end
+
+      # Runs a average query.
+      # See detailed documentation here:
+      # https://keen.io/docs/api/reference/#average-resource
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   target_property (required)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      def average(event_collection, params)
+        query(__method__, event_collection, params)
+      end
+
+      # Runs a select_unique query.
+      # See detailed documentation here:
+      # https://keen.io/docs/api/reference/#select-unique-resource
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   target_property (required)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      def select_unique(event_collection, params)
+        query(__method__, event_collection, params)
+      end
+
+      # Runs a extraction query.
+      # See detailed documentation here:
+      # https://keen.io/docs/api/reference/#extraction-resource
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   target_property (required)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      #   latest (optional)
+      def extraction(event_collection, params={})
+        query(__method__, event_collection, params)
+      end
+
+      # Runs a funnel query.
+      # See detailed documentation here:
+      # https://keen.io/docs/api/reference/#funnel-resource
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   steps (required)
+      def funnel(params)
+        query(__method__, nil, params)
+      end
+
+      private
+
+      def query(query_name, event_collection, params)
+        ensure_project_id!
+        ensure_api_key!
+
+        params[:api_key] = self.api_key
+
+        if event_collection
+          params[:event_collection] = event_collection
+        end
+
+        query_params = preprocess_params(params)
+
+        begin
+          response = Keen::HTTP::Sync.new(
+            api_host, api_port, api_sync_http_options).get(
+              :path => "#{api_query_resource_path(query_name)}?#{query_params}",
+              :headers => api_headers("sync"))
+        rescue Exception => http_error
+          raise HttpError.new("Couldn't perform #{query_name} on Keen IO: #{http_error.message}", http_error)
+        end
+
+        response_body = response.body.chomp
+        process_response(response.code, response_body)["result"]
+      end
+
+      def preprocess_params(params)
+        if params.key?(:filters)
+          params[:filters] = MultiJson.encode(params[:filters])
+        end
+
+        if params.key?(:steps)
+          params[:steps] = MultiJson.encode(params[:steps])
+        end
+
+        if params.key?(:timeframe) && params[:timeframe].is_a?(Hash)
+          params[:timeframe] = MultiJson.encode(params[:timeframe])
+        end
+
+        query_params = ""
+        params.each do |param, value|
+          query_params << "#{param}=#{URI.escape(value)}&"
+        end
+
+        query_params.chop!
+        query_params
+      end
+
+      def api_query_resource_path(analysis_type)
+        "/#{self.api_version}/projects/#{self.project_id}/queries/#{analysis_type}"
+      end
+    end
+  end
+end
+