zvec-ruby 0.1.1 → 0.2.0

data/lib/zvec/schema.rb

@@ -1,9 +1,50 @@
 module Zvec
+  # Defines the structure of a collection: its name, fields, types, and
+  # vector dimensions.
+  #
+  # Schemas are immutable once created -- fields can be added during
+  # initialization but not removed afterward.
+  #
+  # @example Creating a schema with a DSL block
+  #   schema = Zvec::Schema.new("articles") do
+  #     string "title"
+  #     string "body", nullable: true
+  #     int32  "year"
+  #     float  "rating"
+  #     bool   "published"
+  #     vector "embedding", dimension: 384,
+  #            index: Zvec::Ext::HnswIndexParams.new(Zvec::COSINE)
+  #   end
+  #
+  # @example Binary vector field
+  #   schema = Zvec::Schema.new("hashes") do
+  #     field "hash_vec", DataTypes::BINARY, dimension: 128
+  #   end
+  #
+  # @example Sparse vector field
+  #   schema = Zvec::Schema.new("sparse_docs") do
+  #     field "tfidf", DataTypes::SPARSE_VECTOR_FP32, dimension: 30000
+  #   end
+  #
   class Schema
+    # @return [Ext::CollectionSchema] the underlying C++ schema object
     attr_reader :ext_schema
 
+    # Create a new schema.
+    #
+    # @param name [String, Symbol] the collection name (must be non-empty)
+    # @yield optional DSL block evaluated in the schema's context
+    # @raise [Zvec::SchemaError] if name is nil or blank
+    #
+    # @example
+    #   schema = Zvec::Schema.new("my_collection") do
+    #     string "title"
+    #     vector "embedding", dimension: 128
+    #   end
     def initialize(name, &block)
-      raise ArgumentError, "Schema name must be a non-empty string" if name.nil? || name.to_s.strip.empty?
+      if name.nil? || name.to_s.strip.empty?
+        raise SchemaError, "Schema name must be a non-empty string"
+      end
 
       @ext_schema = Ext::CollectionSchema.new(name.to_s)
       @field_types = {}
@@ -11,9 +52,25 @@ module Zvec
       instance_eval(&block) if block
     end
 
+    # Add a field with an explicit data type.
+    #
+    # @param name [String, Symbol] the field name (must be non-empty)
+    # @param type [Symbol] a DataTypes constant (e.g., +DataTypes::STRING+)
+    # @param dimension [Integer, nil] required for vector fields
+    # @param nullable [Boolean] whether the field allows null values
+    # @param index [Ext::HnswIndexParams, Ext::FlatIndexParams, Ext::IVFIndexParams, nil]
+    #   optional index parameters for this field
+    # @return [self] for method chaining
+    # @raise [Zvec::SchemaError] if field name is blank
+    #
+    # @example
+    #   schema.field("tags", DataTypes::ARRAY_STRING)
+    #   schema.field("embedding", DataTypes::VECTOR_FP32, dimension: 128)
     def field(name, type, dimension: nil, nullable: false, index: nil)
       name = name.to_s
-      raise ArgumentError, "Field name must be a non-empty string" if name.strip.empty?
+      if name.strip.empty?
+        raise SchemaError, "Field name must be a non-empty string"
+      end
 
       fs = Ext::FieldSchema.new(name, type)
       fs.dimension = dimension if dimension
@@ -25,61 +82,131 @@ module Zvec
       self
     end
 
+    # Add a dense vector field. Defaults to FP32 precision.
+    #
+    # @param name [String, Symbol] the field name
+    # @param dimension [Integer] the vector dimension (must be > 0)
+    # @param type [Symbol] vector data type (default: {DataTypes::VECTOR_FP32}).
+    #   Also accepts {DataTypes::VECTOR_FP64}, {DataTypes::VECTOR_FP16},
+    #   or {DataTypes::VECTOR_INT8}.
+    # @param index [Ext::HnswIndexParams, Ext::FlatIndexParams, Ext::IVFIndexParams, nil]
+    #   optional index parameters
+    # @return [self]
+    # @raise [ArgumentError] if dimension is not a positive integer
+    #
+    # @example Standard FP32 vector with HNSW index
+    #   schema.vector "embedding", dimension: 384,
+    #                 index: Ext::HnswIndexParams.new(Zvec::COSINE)
+    #
+    # @example FP16 vector (half memory)
+    #   schema.vector "embedding", dimension: 384,
+    #                 type: DataTypes::VECTOR_FP16
+    #
+    # @example INT8 quantized vector (minimal memory)
+    #   schema.vector "embedding", dimension: 384,
+    #                 type: DataTypes::VECTOR_INT8
     def vector(name, dimension:, type: DataTypes::VECTOR_FP32, index: nil)
       raise ArgumentError, "Vector dimension must be a positive integer, got #{dimension.inspect}" unless dimension.is_a?(Integer) && dimension > 0
 
       field(name, type, dimension: dimension, index: index)
     end
 
+    # Add a string field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field} (+nullable:+, +index:+)
+    # @return [self]
     def string(name, **opts)
       field(name, DataTypes::STRING, **opts)
     end
 
+    # Add a 32-bit integer field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def int32(name, **opts)
       field(name, DataTypes::INT32, **opts)
     end
 
+    # Add a 64-bit integer field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def int64(name, **opts)
       field(name, DataTypes::INT64, **opts)
     end
 
+    # Add a 32-bit float field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def float(name, **opts)
       field(name, DataTypes::FLOAT, **opts)
     end
 
+    # Add a 64-bit double field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def double(name, **opts)
       field(name, DataTypes::DOUBLE, **opts)
     end
 
+    # Add a boolean field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def bool(name, **opts)
       field(name, DataTypes::BOOL, **opts)
     end
 
+    # @return [String] the collection name
     def name
       @ext_schema.name
     end
 
+    # @return [Array<String>] all field names in this schema
     def field_names
       @ext_schema.field_names
     end
 
+    # Look up the data type of a field by name.
+    #
+    # @param name [String, Symbol] the field name
+    # @return [Symbol, nil] the data type constant, or nil if not found
     def field_type(name)
       @field_types[name.to_s]
     end
 
+    # Look up the dimension of a vector field.
+    #
+    # @param name [String, Symbol] the field name
+    # @return [Integer, nil] the dimension, or nil if the field is not a vector
     def field_dimension(name)
       @field_dimensions[name.to_s]
     end
 
+    # Check whether a field exists in the schema.
+    #
+    # @param name [String, Symbol] the field name
+    # @return [Boolean]
     def has_field?(name)
       @ext_schema.has_field?(name.to_s)
     end
 
-    # Returns an array of [field_name, dimension] for all vector fields.
+    # Returns a hash of vector field names to their dimensions.
+    #
+    # @return [Hash{String => Integer}] e.g. +{"embedding" => 384}+
     def vector_fields_with_dimensions
       @field_dimensions.select { |name, _| DataTypes::VECTOR_TYPES.include?(@field_types[name]) }
     end
 
+    # @return [String] human-readable representation of the schema
     def to_s
       @ext_schema.to_s
     end

data/lib/zvec/version.rb

@@ -1,3 +1,3 @@
 module Zvec
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/zvec.rb

@@ -16,8 +16,20 @@ require_relative "zvec/query"
 require_relative "zvec/collection"
 
 module Zvec
+  # Base error class for all Zvec errors.
   class Error < StandardError; end
+
+  # Raised when vector dimensions do not match the expected schema dimension.
   class DimensionError < Error; end
 
+  # Raised for schema definition errors (invalid field names, types, etc.).
+  class SchemaError < Error; end
+
+  # Raised for query construction or execution errors.
+  class QueryError < Error; end
+
+  # Raised for collection lifecycle errors (open/close/reopen issues).
+  class CollectionError < Error; end
+
   include DataTypes
 end

data/test/test_edge_cases.rb

@@ -0,0 +1,380 @@
+require_relative "test_helper"
+
+class TestEdgeCases < Minitest::Test
+  include TempDirHelper
+
+  # --- Empty vectors ---
+
+  def test_empty_vector_in_doc_without_schema
+    doc = Zvec::Doc.new
+    doc["vec"] = []
+    result = doc["vec"]
+    assert(result.nil? || result == [])
+  end
+
+  def test_empty_vector_in_doc_with_schema
+    schema = Zvec::Schema.new("test") do
+      vector "embedding", dimension: 4
+    end
+    doc = Zvec::Doc.new(schema: schema)
+    # Empty vectors should be accepted (no dimension to check)
+    doc["embedding"] = []
+    # Should not raise
+  end
+
+  # --- Single-element vectors ---
+
+  def test_single_element_vector
+    doc = Zvec::Doc.new
+    doc["vec"] = [42.0]
+    result = doc["vec"]
+    assert_kind_of Array, result
+    assert_equal 1, result.size
+    assert_in_delta 42.0, result[0], 0.001
+  end
+
+  def test_single_element_vector_with_schema
+    schema = Zvec::Schema.new("test") do
+      vector "embedding", dimension: 1
+    end
+    doc = Zvec::Doc.new(schema: schema)
+    doc["embedding"] = [3.14]
+    result = doc["embedding"]
+    assert_equal 1, result.size
+    assert_in_delta 3.14, result[0], 0.001
+  end
+
+  def test_single_element_vector_query
+    q = Zvec::VectorQuery.new(field_name: "vec", vector: [1.0])
+    assert_kind_of Zvec::VectorQuery, q
+  end
+
+  # --- Very large dimension vectors ---
+
+  def test_large_dimension_schema
+    schema = Zvec::Schema.new("test") do
+      vector "big_vec", dimension: 10_000
+    end
+    assert schema.has_field?("big_vec")
+    assert_equal 10_000, schema.field_dimension("big_vec")
+  end
+
+  def test_large_dimension_doc
+    schema = Zvec::Schema.new("test") do
+      vector "big_vec", dimension: 10_000
+    end
+    doc = Zvec::Doc.new(schema: schema)
+    big_vector = Array.new(10_000) { |i| i.to_f / 10_000 }
+    doc["big_vec"] = big_vector
+    result = doc["big_vec"]
+    assert_equal 10_000, result.size
+    assert_in_delta 0.0, result[0], 0.001
+    assert_in_delta 0.9999, result[9_999], 0.001
+  end
+
+  def test_large_dimension_mismatch
+    schema = Zvec::Schema.new("test") do
+      vector "big_vec", dimension: 10_000
+    end
+    doc = Zvec::Doc.new(schema: schema)
+    small_vector = [1.0, 2.0, 3.0]
+    assert_raises(Zvec::DimensionError) do
+      doc["big_vec"] = small_vector
+    end
+  end
+
+  def test_large_dimension_query
+    big_vector = Array.new(10_000) { 0.1 }
+    q = Zvec::VectorQuery.new(field_name: "big_vec", vector: big_vector)
+    assert_kind_of Zvec::VectorQuery, q
+  end
+
+  # --- Special characters in field names ---
+
+  def test_special_chars_in_field_name
+    doc = Zvec::Doc.new
+    doc["field-with-dashes"] = "dash"
+    assert_equal "dash", doc["field-with-dashes"]
+  end
+
+  def test_dot_in_field_name
+    doc = Zvec::Doc.new
+    doc["meta.title"] = "dotted"
+    assert_equal "dotted", doc["meta.title"]
+  end
+
+  def test_underscore_field_name
+    doc = Zvec::Doc.new
+    doc["_private_field"] = "private"
+    assert_equal "private", doc["_private_field"]
+  end
+
+  def test_numeric_string_field_name
+    doc = Zvec::Doc.new
+    doc["123"] = "numeric name"
+    assert_equal "numeric name", doc["123"]
+  end
+
+  def test_space_in_field_name
+    doc = Zvec::Doc.new
+    doc["field name"] = "spaced"
+    assert_equal "spaced", doc["field name"]
+  end
+
+  def test_special_chars_in_schema_field_name
+    schema = Zvec::Schema.new("test") do
+      string "field-with-dashes"
+      string "meta.title"
+      string "_private"
+    end
+    assert schema.has_field?("field-with-dashes")
+    assert schema.has_field?("meta.title")
+    assert schema.has_field?("_private")
+  end
+
+  # --- Unicode field names ---
+
+  def test_unicode_field_name
+    doc = Zvec::Doc.new
+    doc["\u30BF\u30A4\u30C8\u30EB"] = "Japanese title field"
+    assert_equal "Japanese title field", doc["\u30BF\u30A4\u30C8\u30EB"]
+  end
+
+  def test_emoji_field_name
+    doc = Zvec::Doc.new
+    doc["\u{1F680}rocket"] = "launched"
+    assert_equal "launched", doc["\u{1F680}rocket"]
+  end
+
+  def test_chinese_field_name
+    doc = Zvec::Doc.new
+    doc["\u6807\u9898"] = "Chinese title"
+    assert_equal "Chinese title", doc["\u6807\u9898"]
+  end
+
+  def test_unicode_schema_field_name
+    schema = Zvec::Schema.new("test") do
+      string "\u30BF\u30A4\u30C8\u30EB"
+    end
+    assert schema.has_field?("\u30BF\u30A4\u30C8\u30EB")
+    assert_equal Zvec::DataTypes::STRING, schema.field_type("\u30BF\u30A4\u30C8\u30EB")
+  end
+
+  # --- Unicode values ---
+
+  def test_unicode_string_value
+    doc = Zvec::Doc.new
+    doc["title"] = "\u3053\u3093\u306B\u3061\u306F\u4E16\u754C"
+    assert_equal "\u3053\u3093\u306B\u3061\u306F\u4E16\u754C", doc["title"]
+  end
+
+  def test_unicode_in_string_array
+    doc = Zvec::Doc.new
+    doc["tags"] = ["\u30BF\u30B0\u4E00", "\u30BF\u30B0\u4E8C"]
+    result = doc["tags"]
+    assert_equal ["\u30BF\u30B0\u4E00", "\u30BF\u30B0\u4E8C"], result
+  end
+
+  # --- Custom exception classes ---
+
+  def test_schema_error_is_zvec_error
+    assert Zvec::SchemaError < Zvec::Error
+  end
+
+  def test_query_error_is_zvec_error
+    assert Zvec::QueryError < Zvec::Error
+  end
+
+  def test_collection_error_is_zvec_error
+    assert Zvec::CollectionError < Zvec::Error
+  end
+
+  def test_dimension_error_is_zvec_error
+    assert Zvec::DimensionError < Zvec::Error
+  end
+
+  def test_schema_error_raised_for_nil_name
+    assert_raises(Zvec::SchemaError) { Zvec::Schema.new(nil) }
+  end
+
+  def test_schema_error_raised_for_empty_field
+    schema = Zvec::Schema.new("test")
+    assert_raises(Zvec::SchemaError) { schema.field("", Zvec::DataTypes::STRING) }
+  end
+
+  def test_query_error_raised_for_bad_vector
+    assert_raises(Zvec::QueryError) do
+      Zvec::VectorQuery.new(field_name: "vec", vector: [])
+    end
+  end
+
+  def test_query_error_raised_for_nil_field
+    assert_raises(Zvec::QueryError) do
+      Zvec::VectorQuery.new(field_name: nil, vector: [1.0])
+    end
+  end
+
+  # --- Collection close/reopen lifecycle ---
+
+  def test_collection_closed_flag
+    with_temp_dir("zvec_edge") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", make_schema)
+      refute col.closed?
+      col.close
+      assert col.closed?
+    end
+  end
+
+  def test_collection_close_prevents_operations
+    with_temp_dir("zvec_edge") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", make_schema)
+      col.close
+
+      assert_raises(Zvec::CollectionError) { col.doc_count }
+      assert_raises(Zvec::CollectionError) { col.stats }
+      assert_raises(Zvec::CollectionError) { col.flush }
+      assert_raises(Zvec::CollectionError) { col.optimize }
+      assert_raises(Zvec::CollectionError) do
+        col.add(pk: "x", title: "t", embedding: [1.0, 2.0, 3.0, 4.0])
+      end
+      assert_raises(Zvec::CollectionError) do
+        col.search([1.0, 2.0, 3.0, 4.0])
+      end
+    end
+  end
+
+  def test_collection_double_close_raises
+    with_temp_dir("zvec_edge") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", make_schema)
+      col.close
+      assert_raises(Zvec::CollectionError) { col.close }
+    end
+  end
+
+  def test_collection_destroy_marks_closed
+    with_temp_dir("zvec_edge") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", make_schema)
+      col.destroy
+      assert col.closed?
+    end
+  end
+
+  # --- Edge cases in coercion ---
+
+  def test_coerce_empty_string_to_integer_raises
+    assert_raises(ArgumentError) do
+      Zvec::DataTypes.coerce_value("", Zvec::Ext::DataType::INT64)
+    end
+  end
+
+  def test_coerce_empty_string_to_float_raises
+    assert_raises(ArgumentError) do
+      Zvec::DataTypes.coerce_value("", Zvec::Ext::DataType::DOUBLE)
+    end
+  end
+
+  def test_coerce_very_large_integer
+    result = Zvec::DataTypes.coerce_value(2**62, Zvec::Ext::DataType::INT64)
+    assert_equal 2**62, result
+  end
+
+  def test_coerce_negative_float_to_integer
+    result = Zvec::DataTypes.coerce_value(-3.7, Zvec::Ext::DataType::INT64)
+    assert_equal(-3, result)
+  end
+
+  # --- Edge cases in type detection ---
+
+  def test_detect_type_mixed_array_starts_with_float
+    # Mixed arrays: type detected from first non-nil element
+    assert_equal Zvec::Ext::DataType::VECTOR_FP32, Zvec::DataTypes.detect_type([1.0, "mixed"])
+  end
+
+  def test_detect_type_symbol
+    # Symbols are not a recognized type, returns nil
+    assert_nil Zvec::DataTypes.detect_type(:symbol)
+  end
+
+  def test_detect_type_hash
+    # Hashes are not a recognized type, returns nil
+    assert_nil Zvec::DataTypes.detect_type({ a: 1 })
+  end
+
+  # --- Collection with special character schema names ---
+
+  def test_schema_with_unicode_name
+    schema = Zvec::Schema.new("\u30C6\u30B9\u30C8") do
+      string "title"
+      vector "embedding", dimension: 4
+    end
+    assert_equal "\u30C6\u30B9\u30C8", schema.name
+  end
+
+  def test_schema_with_hyphenated_name
+    schema = Zvec::Schema.new("my-collection") do
+      string "title"
+    end
+    assert_equal "my-collection", schema.name
+  end
+
+  # --- Doc with many fields ---
+
+  def test_doc_with_many_fields
+    doc = Zvec::Doc.new
+    100.times do |i|
+      doc["field_#{i}"] = "value_#{i}"
+    end
+    assert_equal 100, doc.field_names.size
+    assert_equal "value_0", doc["field_0"]
+    assert_equal "value_99", doc["field_99"]
+  end
+
+  # --- Vector with all zeros ---
+
+  def test_zero_vector
+    doc = Zvec::Doc.new
+    doc["vec"] = [0.0, 0.0, 0.0, 0.0]
+    result = doc["vec"]
+    assert_equal [0.0, 0.0, 0.0, 0.0], result
+  end
+
+  # --- Vector with negative values ---
+
+  def test_negative_vector
+    doc = Zvec::Doc.new
+    doc["vec"] = [-1.0, -2.5, -0.001, 0.0]
+    result = doc["vec"]
+    assert_in_delta(-1.0, result[0], 0.001)
+    assert_in_delta(-2.5, result[1], 0.001)
+    assert_in_delta(-0.001, result[2], 0.001)
+  end
+
+  # --- Query with very large topk ---
+
+  def test_query_with_large_topk
+    q = Zvec::VectorQuery.new(field_name: "vec", vector: [1.0], topk: 100_000)
+    assert_equal 100_000, q.ext_query.topk
+  end
+
+  # --- Doc pk edge cases ---
+
+  def test_doc_empty_string_pk
+    doc = Zvec::Doc.new(pk: "")
+    assert_equal "", doc.pk
+  end
+
+  def test_doc_very_long_pk
+    long_pk = "x" * 10_000
+    doc = Zvec::Doc.new(pk: long_pk)
+    assert_equal long_pk, doc.pk
+  end
+
+  private
+
+  def make_schema
+    Zvec::Schema.new("edge_test") do
+      string "title"
+      vector "embedding", dimension: 4
+    end
+  end
+end

data/test/test_helper.rb

@@ -15,6 +15,9 @@ rescue LoadError
   module Zvec
     class Error < StandardError; end
     class DimensionError < Error; end
+    class SchemaError < Error; end
+    class QueryError < Error; end
+    class CollectionError < Error; end
 
     module Ext
       # Stub enums as simple modules with constants
@@ -168,6 +171,7 @@ rescue LoadError
           @docs = {}
           @stats = CollectionStats.new
           @path_value = ""
+          @closed = false
         end
 
         def self.create_and_open(path, ext_schema, opts)
@@ -185,6 +189,11 @@ rescue LoadError
 
         def path; @path_value; end
         def schema; @schema_value; end
+        def closed?; @closed; end
+
+        def close
+          @closed = true
+        end
 
         def stats
           s = CollectionStats.new