Mongoosastic

https://mongoosastic.github.io/mongoosastic/
Admin
Mongoosastic is a Mongoose plugin that automatically indexes your MongoDB models into Elasticsearch,...
Tokens:8,099
Snippets:79
Trust Score:9.7
Update:4 hours ago
Show doc for...
Tokens:
Raw
### Install Mongoosastic with npm

Source: https://mongoosastic.github.io/mongoosastic/

Install the latest version of the mongoosastic package using npm.

```bash
npm install -S mongoosastic
```

--------------------------------

### Connect to multiple hosts with clientOptions

Source: https://mongoosastic.github.io/mongoosastic/

Example showing how to configure multiple Elasticsearch hosts using the clientOptions option.

```javascript
MySchema.plugin(mongoosastic, {
  clientOptions: {
    nodes: [
      'localhost:9200',
      'anotherhost:9200'
    ]
  }
})
```

--------------------------------

### JavaScript example: Add Mongoosastic plugin to a User schema

Source: https://mongoosastic.github.io/mongoosastic/

A JavaScript example showing how to define a Mongoose schema and apply the Mongoosastic plugin to index it into Elasticsearch.

```javascript
const mongoose = require('mongoose')
const mongoosastic = require('mongoosastic')
const Schema = mongoose.Schema

const UserSchema = new Schema({
    name: String,
    email: String,
    city: String
})

UserSchema.plugin(mongoosastic)
```

--------------------------------

### esSearch example with range query

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Example of using Person.esSearch to get the 61st to 80th ranked people in an age range.

```javascript
// only the 61st to 80th ranked people who fit the age group are here!
const people = await Person.esSearch({
  from: 60,
  size: 20,
  query: {
    range: {
      age:{
        from:21,
        to: 30
      }
    }
  }
});
```

--------------------------------

### TypeScript example: Add Mongoosastic plugin to a User schema

Source: https://mongoosastic.github.io/mongoosastic/

A TypeScript example showing how to define a Mongoose schema with TypeScript interfaces and apply the Mongoosastic plugin.

```typescript
import mongoose, { Schema, Document } from 'mongoose'
import mongoosastic, { MongoosasticModel, MongoosasticDocument } from 'mongoosastic'

interface IUser extends Document, MongoosasticDocument {
    name: string,
    email: string,
    city: string,
}

var UserSchema = new Schema({
    name: String,
    email: String,
    city: String
})

UserSchema.plugin(mongoosastic)

const User = mongoose.model<IUser, MongoosasticModel<IUser>>('User', UserSchema)
```

--------------------------------

### Reuse an existing Elasticsearch Client

Source: https://mongoosastic.github.io/mongoosastic/

Example showing how to pass an existing Elasticsearch Client instance to the plugin using the esClient option.

```typescript
import { Client } from '@elastic/elasticsearch'

const esClient = new Client({ node: 'http://localhost:9200' })

MySchema.plugin(mongoosastic, {
  esClient: esClient
})
```

--------------------------------

### Search using the search method

Source: https://mongoosastic.github.io/mongoosastic/

Example of using the search method with Elasticsearch query DSL to find documents.

```javascript
const results = await User.search({
  query_string: {
    query: "john"
  }
});
```

--------------------------------

### Index only specific fields with es_indexed

Source: https://mongoosastic.github.io/mongoosastic/

Example showing how to index only certain fields by setting es_indexed to true on the desired fields.

```javascript
var UserSchema = new Schema({
    name: { type: String, es_indexed: true },
    email: String,
    city: String
})

UserSchema.plugin(mongoosastic)
```

--------------------------------

### Index a geo point

Source: https://mongoosastic.github.io/mongoosastic/mapping.html

Shows how to create a GeoModel instance with a geo_with_lat_lon field containing lat and lon coordinates. The field name must start with 'geo_' to be recognized.

```javascript
var geo = new GeoModel({
  /* … */
  geo_with_lat_lon: { lat: 1, lon: 2}
  /* … */
});
```

--------------------------------

### Configure bulk indexing with mongoosastic

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Set bulk options in the plugin to use Elasticsearch's bulk indexing API. Mongoosastic waits 1 second (or specified delay) until it has 1000 docs (or specified size) before performing bulk indexing. The example uses size 10 and delay 100 milliseconds.

```javascript
BookSchema.plugin(mongoosastic, {
  bulk: {
    size: 10, // preferred number of docs to bulk index
    delay: 100 //milliseconds to wait for enough docs to meet size constraint
  }
});
```

--------------------------------

### Synchronize an existing collection with mongoosastic

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Call Book.synchronize() to open a mongoose stream and index documents individually. The stream emits 'data' events for each document, 'close' when done, and 'error' on failure. The example logs the indexed count.

```javascript
var BookSchema = new Schema({
    title: String
});
BookSchema.plugin(mongoosastic);

const Book = mongoose.model('Book', BookSchema)

const stream = Book.synchronize();
const count = 0;

stream.on('data', function(err, doc) {
  count++;
});

stream.on('close', function() {
  console.log('indexed ' + count + ' documents!');
});

stream.on('error', function(err) {
  console.log(err);
});
```

--------------------------------

### Hydration with hydrate option

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Use { hydrate: true } as the second argument to a search call to get Mongoose objects. The hydrated results are accessible via results.body.hits.hydrated.

```javascript
const results = await User.search(
  {
    query_string: {
      query: 'john'
    }
  },
  { hydrate: true }
);

console.log(results.body.hits.hits) // will be empty: []
console.log(results.body.hits.hydrated)
```

--------------------------------

### Filtered indexing with filter function

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Define a filter function in the mongoosastic plugin options. The function must return true for conditions that should skip indexing. In this example, documents with genre 'action' are not indexed.

```javascript
var MovieSchema = new Schema({
  title: { type: String },
  genre: { type: String, enum: ['horror', 'action', 'adventure', 'other'] }
});

MovieSchema.plugin(mongoosastic, {
  filter: function(doc) {
    return doc.genre === 'action';
  }
});
```

--------------------------------

### Create mapping on demand with createMapping

Source: https://mongoosastic.github.io/mongoosastic/mapping.html

Shows how to create a mapping for a Book model using Book.createMapping with a custom analyzer. This is a one-time operation that should be called manually; if the mapping already exists, an exception is thrown.

```javascript
var BookSchema = new Schema({
    title: { type:String, es_boost:2.0 },
    author: { type: String, es_null_value: "Unknown Author" },
    publicationDate: { type: Date, es_type: 'date'}
})

BookSchema.plugin(mongoosastic);

var Book = mongoose.model('Book', BookSchema);

const mapping = await Book.createMapping({
  "analysis" : {
    "analyzer":{
      "content":{
        "type":"custom",
        "tokenizer":"whitespace"
      }
    }
  }
});
```

--------------------------------

### ExampleSchema with various mapping options

Source: https://mongoosastic.github.io/mongoosastic/mapping.html

Illustrates the currently possible mapping definitions in mongoosastic, including core types, arrays, objects, nested schemas, multi-field, geo point, geo shape, and a custom es_cast function.

```javascript
var ExampleSchema = new Schema({
  // String (core type)
  string: {type:String, es_boost:2.0},

  // Number (core type)
  number: {type:Number, es_type:'integer'},

  // Date (core type)
  date: {type:Date, es_type:'date'},

  // Array type
  array: {type:Array, es_type:'string'},

  // Object type
  object: {
    field1: {type: String},
    field2: {type: String}
  },

  // Nested type
  nested: [SubSchema],

  // Multi field type
  multi_field: {
    type: String,
    es_type: 'multi_field',
    es_fields: {
      multi_field: { type: 'string', index: 'analyzed' },
      untouched: { type: 'string', index: 'not_analyzed' }
    }
  },

  // Geo point type
  geo: {
    type: String,
    es_type: 'geo_point'
  },

  // Geo point type with lat_lon fields
  geo_with_lat_lon: {
    geo_point: {
      type: String,
      es_type: 'geo_point',
      es_lat_lon: true
    },
    lat: { type: Number },
    lon: { type: Number }
  }

  geo_shape: {
    coordinates : [],
    type: {type: String},
    geo_shape: {
      type:String,
      es_type: "geo_shape",
      es_tree: "quadtree",
      es_precision: "1km"
    }
  }

  // Special feature : specify a cast method to pre-process the field before indexing it
  someFieldToCast : {
    type: String,
    es_cast: function(value){
      return value + ' something added';
    }
  }

});

// Used as nested schema above.
var SubSchema = new Schema({
  field1: {type: String},
  field2: {type: String}
});
```

--------------------------------

### Define a BookSchema with es_boost and es_null_value

Source: https://mongoosastic.github.io/mongoosastic/mapping.html

Shows how to set per-field mapping options like es_boost and es_null_value in a schema. The es_type option overrides the schema type for stronger typing.

```javascript
var BookSchema = new Schema({
    title: { type: String, es_boost: 2.0 },
    author: { type: String, es_null_value: "Unknown Author" },
    publicationDate: { type: Date, es_type: 'date' }
});
```

--------------------------------

### Index on demand using index()

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Use the instance method `index()` to manually index a document. The method accepts an optional options object with an `index` property to specify the target index, defaulting to the model's standard index. Note that indexing does not persist to MongoDB; use `save()` for that.

```javascript
const dude = await Dude.findOne({ name:'Jeffrey Lebowski' });

dude.awesome = true;
await dude.index();
```

--------------------------------

### Search with sort option

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Pass a sort option as the second argument to Person.search to sort results by age ascending.

```javascript
const sortedPeople = await Person.search({/* ... */}, { sort: "age:asc" });
```

--------------------------------

### index() - Indexing On Demand

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Index a document to Elasticsearch on demand. The method takes an optional options object with an index field to specify the target index.

```APIDOC
## index() - Indexing On Demand

### Description
Index a document to Elasticsearch on demand. The method takes an optional options object with an index field to specify the target index.

### Method
index()

### Parameters
- `options` (optional) - { index: string } - The index to publish to. Defaults to the standard index that the model was setup with.

### Example
```javascript
const dude = await Dude.findOne({ name:'Jeffrey Lebowski' });

dude.awesome = true;
await dude.index();
```

### Notes
Indexing a model does not mean it will be persisted to mongodb. Use `save()` for that.
```

--------------------------------

### Index a geo shape

Source: https://mongoosastic.github.io/mongoosastic/mapping.html

Shows how to create a GeoModel instance with a geo_shape field of type 'envelope' and coordinates as an array of [lon,lat] pairs.

```javascript
var geo = new GeoModel({
  …
  geo_shape:{
    type:'envelope',
    coordinates: [[3,4],[1,2] /* Arrays of coord : [[lon,lat],[lon,lat]] */
  }
  …
});
```

--------------------------------

### Save document and listen for es-indexed event

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Saving a document triggers indexing in the background. Listen for the 'es-indexed' event to know when indexing is complete.

```javascript
doc.save(function(err){
  if (err) throw err;
  /* Document indexation on going */
  doc.on('es-indexed', function(err, res){
    if (err) throw err;
    /* Document is indexed */
  });
});
```

--------------------------------

### Synchronize a subset of documents based on a query

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Pass a query object to synchronize to index only matching documents. Here, only books by 'Arthur C. Clarke' are synchronized.

```javascript
var stream = Book.synchronize({ author: 'Arthur C. Clarke' })
```

--------------------------------

### Model.search(query, options)

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Performs a search against Elasticsearch using the provided query object. Supports the full Elasticsearch Query DSL and query options like sort and aggregations.

```APIDOC
## Model.search(query, options)

### Description
Performs a search against Elasticsearch using the provided query object. Supports the full Elasticsearch Query DSL and query options like sort and aggregations.

### Method
search

### Endpoint
Model.search(query, options)

### Parameters
#### Query Object
- **query** (object) - Required - The Elasticsearch query DSL object to search with.

#### Options Object
- **sort** (string) - Optional - Sort specification, e.g., "age:asc".
- **aggs** (object) - Optional - Aggregations specification.
- **hydrate** (boolean) - Optional - If true, returns hydrated Mongoose documents.
- **hydrateOptions** (object) - Optional - Options for the Mongoose query used to hydrate results.
- **hydrateWithESResults** (boolean|object) - Optional - If true, enhances hydrated documents with `_esResult` property. Can be an object with `source: false` to skip `_esResult._source`.

### Request Example
```javascript
const people = await Person.search({
  range: {
    age:{
      from:21,
      to: 30
    }
  }
});
```

### Response
Returns the Elasticsearch search response. If `hydrate: true`, the response body contains a `hits.hydrated` array with Mongoose documents.

### Response Example
```javascript
const results = await User.search(
  {
    query_string: {
      query: 'john'
    }
  },
  { hydrate: true }
);

console.log(results.body.hits.hits) // will be empty: []
console.log(results.body.hits.hydrated)
```
```

--------------------------------

### Model.esSearch(rawQuery, options)

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Performs a raw Elasticsearch search with a full query object, useful for paging results. The query object wraps the query object used in `.search()` and accepts the same options.

```APIDOC
## Model.esSearch(rawQuery, options)

### Description
Performs a raw Elasticsearch search with a full query object, useful for paging results. The query object wraps the query object used in `.search()` and accepts the same options.

### Method
esSearch

### Endpoint
Model.esSearch(rawQuery, options)

### Parameters
#### Raw Query Object
- **from** (number) - Optional - Starting offset for results.
- **size** (number) - Optional - Number of results to return.
- **query** (object) - Required - The Elasticsearch query DSL object.

#### Options Object
Same options as `.search()` method.

### Request Example
```javascript
const people = await Person.esSearch({
  from: 60,
  size: 20,
  query: {
    range: {
      age:{
        from:21,
        to: 30
      }
    }
  }
});
```

### Response
Returns the Elasticsearch search response.

### Response Example
```javascript
// only the 61st to 80th ranked people who fit the age group are here!
const people = await Person.esSearch({
  from: 60,
  size: 20,
  query: {
    range: {
      age:{
        from:21,
        to: 30
      }
    }
  }
});
```
```

--------------------------------

### Plugin options for alwaysHydrate and hydrateOptions

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Set default hydration behavior by providing alwaysHydrate and hydrateOptions as plugin options when registering the mongoosastic plugin.

```javascript
var User = new Schema({
    name: { type: String, es_indexed: true },
    email: String,
    city: String
})

User.plugin(mongoosastic, {
  alwaysHydrate: true,
  hydrateOptions: {
    lean: true
  }
})
```

--------------------------------

### Index Mongoose references with es_schema and populate

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Defines Comment and User schemas where comments is a reference to Comment documents. The es_schema field provides the referenced schema for mapping, and es_select limits indexed fields to 'title body'. The populate option in the plugin config specifies which fields to populate during indexing.

```javascript
var Comment = new Schema({
    title: String,
    body: String,
    author: String
});


var User = new Schema({
    name: { type: String, es_indexed: true },
    email: String,
    city: String,
    comments: { 
      type: Schema.Types.ObjectId,
      ref: 'Comment',
      es_schema: Comment,
      es_indexed:true,
      es_select: 'title body'
    }
})

User.plugin(mongoosastic, {
  populate: [
    { path: 'comments', select: 'title body' }
  ]
})
```

--------------------------------

### Remove document and listen for es-removed event

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Removing a document via .remove() triggers unindexing. Listen for the 'es-removed' event to know when unindexing is complete.

```javascript
doc.remove(function(err) {
  if (err) throw err;
  /* Document unindexing in the background */
  doc.on('es-removed', function(err, res) {
    if (err) throw err;
    /* Docuemnt is unindexed */
  });
});
```

--------------------------------

### Hydration with hydrateOptions

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Pass hydrateOptions to specify how to query for the Mongoose object, e.g., selecting only name and age fields.

```javascript
const results = await User.search(
  {
    query_string: {
      query: 'john'
    }
  },
  {
    hydrate: true,
    hydrateOptions: { select: 'name age' }
  },
);
```

--------------------------------

### Raw query with esSearch

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Provide a full Elasticsearch query object to Model.esSearch, including from, size, and query. Useful for paging results.

```javascript
var rawQuery = {
    from: 60,
    size: 20,
    query: /* query object as in .search() */
};

await Model.esSearch(rawQuery, options);
```

--------------------------------

### Mongoosastic plugin syntax

Source: https://mongoosastic.github.io/mongoosastic/

The basic syntax for applying the Mongoosastic plugin to a Mongoose schema.

```javascript
Schema.plugin(mongoosastic, options)
```

--------------------------------

### Index nested models with mongoosastic

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Define schemas with es_indexed fields and apply the mongoosastic plugin to index nested models.

```javascript
var Comment = new Schema({
    title: String,
    body: String,
    author: String
})


var User = new Schema({
    name: { type: String, es_indexed: true },
    email: String,
    city: String,
    comments: { type: [Comment], es_indexed: true }
})

User.plugin(mongoosastic)
```

--------------------------------

### Search with aggregation

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Use the aggs option in Person.search to perform a terms aggregation on the name field.

```javascript
const results = await Person.search({/* ... */}, {
  aggs: {
    'names': {
      'terms': {
        'field': 'name'
      }
    }
  }
});
```

--------------------------------

### Unindex on demand using unIndex()

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Remove a document from the Elasticsearch cluster by calling the `unIndex()` method on a document instance.

```javascript
await doc.unIndex();
```

--------------------------------

### esTruncate() - Truncating an index

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Static method to delete all documents from the associated index. Useful for cleaning up in integration tests.

```APIDOC
## esTruncate() - Truncating an index

### Description
Static method to delete all documents from the associated index. Useful for cleaning up in integration tests.

### Method
esTruncate()

### Example
```javascript
await GarbageModel.esTruncate();
```
```

--------------------------------

### Truncate index using esTruncate()

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

The static method `esTruncate()` deletes all documents from the associated index. It can be combined with `synchronize()` for integration tests that need a clean index.

```javascript
await GarbageModel.esTruncate();
```

--------------------------------

### Specify synchronization options

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Pass an options object as the second argument to synchronize. The saveOnSynchronize option triggers Mongoose save (and pre-save) methods during synchronization, defaulting to the global saveOnSynchronize option.

```javascript
var stream = Book.synchronize({}, { saveOnSynchronize: true })
```

--------------------------------

### Search for documents containing a geo point

Source: https://mongoosastic.github.io/mongoosastic/mapping.html

Shows how to use GeoModel.search with a geo_shape filter to find documents where the shape contains a specific point. The query uses match_all and a geo_shape filter with a point shape.

```javascript
var geoQuery = {
  "match_all": {}
}

var geoFilter = {
  geo_shape: {
    geo_shape: {
      shape: {
        type: "point",
        coordinates: [3,1]
      }
    }
  }
}

const results = await GeoModel.search(geoQuery, { filter: geoFilter })
```

--------------------------------

### Hydration with hydrateWithESResults

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Keep original Elasticsearch result data by setting hydrateWithESResults: true. Documents are enhanced with a _esResult property.

```javascript
const results = await User.search(
  {
    query_string: {
      query: 'john'
    }
  },
  {
    hydrate: true,
    hydrateWithESResults: true,
    hydrateOptions: { select: 'name age' }
  }
);

results.body.hits.hydrated.forEach(function(result) {
  console.log(
    'score',
    result._id,
    result._esResult._score
  );
});
```

--------------------------------

### unIndex() - Unindexing on demand

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Remove a document from the Elasticsearch cluster on demand.

```APIDOC
## unIndex() - Unindexing on demand

### Description
Remove a document from the Elasticsearch cluster on demand.

### Method
unIndex()

### Example
```javascript
await doc.unIndex();
```
```

--------------------------------

### Search with range query

Source: https://mongoosastic.github.io/mongoosastic/queries.html

Use Person.search with a range query to find people between ages 21 and 30. The query object follows Elasticsearch's Query DSL.

```javascript
const people = await Person.search({
  range: {
    age:{
      from:21,
      to: 30
    }
  }
});
```

--------------------------------

### Filtered Indexing

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Specify a filter function to conditionally skip indexing for certain documents. The filter function must return true for conditions that will ignore indexing.

```APIDOC
## Filtered Indexing

### Description
Specify a filter function to conditionally skip indexing for certain documents. The filter function must return true for conditions that will ignore indexing.

### Usage
```javascript
var MovieSchema = new Schema({
  title: { type: String },
  genre: { type: String, enum: ['horror', 'action', 'adventure', 'other'] }
});

MovieSchema.plugin(mongoosastic, {
  filter: function(doc) {
    return doc.genre === 'action';
  }
});
```

### Behavior
Instances of Movie model having 'action' as their genre will not be indexed to Elasticsearch.
```

--------------------------------

### Define Mongoose schemas with nested type for comments

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Defines Comment and User schemas where the comments field is an array of Comment subdocuments. The es_type: 'nested' option changes the Elasticsearch type from the default 'object' to 'nested' to preserve array object relationships. es_include_in_parent: true includes the nested data in the parent document.

```javascript
var Comment = new Schema({
    title: String,
    body: String,
    author: String
})


var User = new Schema({
    name: { type: String, es_indexed: true },
    email: String,
    city: String,
    comments: {
      type:[Comment],
      es_indexed: true,
      es_type: 'nested',
      es_include_in_parent: true
    }
})

User.plugin(mongoosastic)
```

--------------------------------

### Model.remove does not unindex

Source: https://mongoosastic.github.io/mongoosastic/indexing.html

Using Model.remove does not involve mongoose documents and therefore will not unindex the document from Elasticsearch.

```javascript
MyModel.remove({ _id: doc.id }, function(err) {
  /* doc remains in Elasticsearch cluster */
});
```
Tokens:
Raw