A Feathers database adapter for Elasticsearch with full Feathers v5 (Dove) support, built-in security controls, and performance optimizations.
- ✅ Feathers v5 (Dove) - Full compatibility with the latest Feathers
- 🔒 Security-First - Built-in protection against DoS attacks and unauthorized access
- ⚡ Performance - Query caching, lean mode, and complexity budgeting
- 🔍 Rich Queries - Full support for Elasticsearch-specific query operators
- 👨👩👧👦 Parent-Child - Support for parent-child relationships
- 📊 Bulk Operations - Efficient bulk create, patch, and remove
npm install feathers-elasticsearch @elastic/elasticsearch --save
Requirements:
- Feathers v5+
- Elasticsearch 8.x or 9.x (5.x, 6.x, 7.x also supported)
- Node.js 20+
import { feathers } '@feathersjs/feathers'; import express from '@feathersjs/express'; import { Client } from '@elastic/elasticsearch'; import service from 'feathers-elasticsearch'; const app = express(feathers()); const esClient = new Client({ node: 'http://localhost:9200' }); // Configure the service app.use('/messages', service({ Model: esClient, elasticsearch: { index: 'messages', type: '_doc' }, paginate: { default: 10, max: 50 } })); // Use the service app.service('messages').create({ text: 'Hello Feathers!' });
That's it! You now have a fully functional Feathers service with CRUD operations.
- Getting Started Guide - Installation, setup, and your first service
- Migration Guide - Upgrading from v3.x to v4.0
- Configuration - All service options and settings
- Querying - Query syntax and Elasticsearch-specific operators
- Parent-Child Relationships - Working with parent-child documents
- Security - Security configuration and best practices
- Performance Features - Optimization techniques
- Quirks & Limitations - Important behaviors and workarounds
- API Reference - Complete API documentation
- Contributing - How to contribute to the project
- Changelog - Version history and changes
- Testing - Running and writing tests
Version 4.0.0 introduces breaking changes with a focus on security and performance.
1. Raw Method Access Disabled by Default
For security, the raw() method now requires explicit whitelisting:
// v3.x - raw() allowed any Elasticsearch API call await service.raw('indices.delete', { index: 'test' }); // ⚠️ Dangerous! // v4.0+ - Must whitelist methods app.use('/messages', service({ Model: esClient, elasticsearch: { index: 'messages', type: '_doc' }, security: { allowedRawMethods: ['search', 'count'] // Only allow safe methods } })); await service.raw('search', { query: {...} }); // ✅ Works await service.raw('indices.delete', {...}); // ❌ Throws MethodNotAllowed
2. New Security Limits
Default limits protect against DoS attacks:
security: { maxQueryDepth: 50, // Max query nesting depth maxBulkOperations: 10000, // Max bulk operation size maxArraySize: 10000, // Max array size in $in/$nin // ... and more }
3. Performance Improvements
- Content-based query caching (50-90% hit rate vs 5-10%)
- Lean mode for bulk operations (60% faster)
- Configurable refresh strategies
See the Migration Guide for complete upgrade instructions.
// Create const message = await service.create({ text: 'Hello World', user: 'Alice' }); // Find with query const results = await service.find({ query: { user: 'Alice', $sort: { createdAt: -1 }, $limit: 10 } }); // Get by ID const message = await service.get(messageId); // Patch (partial update) await service.patch(messageId, { text: 'Updated text' }); // Remove await service.remove(messageId);
// Full-text search const results = await service.find({ query: { content: { $match: 'elasticsearch' } } }); // Wildcard search const users = await service.find({ query: { email: { $wildcard: '*@example.com' } } }); // Complex search with field boosting const articles = await service.find({ query: { $sqs: { $fields: ['title^5', 'content'], $query: '+javascript +tutorial' } } });
See Querying for all query operators and examples.
// Bulk create with lean mode (60% faster) await service.create(largeDataset, { lean: true, // Don't fetch documents back refresh: false // Don't wait for refresh }); // Per-operation refresh control await service.create(data, { refresh: 'wait_for' // Wait for changes to be searchable });
See Performance Features for optimization techniques.
Tested on:
- Elasticsearch 5.0, 5.6, 6.6, 6.7, 6.8, 7.0, 7.1, 8.x, 9.x
- Feathers v5 (Dove)
- Node.js 18+
Note: Support for Elasticsearch 2.4 was dropped in v3.0. Use feathers-elasticsearch v2.x for Elasticsearch 2.4.
This package includes security features to protect against common vulnerabilities:
- Query depth limiting - Prevent stack overflow from deeply nested queries
- Bulk operation limits - Prevent memory exhaustion
- Raw method whitelisting - Control access to Elasticsearch API
- Input sanitization - Protect against prototype pollution
- Configurable limits - Adjust based on your needs
See Security for complete security documentation.
We welcome contributions! Please see Contributing for guidelines.
Quick Start:
# Clone and install git clone https://github.com/feathersjs/feathers-elasticsearch.git cd feathers-elasticsearch npm install # Run tests ES_VERSION=8.11.0 npm test # Run tests with coverage ES_VERSION=8.11.0 npm run coverage
Copyright (c) 2025
Licensed under the MIT license.