Class ElasticSearchProjectionIndexOptions
- Namespace
- Excalibur.Data.ElasticSearch.Projections
- Assembly
- Excalibur.Data.ElasticSearch.dll
Index configuration options for the ElasticSearch projection store.
public sealed class ElasticSearchProjectionIndexOptions
- Inheritance
-
ElasticSearchProjectionIndexOptions
- Inherited Members
Remarks
Controls index naming, shard/replica layout, refresh behavior, and the mapping convention applied when creating projection indices.
Properties
CreateIndexOnInitialize
Gets or sets a value indicating whether the store creates its index on initialization.
public bool CreateIndexOnInitialize { get; set; }
Property Value
Remarks
What it creates, so the alternative is a real choice. The index is created with a DECLARED
mapping — your projection's public properties, plus the reserved position field as a
long — honouring the configured shard count, replica count and refresh interval. If
creation fails the store RAISES rather than carrying on, because a store that continued would have
the first write auto-create the index with a dynamically inferred mapping, discarding all of those
settings while reporting healthy.
Set it to false only when you provision the index yourself. With it off and the index absent, initialization refuses before issuing a document write. Existing index mappings are checked against the declared mapping. The position field is the one a dynamic mapping is most likely to get wrong, because the projection type does not declare it.
EnsureSearchVisibilityOnProjectionCheckpoint
Gets or sets whether a projection page becomes searchable before its checkpoint advances.
public bool EnsureSearchVisibilityOnProjectionCheckpoint { get; set; }
Property Value
Remarks
Defaults to false. The processor refreshes this index once after the page's folds, including folds skipped because another writer already applied them. Individual writes retain their normal refresh policy, avoiding one wait_for refresh interval per document. Use this option for request-driven or background projection pages; use WaitForSearchVisibilityOnWrite for direct writes that must become searchable before the individual write returns.
SET IT PER PROJECTION, NOT ON A SHARED CONFIGURATION. It puts a full index refresh on the write path of whichever projections it covers, and a refresh is the most expensive thing on that path -- so a shared registration applies it to read models nobody reads synchronously and charges them for a guarantee they do not use.
THE COST IS PER PAGE, AND A PAGE IS NOT ALWAYS A BATCH. "Once per page" is cheap against a page of several hundred events and is the same price as per-document when a page holds one. That is not hypothetical: an INLINE projection advances event by event, because each save waits for the cursor to reach the position it just committed -- so on the inline path this option costs one index refresh per event, and the batch size configured on the processor does not change it. Where that path is driven by a bulk writer such as a change-data-capture backfill, the refresh becomes the throughput limit for the whole job rather than a tax on one request.
Enable it where a request writes and then SEARCHES for its own write, which is the case this option exists for. Where a projection is filled by a background writer and queried later, the index's own RefreshInterval already bounds how stale a search can be, and that is the guarantee such a reader needs. Note that a get-by-id read is realtime either way; only search is affected.
IndexMappingConvention
Gets or sets the index mapping convention for customizing how CLR types are mapped to Elasticsearch field types during index creation.
public IIndexMappingConvention? IndexMappingConvention { get; set; }
Property Value
- IIndexMappingConvention
Defaults to null (uses DefaultIndexMappingConvention).
Remarks
When null (default), the framework applies the standard DefaultIndexMappingConvention which maps CLR types to Elasticsearch types via reflection (string → keyword, int → long, DateTime → date, etc.).
Set this to a custom IIndexMappingConvention to override the default
behavior — for example, mapping strings as text fields with keyword sub-fields,
or applying custom analyzers to specific property patterns.
IndexName
Gets or sets the index name override for this projection store.
public string? IndexName { get; set; }
Property Value
Remarks
When set, replaces the projection type name in the index naming convention.
The full index name becomes {IndexPrefix}-{IndexName} when both are set,
or just {IndexName} when IndexPrefix is empty.
When not set, the default {IndexPrefix}-{projectionTypeName} convention applies.
The default uses the projection's SIMPLE type name, so two read models with the same simple name in different namespaces resolve to one index and would overwrite each other wherever their document ids coincide. That composition is refused at start-up, naming both types, so it cannot reach production silently — set this property (or a distinct IndexPrefix) on at least one of them.
IndexPrefix
Gets or sets the index name prefix for projection indices.
public string IndexPrefix { get; set; }
Property Value
- string
Defaults to "projections".
Remarks
The full index name is composed as: {IndexPrefix}-{name} where name
is either IndexName (if set) or the lowercased projection type name.
Set to empty or whitespace to omit the prefix entirely.
NumberOfReplicas
Gets or sets the number of replicas for new indices.
public int NumberOfReplicas { get; set; }
Property Value
- int
Defaults to 0.
NumberOfShards
Gets or sets the number of shards for new indices.
public int NumberOfShards { get; set; }
Property Value
- int
Defaults to 1.
RefreshInterval
Gets or sets the refresh interval for the index.
public string RefreshInterval { get; set; }
Property Value
- string
Defaults to "1s".
Remarks
Set to "-1" to disable refresh, or a time value like "1s" for near real-time search.
WaitForSearchVisibilityOnWrite
Gets or sets whether writes wait until their changes are searchable.
public bool WaitForSearchVisibilityOnWrite { get; set; }
Property Value
Remarks
Defaults to false. GET-by-id is realtime regardless of this setting. When enabled, each write uses refresh=wait_for; automatic refresh must be enabled on the actual index. Prefer bulk writes for high throughput rather than sequential writes that each wait for a refresh.