activerecord-turbopuffer-adapter 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df2e74234ebc02a8a96d03671b9e73747f3f1e90aff7f7f9c69f045d4e180ae3
-  data.tar.gz: e1b01c5524316e248bcf8b4dfe25a204e3f348b35e5a2b2b1be45b8181a868c6
+  metadata.gz: cc9b47b80bd694b53052b54ca2647989e6bfd911c1a0f2e59056d61cfccf075e
+  data.tar.gz: a306ba71a2c62db295b438c6583f61a765d425a8f2888c328b831df31bf9840b
 SHA512:
-  metadata.gz: 85fdcfcd50b5b9b862c3da6d7c84f783cdcb5a7be2a97f45333e67084c139830005ed28b7ecfa4c516ec0a6c303a9ef683d2cbb395e1b783fc92490531b0c7e2
-  data.tar.gz: bad6f047b6b96456f5bee489116702bd975ead665ea2acaa04cf816f6ddb155102508b959ed99a94b1532831781172c91953d239e898e1a22c5ed7d23f0383ce
+  metadata.gz: f73376471edf444dfc0f2c5dd702d2727a280c307f440da3a367d7d594074a9654e8b20fa58c19c2c6e57a4ab393dbacf17bb8044be82867e9fe7528d5b78874
+  data.tar.gz: 8988590d661ac5c872df12f3e467f939bdb71f291d9485eab31227d3ea3afa3773f8ad8d885f2a91e3b8d3856e92835fc1a2381ceee79978185206b6f52e5479

data/README.md

@@ -105,6 +105,8 @@ Document.find("018f...")
 Document.rank_by("vector", "ANN", query_vector).limit(10)
 Document.rank_by("text", "BM25", "quick walrus").limit(10)
 
+Document.consistency(:eventual).where(published: true)
+
 Document
   .where(published: true)
   .rank_by(["Sum", [
@@ -116,6 +118,8 @@ Document
 
 > Note that turbopuffer has a limit on the maximum number of documents returned (https://turbopuffer.com/docs/query#param-limit), so Document.all.to_a etc. will only return at most 10,000 items
 
+> Eventual reads are cheaper but may not include writes from the last few seconds. Set a default with `turbopuffer_consistency "eventual"` in a model or `consistency: eventual` in `database.yml`. Strong is the default.
+
 ### Using alongside Postgres
 
 While something of a lark, aspirationally the idea of this gem is to make turbopuffer conveniently usable as the primary db in a Rails app. In practice, however, using turbopuffer alongside a traditional primary db (such as postgres) is a supported, potentially more practical solution.

data/lib/active_record/connection_adapters/turbopuffer_adapter.rb

@@ -225,6 +225,14 @@ module ActiveRecord
         0
       end
 
+      def consistency_for(query)
+        model = ::Turbopuffer::ActiveRecord::Schema::Model.for_table(query.namespace)
+        level = query.consistency || model.turbopuffer_consistency || @config[:consistency]
+        return if level.nil?
+
+        { level: ::Turbopuffer::ActiveRecord::Schema::Model.validate_consistency(level).to_sym }
+      end
+
       def turbopuffer_aggregate(namespace, query)
         aggregate_alias, aggregate = query.aggregate_by
 
@@ -233,6 +241,8 @@ module ActiveRecord
         }
 
         tpuf_query_args[:filters] = query.filters if query.filters
+        consistency = consistency_for(query)
+        tpuf_query_args[:consistency] = consistency if consistency
 
         if query.group_by.present?
           tpuf_query_args[:group_by] = query.group_by
@@ -269,6 +279,8 @@ module ActiveRecord
 
         tpuf_query_args[:rank_by] = query.rank_by.first if query.rank_by.present?
         tpuf_query_args[:filters] = query.filters if query.filters
+        consistency = consistency_for(query)
+        tpuf_query_args[:consistency] = consistency if consistency
 
         tpuf_result = namespace.query(tpuf_query_args)
 

data/lib/arel/visitors/turbopuffer.rb

@@ -10,7 +10,8 @@ module Arel::Visitors
         rank_by: @rank_by,
         include_attributes: @include_attributes,
         aggregate_by: @aggregate_by,
-        upsert_rows: @upsert_rows
+        upsert_rows: @upsert_rows,
+        consistency: @consistency
       }
     end
     def to_s = JSON.generate(to_h)
@@ -19,10 +20,11 @@ module Arel::Visitors
     def eql?(other) = other.is_a?(self.class) && to_h == other.to_h
     alias == eql?
 
-    attr_reader :op, :namespace, :filters, :top_k, :rank_by, :include_attributes, :upsert_rows, :aggregate_by, :group_by
+    attr_reader :op, :namespace, :filters, :top_k, :rank_by, :include_attributes, :upsert_rows, :aggregate_by, :group_by,
+                :consistency
 
-    def initialize(op:, namespace:, filters: nil, top_k: nil, rank_by: nil,
-                   include_attributes: nil, upsert_rows: nil, aggregate_by: nil, group_by: nil)
+    def initialize(op:, namespace:, filters: nil, top_k: nil, rank_by: nil, include_attributes: nil,
+                   upsert_rows: nil, aggregate_by: nil, group_by: nil, consistency: nil)
       @op = op
       @namespace = namespace
       @filters = filters
@@ -32,6 +34,7 @@ module Arel::Visitors
       @aggregate_by = aggregate_by
       @group_by = group_by
       @upsert_rows = upsert_rows
+      @consistency = consistency
     end
   end
 
@@ -59,10 +62,14 @@ module Arel::Visitors
       case filters.size
       when 0 then nil
       when 1 then filters.first
-      else [ "And", filters ]
+      else conjunction(filters)
       end
     end
 
+    def conjunction(filters)
+      [ "And", filters.flat_map { |filter| (filter in [ "And", children ]) ? children : [ filter ] } ]
+    end
+
     def aggregate_node(projection)
       projection.is_a?(Arel::Nodes::As) ? projection.left : projection
     end
@@ -116,10 +123,18 @@ module Arel::Visitors
         rank_by:            o.orders.map { |ord| visit(ord) },
         include_attributes: attributes.flat_map { |p| visit(p) },
         group_by:           core.groups.map { |g| visit(g) },
-        aggregate_by:       aggregate && visit(aggregate)
+        aggregate_by:       aggregate && visit(aggregate),
+        consistency:        consistency_hint(core.optimizer_hints)
       )
     end
 
+    def consistency_hint(hints)
+      return unless hints
+
+      hint = hints.expr.reverse.find { |h| h.start_with?("consistency=") }
+      hint&.delete_prefix("consistency=")
+    end
+
     def visit_Arel_Nodes_InsertStatement(o)
       raise NotImplementedError, "INSERT ... SELECT" if o.select
 
@@ -182,7 +197,7 @@ module Arel::Visitors
     def visit_Arel_Table(o) = o.name
 
     # filters
-    def visit_Arel_Nodes_And(o)      = [ "And", o.children.map { |c| visit(c) } ]
+    def visit_Arel_Nodes_And(o)      = conjunction(o.children.map { |c| visit(c) })
     def visit_Arel_Nodes_Or(o)       = [ "Or", [ visit(o.left), visit(o.right) ] ]
     def visit_Arel_Nodes_Grouping(o) = visit(o.expr)
 
@@ -200,10 +215,18 @@ module Arel::Visitors
       "Lt" => "AnyLt", "Lte" => "AnyLte", "Gt" => "AnyGt", "Gte" => "AnyGte"
     }.freeze
 
+    MATCHES_MISSING = [ "Lt", "Lte" ].freeze
+
     def comparison(node, operator, value = visit(node.right))
+      attribute = visit(node.left)
       operator = ARRAY_OPERATORS.fetch(operator) if array_attribute?(node.left) && !value.nil?
+      filter = [ attribute, operator, value ]
 
-      [ visit(node.left), operator, value ]
+      if MATCHES_MISSING.include?(operator) && !value.nil?
+        [ "And", [ filter, [ attribute, "NotEq", nil ] ] ]
+      else
+        filter
+      end
     end
 
     def array_attribute?(node)
@@ -227,7 +250,7 @@ module Arel::Visitors
     def visit_Arel_Nodes_Between(o)
       low, high = o.right.children.map { |bound| visit(bound) }
 
-      [ "And", [ comparison(o, "Gte", low), comparison(o, "Lte", high) ] ]
+      conjunction([ comparison(o, "Gte", low), comparison(o, "Lte", high) ])
     end
 
     def visit_Arel_Nodes_Not(o) = [ "Not", visit(o.expr) ]

data/lib/turbopuffer/active_record/schema/model.rb

@@ -5,10 +5,12 @@ module Turbopuffer
         extend ActiveSupport::Concern
 
         DISTANCE_METRICS = [ "cosine_distance", "euclidean_squared" ].freeze
+        CONSISTENCY_LEVELS = [ "strong", "eventual" ].freeze
 
         included do
           class_attribute :turbopuffer_attributes,        instance_accessor: false, default: [].freeze
           class_attribute :_turbopuffer_distance_metric,  instance_accessor: false, default: "cosine_distance"
+          class_attribute :_turbopuffer_consistency,      instance_accessor: false, default: nil
         end
 
         class << self
@@ -32,6 +34,17 @@ module Turbopuffer
 
             model
           end
+
+          def validate_consistency(level)
+            level = level.to_s
+
+            unless CONSISTENCY_LEVELS.include?(level)
+              raise ArgumentError,
+                "consistency must be one of #{CONSISTENCY_LEVELS.join(", ")}, got #{level.inspect}"
+            end
+
+            level
+          end
         end
 
         class_methods do
@@ -50,6 +63,8 @@ module Turbopuffer
           def turbopuffer_distance_metric(value = nil)
             return _turbopuffer_distance_metric if value.nil?
 
+            value = value.to_s
+
             unless DISTANCE_METRICS.include?(value)
               raise ArgumentError,
                 "distance metric must be one of #{DISTANCE_METRICS.join(", ")}, got #{value.inspect}"
@@ -67,6 +82,16 @@ module Turbopuffer
             ::Turbopuffer::ActiveRecord::Glob.new(pattern, case_sensitive:)
           end
 
+          def consistency(level)
+            optimizer_hints("consistency=#{Model.validate_consistency(level)}")
+          end
+
+          def turbopuffer_consistency(value = nil)
+            return _turbopuffer_consistency if value.nil?
+
+            self._turbopuffer_consistency = Model.validate_consistency(value)
+          end
+
           def predicate_builder
             @predicate_builder ||= super.tap do |builder|
               builder.register_handler(::Regexp, lambda { |attribute, regexp|

data/lib/turbopuffer/active_record/version.rb

@@ -1,5 +1,5 @@
 module Turbopuffer
   module ActiveRecord
-    VERSION = "0.1.1"
+    VERSION = "0.1.3"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-turbopuffer-adapter
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Richard Monette
 bindir: bin
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord