Table of Contents

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

TDocument

The type of the document to manage in Elasticsearch.

Inheritance
ElasticRepositoryBase<TDocument>
Implements
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

client ElasticsearchClient

The Elastic.Clients.Elasticsearch.ElasticsearchClient instance used to communicate with Elasticsearch.

indexName string

The name of the Elasticsearch index that this repository will operate on.

Exceptions

ArgumentNullException

Thrown if client or indexName is null or 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

documentId string

The unique identifier for the document.

document TDocument

The document to be added or updated.

cancellationToken CancellationToken

The 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

documents IEnumerable<TDocument>

The collection of documents to add or update.

idSelector Func<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.

cancellationToken CancellationToken

The 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

documentId string

The unique identifier of the document.

cancellationToken CancellationToken

The cancellation token to cancel the operation if required.

Returns

Task<TDocument>

A Task<TResult> containing the document if found, or null if not found.

InitializeAsync(CancellationToken)

Initializes the Elasticsearch index asynchronously.

public virtual Task InitializeAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation token to cancel the operation if required.

Returns

Task

A Task representing the asynchronous operation.

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

createIndexRequest CreateIndexRequest

The request configuration for creating the index.

cancellationToken CancellationToken

The cancellation token to cancel the operation if required.

Returns

Task

A Task representing the asynchronous operation.

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

cancellationToken CancellationToken

The cancellation token to cancel the operation if required.

Returns

Task

A Task representing the asynchronous operation.

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

numberOfShards int

Number of primary shards for the index.

numberOfReplicas int

Number of replica shards for the index.

cancellationToken CancellationToken

The cancellation token to cancel the operation if required.

Returns

Task

A Task representing the asynchronous operation.

Remarks

Uses the three-tier mapping strategy from Excalibur.Data.ElasticSearch.ElasticIndexMappingBuilder:

  1. Explicit: If TDocument implements IElasticIndexConfiguration<TSelf>, its ConfigureIndex method provides full control over field mappings.
  2. 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

documentId string

The unique identifier of the document to remove.

cancellationToken CancellationToken

The 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

searchRequest SearchRequestDescriptor<TDocument>

The search request containing query details.

cancellationToken CancellationToken

The 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

documentId string

The unique identifier of the document to update.

updatedFields Dictionary<string, object>

A dictionary containing the fields to update and their new values.

cancellationToken CancellationToken

A CancellationToken to observe while waiting for the operation to complete.

Returns

Task<bool>

A Task<TResult> that resolves to true if the update operation succeeded, otherwise an exception is thrown.

Exceptions

ArgumentException

Thrown if documentId is null , empty, or whitespace.

ArgumentNullException

Thrown if updatedFields is null .

ElasticsearchUpdateException

Thrown if the update operation fails. Includes details of the Elasticsearch API response.