Bulk Operations

Bulk operations allow applications to process multiple cache entries in a single network call, significantly reducing network overhead and improving throughput in high-load environments.

Instead of executing individual cache operations for each item, NCache enables you to add, update, retrieve, and remove multiple items in batches. This approach improves performance, minimizes network round-trips, and is recommended when working with large datasets.

Prerequisites

Add Bulk Items To Cache

AddBulk adds an array of CacheItem to the cache with the corresponding cache keys. This method returns a dictionary of all the keys that failed to add, along with the failure reason.

Note

For any keys that fail to add, the failure reason will be returned as an IDictionary.

The following code adds a bulk of product items to the cache. If there are any keys that failed to add, the keys can be handled according to your business needs.

// Precondition: Cache is already connected
// Create an array of all Customer Keys
String[] keys = new String[]
{
    "Customer:ALFKI", "Customer:ANATR", "Customer:ANTON", "Customer:AROUT", "Customer:BERGS"
};

// Get items from cache
IDictionary<string, CacheItem> itemsFetched = cache.GetCacheItemBulk(keys);

// Fetch items from DB which do not exist in Cache
if (itemsFetched.Count < keys.Length)
{
    // Create dictionary of items to be added to cache
    IDictionary<string, CacheItem> missingItems = new Dictionary<string, CacheItem>();

    foreach (string key in keys)
    {
        if (!itemsFetched.ContainsKey(key))
        {
            Customer customer = FetchCustomerFromDB(key);
            CacheItem cacheItem = new CacheItem(customer);
            missingItems.Add(key, cacheItem);
        }
    }

    // Add bulk items to Cache
    IDictionary<string, Exception> keysFailedToAdd = cache.AddBulk(missingItems);

    if (keysFailedToAdd.Count > 0)
    {
        foreach(KeyValuePair<string,Exception> keyFailedToAdd in keysFailedToAdd)
            Console.WriteLine($"Could not add Item {keyFailedToAdd.Key} in cache due to error : {keyFailedToAdd.Value}");
    }
}

Update Bulk Items in Cache

The InsertBulk API is essential for high-load scenarios, as it significantly reduces network round-trips by combining multiple update operations into a single network packet.

InsertBulk updates an array of Cache​Item to the cache against the corresponding key. The method returns a dictionary of all the keys that failed to update, along with the failure reason.

Important

If any keys fail to update, their reasons of failure will be returned as an IDictionary.

The following code example fetches an array of Customers from the database. The Customers are then inserted to the cache as a dictionary of keys and CacheItem using InsertBulk.

// Precondition: Cache is already connected
// Create an array of all Customer Keys
String[] keys = new String[]
{
    "Customer:ALFKI", "Customer:ANATR", "Customer:ANTON", "Customer:AROUT", "Customer:BERGS"
};

// Get items from cache
IDictionary<string, Customer> itemsFetched = cache.GetBulk<Customer>(keys);

// Create a dictionary to store updated items
IDictionary<string, CacheItem> itemsUpdated = new Dictionary<string, CacheItem>();

// Update postal codes of dictionary items
foreach (KeyValuePair<string, Customer> item in itemsFetched)
{
    // Update Postal Code
    item.Value.PostalCode = "05023";

    // Create CacheItem of updated Customer object
    CacheItem updatedCacheItem = new CacheItem(item.Value);

    // Add CacheItem to dictionary
    itemsUpdated.Add(item.Key,updatedCacheItem);
}

if (UpdateDB(itemsUpdated))
{
    // Insert updated bulk items to Cache
    IDictionary<string, Exception> keysFailedToInsert = cache.InsertBulk(itemsUpdated);

    if (keysFailedToInsert.Count > 0)
    {
        foreach (KeyValuePair<string, Exception> keyFailedToInsert in keysFailedToInsert)
            Console.WriteLine($"Could not update Item {keyFailedToInsert.Key} in cache due to error : {keyFailedToInsert.Value}");
    }
}

Retrieve Bulk Items from Cache

NCache allows synchronous bulk retrieval of items in a single call to reduce network costs. Various overloads of the GetBulk method retrieve objects from the cache data for the cache keys specified. GetBulk significantly reduces network round-trips by bundling multiple requests into a single network packet, which is critical for high-load environments. Note that the value is retrieved as a template so it needs to be type cast accordingly if it is a custom class object.

Important

If the keys exist in the cache, a dictionary of cache items and their keys is returned.

The following example retrieves any existing CacheItem that contains an object of the Customer class. The result is returned in an IDictionary of keys and values, which can be enumerated to get the actual values of the keys. Since GetBulk returns a template (that needs to be cast), the object is cast to the Customer type in this example. If the specified key does not exist in the cache, a null value is returned.

// Precondition: Cache is already connected
// Create an array of all keys to fetch
String[] keys = new String[]
{
    "Customer:ALFKI", "Customer:ANATR", "Customer:ANTON", "Customer:AROUT", "Customer:BERGS"
};

// Get items from cache
IDictionary<string, Customer> retrievedItems = cache.GetBulk<Customer>(keys);

// Retrieve customers and their addresses from dictionary
foreach (KeyValuePair<string, Customer> retrievedItem in retrievedItems)
{
    Console.WriteLine($"Customer: {retrievedItem.Value.ContactName}, Address : {retrievedItem.Value.Address}");
}

Retrieve Bulk of CacheItems from Cache

You can also retrieve a bulk of CacheItem using the GetCacheItemBulk method. Here is an example:

// Precondition: Cache is already connected
// Create an array of all keys to fetch
String[] keys = new String[]
{
    "Customer:ALFKI", "Customer:ANATR", "Customer:ANTON", "Customer:AROUT", "Customer:BERGS"
};

// Get items from cache
IDictionary<string, Customer> retrievedItems = cache.GetBulk<Customer>(keys);

// Retrieve customers and their addresses from dictionary
foreach (KeyValuePair<string, Customer> retrievedItem in retrievedItems)
{
    Console.WriteLine($"Customer: {retrievedItem.Value.ContactName}, Address : { retrievedItem.Value.Address}");
}

Remove Bulk Items From Cache

NCache provides a RemoveBulk method to remove a bulk of cache items against the specified array of cache keys. It returns a dictionary of the keys and objects removed from the cache.

Important

If the specified items exist in the cache, a dictionary of the keys and objects removed is returned.

Tip

One quick way to verify whether an item has been removed is to use either of the following properties of the cache class:

  • Count returns the number of items present in the cache.
  • Contains verifies if a specified key exists in the cache.

The following example removes a bulk of existing cache items and casts the returned object into Customer objects.

// Precondition: Cache is already connected
// Create an array of all keys to remove
String[] keysToRemove = new String[]
{
    "Customer:ALFKI", "Customer:ANATR", "Customer:ANTON", "Customer:AROUT", "Customer:BERGS"
};

// Create dictionary to store removed items
IDictionary<string, Customer> removedItems;

// Remove items from DB
if (DeleteFromDB(keysToRemove))
{
    // Remove bulk items from cache
    cache.RemoveBulk(keysToRemove, out removedItems);
    // Check for failed removals
    if (removedItems.Count != keysToRemove.Length)
    {
        Console.WriteLine($"Failed to remove {keysToRemove.Length - removedItems.Count} items from cache.");
    }
}

See Also

.NET: Alachisoft.NCache.Client namespace.
Java: com.alachisoft.ncache.client namespace.
Python: ncache.client class.
Node.js: Cache class.