zvec-ruby 0.1.0 → 0.2.0

data/lib/zvec/data_types.rb

@@ -1,37 +1,143 @@
 module Zvec
+  # Data type constants, coercion utilities, and dispatch tables for mapping
+  # between Ruby types and the underlying C++ zvec engine types.
+  #
+  # == Scalar Types
+  #
+  # * {BINARY} -- Raw binary data
+  # * {STRING} -- UTF-8 string
+  # * {BOOL} -- Boolean (true/false)
+  # * {INT32} -- 32-bit signed integer
+  # * {INT64} -- 64-bit signed integer
+  # * {UINT32} -- 32-bit unsigned integer
+  # * {UINT64} -- 64-bit unsigned integer
+  # * {FLOAT} -- 32-bit IEEE 754 float
+  # * {DOUBLE} -- 64-bit IEEE 754 double
+  #
+  # == Dense Vector Types
+  #
+  # Dense vectors store a fixed-length array of numeric values. Choose the
+  # precision that balances accuracy vs. memory:
+  #
+  # * {VECTOR_FP32} -- 32-bit float vector (default, best accuracy)
+  # * {VECTOR_FP64} -- 64-bit double vector (highest accuracy, 2x memory)
+  # * {VECTOR_FP16} -- 16-bit half-precision vector (half the memory of FP32)
+  # * {VECTOR_INT8} -- 8-bit integer vector (smallest, for quantized models)
+  #
+  # == Sparse Vector Types
+  #
+  # Sparse vectors store only non-zero elements, ideal for high-dimensional
+  # data where most values are zero (e.g., BM25 or TF-IDF features):
+  #
+  # * {SPARSE_VECTOR_FP32} -- Sparse vector with 32-bit float values
+  # * {SPARSE_VECTOR_FP16} -- Sparse vector with 16-bit float values
+  #
+  # == Binary Vectors
+  #
+  # Binary vectors use the {BINARY} type and store bit-packed data, useful for
+  # binary hash codes or Hamming distance searches.
+  #
+  # == Array Types
+  #
+  # * {ARRAY_STRING} -- Array of strings (e.g., tags)
+  # * {ARRAY_INT32} -- Array of 32-bit integers
+  # * {ARRAY_INT64} -- Array of 64-bit integers
+  # * {ARRAY_FLOAT} -- Array of 32-bit floats
+  # * {ARRAY_DOUBLE} -- Array of 64-bit doubles
+  # * {ARRAY_BOOL} -- Array of booleans
+  #
+  # == Quantization Types
+  #
+  # Quantization reduces memory usage and speeds up search at the cost of some
+  # accuracy. Specify a quantization type when creating an index:
+  #
+  #   Ext::HnswIndexParams.new(metric, quantize_type: Ext::QuantizeType::INT8)
+  #
+  # Available quantization types (via +Ext::QuantizeType+):
+  #
+  # * +FP16+ -- Half-precision (16-bit) quantization. Good balance of speed
+  #   and accuracy. Halves memory vs. FP32.
+  # * +INT8+ -- 8-bit integer quantization. ~4x memory reduction vs. FP32.
+  #   Slight accuracy loss.
+  # * +INT4+ -- 4-bit integer quantization. ~8x memory reduction vs. FP32.
+  #   Larger accuracy loss, best for large-scale approximate search.
+  #
+  # == Metric Types
+  #
+  # * {L2} -- Euclidean (L2) distance. Lower is more similar.
+  # * {IP} -- Inner product. Higher is more similar.
+  # * {COSINE} -- Cosine similarity. Higher is more similar. Vectors are
+  #   normalized internally.
+  #
   module DataTypes
     # Re-export C++ enum values as Ruby-friendly constants
+
+    # @return [Symbol] Raw binary data type
     BINARY   = Ext::DataType::BINARY
+    # @return [Symbol] UTF-8 string data type
     STRING   = Ext::DataType::STRING
+    # @return [Symbol] Boolean data type
     BOOL     = Ext::DataType::BOOL
+    # @return [Symbol] 32-bit signed integer data type
     INT32    = Ext::DataType::INT32
+    # @return [Symbol] 64-bit signed integer data type
     INT64    = Ext::DataType::INT64
+    # @return [Symbol] 32-bit unsigned integer data type
     UINT32   = Ext::DataType::UINT32
+    # @return [Symbol] 64-bit unsigned integer data type
     UINT64   = Ext::DataType::UINT64
+    # @return [Symbol] 32-bit float data type
     FLOAT    = Ext::DataType::FLOAT
+    # @return [Symbol] 64-bit double data type
     DOUBLE   = Ext::DataType::DOUBLE
 
+    # @return [Symbol] 32-bit float dense vector
     VECTOR_FP32 = Ext::DataType::VECTOR_FP32
+    # @return [Symbol] 64-bit double dense vector
     VECTOR_FP64 = Ext::DataType::VECTOR_FP64
+    # @return [Symbol] 16-bit half-precision dense vector
     VECTOR_FP16 = Ext::DataType::VECTOR_FP16
+    # @return [Symbol] 8-bit integer dense vector (quantized)
     VECTOR_INT8 = Ext::DataType::VECTOR_INT8
 
+    # @return [Symbol] 32-bit float sparse vector
     SPARSE_VECTOR_FP32 = Ext::DataType::SPARSE_VECTOR_FP32
+    # @return [Symbol] 16-bit float sparse vector
     SPARSE_VECTOR_FP16 = Ext::DataType::SPARSE_VECTOR_FP16
 
+    # @return [Symbol] Array of strings
     ARRAY_STRING = Ext::DataType::ARRAY_STRING
+    # @return [Symbol] Array of 32-bit integers
     ARRAY_INT32  = Ext::DataType::ARRAY_INT32
+    # @return [Symbol] Array of 64-bit integers
     ARRAY_INT64  = Ext::DataType::ARRAY_INT64
+    # @return [Symbol] Array of 32-bit floats
     ARRAY_FLOAT  = Ext::DataType::ARRAY_FLOAT
+    # @return [Symbol] Array of 64-bit doubles
     ARRAY_DOUBLE = Ext::DataType::ARRAY_DOUBLE
+    # @return [Symbol] Array of booleans
     ARRAY_BOOL   = Ext::DataType::ARRAY_BOOL
 
     # Metric types
+
+    # @return [Symbol] Euclidean (L2) distance metric
     L2     = Ext::MetricType::L2
+    # @return [Symbol] Inner product metric
     IP     = Ext::MetricType::IP
+    # @return [Symbol] Cosine similarity metric
     COSINE = Ext::MetricType::COSINE
 
+    # Vector data types for dimension validation
+    # @return [Array<Symbol>] All dense vector data type constants
+    VECTOR_TYPES = [
+      Ext::DataType::VECTOR_FP32,
+      Ext::DataType::VECTOR_FP64,
+      Ext::DataType::VECTOR_FP16,
+      Ext::DataType::VECTOR_INT8,
+    ].freeze
+
     # Setter dispatch table: DataType -> Doc setter method name
+    # @return [Hash{Symbol => Symbol}]
     SETTER_FOR = {
       Ext::DataType::STRING => :set_string,
       Ext::DataType::BOOL   => :set_bool,
@@ -46,6 +152,8 @@ module Zvec
       Ext::DataType::ARRAY_STRING => :set_string_array,
     }.freeze
 
+    # Getter dispatch table: DataType -> Doc getter method name
+    # @return [Hash{Symbol => Symbol}]
     GETTER_FOR = {
       Ext::DataType::STRING => :get_string,
       Ext::DataType::BOOL   => :get_bool,
@@ -59,5 +167,147 @@ module Zvec
       Ext::DataType::VECTOR_FP64 => :get_double_vector,
       Ext::DataType::ARRAY_STRING => :get_string_array,
     }.freeze
+
+    # Detect the zvec data type for a Ruby value.
+    #
+    # Handles edge cases: Integer vs Float, String booleans, nil, empty arrays.
+    #
+    # @param value [Object] the Ruby value to inspect
+    # @return [Symbol, nil] the zvec data type constant, or nil for nil input
+    #
+    # @example
+    #   DataTypes.detect_type("hello")  #=> Ext::DataType::STRING
+    #   DataTypes.detect_type(42)       #=> Ext::DataType::INT64
+    #   DataTypes.detect_type([1.0])    #=> Ext::DataType::VECTOR_FP32
+    #   DataTypes.detect_type(nil)      #=> nil
+    def self.detect_type(value)
+      case value
+      when NilClass              then nil
+      when String                then Ext::DataType::STRING
+      when Integer               then Ext::DataType::INT64
+      when Float                 then Ext::DataType::DOUBLE
+      when TrueClass, FalseClass then Ext::DataType::BOOL
+      when Array                 then detect_array_type(value)
+      end
+    end
+
+    # Coerce a Ruby value into a form suitable for the given zvec data type.
+    #
+    # @param value [Object] the value to coerce
+    # @param target_type [Symbol] the target zvec data type constant
+    # @param field_name [String, nil] optional field name for error messages
+    # @return [Object] the coerced value
+    # @raise [ArgumentError] if the value cannot be coerced to the target type
+    #
+    # @example
+    #   DataTypes.coerce_value(42, Ext::DataType::STRING)  #=> "42"
+    #   DataTypes.coerce_value("3.14", Ext::DataType::DOUBLE)  #=> 3.14
+    #   DataTypes.coerce_value([1, 2], Ext::DataType::VECTOR_FP32)  #=> [1.0, 2.0]
+    def self.coerce_value(value, target_type, field_name: nil)
+      return value if value.nil?
+
+      ctx = field_name ? " for field '#{field_name}'" : ""
+
+      case target_type
+      when Ext::DataType::STRING
+        value.to_s
+      when Ext::DataType::BOOL
+        coerce_bool(value, ctx)
+      when Ext::DataType::INT32, Ext::DataType::INT64,
+           Ext::DataType::UINT32, Ext::DataType::UINT64
+        coerce_integer(value, ctx)
+      when Ext::DataType::FLOAT, Ext::DataType::DOUBLE
+        coerce_float(value, ctx)
+      when Ext::DataType::VECTOR_FP32, Ext::DataType::VECTOR_FP64
+        coerce_float_vector(value, ctx)
+      when Ext::DataType::ARRAY_STRING
+        coerce_string_array(value, ctx)
+      else
+        value
+      end
+    end
+
+    class << self
+      private
+
+      # @param arr [Array] the array to detect the element type for
+      # @return [Symbol] the detected zvec data type
+      def detect_array_type(arr)
+        return Ext::DataType::VECTOR_FP32 if arr.empty?
+
+        first_non_nil = arr.find { |v| !v.nil? }
+        return Ext::DataType::VECTOR_FP32 if first_non_nil.nil?
+
+        case first_non_nil
+        when Float   then Ext::DataType::VECTOR_FP32
+        when Integer then Ext::DataType::VECTOR_FP32
+        when String  then Ext::DataType::ARRAY_STRING
+        when TrueClass, FalseClass then Ext::DataType::ARRAY_BOOL
+        else Ext::DataType::VECTOR_FP32
+        end
+      end
+
+      def coerce_bool(value, ctx)
+        case value
+        when TrueClass, FalseClass then value
+        when "true", "1"           then true
+        when "false", "0"          then false
+        when Integer               then !value.zero?
+        else
+          raise ArgumentError,
+            "Cannot coerce #{value.class} (#{value.inspect}) to Bool#{ctx}"
+        end
+      end
+
+      def coerce_integer(value, ctx)
+        case value
+        when Integer then value
+        when Float   then value.to_i
+        when String
+          Integer(value)
+        else
+          raise ArgumentError,
+            "Cannot coerce #{value.class} (#{value.inspect}) to Integer#{ctx}"
+        end
+      rescue ::ArgumentError
+        raise ArgumentError,
+          "Cannot coerce #{value.class} (#{value.inspect}) to Integer#{ctx}"
+      end
+
+      def coerce_float(value, ctx)
+        case value
+        when Numeric then value.to_f
+        when String
+          Float(value)
+        else
+          raise ArgumentError,
+            "Cannot coerce #{value.class} (#{value.inspect}) to Float#{ctx}"
+        end
+      rescue ::ArgumentError
+        raise ArgumentError,
+          "Cannot coerce #{value.class} (#{value.inspect}) to Float#{ctx}"
+      end
+
+      def coerce_float_vector(value, ctx)
+        unless value.is_a?(Array)
+          raise ArgumentError, "Expected Array for vector#{ctx}, got #{value.class}"
+        end
+        value.map do |v|
+          next 0.0 if v.nil?
+          unless v.is_a?(Numeric)
+            raise ArgumentError,
+              "Vector#{ctx} contains non-numeric element: #{v.inspect}"
+          end
+          v.to_f
+        end
+      end
+
+      def coerce_string_array(value, ctx)
+        unless value.is_a?(Array)
+          raise ArgumentError, "Expected Array for string array#{ctx}, got #{value.class}"
+        end
+        value.map { |v| v.nil? ? "" : v.to_s }
+      end
+    end
   end
 end

data/lib/zvec/doc.rb

@@ -1,7 +1,37 @@
 module Zvec
+  # A document (row) in a zvec collection. Wraps the C++ Doc object and
+  # provides Ruby-friendly field access with automatic type coercion.
+  #
+  # Documents can be created with or without a schema. With a schema,
+  # values are coerced and validated against declared field types and
+  # vector dimensions. Without a schema, types are auto-detected.
+  #
+  # @example Creating a document with a schema
+  #   doc = Zvec::Doc.new(pk: "doc-1", schema: schema)
+  #   doc["title"] = "Hello World"
+  #   doc["embedding"] = [0.1, 0.2, 0.3, 0.4]
+  #
+  # @example Schema-less document (types auto-detected)
+  #   doc = Zvec::Doc.new(pk: "doc-2")
+  #   doc["name"] = "Alice"       # stored as string
+  #   doc["age"] = 30             # stored as int64
+  #   doc["score"] = 0.95         # stored as double
+  #   doc["active"] = true        # stored as bool
+  #   doc["vec"] = [1.0, 2.0]     # stored as float vector
+  #   doc["tags"] = ["a", "b"]    # stored as string array
+  #
   class Doc
+    # @return [Ext::Doc] the underlying C++ document object
     attr_reader :ext_doc
 
+    # Create a new document.
+    #
+    # @param pk [String, Integer, nil] primary key (converted to String)
+    # @param fields [Hash{String, Symbol => Object}] initial field values
+    # @param schema [Zvec::Schema, nil] optional schema for type validation
+    #
+    # @example
+    #   doc = Zvec::Doc.new(pk: "abc", fields: { "title" => "Hello" }, schema: schema)
     def initialize(pk: nil, fields: {}, schema: nil)
       @ext_doc = Ext::Doc.new
       @ext_doc.pk = pk.to_s if pk
@@ -9,53 +39,119 @@ module Zvec
       fields.each { |k, v| set(k, v) } if schema
     end
 
+    # @return [String] the primary key
     def pk
       @ext_doc.pk
     end
 
+    # Set the primary key.
+    #
+    # @param value [String, Integer] the new primary key (converted to String)
+    # @return [void]
     def pk=(value)
       @ext_doc.pk = value.to_s
     end
 
+    # @return [Float] the similarity score (set after search queries)
     def score
       @score || @ext_doc.score
     end
 
+    # Read a field value by name (bracket accessor).
+    #
+    # @param field_name [String, Symbol] the field name
+    # @return [Object, nil] the field value, or nil if not set
+    #
+    # @example
+    #   doc["title"]  #=> "Hello"
     def [](field_name)
       get(field_name)
     end
 
+    # Write a field value by name (bracket accessor).
+    #
+    # @param field_name [String, Symbol] the field name
+    # @param value [Object] the value to set
+    # @return [void]
+    #
+    # @example
+    #   doc["title"] = "Hello"
     def []=(field_name, value)
       set(field_name, value)
     end
 
+    # Set a field value. When a schema is present, the value is coerced to
+    # the declared type and validated. Without a schema, the type is
+    # auto-detected from the Ruby value.
+    #
+    # @param field_name [String, Symbol] the field name (must be non-empty)
+    # @param value [Object] the value to set (nil sets the field to null)
+    # @return [void]
+    # @raise [ArgumentError] if field_name is blank or value type is unsupported
+    # @raise [Zvec::DimensionError] if vector dimension doesn't match schema
+    #
+    # @example
+    #   doc.set("title", "Hello")
+    #   doc.set(:count, 42)
+    #   doc.set("embedding", [0.1, 0.2, 0.3])
     def set(field_name, value)
       field_name = field_name.to_s
+      raise ArgumentError, "Field name must be a non-empty string" if field_name.strip.empty?
+
       return @ext_doc.set_null(field_name) if value.nil?
 
       if @schema
         type = @schema.field_type(field_name)
         if type
+          coerced = DataTypes.coerce_value(value, type, field_name: field_name)
           setter = DataTypes::SETTER_FOR[type]
-          return @ext_doc.send(setter, field_name, value) if setter
+          if setter
+            # Validate vector dimension if schema has dimension info
+            if DataTypes::VECTOR_TYPES.include?(type) && coerced.is_a?(Array)
+              expected_dim = @schema.field_dimension(field_name)
+              if expected_dim && !coerced.empty? && coerced.size != expected_dim
+                raise DimensionError,
+                  "Vector dimension mismatch for field '#{field_name}': " \
+                  "expected #{expected_dim}, got #{coerced.size}"
+              end
+            end
+            return @ext_doc.send(setter, field_name, coerced)
+          end
         end
       end
 
-      # Auto-detect type
+      # Auto-detect type (schema-less mode)
       case value
-      when String  then @ext_doc.set_string(field_name, value)
-      when Integer then @ext_doc.set_int64(field_name, value)
-      when Float   then @ext_doc.set_double(field_name, value)
+      when String                then @ext_doc.set_string(field_name, value)
+      when Integer               then @ext_doc.set_int64(field_name, value)
+      when Float                 then @ext_doc.set_double(field_name, value)
       when TrueClass, FalseClass then @ext_doc.set_bool(field_name, value)
       when Array
-        if value.empty? || value.first.is_a?(Float) || value.first.is_a?(Integer)
-          @ext_doc.set_float_vector(field_name, value.map(&:to_f))
-        elsif value.first.is_a?(String)
-          @ext_doc.set_string_array(field_name, value)
+        detected = DataTypes.detect_type(value)
+        case detected
+        when Ext::DataType::ARRAY_STRING
+          @ext_doc.set_string_array(field_name, value.map { |v| v.nil? ? "" : v.to_s })
+        else
+          # Default: treat as float vector
+          coerced = value.map { |v| v.nil? ? 0.0 : v.to_f }
+          @ext_doc.set_float_vector(field_name, coerced)
         end
+      else
+        raise ArgumentError,
+          "Unsupported value type #{value.class} for field '#{field_name}'"
       end
     end
 
+    # Get a field value by name. Uses the schema getter if available,
+    # otherwise tries common types in order.
+    #
+    # @param field_name [String, Symbol] the field name
+    # @return [Object, nil] the value, or nil if not found or null
+    #
+    # @example
+    #   doc.get("title")      #=> "Hello"
+    #   doc.get(:embedding)   #=> [0.1, 0.2, 0.3]
+    #   doc.get("missing")    #=> nil
     def get(field_name)
       field_name = field_name.to_s
       return nil unless @ext_doc.has?(field_name)
@@ -78,25 +174,38 @@ module Zvec
       nil
     end
 
+    # @return [Array<String>] names of all fields set on this document
     def field_names
       @ext_doc.field_names
     end
 
+    # @return [Boolean] true if no fields have been set
     def empty?
       @ext_doc.empty?
     end
 
+    # Convert the document to a plain Ruby Hash.
+    #
+    # @return [Hash{String => Object}] includes "pk", "score", and all fields
+    #
+    # @example
+    #   doc.to_h  #=> {"pk" => "doc-1", "score" => 0.95, "title" => "Hello"}
     def to_h
       h = { "pk" => pk, "score" => score }
       field_names.each { |f| h[f] = get(f) }
       h
     end
 
+    # @return [String] human-readable representation
     def to_s
       @ext_doc.to_s
     end
 
-    # Wrap a C++ Doc::Ptr into a Ruby Doc
+    # Wrap a C++ Doc::Ptr into a Ruby Doc.
+    #
+    # @param ext_doc [Ext::Doc] the C++ document to wrap
+    # @param schema [Zvec::Schema, nil] optional schema for type-aware access
+    # @return [Zvec::Doc]
     def self.from_ext(ext_doc, schema: nil)
       doc = allocate
       doc.instance_variable_set(:@ext_doc, ext_doc)

data/lib/zvec/query.rb

@@ -1,9 +1,118 @@
 module Zvec
+  # Represents a vector similarity search query.
+  #
+  # == Filter Expression Syntax
+  #
+  # Filters narrow search results using scalar field conditions. The syntax
+  # supports the following operators and combinators:
+  #
+  # === Comparison Operators
+  #
+  #   field == value       # equality
+  #   field != value       # inequality
+  #   field > value        # greater than
+  #   field >= value       # greater than or equal
+  #   field < value        # less than
+  #   field <= value       # less than or equal
+  #
+  # === Logical Operators
+  #
+  #   expr AND expr        # both conditions must match
+  #   expr OR expr         # either condition matches
+  #   NOT expr             # negation
+  #   (expr)               # grouping
+  #
+  # === Set / Range Operators
+  #
+  #   field IN [v1, v2]    # field equals any value in the list
+  #   field NOT IN [v1]    # field does not equal any value in the list
+  #
+  # === String Operators
+  #
+  #   field LIKE "pattern" # SQL-style LIKE with % and _ wildcards
+  #
+  # === Examples
+  #
+  #   "year > 2024"
+  #   "year >= 2020 AND year <= 2025"
+  #   "category IN ['science', 'tech']"
+  #   "title LIKE '%Ruby%'"
+  #   "active == true AND rating > 4.0"
+  #   "(year > 2020 OR featured == true) AND active == true"
+  #
+  # @example Basic query
+  #   query = Zvec::VectorQuery.new(
+  #     field_name: "embedding",
+  #     vector: [0.1, 0.2, 0.3, 0.4],
+  #     topk: 10
+  #   )
+  #
+  # @example Query with filter
+  #   query = Zvec::VectorQuery.new(
+  #     field_name: "embedding",
+  #     vector: [0.1, 0.2, 0.3, 0.4],
+  #     topk: 5,
+  #     filter: "year > 2024 AND category == 'science'"
+  #   )
+  #
+  # @example Query with HNSW search params
+  #   query = Zvec::VectorQuery.new(
+  #     field_name: "embedding",
+  #     vector: [0.1, 0.2, 0.3, 0.4],
+  #     topk: 10,
+  #     query_params: Zvec::Ext::HnswQueryParams.new(ef: 300)
+  #   )
+  #
   class VectorQuery
+    # @return [Ext::VectorQuery] the underlying C++ query object
     attr_reader :ext_query
 
+    # Create a new vector similarity query.
+    #
+    # @param field_name [String, Symbol] the vector field to search
+    #   (must be non-empty)
+    # @param vector [Array<Numeric>] the query vector (must be non-empty,
+    #   all elements must be Numeric)
+    # @param topk [Integer] number of nearest results to return (must be > 0)
+    # @param filter [String, nil] optional filter expression
+    #   (see class-level docs for syntax)
+    # @param include_vector [Boolean] whether to include the stored vectors
+    #   in results
+    # @param output_fields [Array<String>, nil] specific fields to return
+    #   (nil returns all)
+    # @param query_params [Ext::HnswQueryParams, Ext::IVFQueryParams,
+    #   Ext::FlatQueryParams, nil] optional search-time tuning params
+    # @return [VectorQuery]
+    # @raise [Zvec::QueryError] if field_name, vector, or topk are invalid
+    #
+    # @example
+    #   vq = Zvec::VectorQuery.new(
+    #     field_name: "embedding",
+    #     vector: [0.1, 0.2, 0.3],
+    #     topk: 5,
+    #     filter: "year > 2024",
+    #     output_fields: ["title", "year"]
+    #   )
     def initialize(field_name:, vector:, topk: 10, filter: nil,
                    include_vector: false, output_fields: nil, query_params: nil)
+      if field_name.nil? || field_name.to_s.strip.empty?
+        raise QueryError, "field_name must be a non-empty string"
+      end
+      unless vector.is_a?(Array) && !vector.empty?
+        raise QueryError, "vector must be a non-empty Array"
+      end
+      unless topk.is_a?(Integer) && topk > 0
+        raise QueryError, "topk must be a positive integer"
+      end
+
+      # Validate all vector elements are numeric
+      vector.each_with_index do |v, i|
+        unless v.is_a?(Numeric)
+          raise QueryError,
+            "Query vector contains non-numeric element at index #{i}: #{v.inspect}"
+        end
+      end
+
       @ext_query = Ext::VectorQuery.new
       @ext_query.field_name = field_name.to_s
       @ext_query.topk = topk
@@ -20,7 +129,7 @@ module Zvec
         when Ext::FlatQueryParams
           @ext_query.set_flat_query_params(query_params)
         else
-          raise ArgumentError, "Unknown query_params type: #{query_params.class}"
+          raise QueryError, "Unknown query_params type: #{query_params.class}"
         end
       end
     end