Configure Searchable Attributes for Data Structures in Cache

NCache allows you to organize distributed data structures, such as HashSets, Lists, and Queues, by associating them with searchable metadata. A data structure can be associated with searchable attributes such as:

These searchable attributes can be used to query all associated items, as explained in Querying Data Structures. For example, a CacheItem and HashSet can belong to the same group. These attributes are specified using the DataTypeAttributes class.

Important

These attributes cannot be modified once a data structure is created. However, the data structure itself can be modified.

Prerequisites

Before using the NCache client-side APIs, ensure that the following prerequisites are fulfilled:

The following examples configure searchable attributes for a data structure named ProductIDSet. The .NET and Java examples create a HashSet, while the Node.js example creates a List. Group Electronics, Tags, and a Named Tag are associated with the data structure using DataTypeAttributes or DataStructureAttributes.

Tip

One quick way to verify whether a data structure has been created is to use either properties of the Cache class:

  • Count returns the number of items present in the cache.
  • Contains verifies if the specified key of the data structure exists in the cache.
try
{
  // Precondition: Cache is already connected

  // Specify unique cache key for set
  string key = "ProductIDSet";

  // Specify attributes for HashSet
  var attributes = new DataTypeAttributes();

  // Specify group "Electronics"
  attributes.Group = "Electronics";

  // Specify tags
  Tag[] tags = new Tag[2];
  tags[0] = new Tag("2 Year Warranty");
  tags[1] = new Tag("Stainless Steel");
  attributes.Tags = tags;

  // Specify Named Tag
  var namedTag = new NamedTagsDictionary();
  namedTag.Add("Discount", 0.4);
  attributes.NamedTags = namedTag;

  // Create HashSet with attributes
  IDistributedHashSet<int> hashSet = cache.DataTypeManager.CreateHashSet<int>(key, attributes);

  // Adding Product IDs to HashSet
  int[] productIDs = FetchProductIDs();
  foreach(var productID in productIDs)
  {
      // Add product IDs to HashSet
      hashSet.Add(productID);
  }
  // You can also query on this HashSet using these attributes
}
catch (OperationFailedException ex)
{
    // NCache specific exception
    if(ex.ErrorCode == NCacheErrorCodes.KEY_ALREADY_EXISTS)
    {
        // An item with the same key already exists
    }
    else if (ex.ErrorCode == NCacheErrorCodes.CACHEITEM_IN_DATA_STRUCTURES)
    {
        // Data structures cannot be of CacheItem type
        // CacheItems cannot be added in data structures
    }
    else
    {
        // NCache specific exception
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}
Note

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

Additional Resources

NCache provides a sample application for configuring searchable attributes with data structures on GitHub.

See Also

.NET: Alachisoft.NCache.Client.DataTypes namespace
Java: com.alachisoft.ncache.client.datastructures namespace
Node.js: DataStructureManager class