Class ElasticsearchPersistenceProvider
- Namespace
- Excalibur.Data.ElasticSearch.Persistence
- Assembly
- Excalibur.Data.ElasticSearch.dll
Elasticsearch implementation of IPersistenceProvider that provides document persistence using Elasticsearch indices. Supports health monitoring through the IPersistenceProviderHealth sub-interface via GetService(Type).
public sealed class ElasticsearchPersistenceProvider : IPersistenceProvider, IAsyncDisposable, IDisposable, IPersistenceProviderHealth
- Inheritance
-
ElasticsearchPersistenceProvider
- Implements
- Inherited Members
Constructors
ElasticsearchPersistenceProvider(ElasticsearchClient, IOptions<ElasticsearchPersistenceOptions>, ILogger<ElasticsearchPersistenceProvider>)
Initializes a new instance of the ElasticsearchPersistenceProvider class.
public ElasticsearchPersistenceProvider(ElasticsearchClient client, IOptions<ElasticsearchPersistenceOptions> options, ILogger<ElasticsearchPersistenceProvider> logger)
Parameters
clientElasticsearchClientThe Elasticsearch client.
optionsIOptions<ElasticsearchPersistenceOptions>The persistence options.
loggerILogger<ElasticsearchPersistenceProvider>The logger instance.
Properties
IsAvailable
Gets a value indicating whether the provider is ready to serve requests.
public bool IsAvailable { get; }
Property Value
Remarks
Readiness may be established either at construction — when the provider is handed an already
connected dependency, such as a client it does not own — or by InitializeAsync for
providers that build their own connection from configuration. Both are supported; which one
applies is a property of the constructor you chose, not of the interface.
Implementations must report false once disposed, and may report false while otherwise ready if the underlying connection has dropped. This is a cheap, non-blocking status flag rather than a probe: reading it must not perform I/O.
Name
Gets the identity of this configured provider instance.
public string Name { get; }
Property Value
- string
The identity of this configured provider instance.
Remarks
This is the instance dimension, not the engine dimension. Two instances of the same engine
configured separately report different names, which is what lets a consumer tell them apart in
health output, logs and metrics. The engine an instance runs on is reported separately, under the
Provider key of GetMetricsAsync(CancellationToken).
The value is non-null and non-empty, is established at construction, and does not change for the lifetime of the instance — it is readable before InitializeAsync(IPersistenceOptions, CancellationToken) and after disposal. When no name is configured it falls back to a stable per-implementation default.
Known gap: a provider instance shared across several configuration entries reports a single identity, because the shared instance is one object.
ProviderType
Gets the family of store this provider talks to, such as "SQL", "Document" or
"KeyValue".
public string ProviderType { get; }
Property Value
- string
The family of store this provider talks to.
Remarks
This is the family, not the engine and not the instance: several engines share a family, and it is
what a consumer branches on when the shape of the store matters more than which product it is. It
is a fixed literal, constant per implementation, and MUST NOT vary with configuration. For the
engine, read the Provider key of
GetMetricsAsync(CancellationToken); for the configured instance, read
Name.
Methods
DeleteAsync(string, string, CancellationToken)
Deletes a document by its identifier from the specified index.
public Task<bool> DeleteAsync(string indexName, string documentId, CancellationToken cancellationToken)
Parameters
indexNamestringThe index name (without prefix).
documentIdstringThe document identifier.
cancellationTokenCancellationTokenThe cancellation token.
Returns
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()
DisposeAsync()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.
public ValueTask DisposeAsync()
Returns
- ValueTask
A task that represents the asynchronous dispose operation.
GetByIdAsync<TDocument>(string, string, CancellationToken)
Gets a document by its identifier from the specified index.
public Task<TDocument?> GetByIdAsync<TDocument>(string indexName, string documentId, CancellationToken cancellationToken) where TDocument : class
Parameters
indexNamestringThe index name (without prefix).
documentIdstringThe document identifier.
cancellationTokenCancellationTokenThe cancellation token.
Returns
Type Parameters
TDocumentThe document type.
GetMetricsAsync(CancellationToken)
Gets provider-specific health and performance metrics.
public Task<IDictionary<string, object>> GetMetricsAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IDictionary<string, object>>
A dictionary of metric names and values.
Remarks
The returned dictionary MUST contain two identifying entries, and they carry different dimensions:
-
"Provider"is the engine identity — a fixed literal, constant per implementation and identical for every instance of it (for example"SqlServer"for every SQL Server instance). It MUST NOT vary with configuration, and in particular MUST NOT be set from Name, which is the instance dimension and would make the engine unreadable. -
"Name"is the instance identity — the value of Name, which distinguishes two separately configured instances of the same engine.
Together they let a consumer aggregating across a mixed deployment group by engine and still
attribute a reading to the instance that produced it. Keys are compared with an ordinal comparer,
so the casing is part of the contract -- "provider" is a different key and does not satisfy
it. Every other key is provider-specific; the convention is PascalCase. The conformance suite
verifies the required entries.
GetService(Type)
Gets an implementation-specific service. Use to access optional capabilities such as IPersistenceProviderHealth, IPersistenceProviderTransaction, IPersistenceProviderConnection, or provider-specific features.
public object? GetService(Type serviceType)
Parameters
serviceTypeTypeThe type of the requested service.
Returns
Remarks
The default implementation answers for any capability this instance itself implements. Leaf providers need not override it. Decorators MUST override it to defer unknown capabilities to the provider they wrap; a decorator that does not forward silently disables the capability beneath it.
Exceptions
- ArgumentNullException
Thrown when
serviceTypeis null.
IndexAsync<TDocument>(string, string, TDocument, CancellationToken)
Indexes (creates or updates) a document in the specified index.
public Task<bool> IndexAsync<TDocument>(string indexName, string documentId, TDocument document, CancellationToken cancellationToken) where TDocument : class
Parameters
indexNamestringThe index name (without prefix).
documentIdstringThe document identifier.
documentTDocumentThe document to index.
cancellationTokenCancellationTokenThe cancellation token.
Returns
Type Parameters
TDocumentThe document type.
InitializeAsync(IPersistenceOptions, CancellationToken)
Initializes the provider with the specified options.
public Task InitializeAsync(IPersistenceOptions options, CancellationToken cancellationToken)
Parameters
optionsIPersistenceOptionsThe persistence options.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task
A task representing the asynchronous operation.
Remarks
Reachability is verified before the provider reports itself available, so IsAvailable reflects a connection this provider actually made rather than merely the fact that it was asked to initialize.
Exceptions
- InvalidOperationException
The cluster could not be reached. The provider is left unavailable rather than reporting a readiness it has not established.
SearchAsync<TDocument>(string, string, int?, CancellationToken)
Searches for documents in the specified index using a query string.
public Task<IReadOnlyList<TDocument>> SearchAsync<TDocument>(string indexName, string queryString, int? maxResults, CancellationToken cancellationToken) where TDocument : class
Parameters
indexNamestringThe index name (without prefix).
queryStringstringThe Elasticsearch query string.
maxResultsint?The maximum number of results to return.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IReadOnlyList<TDocument>>
A read-only list of matching documents.
Type Parameters
TDocumentThe document type.
TestConnectionAsync(CancellationToken)
Tests the connection to the persistence provider.
public Task<bool> TestConnectionAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenThe cancellation token.