Dust Elasticsearch

Core Rules

• Keep one mappings file per index version and one settings file per region.
• Use version bumps for incompatible mapping or analyzer changes rather than mutating a live index in place.
• Simple analytics indices usually do not need custom analyzers or Elasticsearch plugins.
• If you need prefix search, multi-field mappings, ICU analyzers, or email-aware tokenization, read references/create-index.md before editing mappings.
• Prefer async indexing through front/temporal/es_indexation/* when the write path does not need to block on Elasticsearch freshness.
• Check relocation requirements for any workspace-scoped index that is expected to remain available after workspace region moves.

Current Architecture

This skill focuses on Elasticsearch indices managed in front, especially analytics-style indices, but the patterns also match the broader Dust Elasticsearch setup.

Current examples to copy from:

• front.agent_message_analytics
  • version 2
  • write alias front.agent_message_analytics
  • basic mappings, no custom analyzers
• core.data_sources_nodes
  • version 4
  • write alias core.data_sources_nodes
  • advanced analyzers, edge n-grams, multi-field mappings, and normalizers

The general pattern is:

• versioned physical indices such as front.<index_name>_<version>
• one stable alias such as front.<index_name> for app reads and writes
• mappings and region-specific settings stored alongside the feature code

Primary Files

• front/lib/api/elasticsearch.ts
• front/scripts/create_elasticsearch_index.ts
• front/lib/*/indices/*.mappings.json
• front/lib/*/indices/*.settings.{region}.json
• front/temporal/es_indexation/*
• front/temporal/relocation/activities/destination_region/front/es_indexation.ts
• front/temporal/relocation/workflows.ts

Existing References In Code

• front/lib/user_search/indices/
• front/lib/user_search/index.ts
• front/lib/analytics/indices/
• core/src/search_stores/indices/data_sources_nodes_4.*

Validation

• The document type and mappings agree on field names and field kinds.
• The index has a stable alias constant and an INDEX_DIRECTORIES entry.
• The version in the script invocation matches the versioned mappings/settings filenames.
• Writes target the alias constant rather than a concrete versioned index name.
• Query helpers filter by workspace_id when the index is workspace-scoped.
• Aggregation-only queries use size: 0.
• Temporal integration exists when indexing is asynchronous or needs retries.
• Relocation support exists when the index must be rebuilt in a destination region.

Supporting References

• Environment setup and plugin checks: references/overview.md
• Full index creation and migration details, including analyzers and curl verification: references/create-index.md
• Indexing helper and Temporal examples: references/indexing.md
• Query and aggregation patterns: references/querying.md
• Workspace relocation support: references/relocation.md