okanjo-app-elastic
v5.2.1
Published
Service for interfacing with Elasticsearch
Downloads
9
Maintainers
Readme
Okanjo Elasticsearch Service
Service for interfacing with Elasticsearch for the Okanjo App ecosystem.
This package wraps interfacing with Elasticsearch, so:
- Common elastic operations are simplified
- Built in error reporting for common operations
Installing
Add to your project like so:
npm install okanjo-app-elastic
Peer dependency: Requires
@elastic/elasticsearch
module. Version >= 6.
Requires the
okanjo-app
module.
Example Usage
An example application can be found in docs/example-app. It demonstrates creating an index, loading documents, and searching.
ElasticService
Elasticsearch management class. Must be instantiated to be used.
Properties
elastic.app
– (read-only) The OkanjoApp instance provided when constructedelastic.config
– (read-only) The configuration provided when constructedelastic.index
– (read-only) The string name of the index this instance is bound toelastic.schema
– (read-only) The index settings object for the index this instance is bound toelastic.types
– (read-only) The enumeration of types of documents stored in the indexelastic.client
– (read-only) The elasticsearch client, usable for non-wrapped operations
Methods
new ElasticSearch(app, clientConfig, indexConfig)
Creates a new elastic service instance.
app
– The OkanjoApp instance to bind toclientConfig
– The elasticsearch client configuration objectindexConfig
– The index configuration object.indexConfig.name
– String name of the indexindexConfig.schema
– Index configuration. Should be an object that contains the mappings and settings of the index. This value is used as the body of the create index command.indexConfig.types
– (Legacy) Object map of key-value pairs, defining the types stored in the index.
elastic.exists([options])
Checks whether the index exists or not.
options.index
– Specifiy which index to check existence ofoptions.*
– Passed to theclient.indices.exists
request.
ReturnsPromise<boolean>
, where the result istrue
if the index exists orfalse
if not.
elastic.ping()
Pings the elasticsearch server to see if it is available.
Returns Promise<boolean>
, where the result is true
if the available or false
if not.
elastic.create([options])
Creates the elasticsearch index as configured by the name and schema.
options.index
– The name of the index to create, defaults to the serviceindex
property.options.schema
– The index mappings and settings object ornull
to not set a body at all (e.g. use existing template), or leave unset to default to the serviceschema
property.options.*
– Additional create index request options ReturnsPromise<boolean>
, where the result istrue
if the index was created.
elastic.delete([options])
Deletes the elasticsearch index as configured.
options.index
– The name of the index to create, defaults to the serviceindex
property.\options.*
– Additional delete index request options ReturnsPromise<boolean>
, where the result istrue
if the index was deleted or does not exist.
elastic.search(body, [options])
Searches the index for documents.
body
– Search request object, e.g.{ query: { match_all: {} } }
options.index
– The name of the index to search, defaults to the serviceindex
property.options.*
– Elastic request options, e.g.{ limit: 5 }
elastic.get(id, [options])
Retrieves a doc from the index.
id
– The id of the document to fetchoptions.index
– The name of the index the doc lives in, defaults to the serviceindex
property.options.*
– Additional get request options
elastic.scroll(scrollId, [options])
Scrolls through an open search cursor. Renews the scroll cursor timeout to 5 minutes.
scrollId
– The active scroll idoptions.scroll
– Time to let the cursor live. Defaults to5m
;options.*
– Additional scroll request options
elastic.clearScroll(scrollId, [options])
Cleans up an open scroll cursor. Use this when done scrolling.
scrollId
– The active scroll idoptions.*
– Additional clearScroll request options
elastic.bulk(body, [options,] callback)
Sends a batch of bulk operations to the index.
body
– The bulk body payload, array of operationsoptions.index
– The name of the index to operate on, defaults to the serviceindex
property.options.timeout
– How long to let the bulk operation run. Defaults to5m
.options.refresh
–true
,false
,wait_for
- Iftrue
then refresh the effected shards to make this operation visible to search, ifwait_for
then wait for a refresh to make this operation visible to search, iffalse
then do nothing with refreshes. Defaults towait_for
.options.*
– Additional bulk request options
elastic.getMappings([options])
Gets the index's current mappings.
options.index
– The name of the index to operate on, defaults to the serviceindex
property.options.*
– Additional getMappings request options
elastic.getSettings([options])
Gets the index's current settings.
options.index
– The name of the index to operate on, defaults to the serviceindex
property.options.*
– Additional getMappings request options
elastic.putTemplate(name, index_patterns, schema, [options])
Creates or updates an index template.
name
– Template nameindex_patterns
– Array of index pattern stringsschema
– Template body, e.g.{ mappings: {}, settings: {} }
options.*
– Additional putTemplate request options
elastic.deleteTemplate(name, callback)
name
– Template name to deleteoptions.*
– Additional deleteTemplate request options
elastic.ensureTemplatedIndex(indexConfig, doCreate, [createSchema])
indexConfig
– Typical index configuration objectindexConfig.template_name
– Name of the templateindexConfig.index_patterns
- Array of the index patterns the template applies toindexConfig.template
– The index mappings and settings templateindexConfig.index.name
– The name of the index to create
doCreate
- When truthy, the index will be created if not already presentcreateSchema
– Optional. Override the template mappings and settings, if desired. Defaults tonull
to inherit the template mappings and settings. Use this for overriding stuff like shard counts, e.g.{ settings: { number_of_shards: 10 } }
Not Implemented?
Is your elastic client function missing? No problem.
Use elastic.client
to talk to elasticsearch directly.
Errors will not be automatically reported, so you'll need to do that yourself.
Events
This class fires no events.
Extending and Contributing
Our goal is quality-driven development. Please ensure that 100% of the code is covered with testing.
Before contributing pull requests, please ensure that changes are covered with unit tests, and that all are passing.
Testing
Before you can run the tests, you'll need a working elasticsearch server. We suggest using docker.
For example:
docker pull docker.elastic.co/elasticsearch/elasticsearch:6.8.22
sudo sysctl -w vm.max_map_count=262144
# docker-machine ssh default "sudo sysctl -w vm.max_map_count=262144"
docker run -d -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:6.8.22
If you use docker via virtualbox (e.g. mac, windows), then you'll want that docker-machine line above instead.
To run unit tests and code coverage:
npm run report
Or with custom elasticseraach server
ES_HOST=elastic:[email protected]:9200 npm run report
Update the ES_HOST
environment var to match your docker host (e.g. 127.0.0.1, user, pass, etc)
This will perform:
- Unit tests
- Code coverage report
- Code linting
Sometimes, that's overkill to quickly test a quick change. To run just the unit tests:
npm test
or if you have mocha installed globally, you may run mocha test
instead.