ankane/neighbor

Neighbor – Nearest‑neighbor search for Ruby on Rails

What it is

• A Ruby gem that adds vector‑based similarity search to ActiveRecord models. It lets you store embeddings (or any kind of numeric vector) in your database and query for the k nearest records using common distance metrics.

Key features

• Works with several databases out of the box: PostgreSQL (via the pgvector or cube extensions), MariaDB, MySQL (HeatWave), SQLite, and also has adapters for Redis and S3 vectors.
• Supports many distance functions: Euclidean, cosine, inner‑product, taxicab, Hamming, Jaccard, and more depending on the backend.
• Handles a wide range of vector types: full‑precision (vector), half‑precision (halfvec), binary (bit/bigint), sparse (sparsevec), and int8 vectors for SQLite.
• Provides both exact and approximate indexing (HNSW, IVFFlat) to speed up large‑scale searches.
• Simple model API – add has_neighbors :embedding to an ActiveRecord model and call nearest_neighbors on a record or directly on the class.
• Built‑in helpers for hybrid search (keyword + semantic), sparse search, and online recommendations using the Disco library.

How you use it

1. Add the gem to your Gemfile and run bundle install.
2. Create a vector column in a migration (:vector, :cube, :binary, etc.) matching the database you use.
3. Declare the neighbor relationship in the model with has_neighbors :embedding (optionally specify dimensions, type, or normalization).
4. Populate embeddings – either via an external API (OpenAI, Cohere) or a local model (Informers, Transformers.rb).
5. Query:

   item.nearest_neighbors(:embedding, distance: "euclidean").first(5)
   # or
   Item.nearest_neighbors(:embedding, [0.9, 1.3, 1.1], distance: "cosine").first(5)
   

   Results include a neighbor_distance attribute.

Why it matters

• Enables semantic search, recommendation, and similarity‑based features directly inside a Rails app without needing a separate vector database.
• Leverages the native indexing capabilities of the underlying SQL engine, keeping data and search in the same system.
• Flexible enough for research (sparse vectors, half‑precision) and production (approximate indexes, HeatWave for MySQL).

Typical use‑cases

• Document or product search powered by embeddings.
• Real‑time item‑based recommendations.
• Hybrid keyword‑plus‑semantic retrieval.
• Any Rails‑based service that needs fast similarity look‑ups.

Resources

• Full documentation is in the README, with sections for each supported backend.
• Example code for OpenAI, Cohere, Informers, hybrid search, sparse search, and Disco recommendations.
• Separate adapters: neighbor-redis and neighbor-s3 for non‑SQL stores.

---

All details above are taken directly from the project's README.