vectra-client 1.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70730299dab8475b05688f7017dccd1965b87a49589c96be7633a356af8d57f2
-  data.tar.gz: 14999ebde62586578b444ba45d396cb38f1a4dd5dcbf2fd126e042ebb1c6fae5
+  metadata.gz: 6f59705f200c8a164cc9303e6761776af49e4a81a88f101eae2e371eccca8807
+  data.tar.gz: 217dd74d00151f3ba6e94ed80718999656f9616b84e843dd937197cee612540a
 SHA512:
-  metadata.gz: 69c8fa722ee4abfe3ddf6b19f8bd12f46d09edefee50612021142c3951600666ed854018e8a5c1bc33249895fec42ae18ab1d821beffa989d2700da99c28bcf4
-  data.tar.gz: f27a0df4bbcf618659297b1376ebe977588d32d5dfef76fe7c8f5f38c8780b37e055a0e8d91f6bc3ae8eb7cad88606c760d4ed5882c61756ac1495dedfc339a5
+  metadata.gz: 8e62f19e82dfb88a14ae50f7cee6afdd8d058ece9972de8f447ba3cc881420d401cfd0d3a093d299e8273795958085349a8d3e6416ecd429f50ea2a05103dea3
+  data.tar.gz: ace8ecc519dc588f917e6b29721ed9cfa3ff9b3f3fd7b3e82911233ed7d6e59a9f443e81ae9c0d20dd4891f904d8497cb506064964b00b3dc7587f12137e12bf

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [v1.1.1](https://github.com/stokry/vectra/tree/v1.1.1) (2026-01-15)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.1.0...v1.1.1)
+
+### Added
+- **Text Search Support** - New `text_search` method for keyword-only search without requiring embeddings
+  - Qdrant: BM25 text search
+  - Weaviate: BM25 text search via GraphQL
+  - pgvector: PostgreSQL full-text search (`to_tsvector`, `plainto_tsquery`, `ts_rank`)
+  - Memory: Simple keyword matching (for testing)
+  - Raises `UnsupportedFeatureError` for Pinecone (use sparse vectors instead)
+- **Documentation Search** - Added search functionality to documentation site with `simple-jekyll-search`
+  - Client-side search with fuzzy matching
+  - Search index auto-generated from all documentation pages
+  - Responsive search UI in navigation
+
+### Changed
+- Updated API documentation to include `text_search` method in overview and cheatsheet
+- Enhanced documentation with text search examples and use cases
+
+## [v1.1.0](https://github.com/stokry/vectra/tree/v1.1.0) (2026-01-15)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v1.0.8...v1.1.0)
+
 ## [v1.0.8](https://github.com/stokry/vectra/tree/v1.0.8) (2026-01-14)
 
 [Full Changelog](https://github.com/stokry/vectra/compare/v1.0.7...v1.0.8)

data/README.md

@@ -109,6 +109,14 @@ results = client.hybrid_search(
   text: 'ruby programming',
   alpha: 0.7  # 70% semantic, 30% keyword
 )
+
+# Text-only search (keyword search without embeddings)
+# Supported by: Qdrant, Weaviate, pgvector
+results = client.text_search(
+  index: 'products',
+  text: 'iPhone 15 Pro',
+  top_k: 10
+)
 ```
 
 ## Provider Examples
@@ -218,6 +226,8 @@ This will:
 - **Update the model** to include `ProductVector`
 - **Append to `config/vectra.yml`** with index metadata (no API keys)
 
+When `config/vectra.yml` contains exactly one entry, a plain `Vectra::Client.new` in that Rails app will automatically use that entry's `index` (and `namespace` if present) as its defaults, so you can usually omit `index:` when calling `upsert` / `query` / `text_search`.
+
 ### Complete Rails Guide
 
 For a complete step-by-step guide including:
@@ -307,6 +317,20 @@ Vectra includes 7 production-ready patterns out of the box:
 - **Health Checks** - `healthy?`, `ping`, and `health_check` methods
 - **Instrumentation** - Datadog, New Relic, Sentry, Honeybadger support
 
+## Roadmap
+
+High-level roadmap for `vectra-client`:
+
+- **1.x (near term)**
+  - Reranking middleware built on top of the existing Rack-style middleware stack.
+  - Additional middleware building blocks (sampling, tracing, score normalization).
+  - Smoother Rails UX for multi-tenant setups and larger demos (e‑commerce, RAG, recommendations).
+- **Mid term**
+  - Additional providers where it makes sense and stays maintainable.
+  - Deeper documentation and recipes around reranking and hybrid search.
+
+For a more detailed, always-up-to-date version, see the online roadmap: https://vectra-docs.netlify.app/guides/roadmap/
+
 ## Development
 
 ```bash

data/docs/_layouts/home.html

@@ -55,7 +55,7 @@
   <!-- Hero Section -->
   <section class="tma-hero">
     <div class="tma-hero__container">
-      <span class="tma-hero__badge">v1.1.0 — Hybrid Search, Rails Generator & Middleware</span>
+      <span class="tma-hero__badge">v1.1.1 — Hybrid Search, Rails Generator, Middleware & Text Search</span>
       <h1 class="tma-hero__title">
         Vector Databases,<br>
         <span class="tma-hero__title-gradient">Unified for Ruby.</span>

data/docs/_layouts/page.html

@@ -39,6 +39,12 @@
         <span class="tma-nav__toggle-line"></span>
       </button>
       <ul class="tma-nav__menu" id="nav-menu">
+        <li class="tma-nav__search-wrapper">
+          <div class="tma-search">
+            <input type="search" id="search-input" class="tma-search__input" placeholder="Search docs..." aria-label="Search documentation">
+            <div id="search-results" class="tma-search__results"></div>
+          </div>
+        </li>
         <li><a href="{{ site.baseurl }}/guides/getting-started" class="tma-nav__link">Getting Started</a></li>
         <li><a href="{{ site.baseurl }}/guides/recipes" class="tma-nav__link">Recipes</a></li>
         <li><a href="{{ site.baseurl }}/providers" class="tma-nav__link">Providers</a></li>
@@ -91,6 +97,13 @@
           <li><a href="https://github.com/stokry/vectra/issues" class="tma-sidebar__link" target="_blank">Report Issue ↗</a></li>
         </ul>
       </div>
+
+      <div class="tma-sidebar__section">
+        <h3 class="tma-sidebar__title">Resources</h3>
+        <ul class="tma-sidebar__list">
+          <li><a href="{{ site.baseurl }}/guides/roadmap" class="tma-sidebar__link {% if page.url == '/guides/roadmap/' %}tma-sidebar__link--active{% endif %}">Roadmap</a></li>
+        </ul>
+      </div>
     </aside>
 
     <!-- Main Content -->
@@ -115,6 +128,9 @@
     </div>
   </footer>
 
+  <!-- Simple Jekyll Search -->
+  <script src="https://cdn.jsdelivr.net/npm/simple-jekyll-search@1.10.0/dest/simple-jekyll-search.min.js"></script>
+  
   <script>
     document.addEventListener('DOMContentLoaded', function() {
       const navToggle = document.querySelector('.tma-nav__toggle');
@@ -148,6 +164,19 @@
           }
         });
       }
+
+      // Initialize search
+      if (typeof SimpleJekyllSearch !== 'undefined') {
+        SimpleJekyllSearch({
+          searchInput: document.getElementById('search-input'),
+          resultsContainer: document.getElementById('search-results'),
+          json: '{{ site.baseurl }}/search.json',
+          searchResultTemplate: '<div class="tma-search__result"><a href="{url}" class="tma-search__result-link"><span class="tma-search__result-title">{title}</span><span class="tma-search__result-excerpt">{excerpt}</span></a></div>',
+          noResultsText: '<div class="tma-search__no-results">No results found</div>',
+          fuzzy: true,
+          limit: 10
+        });
+      }
     });
   </script>
 </body>

data/docs/api/cheatsheet.md

@@ -49,6 +49,8 @@ client.upsert(vectors: [...])
 client.query(vector: query_embedding, top_k: 10)
 ```
 
+In a Rails app with `config/vectra.yml` generated by `rails generate vectra:index`, if that YAML file contains only one entry, `Vectra::Client.new` will automatically use that entry's `index` (and `namespace`, if present) as defaults.
+
 ### Upsert
 
 ```ruby
@@ -98,6 +100,23 @@ results = client.hybrid_search(
 
 Supported providers: Qdrant ✅, Weaviate ✅, pgvector ✅, Pinecone ⚠️
 
+### Text Search (keyword-only, no embeddings)
+
+```ruby
+results = client.text_search(
+  index: 'products',
+  text: 'iPhone 15 Pro',
+  top_k: 10,
+  filter: { category: 'electronics' }
+)
+
+results.each do |match|
+  puts "#{match.id} (score=#{match.score.round(3)}): #{match.metadata['title']}"
+end
+```
+
+Supported providers: Qdrant ✅ (BM25), Weaviate ✅ (BM25), pgvector ✅ (PostgreSQL full-text)
+
 ### Fetch
 
 ```ruby
@@ -176,6 +195,14 @@ else
 end
 ```
 
+For fast health checks you can temporarily lower the timeout:
+
+```ruby
+status = client.with_timeout(0.5) do |c|
+  c.ping
+end
+```
+
 ### Ping (with latency)
 
 ```ruby

data/docs/api/methods.md

@@ -36,6 +36,8 @@ client = Vectra::Client.new(
 )
 ```
 
+In a Rails app that uses the `vectra:index` generator, if `config/vectra.yml` contains exactly one entry, `Vectra::Client.new` will automatically use that entry's `index` (and `namespace` if present) as its defaults. This allows you to omit `index:` in most calls (`upsert`, `query`, `text_search`, etc.).
+
 ---
 
 ### `client.upsert(index:, vectors:, namespace: nil)`
@@ -147,6 +149,51 @@ results = client.hybrid_search(
 
 ---
 
+### `client.text_search(index:, text:, top_k: 10, namespace: nil, filter: nil, include_values: false, include_metadata: true)`
+
+Text-only search (keyword search without requiring embeddings).
+
+**Parameters:**
+- `index` (String) - Index/collection name (uses client's default index when omitted)
+- `text` (String) - Text query for keyword search
+- `top_k` (Integer) - Number of results (default: 10)
+- `namespace` (String, optional) - Namespace
+- `filter` (Hash, optional) - Metadata filter
+- `include_values` (Boolean) - Include vector values (default: false)
+- `include_metadata` (Boolean) - Include metadata (default: true)
+
+**Returns:** `Vectra::QueryResult`
+
+**Provider Support:**
+- ✅ Qdrant (BM25)
+- ✅ Weaviate (BM25)
+- ✅ pgvector (PostgreSQL full-text search)
+- ✅ Memory (simple keyword matching - for testing only)
+- ❌ Pinecone (not supported - use sparse vectors instead)
+
+**Example:**
+```ruby
+# Keyword search for exact matches
+results = client.text_search(
+  index: 'products',
+  text: 'iPhone 15 Pro',
+  top_k: 10,
+  filter: { category: 'electronics' }
+)
+
+results.each do |match|
+  puts "#{match.id}: #{match.score} - #{match.metadata['title']}"
+end
+```
+
+**Use Cases:**
+- Product name search (exact matches)
+- Function/class name search in documentation
+- Keyword-based filtering when semantic search is not needed
+- Faster search when embeddings are not available
+
+---
+
 ### `client.fetch(index:, ids:, namespace: nil)`
 
 Fetch vectors by their IDs.
@@ -357,6 +404,28 @@ puts "Latency: #{status[:latency_ms]}ms"
 
 ---
 
+### `client.with_timeout(seconds) { ... }`
+
+Temporarily override the client's request timeout inside a block.
+
+**Parameters:**
+- `seconds` (Float) - Temporary timeout in seconds
+
+**Returns:** Block result
+
+**Example (fast health check in Rails controller):**
+```ruby
+status = client.with_timeout(0.5) do |c|
+  c.ping
+end
+
+render json: status, status: status[:healthy] ? :ok : :service_unavailable
+```
+
+After the block finishes (even if it raises), the previous `config.timeout` value is restored.
+
+---
+
 ### `client.health_check`
 
 Detailed health check with provider-specific information.

data/docs/api/overview.md

@@ -10,15 +10,15 @@ permalink: /api/overview/
 
 ```ruby
 client = Vectra::Client.new(
-  provider: :pinecone,        # Required: :pinecone, :qdrant, :weaviate, :pgvector
+  provider: :pinecone,        # Required: :pinecone, :qdrant, :weaviate, :pgvector, :memory
   api_key: 'your-api-key',    # Required for cloud providers
-  index_name: 'my-index',     # Optional, provider-dependent
-  host: 'localhost',          # For self-hosted providers
-  port: 6333,                 # For self-hosted providers
-  environment: 'us-west-4'    # For Pinecone
+  index: 'my-index',          # Optional default index
+  namespace: 'tenant-1'       # Optional default namespace
 )
 ```
 
+In Rails, if you use the `vectra:index` generator and `config/vectra.yml` contains exactly one entry, a plain `Vectra::Client.new` will automatically pick that entry's `index` (and `namespace` if present) as defaults.
+
 ## Core Methods
 
 ### `upsert(vectors:)`
@@ -138,6 +138,31 @@ results = client.hybrid_search(
 
 **Provider Support:** Qdrant ✅, Weaviate ✅, pgvector ✅, Pinecone ⚠️
 
+### `text_search(index:, text:, top_k:)`
+
+Text-only search (keyword search without requiring embeddings).
+
+**Parameters:**
+- `index` (String) - Index/collection name (uses client's default index when omitted)
+- `text` (String) - Text query for keyword search
+- `top_k` (Integer) - Number of results (default: 10)
+- `namespace` (String, optional) - Namespace
+- `filter` (Hash, optional) - Metadata filter
+- `include_values` (Boolean) - Include vector values (default: false)
+- `include_metadata` (Boolean) - Include metadata (default: true)
+
+**Example:**
+```ruby
+results = client.text_search(
+  index: 'products',
+  text: 'iPhone 15 Pro',
+  top_k: 10,
+  filter: { category: 'electronics' }
+)
+```
+
+**Provider Support:** Qdrant ✅ (BM25), Weaviate ✅ (BM25), pgvector ✅ (PostgreSQL full-text), Memory ✅, Pinecone ❌
+
 ### `healthy?`
 
 Quick health check - returns true if provider connection is healthy.
@@ -151,6 +176,12 @@ if client.healthy?
 end
 ```
 
+You can also run faster checks with a temporary timeout:
+
+```ruby
+fast_ok = client.with_timeout(0.5) { |c| c.healthy? }
+```
+
 ### `ping`
 
 Ping provider and get connection health status with latency.

data/docs/assets/style.css

@@ -165,6 +165,118 @@ body {
   border-color: var(--tma-color-border-hover);
 }
 
+.tma-nav__search-wrapper {
+  position: relative;
+  margin-right: var(--tma-spacing-md);
+}
+
+.tma-search {
+  position: relative;
+}
+
+.tma-search__input {
+  width: 240px;
+  padding: var(--tma-spacing-sm) var(--tma-spacing-md);
+  padding-left: 2.5rem;
+  background: var(--tma-color-bg-tertiary);
+  border: 1px solid var(--tma-color-border);
+  border-radius: var(--tma-radius-sm);
+  color: var(--tma-color-text-primary);
+  font-size: 0.9rem;
+  font-family: var(--tma-font-family-primary);
+  transition: all var(--tma-transition-fast);
+  outline: none;
+}
+
+.tma-search__input::placeholder {
+  color: var(--tma-color-text-muted);
+}
+
+.tma-search__input:focus {
+  width: 320px;
+  border-color: var(--tma-color-accent-primary);
+  background: var(--tma-color-bg-elevated);
+  box-shadow: 0 0 0 3px var(--tma-color-accent-muted);
+}
+
+.tma-search {
+  position: relative;
+}
+
+.tma-search::before {
+  content: '🔍';
+  position: absolute;
+  left: var(--tma-spacing-md);
+  top: 50%;
+  transform: translateY(-50%);
+  color: var(--tma-color-text-muted);
+  pointer-events: none;
+  z-index: 1;
+  font-size: 0.9rem;
+}
+
+.tma-search__results {
+  position: absolute;
+  top: calc(100% + var(--tma-spacing-xs));
+  left: 0;
+  right: 0;
+  max-width: 500px;
+  max-height: 400px;
+  overflow-y: auto;
+  background: var(--tma-color-bg-elevated);
+  border: 1px solid var(--tma-color-border);
+  border-radius: var(--tma-radius-md);
+  box-shadow: var(--tma-shadow-lg);
+  z-index: 1000;
+  display: none;
+}
+
+.tma-search__results:not(:empty) {
+  display: block;
+}
+
+.tma-search__result {
+  border-bottom: 1px solid var(--tma-color-border);
+}
+
+.tma-search__result:last-child {
+  border-bottom: none;
+}
+
+.tma-search__result-link {
+  display: block;
+  padding: var(--tma-spacing-md);
+  text-decoration: none;
+  color: var(--tma-color-text-primary);
+  transition: background var(--tma-transition-fast);
+}
+
+.tma-search__result-link:hover {
+  background: var(--tma-color-bg-hover);
+}
+
+.tma-search__result-title {
+  display: block;
+  font-weight: 600;
+  font-size: 0.95rem;
+  color: var(--tma-color-text-primary);
+  margin-bottom: var(--tma-spacing-xs);
+}
+
+.tma-search__result-excerpt {
+  display: block;
+  font-size: 0.85rem;
+  color: var(--tma-color-text-secondary);
+  line-height: 1.5;
+}
+
+.tma-search__no-results {
+  padding: var(--tma-spacing-lg);
+  text-align: center;
+  color: var(--tma-color-text-muted);
+  font-size: 0.9rem;
+}
+
 .tma-nav__toggle {
   display: none;
   flex-direction: column;
@@ -1261,6 +1373,25 @@ code {
     justify-content: center;
   }
   
+  .tma-nav__search-wrapper {
+    width: 100%;
+    margin-right: 0;
+    margin-bottom: var(--tma-spacing-md);
+  }
+  
+  .tma-search__input {
+    width: 100%;
+  }
+  
+  .tma-search__input:focus {
+    width: 100%;
+  }
+  
+  .tma-search__results {
+    max-width: 100%;
+    right: 0;
+  }
+  
   .tma-features,
   .tma-providers {
     padding: var(--tma-spacing-xl) var(--tma-spacing-md);

data/docs/guides/rails-integration.md

@@ -99,6 +99,8 @@ This will:
 - Update `app/models/product.rb` to include the concern
 - Add configuration to `config/vectra.yml`
 
+When `config/vectra.yml` contains exactly one entry, a plain `Vectra::Client.new` in this Rails app will automatically use that entry's `index` (and `namespace` if present) as its defaults. That means you can usually omit `index:` when calling `upsert`, `query`, `hybrid_search`, or `text_search`.
+
 ### Run Migrations
 
 ```bash

data/docs/guides/roadmap.md

@@ -0,0 +1,53 @@
+---
+layout: page
+title: Roadmap
+permalink: /guides/roadmap/
+---
+
+# Vectra Roadmap
+
+This page outlines the high-level roadmap for **vectra-client**, the unified Ruby client for vector databases.
+
+The roadmap is intentionally focused on **production features** that make AI workloads reliable, observable, and easy to operate in Ruby.
+
+## Near Term (1.x)
+
+- **Reranking middleware**
+  - Middleware that can call external rerankers (e.g., Cohere, Jina, custom HTTP) and reorder search results after a `query`.
+  - Pluggable providers, configurable `top_n`, and safe fallbacks when reranking fails.
+- **More middleware building blocks**
+  - Request sampling / tracing for debugging complex production issues.
+  - Response shaping (e.g., score normalization, custom thresholds) as reusable middleware.
+- **Rails UX improvements**
+  - Convenience generators and helpers for multi-tenant setups.
+  - Better defaults and examples for 1k+ records demos (e‑commerce, blogs, RAG, recommendations).
+
+## Mid Term
+
+- **Additional providers**
+  - Support for more hosted / self-hosted vector solutions where it makes sense and stays maintainable.
+- **First-class reranking guides**
+  - End-to-end documentation for combining vectra-client with external LLMs / rerankers.
+- **More recipes & patterns**
+  - Deeper recipes for analytics, recommendations, and hybrid search in large Rails apps.
+
+## Long Term Vision
+
+Keep **vectra-client** the most **production-ready Ruby toolkit** for vector databases:
+
+- Strong guarantees around retries, circuit breakers, and backpressure.
+- Excellent observability out of the box.
+- Stable, provider-agnostic API that lets you change infra without rewriting your app.
+
+If you have ideas or needs that fit this direction, please open an issue on GitHub so we can prioritise the roadmap around real-world use cases.
+
+{
+  "cells": [],
+  "metadata": {
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 2
+}

data/docs/search.json

@@ -0,0 +1,26 @@
+---
+layout: null
+---
+[
+  {% assign first = true %}
+  {% for page in site.pages %}
+    {% unless page.url == '/' or page.url == '/search.json' or page.url contains '/assets/' or page.url contains '/404' or page.url contains '/feed' or page.url contains '/sitemap' or page.url contains '/robots' or page.url contains '/index.html' or page.url contains '/index.md' %}
+      {% unless first %},{% endunless %}
+      {
+        "title": {{ page.title | default: page.url | jsonify }},
+        "url": {{ page.url | jsonify }},
+        "excerpt": {{ page.content | strip_html | truncatewords: 30 | default: "" | jsonify }}
+      }
+      {% assign first = false %}
+    {% endunless %}
+  {% endfor %}
+  {% for post in site.posts %}
+    {% unless first %},{% endunless %}
+    {
+      "title": {{ post.title | jsonify }},
+      "url": {{ post.url | jsonify }},
+      "excerpt": {{ post.content | strip_html | truncatewords: 30 | default: "" | jsonify }}
+    }
+    {% assign first = false %}
+  {% endfor %}
+]

data/lib/vectra/client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "yaml"
+
 # Ensure HealthCheck is loaded before Client
 require_relative "health_check" unless defined?(Vectra::HealthCheck)
 require_relative "configuration" unless defined?(Vectra::Configuration)
@@ -89,6 +91,7 @@ module Vectra
       @provider = build_provider
       @default_index = options[:index]
       @default_namespace = options[:namespace]
+      apply_rails_vectra_defaults! if @default_index.nil? && @default_namespace.nil?
       @middleware = build_middleware_stack(options[:middleware])
     end
 
@@ -494,6 +497,67 @@ module Vectra
       )
     end
 
+    # Text-only search (keyword search without embeddings)
+    #
+    # Performs keyword/text search without requiring vector embeddings.
+    # Useful for exact matches, product names, function names, etc.
+    #
+    # @param index [String] the index/collection name
+    # @param text [String] text query for keyword search
+    # @param top_k [Integer] number of results to return (default: 10)
+    # @param namespace [String, nil] optional namespace
+    # @param filter [Hash, nil] metadata filter
+    # @param include_values [Boolean] include vector values in results
+    # @param include_metadata [Boolean] include metadata in results
+    # @return [QueryResult] search results
+    #
+    # @example Basic text search
+    #   results = client.text_search(
+    #     index: 'products',
+    #     text: 'iPhone 15 Pro',
+    #     top_k: 10
+    #   )
+    #
+    # @example Text search with filter
+    #   results = client.text_search(
+    #     index: 'products',
+    #     text: 'laptop',
+    #     filter: { category: 'electronics', in_stock: true }
+    #   )
+    #
+    # @raise [UnsupportedFeatureError] if provider doesn't support text search
+    def text_search(index:, text:, top_k: 10, namespace: nil, filter: nil,
+                    include_values: false, include_metadata: true)
+      index ||= default_index
+      namespace ||= default_namespace
+      validate_index!(index)
+      raise ValidationError, "Text query cannot be nil or empty" if text.nil? || text.empty?
+
+      unless provider.respond_to?(:text_search)
+        raise UnsupportedFeatureError,
+              "Text search is not supported by #{provider_name} provider"
+      end
+
+      Instrumentation.instrument(
+        operation: :text_search,
+        provider: provider_name,
+        index: index,
+        metadata: { top_k: top_k }
+      ) do
+        @middleware.call(
+          :text_search,
+          index: index,
+          text: text,
+          top_k: top_k,
+          namespace: namespace,
+          filter: filter,
+          include_values: include_values,
+          include_metadata: include_metadata,
+          provider: provider_name
+        )
+      end
+    end
+
     # Get the provider name
     #
     # @return [Symbol]
@@ -684,6 +748,44 @@ module Vectra
       Middleware::Stack.new(@provider, all_middleware)
     end
 
+    def apply_rails_vectra_defaults!
+      return unless rails_root_available?
+
+      entry = load_single_vectra_entry
+      return unless entry
+
+      apply_vectra_defaults_from(entry)
+    rescue StandardError => e
+      log_error("Failed to infer default index/namespace from config/vectra.yml", e)
+    end
+
+    def rails_root_available?
+      defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+    end
+
+    def vectra_config_path
+      File.join(Rails.root.to_s, "config", "vectra.yml")
+    end
+
+    def load_single_vectra_entry
+      path = vectra_config_path
+      return unless File.exist?(path)
+
+      raw = File.read(path)
+      data = YAML.safe_load(raw, permitted_classes: [], aliases: true) || {}
+      return unless data.is_a?(Hash) && data.size == 1
+
+      data.values.first || {}
+    end
+
+    def apply_vectra_defaults_from(entry)
+      index = entry["index"] || entry[:index]
+      namespace = entry["namespace"] || entry[:namespace]
+
+      @default_index = index if @default_index.nil? && index.is_a?(String) && !index.empty?
+      @default_namespace = namespace if @default_namespace.nil? && namespace.is_a?(String) && !namespace.empty?
+    end
+
     def validate_index!(index)
       raise ValidationError, "Index name cannot be nil" if index.nil?
       raise ValidationError, "Index name must be a string" unless index.is_a?(String)
@@ -750,6 +852,22 @@ module Vectra
       config.logger.debug("[Vectra] #{data.inspect}") if data
     end
 
+    # Temporarily override request timeout within a block.
+    #
+    # This updates the client's configuration timeout for the duration
+    # of the block and then restores the previous value.
+    #
+    # @param seconds [Float] temporary timeout in seconds
+    # @yield [Client] yields self with overridden timeout
+    # @return [Object] block result
+    def with_timeout(seconds)
+      previous = config.timeout
+      config.timeout = seconds
+      yield self
+    ensure
+      config.timeout = previous
+    end
+
     # Temporarily override default index within a block.
     #
     # @param index [String] temporary index name
@@ -790,7 +908,7 @@ module Vectra
       end
     end
 
-    public :with_index, :with_namespace, :with_index_and_namespace
+    public :with_index, :with_namespace, :with_index_and_namespace, :with_timeout
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/vectra/health_check.rb

@@ -31,7 +31,7 @@ module Vectra
 
       # For health checks we bypass client middleware and call the provider
       # directly to avoid interference from custom stacks.
-      indexes = with_timeout(timeout) { provider.list_indexes }
+      indexes = healthcheck_with_timeout(timeout) { provider.list_indexes }
       index_name = index || indexes.first&.dig(:name)
 
       result = base_result(start_time, indexes)
@@ -53,7 +53,7 @@ module Vectra
 
     private
 
-    def with_timeout(seconds, &)
+    def healthcheck_with_timeout(seconds, &)
       Timeout.timeout(seconds, &)
     rescue Timeout::Error
       raise Vectra::TimeoutError, "Health check timed out after #{seconds}s"
@@ -72,7 +72,7 @@ module Vectra
     def add_index_stats(result, index_name, include_stats, timeout)
       return unless include_stats && index_name
 
-      stats = with_timeout(timeout) { provider.stats(index: index_name) }
+      stats = healthcheck_with_timeout(timeout) { provider.stats(index: index_name) }
       result[:index] = index_name
       result[:stats] = {
         vector_count: stats[:total_vector_count],

data/lib/vectra/middleware/request.rb

@@ -55,7 +55,7 @@ module Vectra
       #
       # @return [Boolean]
       def read_operation?
-        [:query, :fetch, :list_indexes, :describe_index, :stats].include?(operation)
+        [:query, :text_search, :hybrid_search, :fetch, :list_indexes, :describe_index, :stats].include?(operation)
       end
     end
   end

data/lib/vectra/providers/memory.rb

@@ -80,6 +80,32 @@ module Vectra
         QueryResult.from_response(matches: matches, namespace: namespace)
       end
 
+      # Text-only search using simple keyword matching in metadata
+      #
+      # For testing purposes only. Performs case-insensitive keyword matching
+      # in metadata values. Not a real BM25/full-text search implementation.
+      #
+      # @param index [String] index name
+      # @param text [String] text query for keyword search
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @return [QueryResult] search results
+      def text_search(index:, text:, top_k:, namespace: nil, filter: nil,
+                      include_values: false, include_metadata: true)
+        ns = namespace || ""
+        candidates = filter_candidates(@storage[index][ns].values, filter)
+        text_lower = text.to_s.downcase
+
+        matches = find_text_matches(candidates, text_lower, include_values, include_metadata)
+        matches = matches.sort_by { |m| -m[:score] }.first(top_k)
+
+        log_debug("Text search returned #{matches.size} results")
+        QueryResult.from_response(matches: matches, namespace: namespace)
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil)
         ns = namespace || ""
@@ -293,6 +319,36 @@ module Vectra
         true
       end
       # rubocop:enable Naming/PredicateMethod
+
+      # Filter candidates by metadata filter
+      def filter_candidates(candidates, filter)
+        return candidates unless filter
+
+        candidates.select { |v| matches_filter?(v, filter) }
+      end
+
+      # Find text matches in candidates
+      def find_text_matches(candidates, text_lower, include_values, include_metadata)
+        candidates.map do |vec|
+          metadata_text = build_metadata_text(vec)
+          next unless metadata_text.include?(text_lower)
+
+          score = calculate_text_score(text_lower, metadata_text)
+          build_match(vec, score, include_values, include_metadata)
+        end.compact
+      end
+
+      # Build metadata text string for searching
+      def build_metadata_text(vector)
+        (vector.metadata || {}).values.map(&:to_s).join(" ").downcase
+      end
+
+      # Calculate text match score based on word matches
+      def calculate_text_score(query_text, metadata_text)
+        query_words = query_text.split(/\s+/)
+        matched_words = query_words.count { |word| metadata_text.include?(word) }
+        matched_words.to_f / query_words.size
+      end
     end
   end
 end

data/lib/vectra/providers/pgvector.rb

@@ -28,6 +28,7 @@ module Vectra
     #   )
     #   client.upsert(index: 'documents', vectors: [...])
     #
+    # rubocop:disable Metrics/ClassLength
     class Pgvector < Base
       include Connection
       include SqlHelpers
@@ -162,6 +163,54 @@ module Vectra
         )
       end
 
+      # Text-only search using PostgreSQL full-text search
+      #
+      # @param index [String] table name
+      # @param text [String] text query for full-text search
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @param text_column [String] column name for full-text search (default: 'content')
+      # @return [QueryResult] search results
+      #
+      # @note Your table should have a text column with a tsvector index:
+      #   CREATE INDEX idx_content_fts ON my_index USING gin(to_tsvector('english', content));
+      def text_search(index:, text:, top_k:, namespace: nil, filter: nil,
+                      include_values: false, include_metadata: true,
+                      text_column: "content")
+        ensure_table_exists!(index)
+
+        select_cols = ["id"]
+        select_cols << "embedding" if include_values
+        select_cols << "metadata" if include_metadata
+
+        # Use ts_rank for scoring
+        text_score = "ts_rank(to_tsvector('english', COALESCE(#{quote_ident(text_column)}, '')), " \
+                     "plainto_tsquery('english', #{escape_literal(text)}))"
+        select_cols << "#{text_score} AS score"
+
+        where_clauses = build_where_clauses(namespace, filter)
+        where_clauses << "to_tsvector('english', COALESCE(#{quote_ident(text_column)}, '')) @@ " \
+                         "plainto_tsquery('english', #{escape_literal(text)})"
+
+        sql = "SELECT #{select_cols.join(', ')} FROM #{quote_ident(index)}"
+        sql += " WHERE #{where_clauses.join(' AND ')}" if where_clauses.any?
+        sql += " ORDER BY score DESC"
+        sql += " LIMIT #{top_k.to_i}"
+
+        result = execute(sql)
+        matches = result.map { |row| build_match_from_row(row, include_values, include_metadata) }
+
+        log_debug("Text search returned #{matches.size} results")
+
+        QueryResult.from_response(
+          matches: matches,
+          namespace: namespace
+        )
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil)
         ensure_table_exists!(index)
@@ -361,5 +410,6 @@ module Vectra
         raise ConfigurationError, "Host (connection URL or hostname) must be configured for pgvector"
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/vectra/providers/qdrant.rb

@@ -110,6 +110,45 @@ module Vectra
         handle_hybrid_search_response(response, alpha, namespace)
       end
 
+      # Text-only search using Qdrant's BM25 text search
+      #
+      # @param index [String] collection name
+      # @param text [String] text query for keyword search
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @return [QueryResult] search results
+      def text_search(index:, text:, top_k:, namespace: nil, filter: nil,
+                      include_values: false, include_metadata: true)
+        qdrant_filter = build_filter(filter, namespace)
+        body = {
+          query: { text: text },
+          limit: top_k,
+          with_vector: include_values,
+          with_payload: include_metadata
+        }
+
+        body[:filter] = qdrant_filter if qdrant_filter
+
+        response = with_error_handling do
+          connection.post("/collections/#{index}/points/query", body)
+        end
+
+        if response.success?
+          matches = transform_search_results(response.body["result"] || [])
+          log_debug("Text search returned #{matches.size} results")
+
+          QueryResult.from_response(
+            matches: matches,
+            namespace: namespace
+          )
+        else
+          handle_error(response)
+        end
+      end
+
       # @see Base#fetch
       def fetch(index:, ids:, namespace: nil) # rubocop:disable Lint/UnusedMethodArgument
         point_ids = ids.map { |id| generate_point_id(id) }

data/lib/vectra/providers/weaviate.rb

@@ -139,6 +139,36 @@ module Vectra
                                       include_values, include_metadata)
       end
 
+      # Text-only search using Weaviate's BM25 text search
+      #
+      # @param index [String] class name
+      # @param text [String] text query for BM25 search
+      # @param top_k [Integer] number of results
+      # @param namespace [String, nil] optional namespace (not used in Weaviate)
+      # @param filter [Hash, nil] metadata filter
+      # @param include_values [Boolean] include vector values
+      # @param include_metadata [Boolean] include metadata
+      # @return [QueryResult] search results
+      def text_search(index:, text:, top_k:, namespace: nil, filter: nil,
+                      include_values: false, include_metadata: true)
+        where_filter = build_where(filter, namespace)
+        graphql = build_text_search_graphql(
+          index: index,
+          text: text,
+          top_k: top_k,
+          where_filter: where_filter,
+          include_values: include_values,
+          include_metadata: include_metadata
+        )
+        body = { "query" => graphql }
+
+        response = with_error_handling do
+          connection.post("#{API_BASE_PATH}/graphql", body)
+        end
+
+        handle_text_search_response(response, index, namespace, include_values, include_metadata)
+      end
+
       # rubocop:disable Metrics/PerceivedComplexity
       def fetch(index:, ids:, namespace: nil)
         body = {
@@ -337,6 +367,26 @@ module Vectra
         build_graphql_query(index, top_k, text, alpha, vector, where_filter, selection_block)
       end
 
+      def build_text_search_graphql(index:, text:, top_k:, where_filter:,
+                                    include_values:, include_metadata:)
+        selection_block = build_selection_fields(include_values, include_metadata).join(" ")
+        <<~GRAPHQL
+          {
+            Get {
+              #{index}(
+                limit: #{top_k}
+                bm25: {
+                  query: "#{text.gsub('"', '\\"')}"
+                }
+                #{"where: #{JSON.generate(where_filter)}" if where_filter}
+              ) {
+                #{selection_block}
+              }
+            }
+          }
+        GRAPHQL
+      end
+
       def build_graphql_query(index, top_k, text, alpha, vector, where_filter, selection_block)
         <<~GRAPHQL
           {
@@ -379,6 +429,20 @@ module Vectra
         end
       end
 
+      def handle_text_search_response(response, index, namespace, include_values, include_metadata)
+        if response.success?
+          matches = extract_query_matches(response.body, index, include_values, include_metadata)
+          log_debug("Text search returned #{matches.size} results")
+
+          QueryResult.from_response(
+            matches: matches,
+            namespace: namespace
+          )
+        else
+          handle_error(response)
+        end
+      end
+
       def validate_config!
         super
         raise ConfigurationError, "Host must be configured for Weaviate" if config.host.nil? || config.host.empty?

data/lib/vectra/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vectra
-  VERSION = "1.1.0"
+  VERSION = "1.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.2
 platform: ruby
 authors:
 - Mijo Kristo
@@ -274,6 +274,7 @@ files:
 - docs/guides/rails-integration.md
 - docs/guides/rails-troubleshooting.md
 - docs/guides/recipes.md
+- docs/guides/roadmap.md
 - docs/guides/runbooks/cache-issues.md
 - docs/guides/runbooks/high-error-rate.md
 - docs/guides/runbooks/high-latency.md
@@ -288,6 +289,7 @@ files:
 - docs/providers/qdrant.md
 - docs/providers/selection.md
 - docs/providers/weaviate.md
+- docs/search.json
 - examples/GRAFANA_QUICKSTART.md
 - examples/README.md
 - examples/active_record_demo.rb