keen 0.8.4 → 0.8.5

data/README.md

@@ -1,6 +1,7 @@
 # Keen IO Official Ruby Client Library
 
 [![Build Status](https://secure.travis-ci.org/keenlabs/keen-gem.png?branch=master)](http://travis-ci.org/keenlabs/keen-gem) [![Code Climate](https://codeclimate.com/github/keenlabs/keen-gem.png)](https://codeclimate.com/github/keenlabs/keen-gem)
+[![Gem Version](https://badge.fury.io/rb/keen.svg)](http://badge.fury.io/rb/keen)
 
 keen-gem is the official Ruby Client for the [Keen IO](https://keen.io/) API. The
 Keen IO API lets developers build analytics features directly into their apps.
@@ -48,7 +49,7 @@ environment-based approach because it keeps sensitive information out of the cod
 
 Once your environment is properly configured, the `Keen` object is ready to go immediately.
 
-### Publishing events
+### Synchronous Publishing
 
 Publishing events requires that `KEEN_WRITE_KEY` is set. Publish an event like this:
 
@@ -57,18 +58,17 @@ 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. 
-The event properties can be any valid Ruby hash and nested properties are allowed. You can learn more about data modeling with Keen IO with the [Data Modeling Guide](https://keen.io/docs/event-data-modeling/event-data-intro/).
+The event properties can be any valid Ruby hash. Nested properties are allowed. Lists of objects are also allowed, but not recommended because they can be difficult to query over. See alternatives to lists of objects [here](http://stackoverflow.com/questions/24620330/nested-json-objects-in-keen-io). You can learn more about data modeling with Keen IO with the [Data Modeling Guide](https://keen.io/docs/event-data-modeling/event-data-intro/). 
+
+Protip: Marshalling gems like [Blockhead](https://github.com/vinniefranco/blockhead) make converting structs or objects to hashes easier.
 
 The event collection need not exist in advance. If it doesn't exist, Keen IO will create it on the first request.
 
 ### Asynchronous publishing
 
-Publishing events shouldn't slow your application down or make
-users wait longer for page loads & server requests.
+Publishing events shouldn't slow your application down or make users wait longer for page loads & server requests.
 
-The Keen IO API is fast, but any synchronous network call you make will
-negatively impact response times. For this reason, we recommend you use the `publish_async`
-method to send events.
+The Keen IO API is fast, but any synchronous network call you make will negatively impact response times. For this reason, we recommend you use the `publish_async` method to send events when latency is a concern. Alternatively, you can drop events into a background queue e.g. Delayed Jobs and publish synchronously from there.
 
 To compare asychronous vs. synchronous performance, check out the [keen-gem-example](http://keen-gem-example.herokuapp.com/) app.
 
@@ -91,7 +91,7 @@ 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 useful 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 an example repository that shows an example of [Eventmachine with Unicorn](https://github.com/dzello/em-unicorn/blob/master/unicorn.rb), specifically the Unicorn config for starting and stopping EventMachine after forking.
+And here's a gist that shows an example of [Eventmachine with Unicorn](https://gist.github.com/jonkgrimes/5103321), specifically the Unicorn config for starting and stopping EventMachine after forking.
 
 Now, in your code, replace `publish` with `publish_async`. Bind callbacks if you require them.
 
@@ -143,6 +143,32 @@ Many of these queries can be performed with group by, filters, series and interv
 
 Detailed information on available parameters for each API resource can be found on the [API Technical Reference](https://keen.io/docs/api/reference/).
 
+##### The Query Method
+
+You can also specify the analysis type as a parameter to a method called `query`:
+
+``` ruby
+Keen.query("median", "purchases", :target_property => "price")  # => 60
+```
+
+This simplifes querying code where the analysis type is dynamic.
+
+##### Getting Query URLs
+
+Sometimes you just want the URL for a query, but don't actually need to run it. Maybe to paste into a dashboard, or open in your browser. In that case, use the `query_url` method:
+
+``` ruby
+Keen.query_url("median", "purchases", :target_property => "price")
+# => "https://api.keen.io/3.0/projects/<project-id>/queries/median?target_property=price&event_collection=purchases&api_key=<api-key>"
+```
+
+If you don't want the API key included, pass the `:exclude_api_key` option:
+
+``` ruby
+Keen.query_url("median", "purchases", { :target_property => "price" }, :exclude_api_key => true)
+# => "https://api.keen.io/3.0/projects/<project-id>/queries/median?target_property=price&event_collection=purchases"
+```
+
 ### Listing collections
 
 The Keen IO API let you get the event collections for the project set, it includes properties and their type. It also returns links to the collection resource.
@@ -297,6 +323,10 @@ EventMachine itself won't do this because it runs in a different thread. Here's
 
 ### Changelog
 
+##### 0.8.5
++ Add support for getting [query URLs](https://github.com/keenlabs/keen-gem/pull/47)
++ Make the `query` method public so code supporting dynamic analysis types is easier to write
+
 ##### 0.8.4
 + Add support for getting [project details](https://keen.io/docs/api/reference/#project-row-resource)
 

data/lib/keen.rb

@@ -49,7 +49,8 @@ module Keen
     def_delegators :default_client,
                    :delete,
                    :event_collections,
-                   :project_info
+                   :project_info,
+                   :query_url
 
     attr_writer :logger
 

data/lib/keen/client/querying_methods.rb

@@ -191,33 +191,58 @@ module Keen
         query(__method__, event_collection, params)
       end
 
+      # Returns the URL for a Query without running it
+      # @param event_colection
+      # @param params [Hash] (required)
+      #   analysis_type (required)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      # @param options
+      #   exclude_api_key
+      def query_url(analysis_type, event_collection, params={}, options={})
+        str = _query_url(analysis_type, event_collection, params)
+        str << "&api_key=#{self.read_key}" unless options[:exclude_api_key]
+        str
+      end
+
+      # Run a query
+      # @param event_colection
+      # @param params [Hash] (required)
+      #   analysis_type (required)
+      #   group_by (optional)
+      #   timeframe (optional)
+      #   interval (optional)
+      #   filters (optional) [Array]
+      #   timezone (optional)
+      def query(analysis_type, event_collection, params={})
+        url = _query_url(analysis_type, event_collection, params)
+        response = get_response(url)
+        response_body = response.body.chomp
+        process_response(response.code, response_body)["result"]
+      end
+
       private
 
-      def query(query_name, event_collection, params)
-        query_params = clone_params(params)
+      def _query_url(analysis_type, event_collection, params={})
         ensure_project_id!
         ensure_read_key!
 
-        if event_collection
-          query_params[:event_collection] = event_collection.to_s
-        end
-
-        query_params = preprocess_params(query_params)
-
-        begin
-          response = Keen::HTTP::Sync.new(self.api_url, self.proxy_url).get(
-              :path => "#{api_query_resource_path(query_name)}?#{query_params}",
-              :headers => api_headers(self.read_key, "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"]
+        query_params = params.dup
+        query_params[:event_collection] = event_collection.to_s if event_collection
+        "#{self.api_url}#{api_query_resource_path(analysis_type)}?#{preprocess_params(query_params)}"
       end
 
-      def clone_params(params)
-        params.dup
+      def get_response(url)
+        uri = URI.parse(url)
+        Keen::HTTP::Sync.new(self.api_url, self.proxy_url).get(
+          :path => "#{uri.path}?#{uri.query}",
+          :headers => api_headers(self.read_key, "sync")
+        )
+      rescue Exception => http_error
+        raise HttpError.new("Couldn't perform #{@analysis_type} on Keen IO: #{http_error.message}", http_error)
       end
 
       def api_query_resource_path(analysis_type)

data/lib/keen/version.rb

@@ -1,3 +1,3 @@
 module Keen
-  VERSION = "0.8.4"
+  VERSION = "0.8.5"
 end

data/spec/keen/client/querying_methods_spec.rb

@@ -172,4 +172,22 @@ describe Keen::Client do
       expect_keen_get(url, "sync", read_key)
     end
   end
+
+  describe "#query_url" do
+    let(:expected) {  }
+
+    it "should returns the URL for a query" do
+      response = client.query_url('count', event_collection)
+      expect(response).to eq 'https://notreal.keen.io/3.0/projects/12345/queries/count?event_collection=users&api_key=abcde'
+    end
+
+    it "should exclude the api key if option is passed" do
+      response = client.query_url('count', event_collection, {}, :exclude_api_key => true)
+      expect(response).to eq 'https://notreal.keen.io/3.0/projects/12345/queries/count?event_collection=users'
+    end
+
+    it "should not run the query" do
+      Keen::HTTP::Sync.should_not receive(:new)
+    end
+  end
 end

data/spec/keen/keen_spec.rb

@@ -94,6 +94,7 @@ describe Keen do
     # pull the query methods list at runtime in order to ensure
     # any new methods have a corresponding delegator
     Keen::Client::QueryingMethods.instance_methods.each do |_method|
+      next if _method.to_sym == :query
       it "should forward the #{_method} query method" do
         @default_client.should_receive(_method).with("users", {})
         Keen.send(_method, "users", {})

metadata

@@ -1,184 +1,79 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: keen
-version: !ruby/object:Gem::Version
-  version: 0.8.4
+version: !ruby/object:Gem::Version 
+  hash: 53
   prerelease: 
+  segments: 
+  - 0
+  - 8
+  - 5
+  version: 0.8.5
 platform: ruby
-authors:
+authors: 
 - Kyle Wild
 - Josh Dzielak
 - Daniel Kador
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-03 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2014-08-01 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: multi_json
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.3'
-- !ruby/object:Gem::Dependency
-  name: addressable
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
-        version: 2.3.5
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 1
+        - 3
+        version: "1.3"
   type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: addressable
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 2
+        - 3
+        - 5
         version: 2.3.5
-- !ruby/object:Gem::Dependency
-  name: guard
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: guard-rspec
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rb-inotify
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rb-fsevent
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rb-fchange
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: ruby_gntp
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: ruby-debug
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rb-readline
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
   type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: debugger
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *id003
 description: Send events and build analytics features into your Ruby applications.
 email: josh@keen.io
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - .rspec
 - .travis.yml
@@ -210,32 +105,41 @@ files:
 - spec/spec_helper.rb
 - spec/synchrony/spec_helper.rb
 - spec/synchrony/synchrony_spec.rb
+has_rdoc: true
 homepage: https://github.com/keenlabs/keen-gem
-licenses:
+licenses: 
 - MIT
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Keen IO API Client
-test_files:
+test_files: 
 - spec/integration/api_spec.rb
 - spec/integration/spec_helper.rb
 - spec/keen/client/maintenance_methods_spec.rb