meilisearch

MeiliSearch JavaScript

MeiliSearch | Website | Blog | Twitter | Documentation | FAQ

⚡ Lightning Fast, Ultra Relevant, and Typo-Tolerant Search Engine MeiliSearch client written in JavaScript

MeiliSearch JavaScript is a client for MeiliSearch written in JavaScript. MeiliSearch is a powerful, fast, open-source, easy to use and deploy search engine. Both searching and indexing are highly customizable. Features such as typo-tolerance, filters, and synonyms are provided out-of-the-box.

Table of Contents

• 🔧 Installation
• 🎬 Getting started
• 🤖 Compatibility with MeiliSearch
• 🎬 Examples
  • Indexes
  • Documents
  • Update status
  • Search
• ⚙️ Development Workflow
• 📜 API Resources

🔧 Installation

npm install meilisearch

yarn add meilisearch

🏃‍♀️ Run MeiliSearch

There are many easy ways to download and run a MeiliSearch instance.

For example, if you use Docker:

$ docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest ./meilisearch --master-key=masterKey

NB: you can also download MeiliSearch from Homebrew or APT.

Import

Front end or ESmodule

import MeiliSearch from 'meilisearch'

const client = new MeiliSearch({
    host: 'http://127.0.0.1:7700',
    apiKey: 'masterKey',
  })

HTML import

<script src="https://cdn.jsdelivr.net/npm/meilisearch@latest/dist/bundles/meilisearch.browser.js"></script>
<script>
  const client = new MeiliSearch({
    host: 'http://127.0.0.1:7700',
    apiKey: 'masterKey',
  })
  client.listIndexes().then(res => {
    console.log({ res });
  })
</script>

Back-End CommonJs

const MeiliSearch = require('meilisearch');

const client = new MeiliSearch({
    host: 'http://127.0.0.1:7700',
    apiKey: 'masterKey',
  })

🎬 Getting started

Here is a quickstart for a search request

const MeiliSearch = require('meilisearch')
// Or if you are on a front-end environment:
import MeiliSearch from 'meilisearch'
;(async () => {
  const client = new MeiliSearch({
    host: 'http://127.0.0.1:7700',
    apiKey: 'masterKey',
  })

  const index = await client.createIndex('books') // If your index does not exist
  // OR
  const index = client.getIndex('books') // If your index exists

  const documents = [
    { book_id: 123, title: 'Pride and Prejudice' },
    { book_id: 456, title: 'Le Petit Prince' },
    { book_id: 1, title: 'Alice In Wonderland' },
    { book_id: 1344, title: 'The Hobbit' },
    { book_id: 4, title: 'Harry Potter and the Half-Blood Prince' },
    { book_id: 42, title: "The Hitchhiker's Guide to the Galaxy" },
  ]

  let response = await index.addDocuments(documents)
  console.log(response) // => { "updateId": 0 }
})()

With the updateId, you can check the status (processed or failed) of your documents addition thanks to this method.

Search in index

// MeiliSearch is typo-tolerant:
const search = await index.search('harry pottre')
console.log(search)

Output:

{
  "hits": [
    {
      "book_id": 4,
      "title": "Harry Potter and the Half-Blood Prince"
    }
  ],
  "offset": 0,
  "limit": 20,
  "processingTimeMs": 1,
  "query": "harry pottre"
}

🤖 Compatibility with MeiliSearch

This package is compatible with the following MeiliSearch versions:

• v0.12.X
• v0.11.X

🎬 Examples

All HTTP routes of MeiliSearch are accessible via methods in this SDK.
You can check out the API documentation.

Go checkout examples!

In this section, the examples contain the await keyword.

Indexes

Create an index

// Create an index
const index = await client.createIndex('books')
// Create an index and give the primary-key
const index = await client.createIndex('books', { primaryKey: 'book_id' })

List all indexes

const indexes = await client.listIndexes()

Get an index object

const index = await client.getIndex('books')

Documents

Fetch documents

// Get one document
const document = await index.getDocument(123)

// Get documents by batch
const documents = await index.getDocuments({ offset: 4, limit: 20 })

Add documents

await index.addDocuments([{ book_id: 2, title: 'Madame Bovary' }])

Response:

{
  "updateId": 1
}

With this updateId you can track your operation update.

Delete documents

// Delete one document
await index.deleteDocument(2)
// Delete several documents
await index.deleteDocuments([1, 42])
// Delete all documents /!\
await index.deleteAllDocuments()

Update status

// Get one update
// Parameter: the updateId got after an asynchronous request (e.g. documents addition)
await index.getUpdateStatus(1)
// Get all update satus
await index.getAllUpdateStatus()

Search

Basic search

const search = await index.search('prince')

{
  "hits": [
    {
      "book_id": 456,
      "title": "Le Petit Prince"
    },
    {
      "book_id": 4,
      "title": "Harry Potter and the Half-Blood Prince"
    }
  ],
  "offset": 0,
  "limit": 20,
  "processingTimeMs": 13,
  "query": "prince"
}

Custom search

All the supported options are described in this documentation section.

await index.search('prince', { limit: 1, attributesToHighlight: '*' })

{
  "hits": [
    {
      "book_id": 456,
      "title": "Le Petit Prince",
      "_formatted": {
        "book_id": 456,
        "title": "Le Petit <em>Prince</em>"
      }
    }
  ],
  "offset": 0,
  "limit": 1,
  "processingTimeMs": 0,
  "query": "prince"
}

⚙️ Development Workflow

If you want to contribute, this section describes the steps to follow.

Thank you for your interest in a MeiliSearch tool! ♥️

Install dependencies

$ yarn --dev

Tests and Linter

Each PR should pass the tests and the linter to be accepted.

# Tests
$ docker run -d -p 7700:7700 getmeili/meilisearch:latest ./meilisearch --master-key=masterKey --no-analytics
$ yarn test
# Linter
$ yarn style
# Linter with fixing
$ yarn style:fix
# Build the project
$ yarn build

Release

MeiliSearch tools follow the Semantic Versioning Convention.

You must do a PR modifying the file package.json with the right version.

"version": X.X.X

Once the changes are merged on master, you can publish the current draft release via the GitHub interface.

A GitHub Action will be triggered and push the package on npm.

📜 API Resources

Search

• Make a search request:

client.getIndex<T>('xxx').search(query: string, options?: SearchParams): Promise<SearchResponse<T>>

Indexes

• List all indexes:

client.listIndexes(): Promise<IndexResponse[]>

• Create new index:

client.createIndex<T>(uid: string, options?: IndexOptions): Promise<Index<T>>

• Get index object:

client.getIndex<T>(uid: string): Index<T>

• Get or create index if it does not exist

client.getOrCreateIndex<T>(uid: string, options?: IndexOptions): Promise<Index<T>>

• Show Index information:

index.show(): Promise<IndexResponse>

• Update Index:

index.updateIndex(data: IndexOptions): Promise<IndexResponse>

• Delete Index:

index.deleteIndex(): Promise<void>

• Get specific index stats

index.getStats(): Promise<IndexStats>

Updates

• Get One update info:

index.getUpdateStatus(updateId: number): Promise<Update>

• Get all updates info:

index.getAllUpdateStatus(): Promise<Update[]>

• Wait for pending update:

index.waitForPendingUpdate(updateId: number, { timeOutMs?: number, intervalMs?: number }): Promise<Update>

Documents

• Add or replace multiple documents:

index.addDocuments(documents: Document<T>[]): Promise<EnqueuedUpdate>

• Add or update multiple documents:

index.updateDocuments(documents: Document<T>[]): Promise<EnqueuedUpdate>

• Get Documents:

index.getDocuments(params: getDocumentsParams): Promise<Document<T>[]>

• Get one document:

index.getDocument(documentId: string): Promise<Document<T>>

• Delete one document:

index.deleteDocument(documentId: string | number): Promise<EnqueuedUpdate>

• Delete multiple documents:

index.deleteDocuments(documentsIds: string[] | number[]): Promise<EnqueuedUpdate>

• Delete all documents: index.deleteAllDocuments(): Promise<Types.EnqueuedUpdate>

Settings

• Get settings:

index.getSettings(): Promise<Settings>

• Update settings:

index.updateSettings(settings: Settings): Promise<EnqueuedUpdate>

• Reset settings:

index.resetSettings(): Promise<EnqueuedUpdate>

Synonyms

• Get synonyms:

index.getSynonyms(): Promise<object>

• Update synonyms:

index.updateSynonym(synonyms: object): Promise<EnqueuedUpdate>

• Reset synonyms:

index.resetSynonym(): Promise<EnqueuedUpdate>

Stop-words

• Get Stop Words index.getStopWords(): Promise<string[]>

• Update Stop Words index.updateStopWords(string[]): Promise<EnqueuedUpdate>

• Reset Stop Words index.resetStopWords(): Promise<EnqueuedUpdate>

Ranking rules

• Get Ranking Rules index.getRankingRules(): Promise<string[]>

• Update Ranking Rules index.updateRankingRules(rankingRules: string[]): Promise<EnqueuedUpdate>

• Reset Ranking Rules index.resetRankingRules(): Promise<EnqueuedUpdate>

Distinct Attribute

• Get Distinct Attribute index.getDistinctAttribute(): Promise<string | void>

• Update Distinct Attribute index.updateDistinctAttribute(distinctAttribute: string): Promise<EnqueuedUpdate>

• Reset Distinct Attribute index.resetDistinctAttribute(): Promise<EnqueuedUpdate>

Searchable Attributes

• Get Searchable Attributes index.getSearchableAttributes(): Promise<string[]>

• Update Searchable Attributes index.updateSearchableAttributes(searchableAttributes: string[]): Promise<EnqueuedUpdate>

• Reset Searchable Attributes index.resetSearchableAttributes(): Promise<EnqueuedUpdate>

Displayed Attributes

• Get Displayed Attributes index.getDisplayedAttributes(): Promise<string[]>

• Update Displayed Attributes index.updateDisplayedAttributes(displayedAttributes: string[]): Promise<EnqueuedUpdate>

• Reset Displayed Attributes index.resetDisplayedAttributes(): Promise<EnqueuedUpdate>

Accept new fields

• Get Accept new fields index.getAcceptNewFields(): Promise<boolean>

• Update Accept new fields index.updateAcceptNewFields(acceptNewFields: boolean): Promise<EnqueuedUpdate>

Keys

• Get keys

client.getKeys(): Promise<Keys>

Healthy

• Check if the server is healthy

client.isHealthy(): Promise<void>

Stats

• Get database stats

client.stats(): Promise<Stats>

Version

• Get binary version

client.version(): Promise<Version>

System

• Get system information

client.systemInformation(): Promise<SysInfo>

• Get system information (pretty mode)

client.systemInformationPretty(): Promise<SysInfoPretty>

---

MeiliSearch provides and maintains many SDKs and Integration tools like this one. We want to provide everyone with an amazing search experience for any kind of project. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the integration-guides repository.