Skip to main content

How to Create a Search Service

In this document, you’ll learn how to create a search service in Medusa. You can create the search service directly in your Medusa backend codebase, in a plugin, or in a module.

Prerequisites​

Medusa Utils Package​

A search service must extend the AbstractSearchServiceCopy to Clipboard class imported from the @medusajs/utilsCopy to Clipboard package. If you don’t already have the package installed, run the following command to install it within your project:

yarn add @medusajs/utils
Report Incorrect CodeCopy to Clipboard

Step 1: Create Search Service Class​

A search service class should be defined in a TypeScript or JavaScript file created in the src/servicesCopy to Clipboard directory. The class must extend the AbstractSearchServiceCopy to Clipboard class imported from the @medusajs/utilsCopy to Clipboard package.

Based on services’ naming conventions, the file’s name should be the slug version of the search service’s name without serviceCopy to Clipboard, and the class’s name should be the pascal case of the search service’s name following by ServiceCopy to Clipboard.

For example, if you’re creating an algolia search service, the file name would be algolia.tsCopy to Clipboard, whereas the class name would be AlgoliaServiceCopy to Clipboard.

You can learn more about services and their naming convention in this documentation.

For example, create the file src/services/my-search.tsCopy to Clipboard with the following content:

src/services/my-search.ts
import { AbstractSearchService } from "@medusajs/utils"

class MySearchService extends AbstractSearchService {
  isDefault = false
  
  createIndex(indexName: string, options: Record<string, any>) {
    throw new Error("Method not implemented.")
  }
  getIndex(indexName: string) {
    throw new Error("Method not implemented.")
  }
  addDocuments(
    indexName: string,
    documents: Record<string, any>[],
    type: string
  ) {
    throw new Error("Method not implemented.")
  }
  replaceDocuments(
    indexName: string,
    documents: Record<string, any>[],
    type: string
  ) {
    throw new Error("Method not implemented.")
  }
  deleteDocument(
    indexName: string,
    document_id: string | number
  ) {
    throw new Error("Method not implemented.")
  }
  deleteAllDocuments(indexName: string) {
    throw new Error("Method not implemented.")
  }
  search(
    indexName: string,
    query: string, 
    options: Record<string, any>
  ) {
    return {
      message: "test",
    }
  }
  updateSettings(
    indexName: string, 
    settings: Record<string, any>
  ) {
    throw new Error("Method not implemented.")
  }

}

export default MySearchService
Report Incorrect CodeCopy to Clipboard

This creates the service MySearchServiceCopy to Clipboard which, at the moment, adds a general implementation of the methods defined in the abstract class AbstractSearchServiceCopy to Clipboard.

Using a Constructor​

You can use a constructor to access services and resources registered in the dependency container, to define any necessary clients if you’re integrating a third-party storage service, and to access plugin options if your search service is defined in a plugin.

For example:

src/services/my-search.ts
// ...
import { ProductService } from "@medusajs/medusa"

type InjectedDependencies = {
  productService: ProductService
}

class MySearchService extends AbstractSearchService {
  // ...
  protected readonly productService_: ProductService

  constructor({ productService }: InjectedDependencies) {
    // @ts-expect-error prefer-rest-params
    super(...arguments)
    this.productService_ = productService
  }

  // ...
}
Report Incorrect CodeCopy to Clipboard

You can access the plugin options in the second parameter passed to the constructor:

src/services/my-search.ts
// ...

class MySearchService extends AbstractSearchService {
  // ...
  protected readonly pluginOptions: Record<string, any>

  constructor({
    productService,
  }: InjectedDependencies, pluginOptions) {
    // @ts-expect-error prefer-rest-params
    super(...arguments)
    
    // ...
    this.pluginOptions = pluginOptions
  }

  // ...
}
Report Incorrect CodeCopy to Clipboard

isDefault Property​

The isDefaultCopy to Clipboard property is mainly used to pinpoint the default search service defined in the Medusa core. For custom search services, the isDefaultCopy to Clipboard property should be falseCopy to Clipboard.

Step 2: Implement Required Methods​

In this section, you’ll learn about the required methods to implement in the search service.

The Medusa backend mainly uses the addDocumentsCopy to Clipboard, deleteDocumentCopy to Clipboard, and searchCopy to Clipboard methods in different scenarios that are explained for each of the methods. Other methods can be helpful based on the search engine you’re integrating.

createIndex​

This method is used to create an index in the search engine.

The method accepts two parameters:

  1. indexNameCopy to Clipboard: this is the first parameter, and it’s a string indicating the name of the index to create.
  2. optionsCopy to Clipboard: this is the second parameter is typically an object, and it can be used to pass any necessary options to the method. This parameter does not have any defined format.

The method does not require any specific data type to be returned.

An example implementation, assuming client_Copy to Clipboard would interact with a third-party service:

src/services/my-search.ts
class MySearchService extends AbstractSearchService {
  // ...

  createIndex(indexName: string, options: Record<string, any>) {
    return this.client_.initIndex(indexName)
  }
}
Report Incorrect CodeCopy to Clipboard

getIndex​

This method is used to retrieve an index’s results from the search engine.

The method accepts one parameter, which is a string indicating the name of the index. The method does not require any specific data type to be returned.

An example implementation, assuming client_Copy to Clipboard would interact with a third-party service:

src/services/my-search.ts
class MySearchService extends AbstractSearchService {
  // ...

  getIndex(indexName: string) {
    return this.client_.getIndex(indexName)
  }
}
Report Incorrect CodeCopy to Clipboard

addDocuments​

This method is used to add a document to an index in the search engine.

This method is used when the Medusa backend loads, indexing all products available in the Medusa backend. It’s also used whenever a new product is added or a product is updated.

The method accepts the following parameters:

  • indexNameCopy to Clipboard: the first parameter is a string indicating the name of the index to add the document to.
  • documentsCopy to Clipboard: the second parameter is typically an array of objects to index. For example, it can be an array of products to index.
  • typeCopy to Clipboard: the third parameter is a string indicating the type of object being indexed. For example, when indexing products, the type would be productsCopy to Clipboard.

The method should return the response of saving the documents in the search engine, but there’s no required format of the response.

An example implementation, assuming client_Copy to Clipboard would interact with a third-party service:

src/services/my-search.ts
class MySearchService extends AbstractSearchService {
  // ...

  async addDocuments(
    indexName: string,
    documents: Record<string, any>[],
    type: string
  ) {
    return await this.client_
      .addDocuments(indexName, documents)
  }
}
Report Incorrect CodeCopy to Clipboard

replaceDocuments​

This method is used to replace the existing documents in the search engine of an index with new documents.

The method accepts the following parameters:

  • indexNameCopy to Clipboard: the first parameter is a string indicating the name of the index to replace the documents in.
  • documentsCopy to Clipboard: the second parameter is typically an array of objects to index. For example, it can be an array of products to index. This would be the new documents to add to the index.
  • typeCopy to Clipboard: the third parameter is a string indicating the type of object being indexed. For example, when indexing products, the type would be productsCopy to Clipboard.

The method should return the response of saving the documents in the search engine, but there’s no required format of the response.

An example implementation, assuming client_Copy to Clipboard would interact with a third-party service:

src/services/my-search.ts
class MySearchService extends AbstractSearchService {
  // ...

  async replaceDocuments(
    indexName: string,
    documents: Record<string, any>[],
    type: string
  ) {
    await this.client_
      .removeDocuments(indexName)
    return await this.client_
      .addDocuments(indexName, documents)
  }
}
Report Incorrect CodeCopy to Clipboard

deleteDocument​

This method is used to delete a document from an index.

When a product is deleted in the Medusa backend, this method is used to delete the product from the search engine’s index.

The method accepts the following parameters:

  • indexNameCopy to Clipboard: the first parameter is a string indicating the name of the index this document belongs in.
  • document_idCopy to Clipboard: the second parameter is a string or a number indicating the ID of the document to delete. When a product is deleted, the product’s ID is passed as the value of this parameter.

The method should return the response of deleting the document in the search engine, but there’s no required format of the response.

An example implementation, assuming client_Copy to Clipboard would interact with a third-party service:

src/services/my-search.ts
class MySearchService extends AbstractSearchService {
  // ...

  async deleteDocument(
    indexName: string,
    document_id: string | number
  ) {
    return await this.client_
      .deleteDocument(indexName, document_id)
  }
}
Report Incorrect CodeCopy to Clipboard

deleteAllDocuments​

This method is used to delete all documents from an index.

The method accepts one parameter, which is a string indicating the name of the index to delete its documents.

The method should return the response of deleting the documents of that index in the search engine, but there’s no required format of the response.

An example implementation, assuming client_Copy to Clipboard would interact with a third-party service:

src/services/my-search.ts
class MySearchService extends AbstractSearchService {
  // ...

  async deleteAllDocuments(indexName: string) {
    return await this.client_
      .deleteDocuments(indexName)
  }
}
Report Incorrect CodeCopy to Clipboard

This method is used to search through an index by a query.

In the Medusa backend, this method is used within the Search Products endpoint to retrieve the search results.

This method accepts the following parameters:

  1. indexNameCopy to Clipboard: the first parameter is a string indicating the index to search through. When using the Search Products endpoint, the index is the default index defined in the IndexNameCopy to Clipboard static property of the ProductServiceCopy to Clipboard, which is productsCopy to Clipboard.
  2. queryCopy to Clipboard: the second parameter is a string indicating the query to use to search through the documents.
  3. optionsCopy to Clipboard: the third parameter is typically an object that can be used to pass any necessary options to the search engine.

Although there’s no required data format or type to be returned to the method, it’s recommended to return an object having a property hitsCopy to Clipboard with its value being an array of results. Each result can be an object of any format. This is recommended as this is the convention followed within Medusa’s official search plugins.

An example implementation, assuming client_Copy to Clipboard would interact with a third-party service:

src/services/my-search.ts
class MySearchService extends AbstractSearchService {
  // ...

  async search(
    indexName: string,
    query: string,
    options: Record<string, any>
  ) {
    const hits = await this.client_
      .search(indexName, query)
    return {
      hits,
    }
  }
}
Report Incorrect CodeCopy to Clipboard

updateSettings​

This method is used to update the settings of an index within the search engine. This can be useful if you want to update the index settings when the plugin options change.

For example, in the Algolia plugin, a loader, which runs when the Medusa backend loads, is used to update the settings of indices based on the plugin options. The loader uses this method to update the settings.

The method accepts the following parameters:

  1. indexNameCopy to Clipboard: the first parameter is a string indicating the index that should be updated.
  2. settingsCopy to Clipboard: the second parameter is typically an object that holds the settings of the index. There’s no defined format for this parameter.

The method should return the response of updating the index in the search engine, but there’s no required format of the response.

An example implementation, assuming client_Copy to Clipboard would interact with a third-party service:

src/services/my-search.ts
class MySearchService extends AbstractSearchService {
  // ...

  async updateSettings(
    indexName: string,
    settings: Record<string, any>
  ) {
    return await this.client_
      .updateSettings(indexName, settings)
  }
}
Report Incorrect CodeCopy to Clipboard

Step 3: Run Build Command​

In the directory of the Medusa backend, run the build command to transpile the files in the srcCopy to Clipboard directory into the distCopy to Clipboard directory:

yarn build
Report Incorrect CodeCopy to Clipboard

Test it Out​

This section explains how to test out your implementation if the search service was created in the Medusa backend codebase. You can refer to the plugin documentation on how to test a plugin.

Run your backend to test it out:

npx @medusajs/medusa-cli develop
Report Incorrect CodeCopy to Clipboard

You can then send a request to the Search Products endpoint to see if your search service returns any results.

See Also​

Was this page helpful?
© 2023 Medusa, Inc. All rights reserved.