n-es-client

A very thin wrapper around signed fetch and http-errors to search and retrieve content from our Elasticsearch clusters in a simple, DRY manner.

const client = require('@financial-times/n-es-client');

client.get('cce58e8e-158c-11e7-80f4-13e067d5072c').then((data) => { … });

Installation

# install from NPM
$ npm i -S @financial-times/n-es-client

# add Elasticsearch read AWS access key
export ES_AWS_ACCESS_KEY=123

# add Elasticsearch read AWS secret access key
export ES_AWS_SECRET_ACCESS_KEY=456

Usage

All methods return a promise. If a request errors then it will be rejected with an appropriate HTTP error. Each method accepts an options object that will be preserved verbatim and sent with the request, either stringified as part of the URL or as the POST body.

All methods have an optional timeout argument that defaults to 3 seconds.

Some methods allow a custom dataHandler argument that will receive and may manipulate the raw response from Elasticsearch instead of the default handler.

It is highly recommended to always use source filtering to fetch only the fields you require.

.get(uuid[, options][, timeout])

Get a content item by UUID. Returns the content source.

Example

client.get('cce58e8e-158c-11e7-80f4-13e067d5072c', { _source: ['id', 'title'] })

.mget(options[, timeout][, dataHandler])

Get multiple content items by UUID. By default returns an array of content sources for the items that were found but allows an optional custom data handler function.

Example

client.mget({
	ids: ['cce58e8e-158c-11e7-80f4-13e067d5072c', '0615fc8c-1558-11e7-80f4-13e067d5072c']
})

client.mget({
	docs: [
		{ _id: 'cce58e8e-158c-11e7-80f4-13e067d5072c', _source: ['title'] },
		{ _id: '0615fc8c-1558-11e7-80f4-13e067d5072c', _source: ['title'] }
	]
})

.search(options[, timeout][, dataHandler])

Get content items by search query (the full query DSL is available). The default sort order is by publishedDate descending and with a query size of 10. By default returns an array of content sources for the items that matched but allows an optional custom data handler function.

Example

client.search({
	_source: ['id', 'title'],
	query: {
		term: { 'annotations.id': 'dbb0bdae-1f0c-11e4-b0cb-b2227cce2b54' }
	},
	size: 100
});

.count(query[, timeout])

Get the number of items by search query (the full query DSL is available). Returns a number.

Example

client.count({
	query: {
		term: { 'annotations.id': 'dbb0bdae-1f0c-11e4-b0cb-b2227cce2b54' }
	}
});

.msearch(queries[, timeout][, dataHandler])

Perform multiple search queries with one request. By default returns an array of query responses including total matches and content sources for the items that were found but allows an optional custom data handler function. Returns an array of result sets in the format [ { total: number, hits: [] } ].

Example

client.msearch([
	{ query: { term: { 'annotations.id': 'cce58e8e-158c-11e7-80f4-13e067d5072c' } } },
	{ query: { term: { 'annotations.id': '0615fc8c-1558-11e7-80f4-13e067d5072c' } } }
])

.concept(uuid[, timeout])

Get a single concept by UUID. Returns an object or undefined if no matches were found.