Manual Reference Source
import MiniSearch from 'minisearch/src/MiniSearch.js'
public class | source

MiniSearch

MiniSearch is the main entrypoint class, and represents a full-text search engine.

Example:

const documents = [
  {
    id: 1,
    title: 'Moby Dick',
    text: 'Call me Ishmael. Some years ago...',
    category: 'fiction'
  },
  {
    id: 2,
    title: 'Zen and the Art of Motorcycle Maintenance',
    text: 'I can see by my watch...',
    category: 'fiction'
  },
  {
    id: 3,
    title: 'Neuromancer',
    text: 'The sky above the port was...',
    category: 'fiction'
  },
  {
    id: 4,
    title: 'Zen and the Art of Archery',
    text: 'At first sight it must seem...',
    category: 'non-fiction'
  },
  // ...and more
]

// Create a search engine that indexes the 'title' and 'text' fields for
// full-text search. Search results will include 'title' and 'category' (plus the
// id field, that is always stored and returned)
const miniSearch = MiniSearch.new({
  fields: ['title', 'text'],
  storeFields: ['title', 'category']
})

// Add documents to the index
miniSearch.addAll(documents)

// Search for documents:
let results = miniSearch.search('zen art motorcycle')
// => [
  { id: 2, title: 'Zen and the Art of Motorcycle Maintenance', category: 'fiction', score: 2.77258 },
  { id: 4, title: 'Zen and the Art of Archery', category: 'non-fiction', score: 1.38629 }
]

Static Method Summary

Static Public Methods
public static

getDefault(optionName: string): *

Get the default value of an option.

public static

loadJSON(json: string, options: Object): MiniSearch

Deserializes a JSON index (serialized with miniSearch.toJSON()) and instantiates a MiniSearch instance.

Constructor Summary

Public Constructor
public

constructor(options: Object)

Member Summary

Public Members
public get

Number of documents in the index

Method Summary

Public Methods
public

add(document: Object)

Adds a document to the index

public

addAll(documents: Object[])

Adds all the given documents to the index

public

addAllAsync(documents: Object[], options: Object): Promise

Adds all the given documents to the index asynchronously.

public

autoSuggest(queryString: string, options: Object): Array<{suggestion: string, score: number}>

Provide suggestions for the given search query

public

remove(document: Object)

Removes the given document from the index.

public

search(queryString: string, options: Object): Array<{id: any, score: number, match: Object}>

Search for documents matching the given search query.

public

Allows serialization of the index to JSON, to possibly store it and later deserialize it with MiniSearch.loadJSON

Static Public Methods

public static getDefault(optionName: string): * source

Get the default value of an option. It will throw an error if no option with the given name exists.

Params:

NameTypeAttributeDescription
optionName string

name of the option

Return:

*

the default value of the given option

Example:

// Get default tokenizer
MiniSearch.getDefault('tokenize')
// Get default term processor
MiniSearch.getDefault('processTerm')
// Unknown options will throw an error
MiniSearch.getDefault('notExisting')
// => throws 'MiniSearch: unknown option "notExisting"'

public static loadJSON(json: string, options: Object): MiniSearch source

Deserializes a JSON index (serialized with miniSearch.toJSON()) and instantiates a MiniSearch instance. It should be given the same options originally used when serializing the index.

Warning: JSON (de)serialization of the index is currently tightly coupled to the index implementation. For this reason, the current implementation is to be considered a beta feature, subject to breaking changes changes in future releases. If a breaking change is introduced, though, it will be properly reported in the changelog.

Params:

NameTypeAttributeDescription
json string

JSON-serialized index

options Object

configuration options, same as the constructor

Return:

MiniSearch

an instance of MiniSearch

Public Constructors

public constructor(options: Object) source

Params:

NameTypeAttributeDescription
options Object

Configuration options

options.fields Array<string>

Fields to be indexed. Required.

options.idField string
  • optional
  • default: 'id'

ID field, uniquely identifying a document

options.storeFields Array<string>
  • optional

Fields to store, so that search results would include them. By default none, so resuts would only contain the id field.

options.extractField function(document: Object, fieldName: string): string
  • optional

Function used to get the value of a field in a document

options.tokenize function(text: string, [fieldName]: string): Array<string>
  • optional

Function used to split a field into individual terms

options.processTerm function(term: string, [fieldName]: string): string
  • optional

Function used to process a term before indexing it or searching

options.searchOptions Object
  • optional

Default search options (see the search method for details)

Example:

// Create a search engine that indexes the 'title' and 'text' fields of your
// documents:
const miniSearch = MiniSearch.new({ fields: ['title', 'text'] })
// Your documents are assumed to include a unique 'id' field, but if you want
// to use a different field for document identification, you can set the
// 'idField' option:
const miniSearch = MiniSearch.new({ idField: 'key', fields: ['title', 'text'] })
// The full set of options (here with their default value) is:
const miniSearch = MiniSearch.new({
  // idField: field that uniquely identifies a document
  idField: 'id',

  // extractField: function used to get the value of a field in a document.
  // By default, it assumes the document is a flat object with field names as
  // property keys and field values as string property values, but custom logic
  // can be implemented by setting this option to a custom extractor function.
  extractField: (document, fieldName) => document[fieldName],

  // tokenize: function used to split fields into individual terms. By
  // default, it is also used to tokenize search queries, unless a specific
  // `tokenize` search option is supplied. When tokenizing an indexed field,
  // the field name is passed as the second argument.
  tokenize: (string, _fieldName) => string.split(SPACE_OR_PUNCTUATION),

  // processTerm: function used to process each tokenized term before
  // indexing. It can be used for stemming and normalization. Return a falsy
  // value in order to discard a term. By default, it is also used to process
  // search queries, unless a specific `processTerm` option is supplied as a
  // search option. When processing a term from a indexed field, the field
  // name is passed as the second argument.
  processTerm: (term, _fieldName) => term.toLowerCase(),

  // searchOptions: default search options, see the `search` method for
  // details
  searchOptions: undefined,

  // fields: document fields to be indexed. Mandatory, but not set by default
  fields: undefined

  // storeFields: document fields to be stored and returned as part of the
  // search results.
  storeFields: []
})

Public Members

public get documentCount: number source

Number of documents in the index

Public Methods

public add(document: Object) source

Adds a document to the index

Params:

NameTypeAttributeDescription
document Object

the document to be indexed

public addAll(documents: Object[]) source

Adds all the given documents to the index

Params:

NameTypeAttributeDescription
documents Object[]

an array of documents to be indexed

public addAllAsync(documents: Object[], options: Object): Promise source

Adds all the given documents to the index asynchronously.

Returns a promise that resolves to undefined when the indexing is done. This method is useful when index many documents, to avoid blocking the main thread. The indexing is performed asynchronously and in chunks.

Params:

NameTypeAttributeDescription
documents Object[]

an array of documents to be indexed

options Object
  • optional

Configuration options

options.chunkSize number
  • optional

Size of the document chunks indexed, 10 by default

Return:

Promise

A promise resolving to null when the indexing is done

public autoSuggest(queryString: string, options: Object): Array<{suggestion: string, score: number}> source

Provide suggestions for the given search query

The result is a list of suggested modified search queries, derived from the given search query, each with a relevance score, sorted by descending score.

Params:

NameTypeAttributeDescription
queryString string

Query string to be expanded into suggestions

options Object
  • optional

Search options. The supported options and default values are the same as for the search method, except that by default prefix search is performed on the last term in the query.

Return:

Array<{suggestion: string, score: number}>

A sorted array of suggestions sorted by relevance score.

Example:

// Get suggestions for 'neuro':
miniSearch.autoSuggest('neuro')
// => [ { suggestion: 'neuromancer', terms: [ 'neuromancer' ], score: 0.46240 } ]
// Get suggestions for 'zen ar':
miniSearch.autoSuggest('zen ar')
// => [
//  { suggestion: 'zen archery art', terms: [ 'zen', 'archery', 'art' ], score: 1.73332 },
//  { suggestion: 'zen art', terms: [ 'zen', 'art' ], score: 1.21313 }
// ]
// Correct spelling mistakes using fuzzy search:
miniSearch.autoSuggest('neromancer', { fuzzy: 0.2 })
// => [ { suggestion: 'neuromancer', terms: [ 'neuromancer' ], score: 1.03998 } ]
// Get suggestions for 'zen ar', but only within the 'fiction' category
// (assuming that 'category' is a stored field):
miniSearch.autoSuggest('zen ar', {
  filter: (result) => result.category === 'fiction'
})
// => [
//  { suggestion: 'zen archery art', terms: [ 'zen', 'archery', 'art' ], score: 1.73332 },
//  { suggestion: 'zen art', terms: [ 'zen', 'art' ], score: 1.21313 }
// ]

public remove(document: Object) source

Removes the given document from the index.

The document to delete must NOT have changed between indexing and deletion, otherwise the index will be corrupted. Therefore, when reindexing a document after a change, the correct order of operations is:

  1. remove old version
  2. apply changes
  3. index new version

Params:

NameTypeAttributeDescription
document Object

the document to be indexed

Search for documents matching the given search query.

The result is a list of scored document IDs matching the query, sorted by descending score, and each including data about which terms were matched and in which fields.

Params:

NameTypeAttributeDescription
queryString string

Query string to search for

options Object
  • optional

Search options. Each option, if not given, defaults to the corresponding value of searchOptions given to the constructor, or to the library default.

options.fields Array<string>
  • optional

Fields to search in. If omitted, all fields are searched

options.boost Object<string, number>
  • optional

Key-value object of boosting values for fields

options.prefix boolean | function(term: string, i: number, terms: Array<string>): boolean
  • optional
  • default: false

Whether to perform prefix search. Value can be a boolean, or a function computing the boolean from each tokenized and processed query term. If a function is given, it is called with the following arguments: term: string - the query term; i: number - the term index in the query terms; terms: Array<string> - the array of query terms.

options.fuzzy number | function(term: string, i: number, terms: Array<string>): boolean | number
  • optional
  • default: false

If set to a number greater than or equal 1, it performs fuzzy search within a maximum edit distance equal to that value. If set to a number less than 1, it performs fuzzy search with a maximum edit distance equal to the term length times the value, rouded at the nearest integer. If set to a function, it calls the function for each tokenized and processed query term and expects a numeric value indicating the maximum edit distance, or a falsy falue if fuzzy search should not be performed. If a function is given, it is called with the following arguments: term: string - the query term; i: number - the term index in the query terms; terms: Array<string> - the array of query terms.

options.combineWith string
  • optional
  • default: 'OR'

How to combine term queries (it can be 'OR' or 'AND')

options.tokenize function(query: string): Array<string>
  • optional

Function used to tokenize the search query. It defaults to the same tokenizer used for indexing.

options.processTerm function(term: string): string | null | undefined | false
  • optional

Function used to process each search term. Return a falsy value to discard a term. Defaults to the same function used to process terms upon indexing.

options.filter function(result: Object): boolean
  • optional

Function used to filter search results, for example on the basis of stored fields

Return:

Array<{id: any, score: number, match: Object}>

A sorted array of scored document IDs matching the search

Example:

// Search for "zen art motorcycle" with default options: terms have to match
// exactly, and individual terms are joined with OR
miniSearch.search('zen art motorcycle')
// => [ { id: 2, score: 2.77258, match: { ... } }, { id: 4, score: 1.38629, match: { ... } } ]
// Search only in the 'title' field
miniSearch.search('zen', { fields: ['title'] })
// Boost a field
miniSearch.search('zen', { boost: { title: 2 } })
// Search for "moto" with prefix search (it will match documents
// containing terms that start with "moto" or "neuro")
miniSearch.search('moto neuro', { prefix: true })
// Search for "ismael" with fuzzy search (it will match documents containing
// terms similar to "ismael", with a maximum edit distance of 0.2 term.length
// (rounded to nearest integer)
miniSearch.search('ismael', { fuzzy: 0.2 })
// Mix of exact match, prefix search, and fuzzy search
miniSearch.search('ismael mob', {
 prefix: true,
 fuzzy: 0.2
})
// Perform fuzzy and prefix search depending on the search term. Here
// performing prefix and fuzzy search only on terms longer than 3 characters
miniSearch.search('ismael mob', {
 prefix: term => term.length > 3
 fuzzy: term => term.length > 3 ? 0.2 : null
})
// Combine search terms with AND (to match only documents that contain both
// "motorcycle" and "art")
miniSearch.search('motorcycle art', { combineWith: 'AND' })
// Filter only results in the 'fiction' category (assuming that 'category'
// is a stored field)
miniSearch.search('motorcycle art', {
  filter: (result) => result.category === 'fiction'
})

public toJSON(): Object source

Allows serialization of the index to JSON, to possibly store it and later deserialize it with MiniSearch.loadJSON

Warning: JSON (de)serialization of the index is currently tightly coupled to the index implementation. For this reason, the current implementation is to be considered a beta feature, subject to breaking changes changes in future releases. If a breaking change is introduced, though, it will be reported in the changelog.

Return:

Object

the serializeable representation of the search index