parse-stack 1.7.4 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adfaf3f682758219d766199934910e0f885bbe3770d5aba4ceb73e575b29a236
-  data.tar.gz: 0ae3f2fba6aa06d1ecc9eb01fd1110066813eed944ec610b1b76c31e55a4a7da
+  metadata.gz: fb8e8c64fc1b8ada3c5746964e7e0cb122a14b6285c40bad92ca99940784ea58
+  data.tar.gz: 52e4ef4525970ec793f7bd309d6fb9c679c3e7ff433cad8b94329c49c8d40c43
 SHA512:
-  metadata.gz: 182fba0ec6563b3c3946d5fdb10d6ad66d9a6777a1c8df8e048935f786c2be1c08e1291b6f586e7cb81b304826cf30581fd5aa1a05be060033c4a21279551264
-  data.tar.gz: 5184b7124197babce5fd543c04096b4ca1284be8be44b0f1df2167b8a8ba813709a11d08007c73194f6c7ca321d97056ac9fd41fdbe7d8da6bf27de825cd17af
+  metadata.gz: ca5320827dbb4fa24950f2fd65dbf7f45d5661e1de379706eb29cb8c3b6a8651b8109eacd6224988455112aaf5b9eba7e0a996281cf79c5ca36db9aedcef160c
+  data.tar.gz: d24aa327c2c77513e26d9a5993ce039ef3a790474dd3c23d8a5a12649d9e24aedc4888da74fd52312ff631800b8be91460e16f5447f84ea7fde4bcd02f5aeb4d

data/.travis.yml

@@ -1,7 +1,7 @@
 language: ruby
 rvm:
-  - 2.2.2
-  - 2.3.2
-  - 2.4.1
+  - 2.3.7
+  - 2.4.4
   - 2.5.1
-before_install: gem install bundler -v 1.16.2
+  - 2.6.0
+before_install: gem install bundler

data/Changes.md

@@ -1,5 +1,10 @@
 ## Parse-Stack Changelog
 
+### 1.8.0
+- NEW: Support for Parse Server [full text search](https://github.com/modernistik/parse-stack#full-text-search-constraint) with the `text_search` operator. Related to [Issue#46](https://github.com/modernistik/parse-stack/issues/46).
+- NEW: Support for `:distinct` aggregation query. Finds the distinct values for a specified field across a single collection or view and returns the results in an array.
+  For example, `User.distinct(:city, :created_at.after => 3.days.ago)` to return an array of unique city names for which records were created in the last 3 days.
+
 ### 1.7.4
 - NEW: Added `parse_object` extension to Hash classes to more easily call
   Parse::Object.build in `map` loops with symbol to proc.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack (1.7.4)
+    parse-stack (1.8.0)
       active_model_serializers (>= 0.9, < 1)
       activemodel (>= 4.2.1, < 6)
       activesupport (>= 4.2.1, < 6)
@@ -14,15 +14,15 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (5.2.0)
-      actionview (= 5.2.0)
-      activesupport (= 5.2.0)
+    actionpack (5.2.1)
+      actionview (= 5.2.1)
+      activesupport (= 5.2.1)
       rack (~> 2.0)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.2.0)
-      activesupport (= 5.2.0)
+    actionview (5.2.1)
+      activesupport (= 5.2.1)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
@@ -32,9 +32,9 @@ GEM
       activemodel (>= 4.1, < 6)
       case_transform (>= 0.2)
       jsonapi-renderer (>= 0.1.1.beta1, < 0.3)
-    activemodel (5.2.0)
-      activesupport (= 5.2.0)
-    activesupport (5.2.0)
+    activemodel (5.2.1)
+      activesupport (= 5.2.1)
+    activesupport (5.2.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
@@ -50,14 +50,14 @@ GEM
     crass (1.0.4)
     daemons (1.2.6)
     debug_inspector (0.0.3)
-    dotenv (2.4.0)
+    dotenv (2.5.0)
     erubi (1.7.1)
     eventmachine (1.2.7)
-    faraday (0.15.2)
+    faraday (0.15.3)
       multipart-post (>= 1.2, < 3)
     faraday_middleware (0.12.2)
       faraday (>= 0.7.4, < 1.0)
-    i18n (1.0.1)
+    i18n (1.1.0)
       concurrent-ruby (~> 1.0)
     jsonapi-renderer (0.2.0)
     loofah (2.2.2)
@@ -68,7 +68,7 @@ GEM
     minitest (5.11.3)
     moneta (1.0.0)
     multipart-post (2.0.0)
-    nokogiri (1.8.2)
+    nokogiri (1.8.4)
       mini_portile2 (~> 2.3.0)
     parallel (1.12.1)
     pry (0.10.4)
@@ -81,7 +81,7 @@ GEM
       binding_of_caller (>= 0.7)
       pry (>= 0.9.11)
     rack (2.0.5)
-    rack-test (1.0.0)
+    rack-test (1.1.0)
       rack (>= 1.0, < 3)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
@@ -90,7 +90,7 @@ GEM
       loofah (~> 2.2, >= 2.2.2)
     rake (12.3.1)
     redcarpet (3.4.0)
-    redis (4.0.1)
+    redis (4.0.2)
     slop (3.6.0)
     thin (1.7.2)
       daemons (~> 1.0, >= 1.0.9)
@@ -99,7 +99,7 @@ GEM
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
-    yard (0.9.13)
+    yard (0.9.16)
 
 PLATFORMS
   ruby

data/README.md

@@ -6,6 +6,10 @@
 
 Below is a [quick start guide](https://github.com/modernistik/parse-stack#overview), but you can also check out the full *[API Reference](https://www.modernistik.com/gems/parse-stack/index.html)* for more detailed information about our Parse Server SDK.
 
+### Hire Us
+
+Interested in our work? You can find us here: [https://www.modernistik.com](https://www.modernistik.com)
+
 ### Code Status
 [![Gem Version](https://img.shields.io/gem/v/parse-stack.svg)](https://github.com/modernistik/parse-stack)
 [![Downloads](https://img.shields.io/gem/dt/parse-stack.svg)](https://rubygems.org/gems/parse-stack)
@@ -134,7 +138,7 @@ result = Parse.call_function :myFunctionName, {param: value}
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Overview](#overview)
+
 - [Architecture](#architecture)
   - [Parse::Client](#parseclient)
   - [Parse::Query](#parsequery)
@@ -203,6 +207,7 @@ result = Parse.call_function :myFunctionName, {param: value}
 - [Advanced Querying](#advanced-querying)
   - [Results Caching](#results-caching)
   - [Counting](#counting)
+  - [Distinct Aggregation](#distinct-aggregation)
   - [Query Expressions](#query-expressions)
     - [:order](#order)
     - [:keys](#keys)
@@ -235,6 +240,7 @@ result = Parse.call_function :myFunctionName, {param: value}
     - [Max Distance Constraint](#max-distance-constraint)
     - [Bounding Box Constraint](#bounding-box-constraint)
     - [Polygon Area Constraint](#polygon-area-constraint)
+    - [Full Text Search Constraint](#full-text-search-constraint)
   - [Relational Queries](#relational-queries)
   - [Compound Queries](#compound-queries)
 - [Query Scopes](#query-scopes)
@@ -1730,7 +1736,8 @@ When a query API is made, the results are cached in the query object in case you
 ```
 
 ### Counting
-If you only need to know the result count for a query, provide count a non-zero value. However, if you need to perform a count query, use `count()` method instead.
+If you only need to know the result count for a query, provide count a
+non-zero value. However, if you need to perform a count query, use `count()` method instead.
 
 ```ruby
  # get number of songs with a play_count > 10
@@ -1743,6 +1750,23 @@ If you only need to know the result count for a query, provide count a non-zero
 
 ```
 
+### Distinct Aggregation
+Finds the distinct values for a specified field across a single collection or
+view and returns the results in an array. You may mix this with additional query constraints.
+
+```ruby
+ # Return a list of unique city names
+ # for users created in the last 10 days.
+ User.distinct :city, :created_at.after => 10.days.ago
+ # ex. ["San Diego", "Los Angeles", "San Juan"]
+
+ # same
+ query = Parse::Query.new("_User")
+ query.where :created_at.after => 10.days.ago
+ query.distinct(:city) #=> ["San Diego", "Los Angeles", "San Juan"]
+
+```
+
 ### Query Expressions
 The set of supported expressions based on what is available through the Parse REST API. _For those who don't prefer the DataMapper style syntax, we have provided method accessors for each of the expressions._ A full description of supported query  operations, please refer to the [`Parse::Query`](https://www.modernistik.com/gems/parse-stack/Parse/Query.html) API reference.
 
@@ -1785,16 +1809,16 @@ Use on Pointer columns to return the full object. You may chain multiple columns
 ```
 
 #### :limit
-Limit the number of objects returned by the query. The default is 100, with Parse allowing a maximum of 1000. The framework also allows a value of `:max`. Utilizing this will have the framework continually intelligently utilize `:skip` to continue to paginate through results until an empty result set is received or the `:skip` limit is reached (10,000). When utilizing `all()`, `:max` is the default option for `:limit`.
+Limit the number of objects returned by the query. The default is 100, with Parse allowing a maximum of 1000. The framework also allows a value of `:max`. Utilizing this will have the framework continually intelligently utilize `:skip` to continue to paginate through results until an empty result set is received or the `:skip` limit is reached. When utilizing `all()`, `:max` is the default option for `:limit`.
 
 ```ruby
  Song.all :limit => 1 # same as Song.first
  Song.all :limit => 1000 # maximum allowed by Parse
- Song.all :limit => :max # up to 11,000 records (theoretical).
+ Song.all :limit => :max
 ```
 
 #### :skip
-Use with limit to paginate through results. Default is 0 with maximum value being 10,000.
+Use with limit to paginate through results. Default is 0.
 
 ```ruby
  # get the next 3 songs after the first 10
@@ -2150,6 +2174,30 @@ Equivalent to the `$geoWithin` Parse query operation and `$polygon` geopoint con
  SunkenShip.all :location.within_polygon => [bermuda, san_juan, miami]
 ```
 
+#### [Full Text Search Constraint](https://www.modernistik.com/gems/parse-stack/Parse/Constraint/FullTextSearchQueryConstraint.html)
+Equivalent to the `$text` Parse query operation and `$search` parameter constraint for efficient search capabilities. By creating indexes on one or more columns your strings are turned into tokens for full text search functionality. The `$search` key can take any number of parameters in hash form. *Requires Parse Server 2.5.0 or later*
+
+```ruby
+ # Do a full text search on "anthony"
+ q.where :field.text_search => "anthony"
+
+ # perform advance searches
+ q.where :field.text_search => {term: "anthony", case_insensitive: true}
+ # equivalent
+ q.where :field.text_search => {:$term => "anthony", :$caseInsensitive => true}
+```
+
+You may use the following keys for the parameters clause.
+
+| Parameter | Use |
+| :--- | :----- |
+| `$term`               | Specify a field to search (**Required**)|
+| `$language`           | Determines the list of stop words and the rules for tokenizer.|
+| `$caseSensitive`      | Enable or disable case sensitive search.|
+| `$diacriticSensitive` | Enable or disable diacritic sensitive search.|
+
+For additional details, please see [Query on String Values](https://docs.parseplatform.org/rest/guide/#queries-on-string-values).
+
 ### Relational Queries
 Equivalent to the `$relatedTo` Parse query operation. If you want to retrieve objects that are members of a `Relation` field in your Parse class.
 
@@ -2610,10 +2658,6 @@ end
 
 ```
 
-## Hire Us
-
-Interested in our consulting work? You can find us here: [https://www.modernistik.com](https://www.modernistik.com)
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/modernistik/parse-stack](https://github.com/modernistik/parse-stack).

data/lib/parse/api/aggregate.rb

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext'
+require_relative './objects'
+module Parse
+
+  module API
+    # REST API methods for fetching CRUD operations on Parse objects.
+    module Aggregate
+      # The class prefix for fetching objects.
+      # @!visibility private
+      PATH_PREFIX = "aggregate/"
+
+      # @!visibility private
+      PREFIX_MAP = Parse::API::Objects::PREFIX_MAP
+
+      # @!visibility private
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class methods to be applied to {Parse::Client}
+      module ClassMethods
+        # Get the aggregate API path for this class.
+        # @param className [String] the name of the Parse collection.
+        # @return [String] the API uri path
+        def aggregate_uri_path(className)
+          if className.is_a?(Parse::Pointer)
+            id = className.id
+            className = className.parse_class
+          end
+          "#{PATH_PREFIX}#{className}"
+        end
+
+      end
+
+      # Get the API path for this class.
+      # @param className [String] the name of the Parse collection.
+      # @return [String] the API uri path
+      def aggregate_uri_path(className)
+        self.class.aggregate_uri_path(className)
+      end
+
+      # Aggregate a set of matching objects for a query.
+      # @param className [String] the name of the Parse collection.
+      # @param query [Hash] The set of query constraints.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      # @see Parse::Query
+      def aggregate_objects(className, query = {}, headers: {}, **opts)
+        response = request :get, aggregate_uri_path(className), query: query, headers: headers, opts: opts
+        response.parse_class = className if response.present?
+        response
+      end
+
+    end #Aggregate
+  end #API
+
+end

data/lib/parse/api/all.rb

@@ -3,6 +3,7 @@
 
 require_relative '../client'
 require_relative "analytics"
+require_relative "aggregate"
 require_relative "batch"
 require_relative "config"
 require_relative "files"

data/lib/parse/client.rb

@@ -107,6 +107,7 @@ module Parse
   # features you'd like to implement.
   class Client
     include Parse::API::Analytics
+    include Parse::API::Aggregate
     include Parse::API::Batch
     include Parse::API::CloudFunctions
     include Parse::API::Config

data/lib/parse/model/core/querying.rb

@@ -252,6 +252,19 @@ module Parse
           query(constraints).count
         end
 
+        # Finds the distinct values for a specified field across a single
+        # collection or view and returns the results in an array.
+        # @example
+        #  # get a list of unique city names for users who are older than 21.
+        #  cities = User.distinct(:city, :age.gt => 21 )
+        # @param field The name of the field to use for unique aggregation.
+        # @param constraints (see #all)
+        # @return [Array] a list of distinct values
+        # @see Parse::Query#distinct
+        def distinct(field, constraints = {})
+          query(constraints).distinct(field)
+        end
+
         # Find objects matching the constraint ordered by the descending created_at date.
         # @param constraints (see #all)
         # @return [Array<Parse::Object>]

data/lib/parse/query.rb

@@ -314,7 +314,7 @@ module Parse
         elsif expression == :keys
           keys value
         elsif expression == :key
-          @key = value
+          keys [value]
         elsif expression == :skip
           skip value
         elsif expression == :limit
@@ -434,7 +434,7 @@ module Parse
     #  Song.all :limit => 2025 # large limits supported.
     #  Song.all :limit => :max # as many records as possible.
     # @param count [Integer,Symbol] The number of records to return. You may pass :max
-    #  to get as many as 11_000 records with the aid if skipping.
+    #  to get as many records as possible (Parse-Server dependent).
     # @return [self]
     def limit(count)
       if count.is_a?(Numeric)
@@ -497,10 +497,15 @@ module Parse
     #  # add where :like_count is greater than 20
     #  query.add_constraint(:like_count.gt, 20)
     #
+    #  # same, but ignore field formatting
+    #  query.add_constraint(:like_count.gt, 20, filter: false)
+    #
     # @param operator [Parse::Operator] an operator object containing the operation and operand.
     # @param value [Object] the value for the constraint.
+    # @param opts [Object] A set of options. Passing :filter with false, will skip field formatting.
+    # @see Query#format_field
     # @return [self]
-    def add_constraint(operator, value = nil, **opts)
+    def add_constraint(operator, value = nil, opts = {})
       @where ||= []
       constraint = operator # assume Parse::Constraint
       unless constraint.is_a?(Parse::Constraint)
@@ -607,6 +612,35 @@ module Parse
         copy_query
     end
 
+    # Queries can be made using distinct, allowing you find unique values for a specified field.
+    # For this to be performant, please remember to index your database.
+    # @example
+    #   # Return a set of unique city names
+    #   # for users who are greater than 21 years old
+    #   Parse::Query.all(distinct: :age)
+    #   query = Parse::Query.new("_User")
+    #   query.where :age.gt => 21
+    #   # triggers query
+    #   query.distinct(:city) #=> ["San Diego", "Los Angeles", "San Juan"]
+    # @note This feature requires use of the Master Key in the API.
+    # @param field [Symbol|String] The name of the field used for filtering.
+    # @version 1.8.0
+    def distinct(field)
+      if field.nil? == false && field.respond_to?(:to_s)
+        # disable counting if it was enabled.
+        old_count_value = @count
+        @count = nil
+        compile_query = compile # temporary store
+        # add distinct field
+        compile_query[:distinct] = Query.format_field(field).to_sym
+        @count = old_count_value
+        # perform aggregation
+        return client.aggregate_objects(@table, compile_query.as_json, _opts ).result
+      else
+        raise ArgumentError, "Invalid field name passed to `distinct`."
+      end
+    end
+
     # Perform a count query.
     # @example
     #  # get number of songs with a play_count > 10

data/lib/parse/query/constraints.rb

@@ -714,6 +714,56 @@ module Parse
       end
     end
 
+
+    class FullTextSearchQueryConstraint < Constraint
+      # @!method text_search
+      # A registered method on a symbol to create the constraint. Maps to Parse
+      # operator "$text" with "$search" subconstraint. Takes a hash of parameters.
+      # @example
+      #  # As many points as you want
+      #  q.where :field.text_search => {parameters}
+      #
+      # Where `parameters` can be one of:
+      #   $term : Specify a field to search (Required)
+      #   $language : Determines the list of stop words and the rules for tokenizer.
+      #   $caseSensitive : Enable or disable case sensitive search.
+      #   $diacriticSensitive : Enable or disable diacritic sensitive search
+      #
+      # @note This method will automatically add `$` to each key of the parameters
+      # hash if it doesn't already have it.
+      # @return [WithinPolygonQueryConstraint]
+      # @version 1.8.0 (requires Server v2.5.0 or later)
+      contraint_keyword :$text
+      register :text_search
+
+      # @return [Hash] the compiled constraint.
+      def build
+        params = formatted_value
+
+        params = { :$term => params.to_s } if params.is_a?(String) || params.is_a?(Symbol)
+
+        unless params.is_a?(Hash)
+          raise ArgumentError, '[Parse::Query] Invalid query value parameter passed to'\
+                      ' `text_search` constraint: Value must be a string or a hash of parameters.'
+        end
+
+        params = params.inject({}) do |h,(k,v)|
+          u = k.to_s
+          u = u.columnize.prepend('$') unless u.start_with?('$')
+          h[u] = v
+          h
+        end
+
+        unless params["$term"].present?
+          raise ArgumentError, "[Parse::Query] Invalid query value parameter passed to"\
+                      " `text_search` constraint: Missing required `$term` subkey.\n"\
+                      "\tExample: #{@operation.operand}.text_search => { term: 'text to search' }"
+        end
+
+        { @operation.operand => { :$text => { :$search => params } } }
+      end
+    end
+
   end
 
 end

data/lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "1.7.4"
+    VERSION = "1.8.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parse-stack
 version: !ruby/object:Gem::Version
-  version: 1.7.4
+  version: 1.8.0
 platform: ruby
 authors:
 - Anthony Persaud
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-29 00:00:00.000000000 Z
+date: 2018-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -184,6 +184,7 @@ files:
 - bin/server
 - bin/setup
 - lib/parse-stack.rb
+- lib/parse/api/aggregate.rb
 - lib/parse/api/all.rb
 - lib/parse/api/analytics.rb
 - lib/parse/api/batch.rb