Module: Woods::Storage::VectorStore::Interface

Included in:
InMemory, Pgvector, Qdrant
Defined in:
lib/woods/storage/vector_store.rb

Overview

Interface that all vector store adapters must implement.

Instance Method Summary collapse

Instance Method Details

#bulk_load(entries) ⇒ Object

Bulk-load pre-computed entries. Dual of #each_entry — the Snapshotter hydrates a store by feeding this the dump contents.

Parameters:

  • entries (Enumerable<Hash>) —

    Each entry has :id, :vector, :metadata keys



59
60
61
 
# File 'lib/woods/storage/vector_store.rb', line 59

def bulk_load(entries)
  store_batch(entries.to_a)
end

#count ⇒ Integer

Return the number of stored vectors.

Returns:

  • (Integer) —

    Total count

Raises:

  • (NotImplementedError) —

    if not implemented by adapter



100
101
102
 
# File 'lib/woods/storage/vector_store.rb', line 100

def count
  raise NotImplementedError
end

#delete(id) ⇒ Object

Delete a vector by ID.

Parameters:

  • id (String) —

    The identifier to delete

Raises:

  • (NotImplementedError) —

    if not implemented by adapter



84
85
86
 
# File 'lib/woods/storage/vector_store.rb', line 84

def delete(id)
  raise NotImplementedError
end

#delete_by_filter(filters) ⇒ Object

Delete vectors matching metadata filters.

Parameters:

  • filters (Hash) —

    Metadata key-value pairs to match

Raises:

  • (NotImplementedError) —

    if not implemented by adapter



92
93
94
 
# File 'lib/woods/storage/vector_store.rb', line 92

def delete_by_filter(filters)
  raise NotImplementedError
end

#each_entry {|id, vector, metadata| ... } ⇒ Enumerator

Iterate over every live entry, yielding ‘(id, vector, metadata)`.

Persistence seam for Snapshotter and similar consumers. Default implementation falls through to ‘NotImplementedError`; adapters that need to support dumping must implement it. Persistent backends (pgvector, Qdrant) aren’t expected to implement this —the Snapshotter only touches non-persistent stores.

Yields:

  • (id, vector, metadata)

Returns:

  • (Enumerator) —

    when no block given

Raises:

  • (NotImplementedError) 


51
52
53
 
# File 'lib/woods/storage/vector_store.rb', line 51

def each_entry
  raise NotImplementedError
end

#search(query_vector, limit: 10, filters: {}) ⇒ Array<SearchResult>

Search for similar vectors using cosine similarity.

Filter values may be scalars (exact match) or Arrays (membership match — “value ∈ array”). Adapters implement the membership semantics natively: in-memory loops, pgvector IN (…), Qdrant ‘match: { any: […] }`.

Parameters:

  • query_vector (Array<Float>) —

    The query embedding vector

  • limit (Integer) (defaults to: 10) —

    Maximum number of results to return

  • filters (Hash) (defaults to: {}) —

    Optional metadata filters — values may be scalars or Arrays

Returns:

  • (Array<SearchResult>) —

    Results sorted by descending similarity

Raises:

  • (NotImplementedError) —

    if not implemented by adapter



76
77
78
 
# File 'lib/woods/storage/vector_store.rb', line 76

def search(query_vector, limit: 10, filters: {})
  raise NotImplementedError
end

#store(id, vector, metadata = {}) ⇒ Object

Store a vector with associated metadata.

Parameters:

  • id (String) —

    Unique identifier for the vector

  • vector (Array<Float>) —

    The embedding vector

  • metadata (Hash) (defaults to: {}) —

    Optional metadata to store alongside the vector

Raises:

  • (NotImplementedError) —

    if not implemented by adapter



26
27
28
 
# File 'lib/woods/storage/vector_store.rb', line 26

def store(id, vector, metadata = {})
  raise NotImplementedError
end

#store_batch(entries) ⇒ Object

Store multiple vectors in a single batch operation.

Default implementation falls back to individual store calls. Adapters should override for bulk-optimized behavior (e.g., multi-row INSERT for pgvector, batch upsert for Qdrant).

Parameters:

  • entries (Array<Hash>) —

    Each entry has :id, :vector, :metadata keys



37
38
39
 
# File 'lib/woods/storage/vector_store.rb', line 37

def store_batch(entries)
  entries.each { |e| store(e[:id], e[:vector], e[:metadata] || {}) }
end