activerecord-turbopuffer-adapter 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23fa3cc80f986e56ce18f779fb0d108fc441bc0eb38bc7f8b3eeb23d25ae1c7b
-  data.tar.gz: 1f888b8b3bf5238a24f32d76bfcfa5fe71ef433a3b85c12db4b0f96d36c888f5
+  metadata.gz: 69922615a71c6eefbe25e734208f52099110685db3ad28073dd79e284ec3381b
+  data.tar.gz: 47e713a1a9336e51dcb6e446e23d3364f2bcf8f23ff944a0b52e2a7d4e49acbf
 SHA512:
-  metadata.gz: c969a1e7195c56421d923e8d711f81c71028fe8b7ccbdb3b774ccb56671db31b75f5e9a9803bd28886ef503cf7c6477171f4175f799cbe025d65fba41e9a0476
-  data.tar.gz: 96966fdeb4d6ebeebaa15d717404359947b5afee6c753b19e92e7fe9fe50ead8e708e7728b654e72ef7706042f7dca34bfbec7cdbf3f278e04fde7449b9b271d
+  metadata.gz: 7b366354338fd3d15e689340dbddf279ebf4b4d3823412ae1ef95d21eca48d1a06b492738b1aa21c9abb87e77906e2d3f07b67e71f80b61241e1f3143126946d
+  data.tar.gz: fe83fd43d546c5e07e19fcc38a14760b2810955f5e3398ce4b4895c19280fa3c77dc88874a6bb771ff5572fd90a6a9ebd13bb0563c2a69fa40de5375b6fa34fa

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,26 @@ 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.
+
+### Errors
+
+Turbopuffer errors are raised as the ActiveRecord exceptions a Rails app already handles.
+
+```ruby
+begin
+  Document.where(published: true).to_a
+rescue ActiveRecord::ConnectionFailed
+  # turbopuffer is unreachable
+rescue ActiveRecord::StatementTimeout
+  # the request timed out
+rescue ActiveRecord::DatabaseConnectionError
+  # the API key is invalid
+rescue ActiveRecord::StatementInvalid => e
+  e.cause # => the underlying Turbopuffer::Errors::APIError, e.g. a bad request or rate limit
+end
+```
+
 ### 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)
 
@@ -351,6 +363,19 @@ module ActiveRecord
       def reconnect
         connect
       end
+
+      def translate_exception(exception, message:, sql:, binds:)
+        case exception
+        when Turbopuffer::Errors::APITimeoutError
+          ActiveRecord::StatementTimeout.new(message, sql: sql, binds: binds, connection_pool: @pool)
+        when Turbopuffer::Errors::APIConnectionError
+          ActiveRecord::ConnectionFailed.new(message, sql: sql, binds: binds, connection_pool: @pool)
+        when Turbopuffer::Errors::AuthenticationError, Turbopuffer::Errors::PermissionDeniedError
+          ActiveRecord::DatabaseConnectionError.new(message)
+        else
+          super
+        end
+      end
     end
   end
 end

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.4"
   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.4
 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