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 and Contributing
• 📜 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 pull getmeili/meilisearch:latest # Fetch the latest version of MeiliSearch image from Docker Hub
$ 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.umd.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 only guarantees the compatibility with the version v0.15.0 of MeiliSearch.

🎬 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 = 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"
}

Placeholder Search

Placeholder search makes it possible to receive hits based on your parameters without having any query (q). To enable this behavior, instead of sending an empty string, the query should be null or undefined.

await index.search(null, {
  facetFilters: ['genre:fantasy'],
  facetsDistribution: ['genre']
})

{
  "hits": [
    {
      "genre": "fantasy",
      "id": 4,
      "title": "Harry Potter and the Half-Blood Prince",
      "comment": "The best book"
    },
    {
      "genre": "fantasy",
      "id": 42,
      "title": "The Hitchhiker's Guide to the Galaxy"
    }
  ],
  "offset": 0,
  "limit": 20,
  "nbHits": 2,
  "exhaustiveNbHits": false,
  "processingTimeMs": 0,
  "query": "",
  "facetsDistribution": { "genre": { "fantasy": 2, "romance": 0, "sci fi": 0, "adventure": 0 } },
  "exhaustiveFacetsCount": true
}

⚙️ Development Workflow and Contributing

Any new contribution is more than welcome in this project!

If you want to know more about the development workflow or want to contribute, please visit our contributing guidelines for detailed instructions!

📜 API Resources

Search

• Make a search request:

client.getIndex<T>('xxx').search(query: string, options: SearchParams = {}, method: 'POST' | 'GET' = 'POST'): 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>

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>

Dumps

• Trigger a dump creation process

client.createDump(): Promise<Types.EnqueuedDump>

• Get the status of a dump creation process

client.getDumpStatus(dumpUid: string): Promise<Types.EnqueuedDump>

---

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.