asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: added search service documentation (#4017)

Browse Source 
* docs: added search service documentation

* added a note about search plugins

* eslint fixes
This commit is contained in:
Shahed Nasser
2023-05-04 17:43:07 +03:00
committed by GitHub
parent 0dbca9552e
commit 09e206fc1b
3 changed files with 483 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

416
docs/content/development/search/create.md Normal file
View File

@@ -0,0 +1,416 @@
---
description: '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.'
addHowToData: true
---
# 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 `AbstractSearchService` class imported from the `@medusajs/utils` package. If you don’t already have the package installed, run the following command to install it within your project:
```bash npm2yarn
npm install @medusajs/utils
```
---
## Step 1: Create Search Service Class
A search service class should be defined in a TypeScript or JavaScript file created in the `src/services` directory. The class must extend the `AbstractSearchService` class imported from the `@medusajs/utils` package.
Based on services’ naming conventions, the file’s name should be the slug version of the search service’s name without `service`, and the class’s name should be the pascal case of the search service’s name following by `Service`.
For example, if you’re creating an algolia search service, the file name would be `algolia.ts`, whereas the class name would be `AlgoliaService`.
:::note
You can learn more about services and their naming convention in [this documentation](../services/overview.mdx).
:::
For example, create the file `src/services/my-search.ts` with the following content:
```ts title=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
```
This creates the service `MySearchService` which, at the moment, adds a general implementation of the methods defined in the abstract class `AbstractSearchService`.
### 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:
<!-- eslint-disable prefer-rest-params -->
```ts title=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
}
// ...
}
```
You can access the plugin options in the second parameter passed to the constructor:
<!-- eslint-disable prefer-rest-params -->
```ts title=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
}
// ...
}
```
### isDefault Property
The `isDefault` property is mainly used to pinpoint the default search service defined in the Medusa core. For custom search services, the `isDefault` property should be `false`.
---
## Step 2: Implement Required Methods
In this section, you’ll learn about the required methods to implement in the search service.
:::note
The Medusa backend mainly uses the `addDocuments`, `deleteDocument`, and `search` 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. `indexName`: this is the first parameter, and it’s a string indicating the name of the index to create.
2. `options`: 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_` would interact with a third-party service:
```ts title=src/services/my-search.ts
class MySearchService extends AbstractSearchService {
// ...
createIndex(indexName: string, options: Record<string, any>) {
return this.client_.initIndex(indexName)
}
}
```
### 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_` would interact with a third-party service:
```ts title=src/services/my-search.ts
class MySearchService extends AbstractSearchService {
// ...
getIndex(indexName: string) {
return this.client_.getIndex(indexName)
}
}
```
### 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:
- `indexName`: the first parameter is a string indicating the name of the index to add the document to.
- `documents`: the second parameter is typically an array of objects to index. For example, it can be an array of products to index.
- `type`: the third parameter is a string indicating the type of object being indexed. For example, when indexing products, the type would be `products`.
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_` would interact with a third-party service:
```ts title=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)
}
}
```
### 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:
- `indexName`: the first parameter is a string indicating the name of the index to replace the documents in.
- `documents`: 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.
- `type`: the third parameter is a string indicating the type of object being indexed. For example, when indexing products, the type would be `products`.
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_` would interact with a third-party service:
```ts title=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)
}
}
```
### 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:
- `indexName`: the first parameter is a string indicating the name of the index this document belongs in.
- `document_id`: 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_` would interact with a third-party service:
```ts title=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)
}
}
```
### 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_` would interact with a third-party service:
```ts title=src/services/my-search.ts
class MySearchService extends AbstractSearchService {
// ...
async deleteAllDocuments(indexName: string) {
return await this.client_
.deleteDocuments(indexName)
}
}
```
### search
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](/api/store#tag/Products/operation/PostProductsSearch) to retrieve the search results.
This method accepts the following parameters:
1. `indexName`: 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 `IndexName` static property of the `ProductService`, which is `products`.
2. `query`: the second parameter is a string indicating the query to use to search through the documents.
3. `options`: 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 `hits` 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_` would interact with a third-party service:
```ts title=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,
}
}
}
```
### 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. `indexName`: the first parameter is a string indicating the index that should be updated.
2. `settings`: 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_` would interact with a third-party service:
```ts title=src/services/my-search.ts
class MySearchService extends AbstractSearchService {
// ...
async updateSettings(
indexName: string,
settings: Record<string, any>
) {
return await this.client_
.updateSettings(indexName, settings)
}
}
```
---
## Step 3: Run Build Command
In the directory of the Medusa backend, run the build command to transpile the files in the `src` directory into the `dist` directory:
```bash npm2yarn
npm run build
```
---
## Test it Out
:::note
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](../plugins/create.md#test-your-plugin) on how to test a plugin.
:::
Run your backend to test it out:
```bash npm2yarn
npm run start
```
You can then send a request to the [Search Products endpoint](/api/store#tag/Products/operation/PostProductsSearch) to see if your search service returns any results.
---
## See Also
- [How to create a plugin](../plugins/create.md)
- [How to publish a plugin](../plugins/publish.md)

44
docs/content/development/search/overview.mdx Normal file
View File

@@ -0,0 +1,44 @@
---
description: "Learn what a search service is and how it’s used in Medusa. A search service is used to manage search indices of searchable items, such as products, and providing results for search operations."
---
import DocCard from '@theme/DocCard';
import Icons from '@theme/Icon';
# Search Service
In this document, you’ll learn what a search service is and how it’s used in Medusa.
## Overview
A search service is used to manage search indices of searchable items, such as products, and providing results for search operations. Although the Medusa core provides basic search functionalities through its endpoints, a search service allows you to integrate third-party services for an optimized search experience and rich search functionalities.
A search service is a service class that is defined in a TypeScript or JavaScript file, which is created in the `src/services` directory of your Medusa backend codebase or plugin. The class must extend the `AbstractSearchService` class imported from the `@medusajs/utils` package.
Using the [dependency container and injection](../fundamentals/dependency-injection.md), the Medusa backend will then use and resolve the search service within the backend’s search operations, such as when the [Search Product](/api/store#tag/Products/operation/PostProductsSearch) endpoint is used. You can also [resolve the service](../services/create-service.md#use-a-service) within your resources to trigger the search where necessary.
Medusa provides official plugins that you can install and use in your Medusa backend. Check out available search plugins [here](../../plugins/search/index.mdx).
### Heirarchy of Search Services
Medusa provides a default search service that doesn’t actually perform any indexing or searching, but acts like a placeholder search service. Only one search service is registered in the dependency container under the `searchService` name.
If you install a search plugin, the search service within it will be registered in the dependency container and used throughout the Medusa backend.
If you create your own search service in the Medusa backend codebase, it will be registered in the dependency container and used throughout the Medusa backend.
---
## Custom Development
Developers can create a custom search service with the desired functionality or third-party integration either directly within the Medusa Core, in a plugin, or in a Commerce Module.
<DocCard item={{
type: 'link',
href: '/development/search/create',
label: 'Create a Search service',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create a search service.'
}
}} />

23
www/docs/sidebars.js
View File

@@ -1656,6 +1656,29 @@ module.exports = {
},
],
},
{
type: "category",
label: "Search Service",
items: [
{
type: "doc",
id: "development/search/overview",
label: "Overview",
},
{
type: "html",
value: "How-to",
customProps: {
sidebar_is_group_divider: true,
},
},
{
type: "doc",
id: "development/search/create",
label: "Create a Search Service",
},
],
},
{
type: "category",
label: "Batch Jobs",