Awesome
<p align="center"> <img src="https://raw.githubusercontent.com/meilisearch/integration-guides/main/assets/logos/meilisearch_js.svg" alt="Meilisearch-JavaScript" width="200" height="200" /> </p> <h1 align="center">Meilisearch JavaScript</h1> <h4 align="center"> <a href="https://github.com/meilisearch/meilisearch">Meilisearch</a> | <a href="https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-js">Meilisearch Cloud</a> | <a href="https://www.meilisearch.com/docs">Documentation</a> | <a href="https://discord.meilisearch.com">Discord</a> | <a href="https://roadmap.meilisearch.com/tabs/1-under-consideration">Roadmap</a> | <a href="https://www.meilisearch.com">Website</a> | <a href="https://www.meilisearch.com/docs/faq">FAQ</a> </h4> <p align="center"> <a href="https://www.npmjs.com/package/meilisearch"><img src="https://img.shields.io/npm/v/meilisearch.svg" alt="npm version"></a> <a href="https://github.com/meilisearch/meilisearch-js/actions"><img src="https://github.com/meilisearch/meilisearch-js/workflows/Tests/badge.svg" alt="Tests"></a> <a href="https://codecov.io/gh/meilisearch/meilisearch-js"> <img src="https://codecov.io/github/meilisearch/meilisearch-js/coverage.svg?branch=main" alt="Codecov"> </a> <a href="https://github.com/prettier/prettier"><img src="https://img.shields.io/badge/styled_with-prettier-ff69b4.svg" alt="Prettier"></a> <a href="https://github.com/meilisearch/meilisearch-js/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-informational" alt="License"></a> <a href="https://ms-bors.herokuapp.com/repositories/10"><img src="https://bors.tech/images/badge_small.svg" alt="Bors enabled"></a> </p> <p align="center">⚡ The Meilisearch API client written for JavaScript</p>Meilisearch JavaScript is the Meilisearch API client for JavaScript developers.
Meilisearch is an open-source search engine. Learn more about Meilisearch.
Table of Contents <!-- omit in TOC -->
- 📖 Documentation
- ⚡ Supercharge your Meilisearch experience
- 🔧 Installation
- 🎬 Getting started
- 🤖 Compatibility with Meilisearch
- 💡 Learn more
- ⚙️ Contributing
- 📜 API resources
📖 Documentation
This readme and Meilisearch JS documentation website contains all the information you need to start using this Meilisearch SDK.
For general information on how to use Meilisearch—such as our API reference, tutorials, guides, and in-depth articles—refer to our main documentation website.
⚡ Supercharge your Meilisearch experience
Say goodbye to server deployment and manual updates with Meilisearch Cloud. Get started with a 14-day free trial! No credit card required.
🔧 Installation
We recommend installing meilisearch-js
in your project with your package manager of choice.
npm install meilisearch
meilisearch-js
officially supports node
versions >= 14 and <= 18.
Instead of using a package manager, you may also import the library directly into your HTML via a CDN.
Run Meilisearch <!-- omit in toc -->
To use one of our SDKs, you must first have a running Meilisearch instance. Consult our documentation for instructions on how to download and launch Meilisearch.
Import <!-- omit in toc -->
After installing meilisearch-js
, you must import it into your application. There are many ways of doing that depending on your development environment.
import
syntax <!-- omit in toc -->
Usage in an ES module environment:
import { MeiliSearch } from 'meilisearch'
const client = new MeiliSearch({
host: 'http://127.0.0.1:7700',
apiKey: 'masterKey',
})
<script>
tag <!-- omit in toc -->
Usage in an HTML (or alike) file:
<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',
})
</script>
require
syntax <!-- omit in toc -->
Usage in a back-end node.js or another environment supporting CommonJS modules:
const { MeiliSearch } = require('meilisearch')
const client = new MeiliSearch({
host: 'http://127.0.0.1:7700',
apiKey: 'masterKey',
})
React Native <!-- omit in toc -->
To use meilisearch-js
with React Native, you must also install react-native-url-polyfill.
Deno<!-- omit in toc -->
Usage in a Deno environment:
import { MeiliSearch } from "https://esm.sh/meilisearch"
const client = new MeiliSearch({
host: 'http://127.0.0.1:7700',
apiKey: 'masterKey',
})
🎬 Getting started
Add documents <!-- omit in toc -->
const { MeiliSearch } = require('meilisearch')
// Or if you are in a ES environment
import { MeiliSearch } from 'meilisearch'
;(async () => {
const client = new MeiliSearch({
host: 'http://127.0.0.1:7700',
apiKey: 'masterKey',
})
// An index is where the documents are stored.
const index = client.index('movies')
const documents = [
{ id: 1, title: 'Carol', genres: ['Romance', 'Drama'] },
{ id: 2, title: 'Wonder Woman', genres: ['Action', 'Adventure'] },
{ id: 3, title: 'Life of Pi', genres: ['Adventure', 'Drama'] },
{ id: 4, title: 'Mad Max: Fury Road', genres: ['Adventure', 'Science Fiction'] },
{ id: 5, title: 'Moana', genres: ['Fantasy', 'Action']},
{ id: 6, title: 'Philadelphia', genres: ['Drama'] },
]
// If the index 'movies' does not exist, Meilisearch creates it when you first add the documents.
let response = await index.addDocuments(documents)
console.log(response) // => { "uid": 0 }
})()
Tasks such as document addition always return a unique identifier. You can use this identifier taskUid
to check the status (enqueued
, canceled
, processing
, succeeded
or failed
) of a task.
Basic search <!-- omit in toc -->
// Meilisearch is typo-tolerant:
const search = await index.search('philoudelphia')
console.log(search)
Output:
{
"hits": [
{
"id": "6",
"title": "Philadelphia",
"genres": ["Drama"]
}
],
"offset": 0,
"limit": 20,
"estimatedTotalHits": 1,
"processingTimeMs": 1,
"query": "philoudelphia"
}
Using search parameters <!-- omit in toc -->
meilisearch-js
supports all search parameters described in our main documentation website.
await index.search(
'wonder',
{
attributesToHighlight: ['*']
}
)
{
"hits": [
{
"id": 2,
"title": "Wonder Woman",
"genres": ["Action", "Adventure"],
"_formatted": {
"id": "2",
"title": "<em>Wonder</em> Woman",
"genres": ["Action", "Adventure"]
}
}
],
"offset": 0,
"limit": 20,
"estimatedTotalHits": 1,
"processingTimeMs": 0,
"query": "wonder"
}
Custom search with filters <!-- omit in toc -->
To enable filtering, you must first add your attributes to the filterableAttributes
index setting.
await index.updateFilterableAttributes([
'id',
'genres'
])
You only need to perform this operation once per index.
Note that Meilisearch rebuilds your index whenever you update filterableAttributes
. Depending on the size of your dataset, this might take considerable time. You can track the process using the tasks API).
After you configured filterableAttributes
, you can use the filter
search parameter to refine your search:
await index.search(
'wonder',
{
filter: ['id > 1 AND genres = Action']
}
)
{
"hits": [
{
"id": 2,
"title": "Wonder Woman",
"genres": ["Action","Adventure"]
}
],
"offset": 0,
"limit": 20,
"estimatedTotalHits": 1,
"processingTimeMs": 0,
"query": "wonder"
}
Placeholder search <!-- omit in toc -->
Placeholder search makes it possible to receive hits based on your parameters without having any query (q
). For example, in a movies database you can run an empty query to receive all results filtered by genre
.
await index.search(
'',
{
filter: ['genres = fantasy'],
facets: ['genres']
}
)
{
"hits": [
{
"id": 2,
"title": "Wonder Woman",
"genres": ["Action","Adventure"]
},
{
"id": 5,
"title": "Moana",
"genres": ["Fantasy","Action"]
}
],
"offset": 0,
"limit": 20,
"estimatedTotalHits": 2,
"processingTimeMs": 0,
"query": "",
"facetDistribution": {
"genres": {
"Action": 2,
"Fantasy": 1,
"Adventure": 1
}
}
}
Note that to enable faceted search on your dataset you need to add genres
to the filterableAttributes
index setting. For more information on filtering and faceting, consult our documentation settings.
Abortable search <!-- omit in toc -->
You can abort a pending search request by providing an AbortSignal to the request.
const controller = new AbortController()
index
.search('wonder', {}, {
signal: controller.signal,
})
.then((response) => {
/** ... */
})
.catch((e) => {
/** Catch AbortError here. */
})
controller.abort()
Using Meilisearch behind a proxy <!-- omit in toc -->
Custom request config <!-- omit in toc -->
You can provide a custom request configuration. for example, with custom headers.
const client: MeiliSearch = new MeiliSearch({
host: 'http://localhost:3000/api/meilisearch/proxy',
requestConfig: {
headers: {
Authorization: AUTH_TOKEN
},
// OR
credentials: 'include'
}
})
Custom http client <!-- omit in toc -->
You can use your own HTTP client, for example, with axios
.
const client: MeiliSearch = new MeiliSearch({
host: 'http://localhost:3000/api/meilisearch/proxy',
httpClient: async (url, opts) => {
const response = await $axios.request({
url,
data: opts?.body,
headers: opts?.headers,
method: (opts?.method?.toLocaleUpperCase() as Method) ?? 'GET'
})
return response.data
}
})
🤖 Compatibility with Meilisearch
This package guarantees compatibility with version v1.x of Meilisearch, but some features may not be present. Please check the issues for more info.
💡 Learn more
The following sections in our main documentation website may interest you:
- Manipulate documents: see the API references or read more about documents.
- Search: see the API references or follow our guide on search parameters.
- Manage the indexes: see the API references or read more about indexes.
- Configure the index settings: see the API references or follow our guide on settings parameters.
This repository also contains more examples.
⚙️ Contributing
We welcome all contributions, big and small! If you want to know more about this SDK's development workflow or want to contribute to the repo, please visit our contributing guidelines for detailed instructions.
📜 API resources
Search <!-- omit in toc -->
Make a search request
client.index<T>('xxx').search(query: string, options: SearchParams = {}, config?: Partial<Request>): Promise<SearchResponse<T>>
Make a search request using the GET method (slower than the search method)
client.index<T>('xxx').searchGet(query: string, options: SearchParams = {}, config?: Partial<Request>): Promise<SearchResponse<T>>
Multi Search
Make multiple search requests
client.multiSearch(queries?: MultiSearchParams, config?: Partial<Request>): Promise<Promise<MultiSearchResponse<T>>>
multiSearch
uses the POST
method when performing its request to Meilisearch.
Search For Facet Values
Search for facet values
client.index<T>('myIndex').searchForFacetValues(params: SearchForFacetValuesParams, config?: Partial<Request>): Promise<SearchForFacetValuesResponse>
Documents <!-- omit in toc -->
Add or replace multiple documents
client.index('myIndex').addDocuments(documents: Document<T>[]): Promise<EnqueuedTask>
Add or replace multiple documents in string format
client.index('myIndex').addDocumentsFromString(documents: string, contentType: ContentType, queryParams: RawDocumentAdditionOptions): Promise<EnqueuedTask>
Add or replace multiple documents in batches
client.index('myIndex').addDocumentsInBatches(documents: Document<T>[], batchSize = 1000): Promise<EnqueuedTask[]>
Add or update multiple documents
client.index('myIndex').updateDocuments(documents: Array<Document<Partial<T>>>): Promise<EnqueuedTask>
Add or update multiple documents in string format
client.index('myIndex').updateDocumentsFromString(documents: string, contentType: ContentType, queryParams: RawDocumentAdditionOptions): Promise<EnqueuedTask>
Add or update multiple documents in batches
client.index('myIndex').updateDocumentsInBatches(documents: Array<Document<Partial<T>>>, batchSize = 1000): Promise<EnqueuedTask[]>
Get Documents
client.index.getDocuments(parameters: DocumentsQuery = {}): Promise<DocumentsResults<T>>>
Get one document
client.index('myIndex').getDocument(documentId: string): Promise<Document<T>>
Delete one document
client.index('myIndex').deleteDocument(documentId: string | number): Promise<EnqueuedTask>
Delete multiple documents
client.index('myIndex').deleteDocuments(params: DocumentsDeletionQuery | DocumentsIds): Promise<EnqueuedTask>
Delete all documents
client.index('myIndex').deleteAllDocuments(): Promise<Types.EnqueuedTask>
Tasks <!-- omit in toc -->
Get all tasks
client.getTasks(parameters: TasksQuery): Promise<TasksResults>
Get one task
client.getTask(uid: number): Promise<Task>
Delete tasks
client.deleteTasks(parameters: DeleteTasksQuery = {}): Promise<EnqueuedTask>
Cancel tasks
client.cancelTasks(parameters: CancelTasksQuery = {}): Promise<EnqueuedTask>
Get all tasks of an index
client.index('myIndex').getTasks(parameters: TasksQuery): Promise<TasksResults>
Get one task of an index
client.index('myIndex').getTask(uid: number): Promise<Task>
Wait for one task
Using the client
client.waitForTask(uid: number, { timeOutMs?: number, intervalMs?: number }): Promise<Task>
Using the index
client.index('myIndex').waitForTask(uid: number, { timeOutMs?: number, intervalMs?: number }): Promise<Task>
Wait for multiple tasks
Using the client
client.waitForTasks(uids: number[], { timeOutMs?: number, intervalMs?: number }): Promise<Task[]>
Using the index
client.index('myIndex').waitForTasks(uids: number[], { timeOutMs?: number, intervalMs?: number }): Promise<Task[]>
Indexes <!-- omit in toc -->
Get all indexes in Index instances
client.getIndexes(parameters: IndexesQuery): Promise<IndexesResults<Index[]>>
Get all indexes
client.getRawIndexes(parameters: IndexesQuery): Promise<IndexesResults<IndexObject[]>>
Create a new index
client.createIndex<T>(uid: string, options?: IndexOptions): Promise<EnqueuedTask>
Create a local reference to an index
client.index<T>(uid: string): Index<T>
Get an index instance completed with information fetched from Meilisearch
client.getIndex<T>(uid: string): Promise<Index<T>>
Get the raw index JSON response from Meilisearch
client.getRawIndex(uid: string): Promise<IndexObject>
Get an object with information about the index
client.index('myIndex').getRawInfo(): Promise<IndexObject>
Update Index
Using the client
client.updateIndex(uid: string, options: IndexOptions): Promise<EnqueuedTask>
Using the index object
client.index('myIndex').update(data: IndexOptions): Promise<EnqueuedTask>
Delete index
Using the client
client.deleteIndex(uid): Promise<void>
Using the index object
client.index('myIndex').delete(): Promise<void>
Get specific index stats
client.index('myIndex').getStats(): Promise<IndexStats>
Return Index instance with updated information
client.index('myIndex').fetchInfo(): Promise<Index>
Get Primary Key of an Index
client.index('myIndex').fetchPrimaryKey(): Promise<string | undefined>
Swap two indexes
client.swapIndexes(params: SwapIndexesParams): Promise<EnqueuedTask>
Settings <!-- omit in toc -->
Get settings
client.index('myIndex').getSettings(): Promise<Settings>
Update settings
client.index('myIndex').updateSettings(settings: Settings): Promise<EnqueuedTask>
Reset settings
client.index('myIndex').resetSettings(): Promise<EnqueuedTask>
Pagination Settings
Get pagination
client.index('myIndex').getPagination(): Promise<PaginationSettings>
Update pagination
client.index('myIndex').updatePagination(pagination: PaginationSettings): Promise<EnqueuedTask>
Reset pagination
client.index('myIndex').resetPagination(): Promise<EnqueuedTask>
Synonyms <!-- omit in toc -->
Get synonyms
client.index('myIndex').getSynonyms(): Promise<Synonyms>
Update synonyms
client.index('myIndex').updateSynonyms(synonyms: Synonyms): Promise<EnqueuedTask>
Reset synonyms
client.index('myIndex').resetSynonyms(): Promise<EnqueuedTask>
Stop words <!-- omit in toc -->
Get stop words
client.index('myIndex').getStopWords(): Promise<string[]>
Update stop words
client.index('myIndex').updateStopWords(stopWords: string[] | null ): Promise<EnqueuedTask>
Reset stop words
client.index('myIndex').resetStopWords(): Promise<EnqueuedTask>
Ranking rules <!-- omit in toc -->
Get ranking rules
client.index('myIndex').getRankingRules(): Promise<string[]>
Update ranking rules
client.index('myIndex').updateRankingRules(rankingRules: string[] | null): Promise<EnqueuedTask>
Reset ranking rules
client.index('myIndex').resetRankingRules(): Promise<EnqueuedTask>
Distinct Attribute <!-- omit in toc -->
Get distinct attribute
client.index('myIndex').getDistinctAttribute(): Promise<string | void>
Update distinct attribute
client.index('myIndex').updateDistinctAttribute(distinctAttribute: string | null): Promise<EnqueuedTask>
Reset distinct attribute
client.index('myIndex').resetDistinctAttribute(): Promise<EnqueuedTask>
Searchable attributes <!-- omit in toc -->
Get searchable attributes
client.index('myIndex').getSearchableAttributes(): Promise<string[]>
Update searchable attributes
client.index('myIndex').updateSearchableAttributes(searchableAttributes: string[] | null): Promise<EnqueuedTask>
Reset searchable attributes
client.index('myIndex').resetSearchableAttributes(): Promise<EnqueuedTask>
Displayed attributes <!-- omit in toc -->
Get displayed attributes
client.index('myIndex').getDisplayedAttributes(): Promise<string[]>
Update displayed attributes
client.index('myIndex').updateDisplayedAttributes(displayedAttributes: string[] | null): Promise<EnqueuedTask>
Reset displayed attributes
client.index('myIndex').resetDisplayedAttributes(): Promise<EnqueuedTask>
Filterable attributes <!-- omit in toc -->
Get filterable attributes
client.index('myIndex').getFilterableAttributes(): Promise<string[]>
Update filterable attributes
client.index('myIndex').updateFilterableAttributes(filterableAttributes: string[] | null): Promise<EnqueuedTask>
Reset filterable attributes
client.index('myIndex').resetFilterableAttributes(): Promise<EnqueuedTask>
Sortable attributes <!-- omit in toc -->
Get sortable attributes
client.index('myIndex').getSortableAttributes(): Promise<string[]>
Update sortable attributes
client.index('myIndex').updateSortableAttributes(sortableAttributes: string[] | null): Promise<EnqueuedTask>
Reset sortable attributes
client.index('myIndex').resetSortableAttributes(): Promise<EnqueuedTask>
Faceting <!-- omit in toc -->
Get faceting
client.index('myIndex').getFaceting(): Promise<Faceting>
Update faceting
client.index('myIndex').updateFaceting(faceting: Faceting): Promise<EnqueuedTask>
Reset faceting
client.index('myIndex').resetFaceting(): Promise<EnqueuedTask>
Typo tolerance <!-- omit in toc -->
Get typo tolerance
client.index('myIndex').getTypoTolerance(): Promise<TypoTolerance>
Update typo tolerance
client.index('myIndex').updateTypoTolerance(typoTolerance: TypoTolerance | null): Promise<EnqueuedTask>
Reset typo tolerance
client.index('myIndex').resetTypoTolerance(): Promise<EnqueuedTask>
Separator tokens <!-- omit in toc -->
Get separator tokens
client.index('myIndex').getSeparatorTokens(): Promise<SeparatorTokens>
Update separator tokens
client.index('myIndex').updateSeparatorTokens(separatorTokens: SeparatorTokens | null): Promise<EnqueuedTask>
Reset separator tokens
client.index('myIndex').resetSeparatorTokens(): Promise<EnqueuedTask>
Non Separator tokens <!-- omit in toc -->
Get non separator tokens
client.index('myIndex').getNonSeparatorTokens(): Promise<NonSeparatorTokens>
Update non separator tokens
client.index('myIndex').updateNonSeparatorTokens(nonSeparatorTokens: NonSeparatorTokens | null): Promise<EnqueuedTask>
Reset non separator tokens
client.index('myIndex').resetNonSeparatorTokens(): Promise<EnqueuedTask>
Dictionary <!-- omit in toc -->
Get dictionary
client.index('myIndex').getDictionary(): Promise<Dictionary>
Update dictionary
client.index('myIndex').updateDictionary(dictionary: Dictionary | null): Promise<EnqueuedTask>
Reset dictionary
client.index('myIndex').resetDictionary(): Promise<EnqueuedTask>
Proximity Precision <!-- omit in toc -->
Get proximity precision
client.index('myIndex').getProximityPrecision(): Promise<ProximityPrecision>
Update proximity precision
client.index('myIndex').updateProximityPrecision(proximityPrecision: ProximityPrecision): Promise<EnqueuedTask>
Reset proximity precision
client.index('myIndex').resetProximityPrecision(): Promise<EnqueuedTask>
Embedders <!-- omit in toc -->
⚠️ This feature is experimental. Activate the vectorStore
experimental feature to use it
Get embedders
client.index('myIndex').getEmbedders(): Promise<Embedders>
Update embedders
client.index('myIndex').updateEmbedders(embedders: Embedders): Promise<EnqueuedTask>
Reset embedders
client.index('myIndex').resetEmbedders(): Promise<EnqueuedTask>
SearchCutoffMs <!-- omit in toc -->
Get SearchCutoffMs
client.index('myIndex').getSearchCutoffMs(): Promise<SearchCutoffMs>
Update SearchCutoffMs
client.index('myIndex').updateSearchCutoffMs(searchCutoffMs: SearchCutoffMs): Promise<EnqueuedTask>
Reset SearchCutoffMs
client.index('myIndex').resetSearchCutoffMs(): Promise<EnqueuedTask>
Keys <!-- omit in toc -->
Get keys
client.getKeys(parameters: KeysQuery): Promise<KeysResults>
Get one key
client.getKey(keyOrUid: string): Promise<Key>
Create a key
client.createKey(options: KeyCreation): Promise<Key>
Update a key
client.updateKey(keyOrUid: string, options: KeyUpdate): Promise<Key>
Delete a key
client.deleteKey(keyOrUid: string): Promise<void>
isHealthy
<!-- omit in toc -->
Return true
or false
depending on the health of the server
client.isHealthy(): Promise<boolean>
Health <!-- omit in toc -->
Check if the server is healthy
client.health(): Promise<Health>
Stats <!-- omit in toc -->
Get database stats
client.getStats(): Promise<Stats>
Version <!-- omit in toc -->
Get binary version
client.getVersion(): Promise<Version>
Dumps <!-- omit in toc -->
Trigger a dump creation process
client.createDump(): Promise<EnqueuedTask>
Snapshots <!-- omit in toc -->
Trigger a snapshot on-demand process
client.createSnapshot(): Promise<EnqueuedTask>
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. For a full overview of everything we create and maintain, take a look at the integration-guides repository.