Class ElasticRepositoryBase<TDocument>
- Namespace
- Excalibur.Data.ElasticSearch
- Assembly
- Excalibur.Data.ElasticSearch.dll
Provides a base implementation for interacting with Elasticsearch for a specific document type.
public abstract class ElasticRepositoryBase<TDocument> : IInitializeElasticIndex, IElasticRepositoryBase<TDocument>, IElasticRepositoryBaseQuery<TDocument> where TDocument : class
Type Parameters
TDocumentThe type of the document to manage in Elasticsearch.
- Inheritance
-
ElasticRepositoryBase<TDocument>
- Implements
-
IElasticRepositoryBase<TDocument>IElasticRepositoryBaseQuery<TDocument>
- Derived
- Inherited Members
Remarks
This class includes operations for adding, updating, retrieving, deleting, and searching documents, as well as initializing indices in Elasticsearch.
Constructors
ElasticRepositoryBase(ElasticsearchClient, string)
Initializes a new instance of the ElasticRepositoryBase<TDocument> class with the specified Elasticsearch client and index name.
protected ElasticRepositoryBase(ElasticsearchClient client, string indexName)
Parameters
clientElasticsearchClientThe Elastic.Clients.Elasticsearch.ElasticsearchClient instance used to communicate with Elasticsearch.
indexNamestringThe name of the Elasticsearch index that this repository will operate on.
Exceptions
- ArgumentNullException
Thrown if
clientorindexNameisnullor empty.
Methods
AddOrUpdateAsync(string, TDocument, CancellationToken)
Adds or updates a document in the Elasticsearch index.
public virtual Task<bool> AddOrUpdateAsync(string documentId, TDocument document, CancellationToken cancellationToken)
Parameters
documentIdstringThe unique identifier for the document.
documentTDocumentThe document to be added or updated.
cancellationTokenCancellationTokenThe cancellation token to cancel the operation if required.
Returns
- Task<bool>
A Task<TResult> indicating whether the operation succeeded.
BulkAddOrUpdateAsync(IEnumerable<TDocument>, Func<TDocument, string>, CancellationToken)
Performs a bulk operation to add or update multiple documents in the Elasticsearch index. Documents are uniquely identified by
an ID provided by the idSelector function.
public virtual Task<bool> BulkAddOrUpdateAsync(IEnumerable<TDocument> documents, Func<TDocument, string> idSelector, CancellationToken cancellationToken)
Parameters
documentsIEnumerable<TDocument>The collection of documents to add or update.
idSelectorFunc<TDocument, string>A function used to select the unique identifier (Elasticsearch document _id) for each document. This identifier ensures documents are correctly created or updated without duplication.
cancellationTokenCancellationTokenThe cancellation token to cancel the operation if required.
Returns
- Task<bool>
A Task<TResult> indicating whether the bulk operation succeeded.
GetByIdAsync(string, CancellationToken)
Retrieves a document from Elasticsearch by its ID.
public virtual Task<TDocument?> GetByIdAsync(string documentId, CancellationToken cancellationToken)
Parameters
documentIdstringThe unique identifier of the document.
cancellationTokenCancellationTokenThe cancellation token to cancel the operation if required.
Returns
- Task<TDocument>
A Task<TResult> containing the document if found, or
nullif not found.
InitializeAsync(CancellationToken)
Initializes the Elasticsearch index asynchronously.
public virtual Task InitializeAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenThe cancellation token to cancel the operation if required.
Returns
Remarks
Provisions the index by invoking InitializeIndexAsync(CancellationToken). The index initializer set is enumerated once at start-up and this is the member it awaits, so a repository declares how its index is created by overriding that one method and nothing else.
InitializeIndexAsync(CreateIndexRequest, CancellationToken)
Initializes the Elasticsearch index using a specific Elastic.Clients.Elasticsearch.IndexManagement.CreateIndexRequest.
protected Task InitializeIndexAsync(CreateIndexRequest createIndexRequest, CancellationToken cancellationToken)
Parameters
createIndexRequestCreateIndexRequestThe request configuration for creating the index.
cancellationTokenCancellationTokenThe cancellation token to cancel the operation if required.
Returns
Exceptions
- InvalidOperationException
Thrown if the index does not exist and cannot be created.
InitializeIndexAsync(CancellationToken)
Provisions this repository's index. Called by InitializeAsync(CancellationToken).
public virtual Task InitializeIndexAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenThe cancellation token to cancel the operation if required.
Returns
Remarks
Does nothing by default, because an index is not always the repository's to create: a repository
reading a projection index must leave it to the projection store, whose mapping declares the
position field and applies the configured conventions and settings. Override this to provision an
index this repository owns -- InitializeIndexWithMappingsAsync(int, int, CancellationToken) derives the mapping
from TDocument.
InitializeIndexWithMappingsAsync(int, int, CancellationToken)
Initializes the Elasticsearch index with mappings derived from the document type.
protected Task InitializeIndexWithMappingsAsync(int numberOfShards = 1, int numberOfReplicas = 1, CancellationToken cancellationToken = default)
Parameters
numberOfShardsintNumber of primary shards for the index.
numberOfReplicasintNumber of replica shards for the index.
cancellationTokenCancellationTokenThe cancellation token to cancel the operation if required.
Returns
Remarks
Uses the three-tier mapping strategy from Excalibur.Data.ElasticSearch.ElasticIndexMappingBuilder:
-
Explicit: If
TDocumentimplements IElasticIndexConfiguration<TSelf>, itsConfigureIndexmethod provides full control over field mappings. - Inferred: Otherwise, public properties are reflected and mapped to appropriate Elasticsearch types (keyword, long, double, date, boolean).
This method is safe to call multiple times — it is a no-op if the index already exists.
RemoveAsync(string, CancellationToken)
Removes a document from the Elasticsearch index.
public virtual Task<bool> RemoveAsync(string documentId, CancellationToken cancellationToken)
Parameters
documentIdstringThe unique identifier of the document to remove.
cancellationTokenCancellationTokenThe cancellation token to cancel the operation if required.
Returns
- Task<bool>
A Task<TResult> indicating whether the operation succeeded.
SearchAsync(SearchRequestDescriptor<TDocument>, CancellationToken)
Executes a search query against the Elasticsearch index.
public virtual Task<SearchResponse<TDocument>> SearchAsync(SearchRequestDescriptor<TDocument> searchRequest, CancellationToken cancellationToken)
Parameters
searchRequestSearchRequestDescriptor<TDocument>The search request containing query details.
cancellationTokenCancellationTokenThe cancellation token to cancel the operation if required.
Returns
- Task<SearchResponse<TDocument>>
A Task<TResult> containing the search response, including matched documents and metadata.
UpdateAsync(string, Dictionary<string, object>, CancellationToken)
Updates specific fields of a document in the Elasticsearch index.
public virtual Task<bool> UpdateAsync(string documentId, Dictionary<string, object> updatedFields, CancellationToken cancellationToken)
Parameters
documentIdstringThe unique identifier of the document to update.
updatedFieldsDictionary<string, object>A dictionary containing the fields to update and their new values.
cancellationTokenCancellationTokenA CancellationToken to observe while waiting for the operation to complete.
Returns
- Task<bool>
A Task<TResult> that resolves to
trueif the update operation succeeded, otherwise an exception is thrown.
Exceptions
- ArgumentException
Thrown if
documentIdisnull, empty, or whitespace.- ArgumentNullException
Thrown if
updatedFieldsisnull.- ElasticsearchUpdateException
Thrown if the update operation fails. Includes details of the Elasticsearch API response.