parse-stack-next 5.2.1 → 5.4.0

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

@@ -63,6 +63,54 @@ module Parse
       # binding it to a provider at the property level.
       class EmbedderNotConfigured < ArgumentError; end
 
+      # Accepted {#vector_visibility} modes.
+      VECTOR_VISIBILITY_MODES = %i[owner_only public].freeze
+
+      # Class-level default for whether this class's `:vector` properties
+      # are included in `as_json` serialization.
+      #
+      # * `:owner_only` (default) — vectors are OMITTED from `as_json`
+      #   unless the caller passes `include_vectors: true`. Embeddings are
+      #   large and leak ML signal; the safe default keeps them off the
+      #   wire and out of API responses. Row-level read access is still
+      #   governed by ACL as usual — this controls serialization exposure,
+      #   not row authorization.
+      # * `:public` — vectors are INCLUDED in `as_json` by default (a
+      #   caller can still suppress per-call with `include_vectors: false`).
+      #
+      #   class Article < Parse::Object
+      #     vector_visibility :public           # expose embeddings in as_json
+      #     property :embedding, :vector, dimensions: 1536, provider: :openai
+      #   end
+      #
+      # Read the effective mode by calling with no argument; it inherits
+      # from the superclass when unset on the subclass.
+      #
+      # @param mode [Symbol, nil] one of {VECTOR_VISIBILITY_MODES}, or nil
+      #   to read the current effective mode.
+      # @return [Symbol] the effective mode (when reading) or the mode set.
+      # @raise [ArgumentError] on an unknown mode.
+      def vector_visibility(mode = nil)
+        if mode.nil?
+          return @vector_visibility if defined?(@vector_visibility) && @vector_visibility
+          return superclass.vector_visibility if superclass.respond_to?(:vector_visibility)
+          return :owner_only
+        end
+        m = mode.to_sym
+        unless VECTOR_VISIBILITY_MODES.include?(m)
+          raise ArgumentError,
+                "#{self}.vector_visibility: mode must be one of " \
+                "#{VECTOR_VISIBILITY_MODES.inspect} (got #{mode.inspect})."
+        end
+        @vector_visibility = m
+      end
+
+      # @return [Boolean] whether `:vector` fields are serialized into
+      #   `as_json` by default for this class (true only for `:public`).
+      def vectors_public_by_default?
+        vector_visibility == :public
+      end
+
       # Find documents whose declared `:vector` property is closest to
       # `vector:` under the Atlas vectorSearch index's similarity
       # function.
@@ -169,6 +217,97 @@ module Parse
         build_vector_hits(raw_hits)
       end
 
+      # Hybrid (lexical + vector) search with reciprocal-rank fusion.
+      #
+      # Runs a lexical Atlas Search branch and a `$vectorSearch` branch
+      # independently, then fuses their ranked results client-side via RRF
+      # (or, on Atlas 8.0+, server-side via native `$rankFusion` when
+      # detected). Both branches enforce ACL/CLP/protectedFields before
+      # fusion — see {Parse::VectorSearch::Hybrid}.
+      #
+      # @example
+      #   Song.hybrid_search(
+      #     text: "love songs about rain",
+      #     lexical: { index: "song_search", query: "rain love" },
+      #     vector:  { num_candidates: 200 },
+      #     k: 20,
+      #     fusion: { k_constant: 60, weights: { lexical: 0.4, vector: 0.6 } },
+      #   )
+      #
+      # @param text [String, nil] natural-language query. Embedded (via
+      #   the resolved `:vector` property's `provider:`) for the vector
+      #   branch, and used as the lexical query unless `lexical[:query]`
+      #   overrides it.
+      # @param query_vector [Array<Float>, Parse::Vector, nil] pre-computed
+      #   query embedding (alternative to `text:` for the vector branch).
+      # @param lexical [Hash] lexical branch config (`:query`, `:index`,
+      #   `:fields`, `:filter`, `:fuzzy`). `:query` defaults to `text:`.
+      # @param vector [Hash] vector branch config (`:field`, `:index`,
+      #   `:num_candidates`, `:filter`, `:vector_filter`). `:field`
+      #   defaults to the class's sole `:vector` property; `:index` is
+      #   auto-discovered when omitted.
+      # @param k [Integer] number of fused hits to return.
+      # @param fusion [Hash, nil] `:method` (`:rrf` / `:rrf_client`),
+      #   `:k_constant`, `:weights` (`{ lexical:, vector: }`).
+      # @param raw [Boolean] return fused raw rows instead of built
+      #   Parse::Object instances.
+      # @param scope_opts [Hash] ACL/CLP scope kwargs forwarded to both
+      #   branches (`session_token:` / `master:` / `acl_user:` /
+      #   `acl_role:`).
+      # @return [Array<Parse::Object>] fused, RRF-ordered; each carries
+      #   `#hybrid_score` and `#hybrid_ranks` (and `#vector_score` /
+      #   `#search_score` when the branch contributed). `raw: true`
+      #   returns the fused Hashes.
+      def hybrid_search(text: nil, query_vector: nil, lexical: {}, vector: {},
+                        k: 20, fusion: nil, raw: false, **scope_opts)
+        require_relative "../../vector_search/hybrid"
+        lex = (lexical || {}).transform_keys(&:to_sym)
+        vec = (vector || {}).transform_keys(&:to_sym)
+
+        field_sym = resolve_vector_field!(vec[:field])
+        declared_dims = vector_properties.dig(field_sym, :dimensions)
+
+        qv = query_vector || vec[:query_vector]
+        qv =
+          if qv.nil?
+            unless text.is_a?(String) && !text.strip.empty?
+              raise ArgumentError,
+                    "#{self}.hybrid_search: pass `text:` (to embed) or a `query_vector:`."
+            end
+            embed_query_text!(text, field_sym)
+          else
+            coerce_query_vector(qv)
+          end
+        Parse::VectorSearch.validate_query_vector!(qv, dimensions: declared_dims)
+
+        lexical_query = lex[:query] || text
+        unless lexical_query.is_a?(String) && !lexical_query.strip.empty?
+          raise ArgumentError,
+                "#{self}.hybrid_search: needs a lexical query — pass `text:` or `lexical: { query: }`."
+        end
+
+        vector_index = vec[:index] || resolve_vector_index!(field_sym, nil)
+
+        fused = Parse::VectorSearch::Hybrid.search(
+          parse_class,
+          lexical: {
+            query: lexical_query, index: lex[:index], fields: lex[:fields],
+            filter: lex[:filter], fuzzy: lex[:fuzzy],
+          },
+          vector: {
+            query_vector: qv, field: field_sym, index: vector_index,
+            num_candidates: vec[:num_candidates], filter: vec[:filter],
+            vector_filter: vec[:vector_filter],
+          },
+          k: k,
+          fusion: fusion,
+          **scope_opts,
+        )
+
+        return fused if raw
+        build_hybrid_hits(fused)
+      end
+
       private
 
       def resolve_vector_field!(field)
@@ -280,6 +419,28 @@ module Parse
           obj
         end.compact
       end
+
+      # Build Parse::Object instances from fused hybrid rows, attaching
+      # the fused score / per-branch ranks plus whatever per-branch scores
+      # survived the merge (`_vscore`, `_score`).
+      def build_hybrid_hits(rows)
+        return [] if rows.nil? || rows.empty?
+        converted = Parse::MongoDB.convert_documents_to_parse(rows, parse_class)
+        converted.each_with_index.map do |doc, idx|
+          obj = Parse::Object.build(doc, parse_class)
+          next nil unless obj
+          src = rows[idx]
+          hscore = src["_hybrid_score"] || src[:_hybrid_score]
+          hranks = src["_hybrid_ranks"] || src[:_hybrid_ranks]
+          vscore = src["_vscore"] || src[:_vscore]
+          sscore = src["_score"] || src[:_score]
+          obj.instance_variable_set(:@_hybrid_score, hscore) unless hscore.nil?
+          obj.instance_variable_set(:@_hybrid_ranks, hranks) unless hranks.nil?
+          obj.instance_variable_set(:@_vector_score, vscore) unless vscore.nil?
+          obj.instance_variable_set(:@_search_score, sscore) unless sscore.nil?
+          obj
+        end.compact
+      end
     end
   end
 end

data/lib/parse/model/file.rb

@@ -734,10 +734,43 @@ module Parse
       ATTRIBUTES
     end
 
-    # @return [Boolean] Two files are equal if they have the same url
+    # The value used to decide whether two {Parse::File}s refer to the same
+    # underlying file -- for equality ({#==}) and, through it, for dirty
+    # tracking (the property setter compares files with `==` to decide whether
+    # a `:file` field changed).
+    #
+    # Today this is the bare canonical {#url}: signed-URL query parameters are
+    # stripped into `@presigned_url` and `force_ssl` coercion is applied, so two
+    # files at the same storage location compare equal regardless of how the URL
+    # was signed or whether it was `http`/`https`. The URL is the best identity
+    # signal currently available -- Parse Server's S3 files adapter does not
+    # surface a content digest (ETag / MD5 / sha256) through `Parse::File`.
+    #
+    # FUTURE DIRECTION: when a files adapter can expose a content hash, this is
+    # the single seam to override so equality keys off file *content* instead of
+    # URL -- e.g. a custom `Parse::File` subclass or adapter shim returning the
+    # S3 ETag / sha256 here. Overriding this one method updates {#==} (and a
+    # future `#eql?`/`#hash` pair, if added) without touching dirty tracking.
+    # No content-hash source exists yet, so the URL is authoritative for now.
+    # @return [String, nil]
+    def content_signature
+      url
+    end
+
+    # @return [Boolean] Two files are equal when their {#content_signature}
+    #   matches. Both sides go through the same reader, so the comparison is
+    #   symmetric and force_ssl-consistent: the previous `@url == u.url` form
+    #   compared one side's raw stored URL against the other's normalized
+    #   reader, so two files at the same location read as unequal whenever
+    #   {Parse::File.force_ssl} coerced one side from `http://` to `https://`
+    #   (and `a == b` disagreed with `b == a`). Because the default signature is
+    #   the bare canonical URL (signed-URL query parameters stripped into
+    #   `@presigned_url`), a freshly re-signed URL for the same object is equal
+    #   while a different underlying location is not. See {#content_signature}
+    #   for the content-hash override seam.
     def ==(u)
       return false unless u.is_a?(self.class)
-      @url == u.url
+      content_signature == u.content_signature
     end
 
     # Allows mass assignment from a Parse JSON hash.

data/lib/parse/model/object.rb

@@ -182,6 +182,14 @@ module Parse
     # @return [Hash, nil] Atlas Search highlights blob.
     def search_highlights; @_search_highlights; end
 
+    # @return [Float, nil] fused reciprocal-rank-fusion score from
+    #   `Class.hybrid_search`.
+    def hybrid_score; @_hybrid_score; end
+
+    # @return [Hash, nil] per-branch 1-based ranks from
+    #   `Class.hybrid_search` (`{ lexical:, vector: }`).
+    def hybrid_ranks; @_hybrid_ranks; end
+
     # @return [Model::TYPE_OBJECT]
     def __type; Parse::Model::TYPE_OBJECT; end
 
@@ -384,7 +392,12 @@ module Parse
       end
 
       # The set of default ACLs to be applied on newly created instances of this class.
-      # By default, public read and write are enabled unless {default_acl_private} is true.
+      # The result follows the class's {acl_policy_setting}: the shipped default
+      # policy is `:owner_else_private`, whose fallback half is {Parse::ACL.private}
+      # (an empty ACL — readable only by the master key until an owner is resolved
+      # at save time). Classes that opt into a `:public*` policy, or set
+      # {default_acl_private} / {set_default_acl}, get the corresponding permissions
+      # instead.
       # @see Parse::ACL.everyone
       # @see Parse::ACL.private
       # @return [Parse::ACL] the current default ACLs for this class.
@@ -398,8 +411,10 @@ module Parse
       end
 
       # A method to set default ACLs to be applied for newly created
-      # instances of this class. All subclasses have public read and write enabled
-      # by default.
+      # instances of this class. Unless overridden, subclasses inherit the
+      # shipped `:owner_else_private` policy (records are private/master-only
+      # until an owner is resolved at save time); use this method (or
+      # {acl_policy}) to grant broader access.
       # @example
       #  class AdminData < Parse::Object
       #
@@ -1223,8 +1238,16 @@ module Parse
       # signal to clients, and they round-trip through the dedicated
       # embed/find_similar pipelines rather than the standard REST
       # save/find. Pass `include_vectors: true` to opt back in (e.g.,
-      # for tests or internal mongo-direct bulk writes).
-      unless opts[:include_vectors] == true
+      # for tests or internal mongo-direct bulk writes). A class may flip
+      # the per-class default with `vector_visibility :public`; an explicit
+      # `include_vectors:` in the call always wins over the class default.
+      include_vectors =
+        if opts.key?(:include_vectors)
+          opts[:include_vectors] == true
+        else
+          self.class.respond_to?(:vectors_public_by_default?) && self.class.vectors_public_by_default?
+        end
+      unless include_vectors
         vector_fields = self.class.respond_to?(:fields) ? self.class.fields(:vector).keys.map(&:to_s) : []
         if vector_fields.any?
           except = Array(opts[:except]).map(&:to_s) | vector_fields

data/lib/parse/mongodb.rb

@@ -1499,7 +1499,7 @@ module Parse
       # @raise [Parse::ACLScope::ACLRequired] when neither
       #   `session_token:` nor `master: true` is supplied and
       #   {Parse::ACLScope.require_session_token} is enabled.
-      def aggregate(collection_name, pipeline, max_time_ms: nil, rewrite_lookups: nil, allow_internal_fields: false, session_token: nil, master: nil, acl_user: nil, acl_role: nil, read_preference: nil)
+      def aggregate(collection_name, pipeline, max_time_ms: nil, rewrite_lookups: nil, allow_internal_fields: false, session_token: nil, master: nil, acl_user: nil, acl_role: nil, read_preference: nil, hint: nil)
         # AS::N envelope. Payload is intentionally metadata-only —
         # `stage_count`, `stage_types`, `collection`, `scope`,
         # `result_count`, `max_time_ms`, `read_preference`. Pipeline
@@ -1620,6 +1620,11 @@ module Parse
 
         agg_opts = {}
         agg_opts[:max_time_ms] = max_time_ms if max_time_ms
+        # Forced index hint (Query#hint). Mirrors Parse Server's REST `hint`
+        # on the mongo-direct path so a bad plan diagnosed with `explain` can
+        # be corrected here too. Accepts an index name (String) or a key
+        # pattern (Hash).
+        agg_opts[:hint] = hint unless hint.nil?
         coll = collection(collection_name)
         if (mode = normalize_read_preference(read_preference))
           coll = coll.with(read: { mode: mode })
@@ -1838,6 +1843,7 @@ module Parse
         cursor = cursor.skip(options[:skip]) if options[:skip]
         cursor = cursor.sort(options[:sort]) if options[:sort]
         cursor = cursor.projection(options[:projection]) if options[:projection]
+        cursor = cursor.hint(options[:hint]) unless options[:hint].nil?
         cursor = cursor.max_time_ms(max_time_ms) if max_time_ms
         results = cursor.to_a
 

data/lib/parse/pipeline_security.rb

@@ -182,13 +182,15 @@ module Parse
     # that `Parse::AtlasSearch` calls do not break. `$vectorSearch` is
     # included for `Parse::VectorSearch` — like `$search`, it is a
     # read-only Atlas index stage and must be the FIRST stage of the
-    # pipeline (Atlas refuses it otherwise).
+    # pipeline (Atlas refuses it otherwise). `$rankFusion` (Atlas 8.0+)
+    # is the native server-side reciprocal-rank-fusion stage used by
+    # `Parse::VectorSearch::Hybrid` — also a read-only stage-0 operator.
     ALLOWED_STAGES = %w[
       $match $group $sort $project $limit $skip $unwind $lookup
       $count $addFields $set $unset $bucket $bucketAuto $facet
       $sample $sortByCount $replaceRoot $replaceWith $redact
       $graphLookup $unionWith
-      $search $searchMeta $listSearchIndexes $vectorSearch
+      $search $searchMeta $listSearchIndexes $vectorSearch $rankFusion
     ].freeze
 
     # Atlas operators that are valid only as the FIRST stage of a
@@ -202,7 +204,7 @@ module Parse
     # for full-text and vector search is the dedicated
     # `atlas_search` / `semantic_search` tools, not raw aggregate.
     STAGE0_ONLY_ATLAS_STAGES = %w[
-      $search $searchMeta $vectorSearch $listSearchIndexes
+      $search $searchMeta $vectorSearch $listSearchIndexes $rankFusion
     ].freeze
 
     # Cap on the length of a caller-supplied `$regex` (or the `regex:`

data/lib/parse/query/constraints.rb

@@ -499,6 +499,35 @@ module Parse
       end
     end
 
+    # Equivalent to the $containedBy Parse query operation. Matches documents
+    # where the array field's values are all within the supplied set (the
+    # inverse of {ContainsAllConstraint}: the field must be a *subset* of the
+    # provided array). The field column should be of type {Array} in your
+    # Parse class.
+    #
+    #  q.where :field.contained_by => [1, 2, 3]
+    #  q.where :tags.contained_by => ["ruby", "rails", "parse"]
+    #
+    # @see ContainsAllConstraint
+    # @see ContainedInConstraint
+    class ContainedByConstraint < Constraint
+      # @!method contained_by
+      # A registered method on a symbol to create the constraint.
+      # Maps to Parse operator "$containedBy".
+      # @example
+      #  q.where :tags.contained_by => ["ruby", "rails"]
+      # @return [ContainedByConstraint]
+      constraint_keyword :$containedBy
+      register :contained_by
+
+      # @return [Hash] the compiled constraint.
+      def build
+        val = formatted_value
+        val = [val].compact unless val.is_a?(Array)
+        { @operation.operand => { key => val } }
+      end
+    end
+
     # Array size constraint using MongoDB aggregation.
     # Parse Server does not natively support $size query constraint, so we use
     # MongoDB aggregation pipeline with $expr and $size to check array length.