Skip to main content

​
Overview

SearchParams types define the parameters for performing searches in Orama. Orama supports three search modes: full-text, vector, and hybrid search, each with its own parameter type.

​
SearchParams

Main search parameters type that unions all search modes. 
type SearchParams<T extends AnyOrama, ResultDocument = TypedDocument<T>> =
  | SearchParamsFullText<T, ResultDocument>
  | SearchParamsHybrid<T, ResultDocument>
  | SearchParamsVector<T, ResultDocument>

​
Full-Text Search

​
SearchParamsFullText

Parameters for traditional full-text search. 
interface SearchParamsFullText<T extends AnyOrama, ResultDocument = TypedDocument<T>>
​
term
string
The search term, sentence, or word to search for.
​
mode
typeof MODE_FULLTEXT_SEARCH
Search mode. Defaults to full-text search if omitted.
​
properties
'*' | FlattenSchemaProperty<T>[]
The properties to search in. Use '*' to search all properties.
​
limit
number
Maximum number of results to return. Default: 10.
​
offset
number
Number of results to skip. Default: 0.
​
sortBy
SortByParams<T, ResultDocument>
Sort configuration. Can be a SorterParams object or custom function.
​
exact
boolean
Whether to match the term exactly (no fuzzy matching).
​
tolerance
number
Maximum Levenshtein distance for fuzzy matching. Default: 0.
​
relevance
BM25Params
BM25 algorithm parameters for relevance scoring.
​
boost
Partial<Record<string, number>>
Score multipliers for specific properties.
​
facets
FacetsParams<T>
Facet configuration for aggregating results.
​
distinctOn
LiteralUnion<T['schema']>
Property to use for deduplication.
​
groupBy
GroupByParams<T, ResultDocument>
Group results by properties.
​
where
Partial<WhereCondition<T['schema']>>
Filter conditions. See Filter Operators below.
​
threshold
number
Minimum score threshold (0-1). Default: 0.
​
preflight
boolean
Only return count and facets, skip actual results.
​
includeVectors
boolean
Include vector values in results. Default: false.

​
Example

import { search } from '@orama/orama';

const results = await search(db, {
  term: 'laptop',
  properties: ['title', 'description'],
  limit: 20,
  offset: 0,
  tolerance: 1,
  boost: {
    title: 2 // Title matches score twice as high
  },
  where: {
    price: { lt: 1000 },
    inStock: true
  },
  facets: {
    category: {
      limit: 10,
      sort: 'DESC'
    }
  },
  sortBy: {
    property: 'price',
    order: 'ASC'
  }
});

​
SearchParamsVector

Parameters for vector similarity search. 
interface SearchParamsVector<T extends AnyOrama, ResultDocument = TypedDocument<T>>
​
mode
typeof MODE_VECTOR_SEARCH
required
Must be set to 'vector'.
​
term
string
Search term (converted to vector by Secure Proxy plugin).
​
vector
{ value: number[], property: string }
Vector for similarity search.
​
similarity
number
Minimum similarity score (0-1). Default: 0.8.
​
limit
number
Maximum number of results. Default: 10.
​
offset
number
Number of results to skip. Default: 0.
​
where
Partial<WhereCondition<T['schema']>>
Filter conditions.
​
facets
FacetsParams<T>
Facet configuration.
​
groupBy
GroupByParams<T, ResultDocument>
Group results by properties.
​
includeVectors
boolean
Include vector values in results. Default: false.

​
Example

const results = await search(db, {
  mode: 'vector',
  vector: {
    value: embeddings, // number[]
    property: 'embedding'
  },
  similarity: 0.8,
  limit: 10,
  where: {
    category: { eq: 'electronics' }
  }
});

​
SearchParamsHybrid

Parameters for combined full-text and vector search. 
interface SearchParamsHybrid<T extends AnyOrama, ResultDocument = TypedDocument<T>>
​
mode
typeof MODE_HYBRID_SEARCH
required
Must be set to 'hybrid'.
​
term
string
required
The search term for full-text search.
​
vector
{ value: number[], property: string }
Vector for similarity search.
​
properties
'*' | FlattenSchemaProperty<T>[]
Properties to search for full-text portion.
​
tolerance
number
Levenshtein distance for full-text matching.
​
relevance
BM25Params
BM25 parameters for full-text search.
​
limit
number
Results per search mode (10 full-text + 10 vector). Default: 10.
​
offset
number
Results to skip per mode. Default: 0.
​
similarity
number
Minimum vector similarity. Default: 0.8.
​
boost
Partial<Record<string, number>>
Property boosts for full-text search.
​
hybridWeights
HybridWeights
Weight distribution between search modes.
​
where
Partial<WhereCondition<T['schema']>>
Filter conditions.
​
facets
FacetsParams<T>
Facets (full-text results only).
​
groupBy
GroupByParams<T, ResultDocument>
Group results.
​
threshold
number
Minimum score for full-text results. Default: 1.
​
includeVectors
boolean
Include vectors in results. Default: false.

​
Example

const results = await search(db, {
  mode: 'hybrid',
  term: 'noise cancelling headphones',
  vector: {
    value: queryEmbedding,
    property: 'embedding'
  },
  hybridWeights: {
    text: 0.3,
    vector: 0.7
  },
  properties: ['title', 'description'],
  limit: 20
});

​
Filter Operators

​
WhereCondition

Filter conditions support various operators based on field type. 
type WhereCondition<TSchema> =
  | { [key in keyof TSchema]?: Operator<TSchema[key]> }
  | { and?: WhereCondition<TSchema>[] }
  | { or?: WhereCondition<TSchema>[] }
  | { not?: WhereCondition<TSchema> }

​
ComparisonOperator

For number fields: 
type ComparisonOperator = {
  gt?: number   // Greater than
  gte?: number  // Greater than or equal
  lt?: number   // Less than
  lte?: number  // Less than or equal
  eq?: number   // Equal
  between?: [number, number]  // Between range
}

​
EnumComparisonOperator

For enum fields: 
type EnumComparisonOperator = {
  eq?: string | number | boolean
  in?: (string | number | boolean)[]
  nin?: (string | number | boolean)[]  // Not in
}

​
EnumArrComparisonOperator

For enum array fields: 
type EnumArrComparisonOperator = {
  containsAll?: (string | number | boolean)[]
  containsAny?: (string | number | boolean)[]
}

​
GeosearchOperation

For geopoint fields: Radius Search 
type GeosearchRadiusOperator = {
  radius: {
    coordinates: Point
    value: number
    unit?: 'cm' | 'm' | 'km' | 'ft' | 'yd' | 'mi'
    inside?: boolean
    highPrecision?: boolean
  }
}
Polygon Search 
type GeosearchPolygonOperator = {
  polygon: {
    coordinates: Point[]
    inside?: boolean
    highPrecision?: boolean
  }
}

​
Filter Examples

// Number comparisons
await search(db, {
  term: 'laptop',
  where: {
    price: { gte: 500, lte: 1500 },
    rating: { gt: 4.0 }
  }
});

// String/boolean exact match
await search(db, {
  term: 'headphones',
  where: {
    category: 'electronics',
    inStock: true
  }
});

// Enum operators
await search(db, {
  term: 'phone',
  where: {
    brand: { in: ['Apple', 'Samsung', 'Google'] },
    condition: { eq: 'new' }
  }
});

// Logical operators
await search(db, {
  term: 'tablet',
  where: {
    or: [
      { price: { lt: 300 } },
      { brand: { eq: 'Apple' } }
    ]
  }
});

// Geosearch - radius
await search(db, {
  term: 'restaurant',
  where: {
    location: {
      radius: {
        coordinates: { lat: 40.7128, lon: -74.0060 },
        value: 5,
        unit: 'km',
        inside: true
      }
    }
  }
});

// Geosearch - polygon
await search(db, {
  term: 'store',
  where: {
    location: {
      polygon: {
        coordinates: [
          { lat: 40.7128, lon: -74.0060 },
          { lat: 40.7580, lon: -73.9855 },
          { lat: 40.7489, lon: -73.9680 }
        ],
        inside: true
      }
    }
  }
});

Build docs developers (and LLMs) love

Get started for freeTalk to us