Data Structures Behavior and Usage in Cache

Note

This feature is only available in NCache Enterprise Edition.

NCache previously supported key-value pair structures, where the key was string type against a value that could be any primitive type, custom object, CacheItem, or data structure. These could then be assigned properties like Groups, Tags, expiration, locking, dependencies and more.

However, updating any value within a data structure, for example a list, in the cache required fetching it from the cache, updating it and then adding it back to the cache which resulted in additional calls over the network. NCache has now eliminated this restriction by providing exclusive support for adding/updating data structures, where the data is manipulated directly over the server, improving performance.

NCache provides explicit support for the following data structures:

List
Queue
Set
Dictionary
Counter

Apart from the functions provided by the native datastructure interfaces, NCache has extended their functionality by providing the option to specify metadata which can be specified with a CacheItem. This means that the data structures can be added with tags, can have expiry and dependency just like other objects of the cache.

Important

Currently, the whole data type 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 get distributed among the nodes.

The following figure shows 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 type is JSON-serialized to support native operations on the server such as Contains().
Data types have their own size too, along with metadata which impacts cache size.

PrimaryField Annotation

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

For example, the Customer class can contain the attribute 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 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

Data Structures in NCache are named, that is they will be stored against a cache key just like other objects in NCache. If a cache key "ProductKey:1" exists for a CacheItem, it cannot be used against a data type.

Searchable Features

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

Data Invalidation Features

Eviction

The whole data type is evicted from the cache if it falls under the category to be evicted. Not only data type creation can cause eviction; any write operation on the data type can trigger eviction, for example an item is added to the list such that eviction criteria is met.

Expiration

Data Structures can be invalidated from the cache after a specified interval of time, just as CacheItems. Data types support both Absolute Expiration and Sliding Expiration.

Cache Dependencies

All cache dependencies are supported by data structures. For key-based dependencies, a list can be dependent on a CacheItem and vice versa, based on their keys.

For more detail, refer to Configure Invalidation Attributes.

Querying on Data Structures

Data types can be queried in cache if they have searchable attributes associated against them during data type creation. Searchable attributes include:

Groups
Tags
Named Tags

These attributes can be associated with a CacheItem, custom object, JSON object or any data type in cache.

For more detail, refer to Query on Data Structures.

Backing Source Providers

Read-Through: This is at collection level only. Data types can be read-through from data source if not found in cache. Individual items of a data type will not be read-through, for example, the whole list is fetched from data source.
Write-Through: Write-Through is triggered in two cases:
1. Data type is created in cache (collection level)
2. If data is added to an already existing data type (item level)

For more detail, refer to Backing Source Providers.

Cache Loader

You can load data structures into the cache on cache start up automatically. This requires implementing a custom implementation which is deployed over the server.

For more detail, refer to Cache Loader.

Bridge for WAN Replication

Bridge is used to replicate data from one on-site cache(s) to another on-site/off-site cache(s) across WAN for disaster recovery. Data types can also be replicated over a bridge.

For more detail, refer to Bridge for WAN Replication.

Client Cache

Data type is not stored on the client cache. Any Get operation will fetch from the main cache but not store it in client cache.

For more detail, refer to Client Cache.

Locking

NCache provides an efficient locking mechanism for data synchronization and integrity within the cache store being updated by different parallel clients. NCache internal locking guarantees the consistency of data structures across the entire cache cluster for every update for the same data type.

Event Notifications

Cache Level and Key based Events are supported along with Data Structure Level Events. These both can be registered together on a data type. For example:

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

Limitations

Nested data structures are not supported yet, only single level are supported.
CacheItem cannot be stored within a data type, for example, a list of CacheItem is not yet supported. Primitive and custom objects are supported.
HashSet can only store primitive types, not custom objects.
A Dictionary key can only be of string type.

Topology Wise Behavior

Mirror

For mirror topology, operations are performed on the active node which are then replicated to the passive node.

Replicated

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

Partitioned

In partitioned topology, the whole data type exists on the same node, it is distributed based on the key. This means that no matter how large the dictionary is, the whole of it will exist on one node - the dictionary itself will not be partitioned across nodes.

Partition of Replica

In partition-of-replica topology, operations behave the same as in partitioned topology. The data type is distributed based on the cache key, and the whole of it will reside on the same node. Its replica will exist on the other node.

Bridge

Just like other data in cache, data structures can also be replicated over WAN using bridges.