Table of Contents

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

client ElasticsearchClient

The Elasticsearch client.

options IOptions<ElasticsearchPersistenceOptions>

The persistence options.

logger ILogger<ElasticsearchPersistenceProvider>

The logger instance.

Properties

IsAvailable

Gets a value indicating whether the provider is ready to serve requests.

public bool IsAvailable { get; }

Property Value

bool

true while the provider is ready to serve and has not been disposed; otherwise, false.

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

indexName string

The index name (without prefix).

documentId string

The document identifier.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<bool>

true if the document was deleted; otherwise false.

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

indexName string

The index name (without prefix).

documentId string

The document identifier.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<TDocument>

The document if found; otherwise null.

Type Parameters

TDocument

The document type.

GetMetricsAsync(CancellationToken)

Gets provider-specific health and performance metrics.

public Task<IDictionary<string, object>> GetMetricsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The 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

serviceType Type

The type of the requested service.

Returns

object

The service instance, or null if not supported.

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 serviceType is 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

indexName string

The index name (without prefix).

documentId string

The document identifier.

document TDocument

The document to index.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<bool>

true if the operation succeeded; otherwise false.

Type Parameters

TDocument

The document type.

InitializeAsync(IPersistenceOptions, CancellationToken)

Initializes the provider with the specified options.

public Task InitializeAsync(IPersistenceOptions options, CancellationToken cancellationToken)

Parameters

options IPersistenceOptions

The persistence options.

cancellationToken CancellationToken

The 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

indexName string

The index name (without prefix).

queryString string

The Elasticsearch query string.

maxResults int?

The maximum number of results to return.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IReadOnlyList<TDocument>>

A read-only list of matching documents.

Type Parameters

TDocument

The document type.

TestConnectionAsync(CancellationToken)

Tests the connection to the persistence provider.

public Task<bool> TestConnectionAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation token.

Returns

Task<bool>

true if the connection is successful; otherwise, false.