Data Structures Behavior and Usage in Cache

NCache supports the key-value pair structures where the key is a string type against a value that can be any primitive type, custom object, CacheItem, or a data structure. Groups, Tags, Expiration, Locking, Dependencies, and more can be assigned to these values.

Note

This feature is only available in the NCache Enterprise.

However, updating any value within a data structure, let's say a list, required fetching it from the cache, updating it, and then adding it back into the cache. This resulted in additional calls over the network. NCache has now eliminated this restriction by providing exclusive support for adding/updating data structures by manipulating data directly over the server. Hence, improving the overall performance.

NCache provides explicit support for the following data structures:

List
Queue
HashSet
Dictionary
Counter

Apart from the functions provided by the native data structure interfaces, NCache extends its functionality by providing the option to specify metadata using a CacheItem. This means that the data structures can have Tags, Expiration, and Dependency, just like the other objects of the cache.

Important

The whole data structure will reside in one node of a clustered cache. For example, if you create a dictionary of 100 items, the whole dictionary of 100 items will exist in one node and not be distributed among other nodes.

The following figure shows the various data structures against their respective cache keys residing in a clustered cache of 3 nodes:

Data Structures in NCache

Feature Wise Behavior

Storage

Any item stored within a data structure is JSON-serialized to support native operations on the server, such as Contains.
The data structures have their own size along with the metadata which impacts the cache size.

PrimaryField Annotation

[PrimaryField] annotation can be used in user model classes for the data structures including the List and the Queue. The search operations on the data structures, such as Contains, can be used to serialize and send only that attribute/property instead of serializing and transferring the entire object over to the server. Only the PrimaryField attribute will be sent to the server and compared on the server side, decreasing the cost of the operation.

For example, the Customer class contains the property CustomerId, which is unique. This can be marked as the PrimaryField, and instead of comparing the complete object, for let's say Contains, comparing just the PrimaryField can complete the operation.

class Customer
{
    [PrimaryField]
    public string CustomerId { get;  set; }
    public string Name { get; set; }
    public string Address { get; set; }
}

Cache Keys

The data structures in NCache are named, i.e., they will be stored against a cache key like the other objects in NCache. If a cache key exists for a CacheItem, it cannot be used against a data structure.

Searchable Features

Searchable attributes like Groups, Tags, and Named Tags can be specified against a data structure during its creation. A CacheItem and a data structure can belong to the same group/tag/named tag. For more details, refer to Configure Searchable Attributes.

Data Invalidation Features

Eviction

The whole data structure is evicted from the cache if it falls under the "to be evicted" category. Not only does the data structure creation lead to the possible eviction, but any write operation on the data structure can trigger the eviction as well. For example, an item is added to the list such that the eviction criteria are met.

Expiration

The data structures can be invalidated from the cache after a specified interval of time, just like a CacheItem. The data structures support both, Absolute Expiration and Sliding Expiration.

Cache Dependencies [Deprecated]

The data structures support all the cache dependencies. For key-based dependencies, a list can be dependent on a CacheItem and vice versa. For more detail, refer to Configure Invalidation Attributes.

Querying on Data Structures

The data structures can be queried in the cache if they have searchable attributes configured. The searchable attributes include:

Groups [Deprecated]
Tags
Named Tags

For more details, refer to Query on Data Structures.

Backing Source Providers

Read-Through

This is at the collection level only. The data structures can be read directly from a data source if not found in the cache. Individual items of a data structure will not be read from the data source. Therefore, the whole list of items should be fetched from the data source.

Write-Through

Write-through is triggered in two cases:

Upon the data structure creation inside the cache (collection level).
Upon the addition of data to an already existing data structure (item level).

Cache Loader and Refresher

You can load data structures into the cache on cache start-up automatically, using the Cache Startup Loader feature. This requires implementing an interface ICacheLoader with its methods. Also, if there is any change or update in the data, Cache Refresher is used to refresh the data. For more details, refer to Cache Loader and Refresher.

Client Cache

The data structure is not stored on the client cache. Any Get operation will fetch it from the main cache but not store it on the client cache. For more details, refer to Client Cache. For example, when we take a lock on a dictionary the whole dictionary gets locked, and no further operations.

Locking

The NCache provides an efficient locking mechanism for the data synchronization and the integrity within the cache store being updated by different parallel clients. NCache's internal locking guarantees the consistency of the data structures across the entire cache cluster for every update for the same data structure. For example, whole dictionary is locked when we lock a dictionary.

Event Notifications

The cache-level events and the key-based events are supported along with the data structure-level events and can be registered together on a data structure. For example:

A list is created in the cache. This triggers the ItemAdded Cache Level Event and not the data structure event.
An item is added to this list. This triggers the ItemUpdated Cache Level Event as the list has been updated and the ItemAdded data structure event as a new item has been added to the list.

Limitations

The nested data structures are not yet supported.
The CacheItem cannot be stored within a data structure. For example, a list of CacheItems is not yet supported.
The custom objects in the HashSet are not yet supported.
A Dictionary key can only be of string type.

Topology Wise Behavior

Mirror Topology

For Mirror Topology, operations are performed on the active node. These operations are then replicated to the passive node.

Replicated Topology

For Replicated Topology, the operations are performed on the node the client is connected to, which then replicates the operations to all nodes.

Partitioned Topology

In Partitioned Topology, the whole data structure exists on the same node. It is distributed based on the key. This means that no matter how large the dictionary is, it will exist on one node; the dictionary itself will not be partitioned across nodes.

Partition-Replica Topology

In Partition-Replica Topology, the operations behave the same as in partitioned topology. The data structure is distributed based on the cache key, and it will reside on the same node. Its replica will exist on the other node.