IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Usage recommendations Migration guide: From NEST v7 to .NET Client v8 »

› ›

CRUD usage examples

edit

CRUD usage examples

edit

This page helps you to understand how to perform various basic Elasticsearch CRUD (create, read, update, delete) operations using the .NET client. It demonstrates how to create a document by indexing an object into Elasticsearch, read a document back, retrieving it by ID or performing a search, update one of the fields in a document and delete a specific document.

These examples assume you have an instance of the ElasticsearchClient accessible via a local variable named client and several using directives in your C# file.

using System;
using Elastic.Clients.Elasticsearch;
using Elastic.Clients.Elasticsearch.QueryDsl;
var client = new ElasticsearchClient();

The default constructor, assumes an unsecured Elasticsearch server is running and exposed on http://localhost:9200. See connecting for examples of connecting to secured servers and Elastic Cloud deployments.

The examples operate on data representing tweets. Tweets are modelled in the client application using a C# class named Tweet containing several properties that map to the document structure being stored in Elasticsearch.

public class Tweet
{
    public int Id { get; set; } 
    public string User { get; set; }
    public DateTime PostDate { get; set; }
    public string Message { get; set; }
}

By default, the .NET client will try to find a property called Id on the class. When such a property is present it will index the document into Elasticsearch using the ID specified by the value of this property.

Indexing a document

edit

Documents can be indexed by creating an instance representing a tweet and indexing it via the client. In these examples, we will work with an index named my-tweet-index.

var tweet = new Tweet 
{
    Id = 1,
    User = "stevejgordon",
    PostDate = new DateTime(2009, 11, 15),
    Message = "Trying out the client, so far so good?"
};

var response = await client.IndexAsync(tweet, "my-tweet-index"); 

if (response.IsValidResponse) 
{
    Console.WriteLine($"Index document with ID {response.Id} succeeded."); 
}

	Create an instance of the `Tweet` class with relevant properties set.
	Prefer the async APIs, which require awaiting the response.
	Check the `IsValid` property on the response to confirm that the request and operation succeeded.
	Access the `IndexResponse` properties, such as the ID, if necessary.

Getting a document

edit

var response = await client.GetAsync<Tweet>(1, idx => idx.Index("my-tweet-index")); 

if (response.IsValidResponse)
{
    var tweet = response.Source; 
}

	The `GetResponse` is mapped 1-to-1 with the Elasticsearch JSON response.
	The original document is deserialized as an instance of the Tweet class, accessible on the response via the `Source` property.

Searching for documents

edit

The client exposes a fluent interface and a powerful query DSL for searching.

var response = await client.SearchAsync<Tweet>(s => s 
    .Index("my-tweet-index") 
    .From(0)
    .Size(10)
    .Query(q => q
        .Term(t => t.User, "stevejgordon") 
    )
);

if (response.IsValidResponse)
{
    var tweet = response.Documents.FirstOrDefault(); 
}

	The generic type argument specifies the `Tweet` class, which is used when deserialising the hits from the response.
	The index can be omitted if a `DefaultIndex` has been configured on ElasticsearchClientSettings`, or a specific index was configured when mapping this type.
	Execute a term query against the `user` field, searching for tweets authored by the user stevejgordon.
	Documents matched by the query are accessible via the `Documents` collection property on the `SearchResponse`.

You may prefer using the object initializer syntax for requests if lambdas aren’t your thing.

var request = new SearchRequest("my-tweet-index") 
{
    From = 0,
    Size = 10,
    Query = new TermQuery("user") { Value = "stevejgordon" }
};

var response = await client.SearchAsync<Tweet>(request); 

if (response.IsValidResponse)
{
    var tweet = response.Documents.FirstOrDefault();
}

	Create an instance of `SearchRequest`, setting properties to control the search operation.
	Pass the request to the `SearchAsync` method on the client.

Updating documents

edit

Documents can be updated in several ways, including by providing a complete replacement for an existing document ID.

tweet.Message = "This is a new message"; 

var response = await client.UpdateAsync<Tweet, Tweet>("my-tweet-index", 1, u => u
    .Doc(tweet)); 

if (response.IsValidResponse)
{
    Console.WriteLine("Update document succeeded.");
}

	Update a property on the existing tweet instance.
	Send the updated tweet object in the update request.

Deleting documents

edit

Documents can be deleted by providing the ID of the document to remove.

var response = await client.DeleteAsync("my-tweet-index", 1);

if (response.IsValidResponse)
{
    Console.WriteLine("Delete document succeeded.");
}

« Usage recommendations Migration guide: From NEST v7 to .NET Client v8 »