zvec-ruby 0.1.0

data/test/test_active_record.rb

@@ -0,0 +1,55 @@
+require_relative "test_helper"
+
+# Unit tests for the ActiveRecord::Vectorize concern (pure Ruby logic only).
+# These test the module structure and configuration without requiring Rails
+# or a real database.
+class TestActiveRecordVectorize < Minitest::Test
+  def setup
+    @ar_available = begin
+      require "zvec/active_record"
+      true
+    rescue LoadError
+      false
+    end
+  end
+
+  def test_module_defined
+    skip "active_record deps not available" unless @ar_available
+    assert defined?(Zvec::ActiveRecord::Vectorize)
+  end
+
+  def test_instance_methods_module_defined
+    skip "active_record deps not available" unless @ar_available
+    assert defined?(Zvec::ActiveRecord::Vectorize::InstanceMethods)
+  end
+
+  def test_search_methods_module_defined
+    skip "active_record deps not available" unless @ar_available
+    assert defined?(Zvec::ActiveRecord::Vectorize::SearchMethods)
+  end
+
+  def test_instance_methods_has_zvec_update_embedding
+    skip "active_record deps not available" unless @ar_available
+    assert Zvec::ActiveRecord::Vectorize::InstanceMethods.instance_methods.include?(:zvec_update_embedding!)
+  end
+
+  def test_instance_methods_has_zvec_remove_embedding
+    skip "active_record deps not available" unless @ar_available
+    assert Zvec::ActiveRecord::Vectorize::InstanceMethods.instance_methods.include?(:zvec_remove_embedding!)
+  end
+
+  def test_instance_methods_has_zvec_embedding
+    skip "active_record deps not available" unless @ar_available
+    assert Zvec::ActiveRecord::Vectorize::InstanceMethods.instance_methods.include?(:zvec_embedding)
+  end
+
+  def test_search_methods_has_zvec_store
+    skip "active_record deps not available" unless @ar_available
+    assert Zvec::ActiveRecord::Vectorize::SearchMethods.instance_methods.include?(:zvec_store)
+  end
+
+  def test_search_methods_has_vector_search
+    skip "active_record deps not available" unless @ar_available
+    assert Zvec::ActiveRecord::Vectorize::SearchMethods.instance_methods.include?(:vector_search)
+  end
+end

data/test/test_collection.rb

@@ -0,0 +1,312 @@
+require_relative "test_helper"
+
+# These tests require the native extension and a working zvec installation.
+# They are skipped when NATIVE_EXT_AVAILABLE is false.
+class TestCollection < Minitest::Test
+  include TempDirHelper
+
+  def setup
+    skip "Native extension not available" unless NATIVE_EXT_AVAILABLE
+
+    @schema = Zvec::Schema.new("test_collection") do
+      string "title"
+      int32 "year"
+      float "rating"
+      vector "embedding", dimension: 4,
+             index: Zvec::Ext::HnswIndexParams.new(Zvec::COSINE)
+    end
+  end
+
+  # --- Creation ---
+
+  def test_create_and_open
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      assert_kind_of Zvec::Collection, col
+      col.destroy
+    end
+  end
+
+  def test_path
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      assert_equal path, col.path
+      col.destroy
+    end
+  end
+
+  def test_schema_preserved
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      assert_same @schema, col.schema
+      col.destroy
+    end
+  end
+
+  # --- Open existing ---
+
+  def test_open_existing
+    skip "Cannot reopen without explicit close (collection locks on open)"
+  end
+
+  # --- Insert ---
+
+  def test_insert_single_doc
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      doc = Zvec::Doc.new(pk: "doc1", schema: @schema)
+      doc["title"] = "Test"
+      doc["year"] = 2025
+      doc["rating"] = 4.5
+      doc["embedding"] = [0.1, 0.2, 0.3, 0.4]
+      result = col.insert(doc)
+      assert_kind_of Array, result
+      col.destroy
+    end
+  end
+
+  def test_insert_multiple_docs
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      docs = 3.times.map do |i|
+        d = Zvec::Doc.new(pk: "doc#{i}", schema: @schema)
+        d["title"] = "Title #{i}"
+        d["year"] = 2020 + i
+        d["rating"] = i.to_f
+        d["embedding"] = [0.1 * i, 0.2, 0.3, 0.4]
+        d
+      end
+      result = col.insert(docs)
+      assert_equal 3, result.size
+      col.destroy
+    end
+  end
+
+  # --- Add convenience ---
+
+  def test_add_hash
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.add(pk: "d1", title: "Hi", year: 2025, rating: 5.0,
+              embedding: [0.1, 0.2, 0.3, 0.4])
+      assert_equal 1, col.doc_count
+      col.destroy
+    end
+  end
+
+  # --- Doc count ---
+
+  def test_doc_count
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      assert_equal 0, col.doc_count
+
+      3.times do |i|
+        col.add(pk: "d#{i}", title: "T", year: 2025, rating: 1.0,
+                embedding: [0.1, 0.2, 0.3, 0.4])
+      end
+      assert_equal 3, col.doc_count
+      col.destroy
+    end
+  end
+
+  # --- Fetch ---
+
+  def test_fetch_existing
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.add(pk: "f1", title: "Fetched", year: 2025, rating: 3.0,
+              embedding: [0.1, 0.2, 0.3, 0.4])
+
+      result = col.fetch("f1")
+      assert_kind_of Hash, result
+      assert result.key?("f1")
+      doc = result["f1"]
+      assert_kind_of Zvec::Doc, doc
+      assert_equal "Fetched", doc["title"]
+      col.destroy
+    end
+  end
+
+  def test_fetch_multiple
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.add(pk: "a", title: "A", year: 2025, rating: 1.0, embedding: [0.1, 0.2, 0.3, 0.4])
+      col.add(pk: "b", title: "B", year: 2025, rating: 2.0, embedding: [0.4, 0.3, 0.2, 0.1])
+
+      result = col.fetch("a", "b")
+      assert_equal 2, result.size
+      col.destroy
+    end
+  end
+
+  # --- Search ---
+
+  def test_search
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.add(pk: "s1", title: "Near", year: 2025, rating: 5.0,
+              embedding: [1.0, 0.0, 0.0, 0.0])
+      col.add(pk: "s2", title: "Far", year: 2025, rating: 1.0,
+              embedding: [0.0, 0.0, 0.0, 1.0])
+
+      results = col.search([1.0, 0.0, 0.0, 0.0], top_k: 2)
+      assert_kind_of Array, results
+      assert_equal 2, results.size
+      results.each { |r| assert_kind_of Zvec::Doc, r }
+      # The nearest doc should be "s1"
+      assert_equal "s1", results.first.pk
+      col.destroy
+    end
+  end
+
+  def test_search_with_field
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.add(pk: "x", title: "X", year: 2025, rating: 1.0,
+              embedding: [1.0, 0.0, 0.0, 0.0])
+
+      results = col.search([1.0, 0.0, 0.0, 0.0], field: :embedding, top_k: 1)
+      assert_equal 1, results.size
+      col.destroy
+    end
+  end
+
+  # --- Query ---
+
+  def test_query_with_filter
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.add(pk: "q1", title: "Old", year: 2020, rating: 1.0, embedding: [1.0, 0.0, 0.0, 0.0])
+      col.add(pk: "q2", title: "New", year: 2025, rating: 5.0, embedding: [0.9, 0.1, 0.0, 0.0])
+
+      results = col.query(
+        field_name: "embedding",
+        vector: [1.0, 0.0, 0.0, 0.0],
+        topk: 10,
+        filter: "year=2025"
+      )
+      assert results.all? { |r| r.is_a?(Zvec::Doc) }
+      col.destroy
+    end
+  end
+
+  # --- Upsert ---
+
+  def test_upsert
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      doc = Zvec::Doc.new(pk: "u1", schema: @schema)
+      doc["title"] = "Original"
+      doc["year"] = 2025
+      doc["rating"] = 1.0
+      doc["embedding"] = [0.1, 0.2, 0.3, 0.4]
+      col.insert(doc)
+
+      doc2 = Zvec::Doc.new(pk: "u1", schema: @schema)
+      doc2["title"] = "Updated"
+      doc2["year"] = 2026
+      doc2["rating"] = 5.0
+      doc2["embedding"] = [0.4, 0.3, 0.2, 0.1]
+      col.upsert(doc2)
+
+      assert_equal 1, col.doc_count
+      col.destroy
+    end
+  end
+
+  # --- Delete ---
+
+  def test_delete
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.add(pk: "del1", title: "Delete me", year: 2025, rating: 1.0,
+              embedding: [0.1, 0.2, 0.3, 0.4])
+      assert_equal 1, col.doc_count
+
+      col.delete("del1")
+      assert_equal 0, col.doc_count
+      col.destroy
+    end
+  end
+
+  def test_delete_multiple
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      3.times { |i| col.add(pk: "d#{i}", title: "T", year: 2025, rating: 1.0, embedding: [0.1, 0.2, 0.3, 0.4]) }
+      assert_equal 3, col.doc_count
+
+      col.delete("d0", "d1")
+      assert_equal 1, col.doc_count
+      col.destroy
+    end
+  end
+
+  # --- Flush ---
+
+  def test_flush
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.add(pk: "fl1", title: "Flush", year: 2025, rating: 1.0,
+              embedding: [0.1, 0.2, 0.3, 0.4])
+      result = col.flush
+      assert_same col, result
+      col.destroy
+    end
+  end
+
+  # --- Optimize ---
+
+  def test_optimize
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.add(pk: "o1", title: "Opt", year: 2025, rating: 1.0,
+              embedding: [0.1, 0.2, 0.3, 0.4])
+      result = col.optimize
+      assert_same col, result
+      col.destroy
+    end
+  end
+
+  # --- Stats ---
+
+  def test_stats
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      stats = col.stats
+      assert_respond_to stats, :doc_count
+      assert_respond_to stats, :index_completeness
+      col.destroy
+    end
+  end
+
+  # --- Destroy ---
+
+  def test_destroy
+    with_temp_dir do |dir|
+      path = File.join(dir, "col")
+      col = Zvec::Collection.create_and_open(path, @schema)
+      col.destroy
+      # After destroy, the collection directory should be gone
+      refute Dir.exist?(path)
+    end
+  end
+end

data/test/test_data_types.rb

@@ -0,0 +1,165 @@
+require_relative "test_helper"
+
+class TestDataTypes < Minitest::Test
+  # --- Scalar data type constants ---
+
+  def test_string_type_defined
+    refute_nil Zvec::DataTypes::STRING
+  end
+
+  def test_bool_type_defined
+    refute_nil Zvec::DataTypes::BOOL
+  end
+
+  def test_int32_type_defined
+    refute_nil Zvec::DataTypes::INT32
+  end
+
+  def test_int64_type_defined
+    refute_nil Zvec::DataTypes::INT64
+  end
+
+  def test_uint32_type_defined
+    refute_nil Zvec::DataTypes::UINT32
+  end
+
+  def test_uint64_type_defined
+    refute_nil Zvec::DataTypes::UINT64
+  end
+
+  def test_float_type_defined
+    refute_nil Zvec::DataTypes::FLOAT
+  end
+
+  def test_double_type_defined
+    refute_nil Zvec::DataTypes::DOUBLE
+  end
+
+  # --- Vector data type constants ---
+
+  def test_vector_fp32_defined
+    refute_nil Zvec::DataTypes::VECTOR_FP32
+  end
+
+  def test_vector_fp64_defined
+    refute_nil Zvec::DataTypes::VECTOR_FP64
+  end
+
+  def test_vector_fp16_defined
+    refute_nil Zvec::DataTypes::VECTOR_FP16
+  end
+
+  def test_vector_int8_defined
+    refute_nil Zvec::DataTypes::VECTOR_INT8
+  end
+
+  # --- Sparse vector data type constants ---
+
+  def test_sparse_vector_fp32_defined
+    refute_nil Zvec::DataTypes::SPARSE_VECTOR_FP32
+  end
+
+  def test_sparse_vector_fp16_defined
+    refute_nil Zvec::DataTypes::SPARSE_VECTOR_FP16
+  end
+
+  # --- Array data type constants ---
+
+  def test_array_string_defined
+    refute_nil Zvec::DataTypes::ARRAY_STRING
+  end
+
+  def test_array_int32_defined
+    refute_nil Zvec::DataTypes::ARRAY_INT32
+  end
+
+  def test_array_float_defined
+    refute_nil Zvec::DataTypes::ARRAY_FLOAT
+  end
+
+  def test_array_bool_defined
+    refute_nil Zvec::DataTypes::ARRAY_BOOL
+  end
+
+  # --- Metric type constants ---
+
+  def test_l2_metric_defined
+    refute_nil Zvec::DataTypes::L2
+  end
+
+  def test_ip_metric_defined
+    refute_nil Zvec::DataTypes::IP
+  end
+
+  def test_cosine_metric_defined
+    refute_nil Zvec::DataTypes::COSINE
+  end
+
+  # --- Top-level module includes DataTypes ---
+
+  def test_zvec_includes_cosine
+    refute_nil Zvec::COSINE
+  end
+
+  def test_zvec_includes_vector_fp32
+    refute_nil Zvec::VECTOR_FP32
+  end
+
+  def test_zvec_includes_string
+    refute_nil Zvec::STRING
+  end
+
+  # --- Dispatch tables ---
+
+  def test_setter_for_has_string
+    assert_equal :set_string, Zvec::DataTypes::SETTER_FOR[Zvec::Ext::DataType::STRING]
+  end
+
+  def test_setter_for_has_bool
+    assert_equal :set_bool, Zvec::DataTypes::SETTER_FOR[Zvec::Ext::DataType::BOOL]
+  end
+
+  def test_setter_for_has_int32
+    assert_equal :set_int32, Zvec::DataTypes::SETTER_FOR[Zvec::Ext::DataType::INT32]
+  end
+
+  def test_setter_for_has_int64
+    assert_equal :set_int64, Zvec::DataTypes::SETTER_FOR[Zvec::Ext::DataType::INT64]
+  end
+
+  def test_setter_for_has_float
+    assert_equal :set_float, Zvec::DataTypes::SETTER_FOR[Zvec::Ext::DataType::FLOAT]
+  end
+
+  def test_setter_for_has_double
+    assert_equal :set_double, Zvec::DataTypes::SETTER_FOR[Zvec::Ext::DataType::DOUBLE]
+  end
+
+  def test_setter_for_has_vector_fp32
+    assert_equal :set_float_vector, Zvec::DataTypes::SETTER_FOR[Zvec::Ext::DataType::VECTOR_FP32]
+  end
+
+  def test_setter_for_has_vector_fp64
+    assert_equal :set_double_vector, Zvec::DataTypes::SETTER_FOR[Zvec::Ext::DataType::VECTOR_FP64]
+  end
+
+  def test_setter_for_has_array_string
+    assert_equal :set_string_array, Zvec::DataTypes::SETTER_FOR[Zvec::Ext::DataType::ARRAY_STRING]
+  end
+
+  def test_setter_for_is_frozen
+    assert Zvec::DataTypes::SETTER_FOR.frozen?
+  end
+
+  def test_getter_for_has_string
+    assert_equal :get_string, Zvec::DataTypes::GETTER_FOR[Zvec::Ext::DataType::STRING]
+  end
+
+  def test_getter_for_has_float_vector
+    assert_equal :get_float_vector, Zvec::DataTypes::GETTER_FOR[Zvec::Ext::DataType::VECTOR_FP32]
+  end
+
+  def test_getter_for_is_frozen
+    assert Zvec::DataTypes::GETTER_FOR.frozen?
+  end
+end