---

name: Elasticsearch description: Use when searching, indexing, bulk-loading, or rebuilding indices on RI's Elasticsearch cluster (locked at 5.2) via ServiceLib.Elasticsearch.

Elasticsearch (5.2, fixed)

The cluster runs Elasticsearch 5.2 and will not change. Use ES 5.2 API shapes: _type still exists in bulk metadata, hits.total is a plain int, and modern client libraries won't work. We do not use NEST — ServiceLib.Elasticsearch is a plain HttpClient wrapper over the REST API.

Working code in this folder: Elasticsearch.cs (the ServiceLib wrapper) and ElasticsearchService.cs (JordanPrice's use of it, including the full alias rebuild). Method-level detail: reference-wrapper.md.

Conventions

• Search results are parsed as dynamic (Newtonsoft) and navigated by property name: result.hits.hits[0]._source, null-safe with ?. and ?.ToString() ?? "". No typed models.
• Complex queries are raw string literals ($$"""...""") with interpolated values.
• Wrapper methods return the string "Error" on failure rather than throwing — callers must check for it.
• Indices are created without explicit mappings — let ES auto-detect field types (matches production).
• Scroll downloads (DownloadIndex): 5000-doc batches, 1m timeout, and the scroll context is always cleared in a finally block — leaked scroll contexts hold resources on this old cluster.

Index rebuild: timestamped index + alias (JordanPrice-proven)

Zero-downtime full rebuild, proven in JordanPrice:

1. Create timestamped index, e.g. price_discount_20250116_123456
2. Bulk-load all documents into it
3. Atomically switch alias price_discount in one _aliases call (remove price_discount_* + add new index)
4. On failure, delete the new index; rollback is just switching the alias back

Architectural direction: the legacy Java codebase writes whole timestamped indices and flips aliases as above. RI's stated direction for new work is in-place overwrites and deletes instead of full rebuilds — prefer that for new services, but the alias pattern remains the proven fallback for full reloads.

De-aliasing for document operations

ES 5.2 misroutes single-document operations addressed to an alias. The wrapper's DeAliasURL/ConcreteIndex resolve an alias to its concrete index first and build URLs as /{concrete_index}/{alias}/{id}. Any direct document PUT/DELETE against a name that might be an alias must go through this (see reference-wrapper.md).

Bulk format nulls (BulkToJson)

BulkToJson builds the NDJSON body with an asymmetry that matters: action metadata lines are serialized keeping nulls, document lines ignoring nulls. Keep that split when touching bulk code — dropping nulls from metadata or including them in documents both cause subtle diffs against the legacy Java output.