parse-stack-next 5.3.0 → 5.4.0

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

@@ -128,6 +128,39 @@ module Parse
         base.extend(ClassMethods)
       end
 
+      # Recompute this record's managed embedding(s) in-place, NOW,
+      # without a save. Runs the same digest-tracked recompute the
+      # `before_save` callback runs: a provider call happens only when the
+      # source text/URL changed since the last embed (digest miss). Useful
+      # to populate the vector before inspecting it, or to force a refresh
+      # in a console.
+      #
+      # @param field [Symbol, nil] limit to one embed target; nil
+      #   recomputes every declared directive.
+      # @return [self]
+      # @raise [ArgumentError] when `field:` names no embed target, or the
+      #   class declares no `embed` directives.
+      def compute_embedding!(field: nil)
+        directives = self.class.embed_directives
+        if directives.empty?
+          raise ArgumentError, "#{self.class}#compute_embedding!: no `embed` directives declared."
+        end
+        selected =
+          if field
+            d = directives[field.to_sym]
+            unless d
+              raise ArgumentError,
+                    "#{self.class}#compute_embedding!: :#{field} is not an embed target " \
+                    "(have #{directives.keys.inspect})."
+            end
+            [d]
+          else
+            directives.values
+          end
+        selected.each { |directive| Parse::Core::EmbedManaged.recompute_embedding!(self, directive) }
+        self
+      end
+
       module ClassMethods
         # Per-class registry of {EmbedDirective}s keyed by target vector
         # property symbol. Read by tests and tooling; written only by
@@ -300,6 +333,86 @@ module Parse
           into
         end
 
+        # Backfill embeddings for records whose managed vector field is
+        # still null — the bulk counterpart to the per-save embed path.
+        # Walks the class with objectId-cursor pagination (robust to the
+        # result set shrinking as records are embedded; terminates even
+        # when a record has no source text and stays null), saving each
+        # pending record so its `before_save` embed callback runs.
+        #
+        # Intended as an admin / maintenance operation: it reads and
+        # writes through the default client, so run it with a master-key
+        # client (or pass `save_opts:` carrying a `session_token:` that can
+        # write every row).
+        #
+        # @param field [Symbol, nil] limit the backfill to one embed
+        #   target; nil processes every declared directive.
+        # @param batch_size [Integer] rows fetched per round (default 100).
+        # @param limit [Integer, nil] stop after embedding at most this
+        #   many records across all directives; nil = no cap.
+        # @param where [Hash, nil] extra query constraints AND-ed with the
+        #   null-target filter (e.g. `{ published: true }`).
+        # @param save_opts [Hash] options forwarded to each `record.save`
+        #   (e.g. `session_token:`).
+        # @return [Integer] number of records saved (embedded).
+        # @raise [ArgumentError] when `field:` names no embed target, or
+        #   the class declares no `embed` directives.
+        def embed_pending!(field: nil, batch_size: 100, limit: nil, where: nil, save_opts: {})
+          bs = Integer(batch_size)
+          raise ArgumentError, "#{self}.embed_pending!: batch_size must be positive." if bs <= 0
+          directives = resolve_embed_directives_for_backfill(field)
+
+          processed = 0
+          directives.each do |directive|
+            remaining = limit ? (limit - processed) : nil
+            break if remaining && remaining <= 0
+            processed += backfill_embed_directive!(directive, bs, where, remaining, save_opts)
+          end
+          processed
+        end
+
+        # @!visibility private
+        def resolve_embed_directives_for_backfill(field)
+          if field
+            d = embed_directives[field.to_sym]
+            unless d
+              raise ArgumentError,
+                    "#{self}.embed_pending!: :#{field} is not an embed target " \
+                    "(have #{embed_directives.keys.inspect})."
+            end
+            [d]
+          else
+            ds = embed_directives.values
+            raise ArgumentError, "#{self}.embed_pending!: no `embed` directives declared." if ds.empty?
+            ds
+          end
+        end
+
+        # @!visibility private
+        # objectId-cursor walk over rows where `directive.into` is null.
+        def backfill_embed_directive!(directive, batch_size, where, remaining, save_opts)
+          count = 0
+          cursor = nil
+          loop do
+            q = query(directive.into.null => true)
+            q = q.where(where) if where.is_a?(Hash) && !where.empty?
+            q = q.where(:objectId.gt => cursor) if cursor
+            q.order(:objectId.asc)
+            q.limit(batch_size)
+            batch = q.results
+            break if batch.nil? || batch.empty?
+
+            batch.each do |record|
+              cursor = record.id
+              record.save(**save_opts)
+              count += 1
+              return count if remaining && count >= remaining
+            end
+            break if batch.length < batch_size
+          end
+          count
+        end
+
         # @!visibility private
         # Prepend a module that intercepts the public `<into>=` setter
         # and raises {ProtectedFieldError} unless the current thread has

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

@@ -554,7 +554,7 @@ module Parse
       # @return [Parse::LiveQuery::Subscription] the subscription object
       # @see Parse::LiveQuery::Subscription
       # @see Parse::Query#subscribe
-      def subscribe(where: {}, fields: nil, session_token: nil, client: nil,
+      def subscribe(where: {}, fields: nil, keys: nil, watch: nil, session_token: nil, client: nil,
                     use_master_key: false, &block)
         # Fall through to the ambient set by `Parse.with_session` / `Parse.login`
         # so a caller wrapping a region with `with_session(user) { Klass.subscribe ... }`
@@ -565,6 +565,8 @@ module Parse
         end
         query(where).subscribe(
           fields: fields,
+          keys: keys,
+          watch: watch,
           session_token: session_token,
           client: client,
           use_master_key: use_master_key,

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/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.