Makeen-search NPM

makeen-search

The Search module provides an API to enable the search powered by different fulltext search engines (like Elasticsearch). It is consumed by makeen-mongodb to provide the search methods for the repositories. Also the generateRESTRouter helper automatically creates a ‘/search’ endpoint for the repositories that have the search feature enabled.

Getting started

This module can be used both standalone and using the makeen-mongodb's Repository instance. But first the configuration should be defined. Add the elasticsearch key to your application config.

Configuration

Example:

{
    // ...
    elasticsearch: {
      connections: [
        {
          name: 'defaultSearchConnection',
          engine: 'elasticsearch',
          url: 'http://localhost:9200/',
          options: {
            log: 'trace',
          },
        },
      ],
    },
    // ...
}

Available configuration options:

connections (required) - Array of connections.
defaultConnection - Name of the connection that will be used by default. If not specified, the first connection in the connections array will be set as default.

Connection config object structure

name (required) - Name of the connection.
engine (required) - Engine that powers the connection. See the list of supported engines below.
url (required) - URL of the connection.
options - Options that will be passed to the engine client.

Supported engines

elasticsearch - Allows to use the Elasticsearch as a search engine.

Usage

You can use this module both standalone and through the instance of the Repository class provided by the makeen-mongodb module.

Usage with repository instance

Example:

const [
  { generateRESTRouter },
  { createRepository },
  { getDefaultSearchConnection },
] = await this.dependencies([
  'makeen.router',
  'makeen.mongoDb',
  'makeen.search',
]);

const userSchema = {
  name: Joi.string().required(),
  archived: Joi.boolean().default(false),
  createdAt: Joi.date(),
  updatedAt: Joi.date(),
};

const User = mongoDb.createRepository({
  name: 'User',
  schema: userSchema,
});

const searchConnection = getDefaultSearchConnection();

// Enable the search module integration
// Default methods of the Repository class sync the data to the search engine.
// If default methods are re-assigned, they should be updated to support the sync too.
await User.enableSearch({
  connection: searchConnection,
  indexSchema: searchConnection.searchService.adaptJoiSchema(userSchema),
});

Insight on this example

This is an example of the main class of the User module. There we import the getDefaultSearchConnection method from the search module and use the strange adaptJoiSchema thing. getDefaultSearchConnection() returns the connection object (don't confuse with a connection config object) and searchConnection.searchService.adaptJoiSchema(userSchema) converts the Joi schema we use for validation to the schema that can be understood by our search engine. This schema is used to create the index and to check if the schema of the existing index is up-to-date.

To get more information about these methods, you should navigate to the API section.

:shipit: Tip by Mr. Squirrel:

By using the generateRESTRouter with the repository that has search enabled, you automatically get a '/%repositoryName%/search' endpoint that accepts the query, limit and offset params.

API

Exported methods of the Search module

createSearchConnection(connectionOptions)

Creates a new connection.

Arguments:

connectionOptions - connection config object.

getSearchConnection(name)

Returns a connection object by the connection name.

Arguments:

name - Name of the connection.

getDefaultSearchConnection()

Returns the default connection object.

Connection object structure

engine - Engine object.
client - Instance of the engine client.
options - Object which contains the properties passed to the engine client using the 'options' property of the connection config object.
searchService - Service class that is used as an abstraction layer to the selected engine's client.
search - Function which returns an instance of the search service. Index name can be passed as the first argument to define a default index for the methods that require the index parameter.

Repository

enableSearch

Enables search integration on the repository instance.

Params:

connection (required) - Search connection object this repository will be using.
index - Index name this repository should be indexing/removing documents to/from. If not specified, the lowercased repository collection name is used as index name.
indexSchema (required) - Schema of the index the repository will use.
router - Custom search router. Used by the 'generateRESTRouter' helper provided by the makeen-mongodb module. If not set, '/search' endpoint is created automatically.

Minimal API of any search service

index

Creates/updates the document in the index.

Params:

index (required) - Index name.
id - Id of the document in the index. If not specified, the _id property of the data object is used.
data (required) - Data object to be stored in the index.

deleteById

Removes the document with the specified id from the index.

Params:

index (required) - Index name.
id (required) - Id of the document to remove.

findByQuery

Searches through the index using the specified query, limit and offset.

findByAdvancedQuery

Searches through the index using a more advanced body parameter, limit and offset.(https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference.html#api-search)

Params:

index (required) - Index name.
query - Query string.
limit - Number of documents to retrieve.
offset - Search offset.

createIndex

Creates an index with specified name and settings.

Params:

index (required) - Index name.
schema - Object which is a schema for documents that will be stored inside the created index.
settings - Additional index settings.

getIndex

Retrieves the index information from the search engine.

Params:

index (required) - Index name.

deleteIndex

Removes the index by it's name.

Params:

index (required) - Index name.

compareIndexSchema

Compares the specified schema with the one that the specified index has. Returns true if schemas are equal and false if not.

Params:

index (required) - Name of the index whose schema should be compared to the schema passed to the schema param.
schema (required) - Schema to compare to.

adaptJoiSchema(joiSchema)

Converts the specified Joi schema to a format that is understandable by the search engine.

Arguments:

joiSchema - Joi shema that should be converted.

:warning: If index is not specified where it is required, the default index will be used. If default index is not specified either, an error will be thrown.