zvec-ruby 0.1.1 → 0.2.0

data/lib/zvec/data_types.rb

@@ -1,37 +1,134 @@
 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,
@@ -40,6 +137,7 @@ module Zvec
     ].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,
@@ -54,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,
@@ -69,7 +169,17 @@ module Zvec
     }.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
@@ -82,7 +192,17 @@ module Zvec
     end
 
     # Coerce a Ruby value into a form suitable for the given zvec data type.
-    # Returns the coerced value, or raises ArgumentError on impossible coercion.
+    #
+    # @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?
 
@@ -110,6 +230,8 @@ module Zvec
     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?
 

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,26 +39,61 @@ 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?
@@ -77,6 +142,16 @@ module Zvec
       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)
@@ -99,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,17 +1,114 @@
 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)
-      raise ArgumentError, "field_name must be a non-empty string" if field_name.nil? || field_name.to_s.strip.empty?
-      raise ArgumentError, "vector must be a non-empty Array" unless vector.is_a?(Array) && !vector.empty?
-      raise ArgumentError, "topk must be a positive integer" unless topk.is_a?(Integer) && topk > 0
+      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 ArgumentError,
+          raise QueryError,
             "Query vector contains non-numeric element at index #{i}: #{v.inspect}"
         end
       end
@@ -32,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

data/lib/zvec/ruby_llm.rb

@@ -4,17 +4,40 @@ module Zvec
   module RubyLLM
     # A vector store backend for the ruby_llm gem.
     #
-    # Usage with ruby_llm:
+    # Provides a simple add/search/delete interface on top of a {Zvec::Collection}.
+    # Compatible with the ruby_llm vector store protocol.
+    #
+    # @example Basic usage
     #   store = Zvec::RubyLLM::Store.new("/path/to/db", dimension: 1536)
-    #   store.add("doc-1", embedding: [...], metadata: { title: "Hello" })
+    #   store.add("doc-1", embedding: [...], content: "Hello world")
     #   results = store.search([0.1, 0.2, ...], top_k: 5)
+    #   results.first  #=> { id: "doc-1", score: 0.98, content: "Hello world", metadata: {} }
+    #
+    # @example With metadata
+    #   store.add("doc-2", embedding: [...], content: "Ruby", metadata: { category: "lang" })
     #
     class Store
+      # @return [String] default vector field name
       DEFAULT_VECTOR_FIELD = "embedding"
+      # @return [String] default content field name
       DEFAULT_CONTENT_FIELD = "content"
 
-      attr_reader :collection, :dimension
+      # @return [Zvec::Collection] the underlying collection
+      attr_reader :collection
+      # @return [Integer] the vector dimension
+      attr_reader :dimension
 
+      # Create a new store, opening an existing collection or creating one.
+      #
+      # @param path [String] directory path for the collection data
+      # @param dimension [Integer] the vector dimension (must be > 0)
+      # @param metric [Symbol] similarity metric (+:cosine+, +:l2+, or +:ip+)
+      # @param vector_field [String] name of the vector field (default: "embedding")
+      # @param content_field [String] name of the content field (default: "content")
+      # @raise [ArgumentError] if metric is not one of +:cosine+, +:l2+, +:ip+
+      #
+      # @example
+      #   store = Zvec::RubyLLM::Store.new("/tmp/store", dimension: 384, metric: :l2)
       def initialize(path, dimension:, metric: :cosine, vector_field: DEFAULT_VECTOR_FIELD,
                      content_field: DEFAULT_CONTENT_FIELD)
         @vector_field = vector_field.to_s
@@ -47,6 +70,15 @@ module Zvec
       end
 
       # Add a document with its embedding and optional metadata.
+      #
+      # @param id [String, Integer] the document's primary key
+      # @param embedding [Array<Numeric>] the vector embedding
+      # @param content [String, nil] optional text content
+      # @param metadata [Hash{String, Symbol => Object}] additional fields to store
+      # @return [Array] write results from the collection
+      #
+      # @example
+      #   store.add("doc-1", embedding: [0.1, 0.2, 0.3], content: "Hello")
       def add(id, embedding:, content: nil, metadata: {})
         doc = Zvec::Doc.new(pk: id, schema: @schema)
         doc[@vector_field] = embedding
@@ -55,8 +87,20 @@ module Zvec
         @collection.insert(doc)
       end
 
-      # Batch-add documents.
-      # docs: array of { id:, embedding:, content:, metadata: {} }
+      # Batch-add multiple documents at once.
+      #
+      # @param docs [Array<Hash>] documents, each containing:
+      #   * +:id+ [String, Integer] -- primary key (required)
+      #   * +:embedding+ [Array<Numeric>] -- the vector (required)
+      #   * +:content+ [String, nil] -- optional text content
+      #   * +:metadata+ [Hash, nil] -- optional additional fields
+      # @return [Array] write results from the collection
+      #
+      # @example
+      #   store.add_many([
+      #     { id: "a", embedding: [0.1, 0.2], content: "Hello" },
+      #     { id: "b", embedding: [0.3, 0.4], content: "World" },
+      #   ])
       def add_many(docs)
         zvec_docs = docs.map do |d|
           doc = Zvec::Doc.new(pk: d[:id], schema: @schema)
@@ -69,6 +113,22 @@ module Zvec
       end
 
       # Search for similar vectors.
+      #
+      # @param query_vector [Array<Numeric>] the query vector
+      # @param top_k [Integer] maximum number of results (default: 10)
+      # @param filter [String, nil] optional filter expression
+      #   (see {Zvec::VectorQuery} for filter syntax)
+      # @return [Array<Hash>] results, each containing:
+      #   * +:id+ [String] -- document primary key
+      #   * +:score+ [Float] -- similarity score
+      #   * +:content+ [String, nil] -- the content field value
+      #   * +:metadata+ [Hash] -- all other stored fields
+      #
+      # @example
+      #   results = store.search([0.1, 0.2, 0.3], top_k: 5)
+      #   results.first[:id]      #=> "doc-1"
+      #   results.first[:score]   #=> 0.95
+      #   results.first[:content] #=> "Hello"
       def search(query_vector, top_k: 10, filter: nil)
         results = @collection.query(
           field_name: @vector_field,
@@ -86,20 +146,32 @@ module Zvec
         end
       end
 
-      # Delete documents by IDs.
+      # Delete documents by primary key(s).
+      #
+      # @param ids [Array<String, Integer>] one or more primary keys
+      # @return [Array] write results from the collection
       def delete(*ids)
         @collection.delete(*ids.flatten)
       end
 
-      # Fetch documents by IDs.
+      # Fetch documents by primary key(s).
+      #
+      # @param ids [Array<String, Integer>] one or more primary keys
+      # @return [Hash{String => Zvec::Doc}] mapping of pk to document
       def fetch(*ids)
         @collection.fetch(*ids.flatten)
       end
 
+      # Flush pending writes to disk.
+      #
+      # @return [self]
       def flush
         @collection.flush
       end
 
+      # Return the number of documents in the store.
+      #
+      # @return [Integer]
       def count
         @collection.doc_count
       end