Getting instant help by the DeepWiki AI assistant:

Next-Generation full-text search library for Browser and Node.js

Basic Start  • API Reference  • Encoder  • Document Search  • Persistent Indexes  • Using Worker  • Tag Search  • Highlighting  • Resolver  • Changelog

Please Support this Project

FlexSearch has been helping developers around the world build powerful, efficient search functionalities for years. Maintaining and improving the library requires significant time and resources. If you’ve found this project valuable and you're interested in supporting the project, please consider donating. Thanks a lot for your continued support!

FlexSearch Sponsors

Antithesis Operations LLC

FlexSearch performs queries up to 1,000,000 times faster compared to other libraries by also providing powerful search capabilities like multi-field search (document search), phonetic transformations, partial matching, tag-search, result highlighting or suggestions.

Bigger workloads are scalable through workers to perform any updates or queries to the index in parallel through dedicated balanced threads.

The latest generation v0.8 introduce Persistent Indexes, well optimized for scaling of large datasets and running in parallel. All available features was natively ported right into the database engine of your choice.

FlexSearch was nominated by the GitNation for the "Best Technology of the Year".

Supported Platforms:

• Browser
• Node.js

Supported Database:

• InMemory (Default)
• IndexedDB (Browser)
• Redis
• SQLite
• Postgres
• MongoDB
• Clickhouse

Supported Charsets:

• Latin
• Chinese, Korean, Japanese (CJK)
• Hindi
• Arabic
• Cyrillic
• Greek and Coptic
• Hebrew

Common Code Examples:

• Node.js: Module (ESM)
• Node.js: CommonJS
• Browser: Module (ESM)
• Browser: Legacy Script

Demos:

• Auto-Complete

Benchmarks:

• Performance Benchmark
• Matching Benchmark

Run Comparison: Performance Benchmark "Gulliver's Travels"

Extern Projects & Plugins:

• React: https://github.com/angeloashmore/react-use-flexsearch
• Vue: https://github.com/Noction/vue-use-flexsearch
• Gatsby: https://www.gatsbyjs.org/packages/gatsby-plugin-flexsearch/
• Nikola: https://plugins.getnikola.com/v8/flexsearch_plugin/

Table of contents

• Load Library (Node.js, ESM, Legacy Browser)
  • Non-Module Bundles (ES5 Legacy)
  • Module (ESM)
  • Node.js
• Basic Usage and Variants
  • Index Options
  • Search Options
• Common Code Examples (Browser, Node.js)
• API Overview
• Presets
• Context Search
  • Context Options
• Fast-Update Mode
• Suggestions
• Document Search (Multi-Field Search)
  • Document Index Options
  • Document Descriptor
  • Document Search Options
  • Multi-Tag Search
  • Result Highlighting
    • Highlighting Options
      • Boundary Options
      • Ellipsis Options
• Phonetic Search (Fuzzy Search)
• Tokenizer (Partial Search)
• Charset Collection
• Encoder
  • Encoder Options
  • Universal Charset Collection
  • Latin Charset Encoder Presets
  • Language Specific Preset
  • Custom Encoder
• Async Non-Blocking Runtime Balancer
• Worker Indexes
  • Worker Index Options
• Resolver (Complex Queries)
  • Resolver Options
  • Boolean Operations (and, or, xor, not)
  • Boost
  • Limit / Offset
  • Resolve
• Auto-Balanced Cache by Popularity/Last Query
• Export / Import Indexes
  • Fast-Boot Serialization
• Persistent Indexes
  • Persistent Index Options
  • IndexedDB (Browser)
  • Postgres
  • Redis
  • MongoDB
  • SQLite
  • Clickhouse
• Custom Score Function
• Custom Builds
• Extended Keystores (In-Memory Index)
• Best Practices
  • Page-Load / Fast-Boot
  • Prefer numeric typed IDs

Load Library (Node.js, ESM, Legacy Browser)

npm install flexsearch

The dist folder is located in: node_modules/flexsearch/dist/

It is not recommended to use the /src/ folder of this repository as it requires some kind of conditional compilation to resolve the build flags. The /dist/ folder contains every version you might need including unminified ES6 modules. When none of the /dist/ folder versions works for you please open an issue. Alternatively you can read more about Custom Builds.

The Node.js package includes all features.

The abbreviations used at the end of the filenames indicates:

• bundle All features included, FlexSearch is available on window.FlexSearch
• light Only basic features are included, FlexSearch is available on window.FlexSearch
• es5 bundle has support for EcmaScript5, FlexSearch is available on window.FlexSearch
• module indicates that this bundle is a Javascript module (ESM), FlexSearch members are available by import { Index, Document, Worker, Encoder, Charset } from "./flexsearch.bundle.module.min.js" or alternatively using the default export import FlexSearch from "./flexsearch.bundle.module.min.js"
• min bundle is minified
• debug bundle has enabled debug mode and contains additional code just for debugging purposes (do not use for production)

Load Library

Non-Module Bundles (ES5 Legacy)

Non-Module Bundles export all their features to the public namespace "FlexSearch" e.g. window.FlexSearch.Index or window.FlexSearch.Document.

Load the bundle by a script tag:

<script src="dist/flexsearch.bundle.min.js"></script>
<script>
  // ... access FlexSearch
  var Index = window.FlexSearch.Index;
  var index = new Index(/* ... */);
</script>

FlexSearch Members are accessible on:

var Index = window.FlexSearch.Index;
var Document = window.FlexSearch.Document;
var Encoder = window.FlexSearch.Encoder;
var Charset = window.FlexSearch.Charset;
var Resolver = window.FlexSearch.Resolver;
var Worker = window.FlexSearch.Worker;
var IdxDB = window.FlexSearch.IndexedDB;
// only exported by non-module builds:
var Language = window.FlexSearch.Language;

Load language packs:

<!-- English: -->
<script src="dist/lang/en.min.js"></script>
<!-- German: -->
<script src="dist/lang/de.min.js"></script>
<!-- French: -->
<script src="dist/lang/fr.min.js"></script>
<script>
  var EnglishEncoderPreset = window.FlexSearch.Language.en;
  var GermanEncoderPreset = window.FlexSearch.Language.de;
  var FrenchEncoderPreset = window.FlexSearch.Language.fr;
</script>

Module (ESM)

When using modules you can choose from 2 variants: flexsearch.xxx.module.min.js has all features bundled ready for production, whereas the folder /dist/module/ export all the features in the same structure as the source code but here compiler flags was resolved.

Also, for each variant there exist:

1. A debug version for the development
2. A pre-compiled minified version for production

Use the bundled version exported as a module (default export):

<script type="module">
    import FlexSearch from "./dist/flexsearch.bundle.module.min.js";
    const index = new FlexSearch.Index(/* ... */);
</script>

Or import FlexSearch members separately by:

<script type="module">
    import { Index, Document, Encoder, Charset, Resolver, Worker, IndexedDB }
        from "./dist/flexsearch.bundle.module.min.js";
    const index = new Index(/* ... */);
</script>

Use bundled style on non-bundled modules:

<script type="module">
    import { Index, Document, Encoder, Charset, Resolver, Worker, IndexedDB }
        from "./dist/module/bundle.js";
    const index = new Index(/* ... */);
</script>

Use non-bundled modules by file default exports:

<script type="module">
    import Index from "./dist/module/index.js";
    import Document from "./dist/module/document.js";
    import Encoder from "./dist/module/encoder.js";
    import Charset from "./dist/module/charset.js";
    import Resolver from "./dist/module/resolver.js";
    import Worker from "./dist/module/worker.js";
    import IndexedDB from "./dist/module/db/indexeddb/db.js";
    const index = new Index(/* ... */);
</script>

Language packs are accessible via:

import EnglishEncoderPreset from "./dist/module/lang/en.js";
import GermanEncoderPreset from "./dist/module/lang/de.js";
import FrenchEncoderPreset from "./dist/module/lang/fr.js";

Also, pre-compiled non-bundled production-ready modules are located in dist/module-min/, whereas the debug version is located at dist/module-debug/.

You can also load modules via CDN:

<script type="module">
    import Index from "https://unpkg.com/flexsearch@0.8.212/dist/module/index.js";
    const index = new Index(/* ... */);
</script>

Node.js

Install FlexSearch via NPM:

npm install flexsearch

Use the default export:

const FlexSearch = require("flexsearch");
const index = new FlexSearch.Index(/* ... */);

Or require FlexSearch members separately by:

const { Index, Document, Encoder, Charset, Resolver, Worker } = require("flexsearch");
const index = new Index(/* ... */);

When using ESM instead of CommonJS:

import { Index, Document, Encoder, Charset, Resolver, Worker } from "flexsearch";
const index = new Index(/* ... */);

Language packs are accessible via:

const EnglishEncoderPreset = require("flexsearch/lang/en");
const GermanEncoderPreset = require("flexsearch/lang/de");
const FrenchEncoderPreset = require("flexsearch/lang/fr");

Persistent Connectors are accessible via:

const Postgres = require("flexsearch/db/postgres");
const Sqlite = require("flexsearch/db/sqlite");
const MongoDB = require("flexsearch/db/mongodb");
const Redis = require("flexsearch/db/redis");
const Clickhouse = require("flexsearch/db/clickhouse");

Basic Usage and Variants

There are 3 types of indexes:

1. Index is a flat high performance index which stores id-content-pairs.
2. Worker / WorkerIndex is also a flat index which stores id-content-pairs but runs in background as a dedicated worker thread.
3. Document is multi-field index which can store complex JSON documents (could also exist of worker indexes).

The most of you probably need just one of them according to your scenario. Any of these 3 index type are upgradable to persistent indexes.

The worker instance inherits from type Index and basically works like a standard FlexSearch Index. A document index is a complex register automatically operating on several of those standard indexes in parallel. Worker-Support in documents needs to be enabled by just passing the appropriate option during creation e.g. { worker: true }.

index.add(id, text);
const result = index.search(text, options);

document.add(doc);
const result = document.search(text, options);

await worker.add(id, text);
const result = await worker.search(text, options);

Every method called on a Worker index is treated as async. You will get back a Promise or you can provide a callback function as the last parameter alternatively.

Common Code Examples

The documentation will refer to several examples. A list of all examples:

• basic
• basic-suggestion
• basic-persistent
• basic-resolver
• basic-worker
• basic-worker-extern-config
• basic-worker-export-import
• basic-export-import
• document
• document-persistent
• document-resolver
• document-worker
• document-worker-extern-config
• document-export-import
• document-worker-export-import
• language-pack

• basic
• basic-suggestion
• basic-persistent
• basic-resolver
• basic-worker
• basic-worker-extern-config
• basic-worker-export-import
• basic-export-import
• document
• document-persistent
• document-resolver
• document-worker
• document-worker-extern-config
• document-export-import
• document-worker-export-import
• language-packs

• basic
• basic-suggestion
• basic-persistent
• basic-resolver
• basic-worker
• document
• document-highlighting
• document-persistent
• document-resolver
• document-worker
• language-pack

• basic
• basic-suggestion
• basic-persistent
• basic-resolver
• basic-worker
• basic-worker-extern-config
• document
• document-highlighting
• document-persistent
• document-resolver
• document-worker
• document-worker-extern-config
• language-pack

API Overview

Constructors:

• new Index(<options>) : index
• new Document(options) : document
• new Worker(<options>) : worker
• new Encoder(<options>, <options>, ...) : encoder
• new Resolver(<options>) : resolver
• new IndexedDB(<options>) : indexeddb

Global Members:

• Charset
• Language (Legacy Browser Only)

Index / Worker-Index Methods:

• index.add(id, string)
• index.append(id, string)
• index.update(id, string)
• index.remove(id)
• index.search(string, <limit>, <options>)
• index.search(options)
• index.searchCache(...)
• index.contain(id)
• index.clear()
• index.cleanup()

• async index.export(handler)
• async index.import(key, data)
• async index.serialize(boolean)

• async index.mount(db)
• async index.commit()
• async index.destroy()

Document Methods:

• document.add(<id>, document)
• document.append(<id>, document)
• document.update(<id>, document)
• document.remove(id)
• document.remove(document)
• document.search(string, <limit>, <options>)
• document.search(options)
• document.searchCache(...)
• document.contain(id)
• document.clear()
• document.cleanup()
• document.get(id)
• document.set(<id>, document)

• async document.export(handler)
• async document.import(key, data)

• async document.mount(db)
• async document.commit()
• async document.destroy()

Document Properties:

• document.store

Async Equivalents (Non-Blocking Balanced):

• async .addAsync( ... , <callback>)
• async .appendAsync( ... , <callback>)
• async .updateAsync( ... , <callback>)
• async .removeAsync( ... , <callback>)
• async .searchAsync( ... , <callback>)
• async .searchCacheAsync( ... , <callback>)

Async methods will return a Promise, additionally you can pass a callback function as the last parameter.

Methods .export() and also .import() are always async as well as every method you call on a Worker-based or Persistent Index.

Encoder Methods:

• encoder.encode(string)
• encoder.assign(options, <options>, ...)
• encoder.addFilter(string)
• encoder.addStemmer(string => boolean)
• encoder.addMapper(char, char)
• encoder.addMatcher(string, string)
• encoder.addReplacer(regex, string)

Resolver Methods:

• resolver.and(options)
• resolver.or(options)
• resolver.xor(options)
• resolver.not(options)
• resolver.boost(number)
• resolver.limit(number)
• resolver.offset(number)
• resolver.resolve(<options>)

Resolver Properties:

• resolver.result
• resolver.await (Async)

StorageInterface Methods:

• async db.mount(index, <options>)
• async db.open()
• async db.close()
• async db.destroy()
• async db.clear()
• async db.commit(index)

Charset Universal Encoder Preset:

• Charset.Exact
• Charset.Default
• Charset.Normalize

Charset Latin-specific Encoder Preset:

• Charset.LatinBalance
• Charset.LatinAdvanced
• Charset.LatinExtra
• Charset.LatinSoundex

Charset Chinese, Japanese, Korean Encoder Preset:

• Charset.CJK

Language Encoder Preset:

• en
• de
• fr

Basic Usage

Create a new index

const index = new Index();

Create a new index and choosing one of the Presets:

const index = new Index("match");

Create a new index with custom options:

const index = new Index({
    tokenize: "forward"
});

Create a new index and extend a preset with custom options:

var index = new FlexSearch({
    preset: "memory",
    tokenize: "forward",
    resolution: 5
});

Create a new index and assign an Encoder:

import { Charset } from "flexsearch";
const index = new Index({
    tokenize: "forward",
    encoder: Charset.LatinBalance
});

Related Topics: Index Options  •  Resolution  •  Charset Collection  •  Tokenizer

Add text item to an index

Every content which should be added to the index needs an ID. When your content has no ID, then you need to create one by passing an index or count or something else as an ID (a value from type number is highly recommended). Those IDs are unique references to a given content. This is important when you update or adding over content through existing IDs. When referencing is not a concern, you can simply use something simple like count++.

Index.add(id, string)

index.add(0, "John Doe");

Search items

Index.search(string | options, <limit>, <options>)

index.search("John");

Limit the result:

index.search("John", 10);

Check existence of already indexed IDs

You can check if an ID was already indexed by:

if(index.contain(1)){
    console.log("ID was found in index");
}

Update item from an index

Index.update(id, string)

index.update(0, "Max Miller");

Remove item from an index

Index.remove(id)

index.remove(0);

Clear all items from an index

Index.clear()

index.clear();

Chaining

Simply chain methods like:

const index = new Index().addMatcher({'â': 'a'}).add(0, 'foo').add(1, 'bar');

index.remove(0).update(1, 'foo').add(2, 'foobar');

Index Options

Search Options

Suggestions

Any query on each of the index types is supporting the option suggest: true. Also within some of the Resolver stages (and, not, xor) you can add this option for the same purpose.

When suggestions is enabled, it allows results which does not perfectly match to the given query e.g. when one term was not included. Suggestion-Search will keep track of the scoring, therefore the first result entry is the closest one to a perfect match.

const index = new Index().add(1, "cat dog bird");
const result = index.search("cat fish");
// result => []

Same query with suggestion enabled:

const result = index.search("cat fish", { suggest: true });
// result => [ 1 ]

At least one match (or partial match) has to be found to get back any result:

const result = index.search("horse fish", { suggest: true });
// result => []

Resolution

The resolution refers to the maximum count of scoring slots on which the content is divided into.

A formula to determine a well-balanced value for the resolution is: