Core Features

Search

Copy page

Cortex implements hybrid search that combines three search methods: vector similarity, keyword matching, and metadata matching. Ask AI/context retrieval uses a different fusion — vector, keyword, and graph traversal, with graph in place of metadata — followed by optional cross-encoder re-ranking. The search endpoint itself stops at its fusion.

Search Methods

Vector Search (Semantic)

Uses embedding similarity to find conceptually related content, even with different wording.

• Powered by OpenAI text-embedding-3-small (1536 dimensions)
• Stored and queried via Neo4j's native vector index
• Finds related concepts, synonyms, and paraphrases

Keyword Search (Full-Text)

Traditional full-text search for exact term matching.

• Uses Neo4j's full-text indexes
• Great for specific terms, names, and codes
• The query is reduced to its word tokens before it reaches the index, so Lucene syntax characters can't break the leg

Metadata Search

Matches document metadata by case-insensitive containment and returns the matching documents' chunks.

• Document filename (relevance 3.0)
• Custom-input topic hint (relevance 2.5)
• Raw content of custom inputs (relevance 2.0)

Hybrid Search Architecture

API Usage

Basic Search

Code
 
curl -X POST "http://localhost:8000/api/search" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning algorithms",
    "limit": 10
  }'

Response

Code
 
{
  "results": [
    {
      "id": "chunk_abc123",
      "content": "Machine learning algorithms can be categorized into supervised, unsupervised, and reinforcement learning...",
      "score": 0.92,
      "document_id": "doc_xyz789",
      "document_title": "ML Fundamentals.pdf",
      "metadata": {
        "page": 15,
        "chunk_index": 3
      }
    }
  ],
  "total": 45,
  "query_time_ms": 127
}

Advanced Search

Code
 
curl -X POST "http://localhost:8000/api/search" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "neural network training",
    "limit": 20,
    "collection_id": "research-papers",
    "search_type": "hybrid",
    "filters": {
      "document_type": "pdf"
    }
  }'

Search Types

Type	Description	When to Use
hybrid	All methods combined (default)	General queries
vector	Semantic search only	Conceptual/abstract queries
keyword	Full-text search only	Exact term matching
graph	Graph traversal only	Relationship exploration

Reciprocal Rank Fusion (RRF)

Cortex uses RRF to combine results from multiple search methods:

Code
 
RRF_score(d) = Σ 1 / (k + rank(d))

Where:

• k is a constant (default: 60)
• rank(d) is the 1-based position in each result list (the first result has rank 1)

The weights for the search endpoint's three legs are fixed defaults (vector 0.5, keyword 0.3, metadata 0.2). The VECTOR_WEIGHT, KEYWORD_WEIGHT, and GRAPH_WEIGHT environment variables tune a different fusion — the Ask AI/context retrieval path, whose RRF legs are vector + keyword + graph traversal.

Cross-Encoder Re-ranking

Cross-encoder re-ranking is not part of the /api/search response — the returned score is the RRF fusion score. The Ask AI endpoints re-rank their retrieval candidates through a cross-encoder model for higher precision:

• Model: cross-encoder/ms-marco-MiniLM-L-6-v2
• Considers query-document pairs together
• Enable/disable via ENABLE_RERANKING (Applies to Ask AI retrieval, not to search results)

Collection-Scoped Search

By default, search queries span all collections. To narrow results to a specific collection, pass collection_id:

Code
 
# Search all collections (default — omit collection_id)
curl -X POST "http://localhost:8000/api/search" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly results"
  }'

# Search a specific collection
curl -X POST "http://localhost:8000/api/search" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly results",
    "collection_id": "financial-reports"
  }'

Graph Context

/api/search responses contain no graph context. Entity/relationship context appears on Ask AI and /api/context responses, whose different retrieval fusion uses graph traversal in place of metadata matching.

Performance Tips

1. Use collection scoping when needed - Search spans all collections by default; narrow to a specific collection for focused results
2. Search weights are fixed - The endpoint always fuses vector/keyword/metadata at 0.5/0.3/0.2; the weight environment variables tune Ask AI retrieval instead
3. Limit results - Start with smaller limits and paginate
4. Re-ranking lives on Ask AI - The cross-encoder step improves Ask AI retrieval precision; search results are always returned RRF-fused