What is the benefit of using Tags in NCache?

Tags allow for the logical categorization of cache data. By assigning tags to items, you can create logical datasets within a distributed cache, enabling targeted retrieval and bulk management based on common attributes.

Can I add multiple tags to a single cache item?

Yes, NCache allows you to assign an array or list of multiple tags to a single CacheItem, facilitating complex data grouping and search capabilities.

Does updating a tag override existing tags?

Using the Insert method with a new tag list will override the existing tags. To preserve current tags and add new ones, you must fetch the existing list and append the new tags programmatically before re-inserting.

Add/Update Data with Tags

NCache allows the user to create Tags and then add items to the cache with them. Moreover, you can update and append new Tags to an already existing Tag list.

Prerequisites

To learn about the standard prerequisites required to work with all NCache client-side features, please refer to the given page on Client-Side API Prerequisites.
For API details, refer to: ICache, CacheItem, CacheItemVersion, Tag, Insert, Add,Tags, Count, Contains.

Install either of the following NuGet packages in your .NET client application:
- Enterprise: Install-Package Alachisoft.NCache.SDK -Version 4.9.1.0
- Professional: Install-Package Alachisoft.NCache.Professional.SDK -Version 4.9.1.0
Create a new Console Application.
Make sure that the data being added is serializable.
Add NCache References by locating %NCHOME%\NCache\bin\assembly\4.0 and adding Alachisoft.NCache.Web and Alachisoft.NCache.Runtime as appropriate.
Include the Alachisoft.NCache.Web.Caching and Alachisoft.NCache.Runtime.Caching namespaces in your application.
To learn more about the NCache Legacy API, please download the NCache 4.9 documents available as a .zip file on the Alachisoft Website.

Tag Data

CacheItem is a custom class provided by NCache which can be used to add data to the cache. CacheItem also lets you set additional specifications associated with an object as a property of the Tags class.

Warning

If the key already exists, an exception will be thrown.
Providing a Null Tag array will throw an ArgumentNullException.

The following example adds a CacheItem containing the object customer to the cache using the Add API. It then sets an additional Tag property against it by adding the Tags.

// Precondition: Cache is already connected

// A VIP Customer from the East Coast region has logged into an e-commerce website
// The customer will be added to the cache according to the category Tags

string customerKey = $"Customer:ALFKI";
Customer customer = cache.Get<Customer>(customerKey);

// Get customer from database if not found in cache
if (customer == null)
{
    // Get customer from database
    customer = FetchCustomerFromDB("ALFKI");

    // Create a new CacheItem
    var cacheItem = new CacheItem(customer);

    // Create an array of Tags assigned to customer
    Tag[] tags = new Tag[2];
    tags[0] = new Tag("East Coast Customers");
    tags[1] = new Tag("VIP Customers");

    // Setting the Tag property of the cacheItem
    cacheItem.Tags = tags;

    cache.Add(customerKey, cacheItem);
    // CacheItem added successfully
}

// Precondition: Cache is already connected

// A VIP Customer from the East Coast region has logged into an e-commerce website
// The customer will be added to the cache according to the category Tags

String customerKey = "Customer:ALFKI";
Customer customer = null;
customer = cache.get(customerKey, Customer.class);


// Get customer from database if not found in cache
if (customer == null) 
{
    // Get customer from database
    customer = fetchCustomerFromDB("ALFKI");

    // Create a new CacheItem
    CacheItem cacheItem = new CacheItem(customer);

    // Create an array of Tags assigned to customer
    Tag[] tags = new Tag[2];
    tags[0] = new Tag("East Coast Customers");
    tags[1] = new Tag("VIP Customers");

    // Setting the Tag property of the cacheItem
    cacheItem.setTags(List.of(tags));

    cache.add(customerKey, cacheItem);

}

# Precondition: Cache is already connected

# A VIP Customer from the East Coast region has logged into an e-commerce website
# The customer will be added to the cache according to the category Tags

customer_key = f"Customer:{'ALFKI'}"
customer = cache.get(customer_key,Customer)

# Get customer from database if not found in cache
if customer is None:
    customer = fetch_customer_from_db("ALFKI")

    # Create a new CacheItem
    cache_item = CacheItem(customer)

    # Create a list of Tags assigned to customer
    tags = [
        Tag("East Coast Customers"),
        Tag("VIP Customers")
    ]

    # Setting the Tag property of the cache_item
    cache_item.set_tags(tags)

    cache.add(customer_key, cache_item)
    # CacheItem added successfully

// Precondition: Cache is already connected

// This is an async method

// A VIP Customer from the East Coast region has logged into an e-commerce website
// The customer will be added to the cache according to the category Tags

var customerKey = "Customer:ALFKI";

// Get customer from database
var customer = await this.fetchCustomerFromDB("ALFKI");

// Create a new CacheItem
var cacheItem = new ncache.CacheItem(JSON.stringify(customer));

// Create an array of Tags assigned to customer
var tags = [
    new ncache.Tag("East Coast Customers"),
    new ncache.Tag("VIP Customers")
];

// Setting the Tag property of the cacheItem
cacheItem.setTags(tags);

await this.cache.add(customerKey, cacheItem);
// CacheItem added successfully

// Using NCache Enterprise 4.9.1
// Precondition: Cache is already connected

// The customer will be added to the cache according to the category Tags

string customerKey = $"Customer:ALFKI";
Customer customer = (Customer)cache.Get(customerKey);

// Get customer from database if not found in cache
if (customer == null)
{
    // Get customer from database
    customer = FetchCustomerFromDB("ALFKI");

    // Create a new CacheItem
    var cacheItem = new CacheItem(customer);

    // Create an array of Tags assigned to customer
    Tag[] tags = new Tag[2];
    tags[0] = new Tag("East Coast Customers");
    tags[1] = new Tag("VIP Customers");

    // Setting the Tag property of the cacheItem
    cacheItem.Tags = tags;

    cache.Add(customerKey, cacheItem);
    // CacheItem added successfully
}

Note

To ensure the operation is fail-safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Update Data with Tags

Updating Tags through CacheItem requires the item to be first fetched, its Tags to be modified, and then re-inserted into the cache using the Insert method. The following example first fetches the CacheItem, creates a Tag list with the new Tags, and then reinserts the CacheItem in the cache along with the modified Tag list. Hence, it overrides the value of existing Tags.

// Precondition: Cache is already connected

// A VIP Customer has logged into an e-commerce website from a different region, i.e., West Coast
// This customer will be added to the cache according to the category Tags

// Create an array of new Tags assigned to customer with different region
Tag[] tags = new Tag[2];
tags[0] = new Tag("West Coast Customers");
tags[1] = new Tag("VIP Customers");

// Set the Tag property of the cacheItem with a new updated array
cacheItem.Tags = tags;

// Re-insert the updated cacheItem into cache with different Tags
cache.Insert(customerKey, cacheItem);

// Precondition: Cache is already connected

// A VIP Customer has logged into an e-commerce website from a different region i.e. West Coast
// This customer will be added to the cache according to the category Tags

// Create an array of new Tags assigned to customer with different region
Tag[] tags = new Tag[2];
tags[0] = new Tag("West Coast Customers");
tags[1] = new Tag("VIP Customers");

// Set the Tag property of the cacheItem with the new updated array
cacheItem.setTags(List.of(tags));

// Re-insert the updated cacheItem into cache with different Tags
cache.insert(customerKey, cacheItem);

# Precondition: Cache is already connected

# A VIP Customer has logged into an e-commerce website from a different region, i.e., West Coast
# This customer will be added to the cache according to the category Tags

## Create an array of new Tags assigned to customer with different region
new_tags = [
    Tag("West Coast Customers"),
    Tag("VIP Customers")
]

# Set the Tag property of the cacheItem with a new updated array
cache_item.set_tags(new_tags)

# Re-insert the updated cacheItem into cache with different Tags
cache.insert(customer_key, cache_item)

// Precondition: Cache is already connected

// This is an async method

// A VIP Customer has logged into an e-commerce website from a different region, i.e., West Coast
// This customer will be added to the cache according to the category Tags

// Create an array of new Tags assigned to customer with different region
var newTags = [
    new ncache.Tag("West Coast Customers"),
    new ncache.Tag("VIP Customers")
];

// Set the Tag property of the cacheItem with a new updated array
cacheItem.setTags(newTags);

// Re-insert the updated cacheItem into cache with different Tags
await this.cache.insert(key, cacheItem);

Append Tags to Already Existing Tags

If there is a need to append a new Tag to the already present Tags or if a Tag needs to be removed from the already present Tags, the operation will require manipulating the Tags array. For this purpose, create a new list with the Tags to append and copy that list to the array containing the Tags already. This way a new Tag would be added to the array containing the Tags previously created without affecting them. The following example appends new Tags to an already existing Tag list.

// Precondition: Cache is already connected

// A customer has logged in from the US who wants to add Tags for the country and region
string customerKey = $"Customer:ALFKI";

// Get CacheItem from Cache
CacheItem cachedCustomer = cache.GetCacheItem(customerKey);

// Create new list for Tags
var customerTags = new List<Tag>();

// Initialize the list with existing Tags
customerTags = new List<Tag>(cachedCustomer.Tags);

// Add new Tags to existing list of Tags
customerTags.Add(new Tag("US Customers"));

// Assign newly built Tag list to the cached customer object
cachedCustomer.Tags = customerTags.ToArray();

// Update the modified customer object in cache
cache.Insert(customerKey, cachedCustomer);

// Precondition: Cache is already connected

// A customer has logged in from the US who wants to add Tags for the country and region
String customerKey = "Customer:ALFKI";

// Get CacheItem from Cache
CacheItem cachedCustomer = cache.getCacheItem(customerKey);

// Initialize a list with existing Tags
List<Tag> customerTags = new ArrayList<>(cachedCustomer.getTags());

// Add new Tags to existing list of Tags
customerTags.add(new Tag("US Customers"));

// Assign the newly built Tag list to the cached customer object
cachedCustomer.setTags(customerTags);

// Update the modified customer object in cache
cache.insert(customerKey, cachedCustomer);

# Precondition: Cache is already connected

 # A customer has logged in from the US who wants to add Tags for the country and region
customerKey = f"Customer:{'ALFKI'}"

# Get CacheItem from Cache
cached_customer = cache.get_cacheitem(customerKey)

# Create new list for Tags
customer_tags = cached_customer.get_tags()

# Add new Tags to existing list of Tags
customer_tags.append(Tag("US Customers"))

# Assign newly built Tag list to the cached customer object
cached_customer.set_tags(customer_tags)

# Update the modified customer object in cache
cache.insert(customerKey, cached_customer)

// Precondition: Cache is already connected

// This is an async method

// A customer has logged in from the US who wants to add Tags for the country and region
var customerKey = "Customer:ALFKI";

// Get CacheItem from Cache
var cachedCustomer = await this.cache.getCacheItem(customerKey);

// Create new Tag array
var customerTags = [];

// Initialize the list with existing Tags
customerTags = [cachedCustomer.getTags()];

// Add new Tags to existing list of Tags
customerTags.fill(new ncache.Tag("US Customers"));

// Assign newly built Tag list to the cached customer object
cachedCustomer.setTags(customerTags);

// Update the modified customer object in cache
await this.cache.insert(customerKey, cachedCustomer);

Additional Resources

NCache provides sample application for Tags on GitHub.