activerecord-turbopuffer-adapter 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23fa3cc80f986e56ce18f779fb0d108fc441bc0eb38bc7f8b3eeb23d25ae1c7b
-  data.tar.gz: 1f888b8b3bf5238a24f32d76bfcfa5fe71ef433a3b85c12db4b0f96d36c888f5
+  metadata.gz: cc9b47b80bd694b53052b54ca2647989e6bfd911c1a0f2e59056d61cfccf075e
+  data.tar.gz: a306ba71a2c62db295b438c6583f61a765d425a8f2888c328b831df31bf9840b
 SHA512:
-  metadata.gz: c969a1e7195c56421d923e8d711f81c71028fe8b7ccbdb3b774ccb56671db31b75f5e9a9803bd28886ef503cf7c6477171f4175f799cbe025d65fba41e9a0476
-  data.tar.gz: 96966fdeb4d6ebeebaa15d717404359947b5afee6c753b19e92e7fe9fe50ead8e708e7728b654e72ef7706042f7dca34bfbec7cdbf3f278e04fde7449b9b271d
+  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
 
@@ -120,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
 

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.2"
+    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.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Richard Monette
 bindir: bin
 cert_chain: []
-date: 2026-09-20 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord