activerecord-turbopuffer-adapter 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc9b47b80bd694b53052b54ca2647989e6bfd911c1a0f2e59056d61cfccf075e
-  data.tar.gz: a306ba71a2c62db295b438c6583f61a765d425a8f2888c328b831df31bf9840b
+  metadata.gz: 8bb295502835167a50a215f96707b208574ac3e6641b3cd9d02c50646b2335b6
+  data.tar.gz: '09c4fcdaf392f394619a7a1b786a0be832e248edd7449a5d49e804908fd4d94d'
 SHA512:
-  metadata.gz: f73376471edf444dfc0f2c5dd702d2727a280c307f440da3a367d7d594074a9654e8b20fa58c19c2c6e57a4ab393dbacf17bb8044be82867e9fe7528d5b78874
-  data.tar.gz: 8988590d661ac5c872df12f3e467f939bdb71f291d9485eab31227d3ea3afa3773f8ad8d885f2a91e3b8d3856e92835fc1a2381ceee79978185206b6f52e5479
+  metadata.gz: d822446b93294cbca0db8d9cb13a373588e160805d6dc1f1d8e9e88b3d6695ebff58e3cb94fae1715bf0e42850cafb6b88b807b369cc48d174dbeab893e7c35a
+  data.tar.gz: a22568481e63de3ca8a83a7367a59ac9b1e57853ed2315873c2948cd17a0bf4d4a348e77188e8d2f9deefcc25484b8e128e028948dbe11c4064adbc1909e1ffe

data/README.md

@@ -120,6 +120,24 @@ Document
 
 > 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

@@ -32,12 +32,17 @@ module ActiveRecord
           m.register_type "float",    Type::Float.new
           m.register_type "bool",     Type::Boolean.new
           m.register_type "datetime", ::Turbopuffer::ActiveRecord::Type::DateTime.new
+          m.register_type "bytes",    ::Turbopuffer::ActiveRecord::Type::Bytes.new
+          m.register_type "{}f16",    ::Turbopuffer::ActiveRecord::Type::SparseVector.new
           m.register_type(%r{\A\[\].+\z}) do |type|
             ::Turbopuffer::ActiveRecord::Type::Array.new(m.lookup(type.delete_prefix("[]")))
           end
           m.register_type(%r{\A\[\d+\]f(?:16|32)\z}) do |type|
             ::Turbopuffer::ActiveRecord::Type::Vector.new(type[/\d+/].to_i)
           end
+          m.register_type(%r{\A\[\d+\]i8\z}) do |type|
+            ::Turbopuffer::ActiveRecord::Type::Vector.new(type[/\d+/].to_i, integer: true)
+          end
         end
       end
 
@@ -96,7 +101,7 @@ module ActiveRecord
 
       def type_cast(value)
         case value
-        when Array
+        when Array, Hash
           value
         else
           super
@@ -363,6 +368,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/turbopuffer/active_record/schema/attribute.rb

@@ -2,7 +2,7 @@ module Turbopuffer
   module ActiveRecord
     module Schema
       class Attribute
-        TYPES = %r{\A(?:\[\])?(?:string|uuid|int|uint|float|bool|datetime)\z|\A\[\d+\]f(?:16|32)\z}
+        TYPES = %r{\A(?:\[\])?(?:string|uuid|int|uint|float|bool|datetime)\z|\Abytes\z|\A\[\d+\](?:f16|f32|i8)\z|\A\{\}f16\z}
 
         attr_reader :name, :type, :filterable, :full_text_search, :ann, :glob, :regex, :notnull
 

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

@@ -115,6 +115,7 @@ module Turbopuffer
               attrs[:ann] = true if attribute.ann
               attrs[:glob] = true if attribute.glob
               attrs[:regex] = true if attribute.regex
+              attrs[:sparse_knn] = { distance_metric: "dot_product" } if attribute.type == "{}f16"
 
               schema[attribute.name] = attrs
             end

data/lib/turbopuffer/active_record/type/bytes.rb

@@ -0,0 +1,21 @@
+require "base64"
+
+module Turbopuffer
+  module ActiveRecord
+    module Type
+      class Bytes < ::ActiveModel::Type::Value
+        def serialize(value)
+          return if value.nil?
+
+          Base64.strict_encode64(value)
+        end
+
+        def deserialize(value)
+          return if value.nil?
+
+          Base64.decode64(value)
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/type/sparse_vector.rb

@@ -0,0 +1,21 @@
+module Turbopuffer
+  module ActiveRecord
+    module Type
+      class SparseVector < ::ActiveModel::Type::Value
+        include ::ActiveModel::Type::Helpers::Mutable
+
+        def serialize(value)
+          return if value.nil?
+
+          value.to_h { |key, weight| [ key.to_s, Float(weight) ] }
+        end
+
+        def deserialize(value)
+          return if value.nil?
+
+          value.to_h.transform_keys(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/type/vector.rb

@@ -4,15 +4,16 @@ module Turbopuffer
       class Vector < ::ActiveModel::Type::Value
         include ::ActiveModel::Type::Helpers::Mutable
 
-        def initialize(dimensions)
+        def initialize(dimensions, integer: false)
           @dimensions = dimensions
+          @integer = integer
           super()
         end
 
         def serialize(value)
           return if value.nil?
 
-          vector = ::Array.wrap(value).map { |component| Float(component) }
+          vector = ::Array.wrap(value).map { |component| component(component) }
 
           unless vector.size == @dimensions
             raise ArgumentError, "expected a vector of #{@dimensions} dimensions, got #{vector.size}"
@@ -24,6 +25,19 @@ module Turbopuffer
         def deserialize(value)
           value
         end
+
+        private
+
+        def component(value)
+          number = Float(value)
+          return number unless @integer
+
+          unless number == number.to_i
+            raise ArgumentError, "expected an integer vector component, got #{value.inspect}"
+          end
+
+          number.to_i
+        end
       end
     end
   end

data/lib/turbopuffer/active_record/type.rb

@@ -1,7 +1,9 @@
 require "turbopuffer/active_record/type/date_time"
 require "turbopuffer/active_record/type/unsigned_integer"
+require "turbopuffer/active_record/type/bytes"
 require "turbopuffer/active_record/type/array"
 require "turbopuffer/active_record/type/vector"
+require "turbopuffer/active_record/type/sparse_vector"
 
 module Turbopuffer
   module ActiveRecord

data/lib/turbopuffer/active_record/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-turbopuffer-adapter
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Richard Monette
 bindir: bin
 cert_chain: []
-date: 2026-09-22 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -81,7 +95,9 @@ files:
 - lib/turbopuffer/active_record/schema/model.rb
 - lib/turbopuffer/active_record/type.rb
 - lib/turbopuffer/active_record/type/array.rb
+- lib/turbopuffer/active_record/type/bytes.rb
 - lib/turbopuffer/active_record/type/date_time.rb
+- lib/turbopuffer/active_record/type/sparse_vector.rb
 - lib/turbopuffer/active_record/type/unsigned_integer.rb
 - lib/turbopuffer/active_record/type/vector.rb
 - lib/turbopuffer/active_record/version.rb