Options
All
  • Public
  • Public/Protected
  • All
Menu

Class MiniSearch<T>

MiniSearch is the main entrypoint class, implementing a full-text search engine in memory.

Type parameters

  • T = any

    The type of the documents being indexed.

    Basic 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 = new MiniSearch({
      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 }
    // ]
    

Hierarchy

  • MiniSearch

Index

Constructors

constructor

  • Parameters

    • options: Options<T>

      Configuration options

      Examples:

      // Create a search engine that indexes the 'title' and 'text' fields of your
      // documents:
      const miniSearch = new MiniSearch({ fields: ['title', 'text'] })
      

      ID Field:

      // 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 = new MiniSearch({ idField: 'key', fields: ['title', 'text'] })
      

      Options and defaults:

      // The full set of options (here with their default value) is:
      const miniSearch = new MiniSearch({
        // 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: []
      })
      

    Returns MiniSearch

Accessors

documentCount

  • get documentCount(): number

Methods

add

  • add(document: T): void
  • Adds a document to the index

    Parameters

    • document: T

      The document to be indexed

    Returns void

addAll

  • addAll(documents: T[]): void
  • Adds all the given documents to the index

    Parameters

    • documents: T[]

      An array of documents to be indexed

    Returns void

addAllAsync

  • addAllAsync(documents: T[], options?: { chunkSize?: undefined | number }): Promise<void>
  • 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.

    Parameters

    • documents: T[]

      An array of documents to be indexed

    • Default value options: { chunkSize?: undefined | number } = {}

      Configuration options

      • Optional chunkSize?: undefined | number

    Returns Promise<void>

    A promise resolving to undefined when the indexing is done

autoSuggest

  • 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.

    Basic usage:

    // Get suggestions for 'neuro':
    miniSearch.autoSuggest('neuro')
    // => [ { suggestion: 'neuromancer', terms: [ 'neuromancer' ], score: 0.46240 } ]
    

    Multiple words:

    // 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 }
    // ]
    

    Fuzzy suggestions:

    // Correct spelling mistakes using fuzzy search:
    miniSearch.autoSuggest('neromancer', { fuzzy: 0.2 })
    // => [ { suggestion: 'neuromancer', terms: [ 'neuromancer' ], score: 1.03998 } ]
    

    Filtering:

    // 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 }
    // ]
    

    Parameters

    • queryString: string

      Query string to be expanded into suggestions

    • Default value options: SearchOptions = {}

      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.

    Returns Suggestion[]

    A sorted array of suggestions sorted by relevance score.

remove

  • remove(document: T): void
  • 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

    Parameters

    • document: T

      The document to be removed

    Returns void

removeAll

  • removeAll(documents?: T[]): void
  • Removes all the given documents from the index. If called with no arguments, it removes all documents from the index.

    Parameters

    • Optional documents: T[]

      The documents to be removed. If this argument is omitted, all documents are removed. Note that, for removing all documents, it is more efficient to call this method with no arguments than to pass all documents.

    Returns void

search

  • 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.

    Basic usage:

    // 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: { ... } } ]
    

    Restrict search to specific fields:

    // Search only in the 'title' field
    miniSearch.search('zen', { fields: ['title'] })
    

    Field boosting:

    // Boost a field
    miniSearch.search('zen', { boost: { title: 2 } })
    

    Prefix search:

    // Search for "moto" with prefix search (it will match documents
    // containing terms that start with "moto" or "neuro")
    miniSearch.search('moto neuro', { prefix: true })
    

    Fuzzy search:

    // 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 })
    

    Combining strategies:

    // Mix of exact match, prefix search, and fuzzy search
    miniSearch.search('ismael mob', {
     prefix: true,
     fuzzy: 0.2
    })
    

    Advanced prefix and fuzzy search:

    // 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 with AND:

    // Combine search terms with AND (to match only documents that contain both
    // "motorcycle" and "art")
    miniSearch.search('motorcycle art', { combineWith: 'AND' })
    

    Filtering results:

    // Filter only results in the 'fiction' category (assuming that 'category'
    // is a stored field)
    miniSearch.search('motorcycle art', {
      filter: (result) => result.category === 'fiction'
    })
    

    Advanced combination of queries:

    It is possible to combine different subqueries with OR and AND, and even with different search options, by passing a query expression tree object as the first argument, instead of a string.

    // Search for documents that contain "zen" AND ("motorcycle" OR "archery")
    miniSearch.search({
      combineWith: 'AND',
      queries: [
        'zen',
        {
          combineWith: 'OR',
          queries: ['motorcycle', 'archery']
        }
      ]
    })
    

    Each node in the expression tree can be either a string, or an object that supports all SearchOptions fields, plus a queries array field for subqueries.

    Note that, while this can become complicated to do by hand for complex or deeply nested queries, it provides a formalized expression tree API for external libraries that implement a parser for custom query languages.

    Parameters

    Returns SearchResult[]

toJSON

  • toJSON(): AsPlainObject
  • Allows serialization of the index to JSON, to possibly store it and later deserialize it with MiniSearch.loadJSON.

    Normally one does not directly call this method, but rather call the standard JavaScript JSON.stringify() passing the MiniSearch instance, and JavaScript will internally call this method. Upon deserialization, one must pass to loadJSON the same options used to create the original instance that was serialized.

    Usage:

    // Serialize the index:
    let miniSearch = new MiniSearch({ fields: ['title', 'text'] })
    miniSearch.addAll(documents)
    const json = JSON.stringify(miniSearch)
    
    // Later, to deserialize it:
    miniSearch = MiniSearch.loadJSON(json, { fields: ['title', 'text'] })
    

    Returns AsPlainObject

    A plain-object serializeable representation of the search index.

Static getDefault

  • getDefault(optionName: string): any
  • Returns the default value of an option. It will throw an error if no option with the given name exists.

    Parameters

    • optionName: string

      Name of the option

    Returns any

    The default value of the given option

    Usage:

    // 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"'
    

Static loadJSON

  • 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.

    Usage:

    // If the index was serialized with:
    let miniSearch = new MiniSearch({ fields: ['title', 'text'] })
    miniSearch.addAll(documents)
    
    const json = JSON.stringify(miniSearch)
    // It can later be deserialized like this:
    miniSearch = MiniSearch.loadJSON(json, { fields: ['title', 'text'] })
    

    Type parameters

    • T = any

    Parameters

    • json: string

      JSON-serialized index

    • options: Options<T>

      configuration options, same as the constructor

    Returns MiniSearch<T>

    An instance of MiniSearch deserialized from the given JSON.

Generated using TypeDoc