Skip to main content

​
Full-Text Search

Full-text search is the default search mode in Orama. It allows you to search for documents based on text content across multiple properties with advanced features like BM25 ranking, typo tolerance, and field boosting.

​
Basic Full-Text Search

The simplest way to perform a full-text search is to provide a search term: 
import { create, insert, search } from '@orama/orama'

const db = create({
  schema: {
    name: 'string',
    description: 'string',
    price: 'number'
  }
})

insert(db, {
  name: 'Noise cancelling headphones',
  description: 'Best noise cancelling headphones on the market',
  price: 99.99
})

const results = search(db, {
  term: 'Best headphones'
})

​
Search Response

Full-text search returns a structured response with the following properties: 
{
  elapsed: {
    raw: 21492,
    formatted: '21μs',
  },
  hits: [
    {
      id: '41013877-56',
      score: 0.925085832971998432,
      document: {
        name: 'Noise cancelling headphones',
        description: 'Best noise cancelling headphones on the market',
        price: 99.99
      }
    }
  ],
  count: 1
}
​
count
number
The total number of matched documents
​
hits
Result[]
An array of matched documents taking limit and offset into account
​
elapsed
ElapsedTime
The time taken to search, with both raw nanoseconds and formatted time
​
facets
FacetResult
The facets results if facets are enabled
​
groups
GroupResult[]
The groups results if grouping is enabled

​
Search Parameters

​
term

The search term, sentence, or word to search for: 
const results = search(db, {
  term: 'Red Headphones'
})
The term parameter is optional. When omitted, Orama will return all documents or filter based on the where clause.

​
properties

Specify which properties to search in. By default, Orama searches all string properties: 
const results = search(db, {
  term: 'Michael',
  properties: ['title', 'author']
})

const results = search(db, {
  term: 'headphones',
  properties: '*'
})

​
limit and offset

Control pagination of search results: 
const results = search(db, {
  term: 'headphones',
  limit: 10,  // Return 10 results (default: 10)
  offset: 20  // Skip first 20 results (default: 0)
})

​
mode

Explicitly set the search mode to full-text: 
import { MODE_FULLTEXT_SEARCH } from '@orama/orama'

const results = search(db, {
  term: 'headphones',
  mode: MODE_FULLTEXT_SEARCH // This is the default
})
The mode parameter can be MODE_FULLTEXT_SEARCH, MODE_VECTOR_SEARCH, or MODE_HYBRID_SEARCH. When omitted, Orama defaults to full-text search.

​
Advanced Search Options

​
exact

Perform exact phrase matching (case-sensitive): 
const results = search(db, {
  term: 'Red Headphones',
  exact: true
})
When exact is set to true, the search becomes case-sensitive and will only match documents where the search terms appear as complete words in the specified properties.

​
preflight

Perform a preflight query to get only facets and document count without fetching full documents: 
const result = search(db, {
  term: 'Red Headphones',
  preflight: true
})

console.log(result)
// {
//   elapsed: {
//     raw: 181208,
//     formatted: '181μs'
//   },
//   count: 100,
// }
Preflight queries are useful for displaying search result counts and facets before loading the full results.

​
distinctOn

Return only one result per unique value of a specified property: 
const results = search(db, {
  term: 'Headphones',
  distinctOn: 'category.primary'
})

​
BM25 Relevance Tuning

Orama uses the BM25 algorithm for scoring search results. You can customize the BM25 parameters: 
const results = search(db, {
  term: 'headphones',
  relevance: {
    k: 1.2,  // Term frequency saturation (default: 1.2, range: 1.2-2.0)
    b: 0.75, // Document length impact (default: 0.75)
    d: 0.5   // Frequency normalization (default: 0.5)
  }
})
​
relevance.k
number
default:"1.2"
Term frequency saturation parameter. Higher values give more importance to term frequency. Should be between 1.2 and 2.0.
​
relevance.b
number
default:"0.75"
Document length saturation impact. Higher values give more importance to document length.
​
relevance.d
number
default:"0.5"
Frequency normalization lower bound.

​
Performance Considerations

1

Use Property Filtering

Limit the search to specific properties to improve performance:
search(db, {
  term: 'query',
  properties: ['title'] // Faster than searching all properties
})
2

Implement Pagination

Use limit and offset to paginate results and avoid loading too many documents:
search(db, {
  term: 'query',
  limit: 20,
  offset: 0
})
3

Use Preflight for Counts

Use preflight queries when you only need counts:
search(db, {
  term: 'query',
  preflight: true
})

Typo Tolerance

Handle misspellings and typos in search queries

Boosting

Give more importance to specific fields

Filters

Filter search results by property values

Facets

Generate facets for filtering options

Build docs developers (and LLMs) love

Get started for freeTalk to us