Indexing

Introduction

Indexing is the process of taking an object and sending it to the service for storage and analysis so that it can later be retrieved or included in search results. If a document of the same type with the same ID already exists it will be overwritten (or updated if you like). The client API supports indexing any .NET object. As objects are serialized upon indexing the only restriction is that indexed objects can be serialized. If for some reason, typically circular references, an object cannot be serialized the API also supports customizing how the object is serialized and indexed in a number of ways. This flexibility in how objects are serialized and indexed can also be used to implement functionality, such as indexing the return value of extension methods.

Indexing objects

Indexing is done using the Index method exposed by the IClient interface. Given that we have an instance of a Client and an object to index, indexing can be done like this:

IClient client = //A client retrieved from config or injected into the method
BlogPost blogPost = //An instance of an arbitrary class

client.Index(blogPost);

Multiple objects can also be indexed in a batch:

BlogPost blogPost = //An instance of an arbitrary class
Article article = //An instance of another arbitrary class

//Indexing supplying objects as params
client.Index(blogPost, article);

var listOfObjects = new List<object>
                    {
                        blogPost,
                        article
                    };
//Indexing supplying IEnumerable
client.Index(listOfObjects);

Once indexed an instance of the IndexResult class is returned with which we can verify that indexing worked and retrieve the document ID:

var result = client.Index(blogPost);
bool succesfull = result.Ok;
string id = result.Id;

Time delay

Once an object has been indexed it is instantly available for retrieval using the Client’s Get method. However, before it will be returned in search results the index needs to be refreshed. This happens automatically every second. However, if it is absolutely crucial that it is available immediately we can modify the command that the Client executes to tell the service to refresh the index right away. This should however be done only if it is really necessary and preferably only while testing or debugging as it can have severe performance implications.

client.Index(blogPost, 
        x => x.Refresh = true);

Identity

Unless specified the service will automatically assign an id to the indexed document. To explicitly specify the ID we can either modify the command or annotate a property on the indexed class with the ID attribute. In both cases the value of the ID must be compatible with the DocumentID type.

//Specifying the id by modifying the command
client.Index(blogPost, 
        x => x.Id = 42);

//Specifying that a property should be used as id
public class BlogPost
{
    [Id]
    public int Id { get; set; }
}

It is also possible to modify the Client class conventions to use a specific property or method as the ID for all instances of a type without modifying the actual class.

client.Conventions.ForInstancesOf<Product>()
    .IdIs(x => x.Key);

Ignoring properties

Individual properties in a class can be excluded from indexing by annotating them with the JsonIgnore attribute. It is also possible to exclude properties without modifying the classes that they are in using the Client class conventions.

public class BlogPost
{
    [JsonIgnore]
    public int SomethingInternal { get; set; }
}

Time to live

Individual documents can be set to be deleted after a specific time period by the use of the time to live functionality. This can be set by either modifying the command or by annotating a property on the indexed class with the TimeToLive attribute.

//Specifying the time to live by modifying the command
client.Index(blogPost, 
        x => x.TimeToLive =  new TimeSpan(0, 0, 10));

//Specifying that a property should be used as time to live
public class BlogPost
{
     [Id]
     public int Id { get; set; }

     [TimeToLive]
     public TimeToLive TimeToLive { get; set; }
}

The granularity of time to live is 60 seconds meaning that the documents will be deleted within 60 seconds of the actual time to live.

Customizing type indexing

It is possible to customize how type is serialized and indexed in a number of ways. Properties can be excluded, HTML tags in string properties can be removedand return values of methods can be included so that they can later be used when searching or filtering.