elasticsearch-plugin

@deenruv/elasticsearch-plugin

Replaces the default Deenruv product search with Elasticsearch for advanced full-text search, faceted filtering, price range queries, custom mappings, and geo-spatial search.

Requires Elasticsearch v7.0 or higher (below v7.10.2 due to client compatibility).

Installation

pnpm add @deenruv/elasticsearch-plugin @elastic/elasticsearch

Make sure to remove DefaultSearchPlugin from your config if present.

Configuration

import { ElasticsearchPlugin } from '@deenruv/elasticsearch-plugin';

const config = {
  plugins: [
    ElasticsearchPlugin.init({
      host: 'http://localhost',
      port: 9200,
    }),
  ],
};

Options:

Option	Type	Default	Description
host	string	'http://localhost'	Elasticsearch host
port	number	9200	Elasticsearch port
clientOptions	ClientOptions	-	Direct Elasticsearch client options (overrides host/port)
connectionAttempts	number	10	Max connection retry attempts on startup
connectionAttemptInterval	number	5000	Interval (ms) between connection attempts
indexPrefix	string	'deenruv-'	Prefix for Elasticsearch indices
indexSettings	object	{}	Elasticsearch index settings (analyzers, filters, etc.)
indexMappingProperties	object	{}	Custom index mapping properties
customProductMappings	object	{}	Custom fields indexed from Products
customProductVariantMappings	object	{}	Custom fields indexed from ProductVariants
searchConfig	SearchConfig	See below	Internal search query configuration
bufferUpdates	boolean	false	Buffer index updates for manual batch execution
hydrateProductRelations	string[]	[]	Additional Product relations to fetch during reindexing
hydrateProductVariantRelations	string[]	[]	Additional ProductVariant relations to fetch during reindexing
extendSearchInputType	object	{}	Add custom fields to the SearchInput GraphQL type
extendSearchSortType	string[]	[]	Add custom sort parameters

SearchConfig defaults:

Option	Default	Description
facetValueMaxSize	50	Max FacetValues returned per search
collectionMaxSize	50	Max Collections returned per search
totalItemsMaxSize	10000	Max total items tracked
multiMatchType	'best_fields'	Elasticsearch multi-match query type
priceRangeBucketInterval	1000	Price range bucket interval (in cents)
mapQuery	identity	Custom query transformation function
mapSort	identity	Custom sort transformation function
scriptFields	{}	Computed script fields (e.g. geo-distance)

Features

• Drop-in replacement for DefaultSearchPlugin
• Price range filtering and price bucket aggregations
• Custom product/variant field mappings exposed via GraphQL
• Script fields for computed values (e.g. geo-spatial distance)
• Configurable search boosting per field
• Custom index analyzers and mapping properties
• Buffered updates for high-volume environments
• Health check integration
• Automatic index management and reindexing on entity changes
• Supports fuzzy search, wildcard queries via mapQuery
• Custom sort parameters via mapSort

Admin UI

Server-only plugin. No Admin UI extensions.

API Extensions

Both Admin and Shop APIs are extended with price range data and custom mapping fields:

extend type SearchResponse {
  prices: SearchResponsePriceData!
}

type SearchResponsePriceData {
  range: PriceRange!
  rangeWithTax: PriceRange!
  buckets: [PriceRangeBucket!]!
  bucketsWithTax: [PriceRangeBucket!]!
}

type PriceRangeBucket {
  to: Int!
  count: Int!
}

extend input SearchInput {
  priceRange: PriceRangeInput
  priceRangeWithTax: PriceRangeInput
}

input PriceRangeInput {
  min: Int!
  max: Int!
}

When customProductMappings or customProductVariantMappings are defined, additional fields are exposed on SearchResult:

type SearchResult {
  customProductMappings: CustomProductMappings
  customProductVariantMappings: CustomProductVariantMappings
  customMappings: CustomMappings  # Union of both
}