GridGain Developers Hub
GitHub logo GridGain iso GridGain.com
GridGain Software Documentation

Near Caches

A near cache is a local cache that stores the most recently or most frequently accessed data on the local node. Let’s say your application launches a client node and regularly queries reference data, such as country codes. Because client nodes do not store data, these queries will always fetch data from the remote nodes. You can configure a near cache to keep the country codes on the local node while your application is running.

A near cache is configured for a specific regular cache and holds data for that cache only.

Near caches store data in the on-heap memory. You can configure the maximum size of the cache and eviction policy for near cache entries.

Configuring Near Cache

A near cache can be configured for a particular cache in the cache’s configuration.

<bean class="org.apache.ignite.configuration.CacheConfiguration">
    <property name="name" value="myCache"/>
    <property name="nearConfiguration">
        <bean class="org.apache.ignite.configuration.NearCacheConfiguration">
            <property name="nearEvictionPolicyFactory">
                <bean class="org.apache.ignite.cache.eviction.lru.LruEvictionPolicyFactory">
                    <property name="maxSize" value="100000"/>
                </bean>
            </property>
        </bean>
    </property>
</bean>
// Create a near-cache configuration for "myCache".
NearCacheConfiguration<Integer, Integer> nearCfg = new NearCacheConfiguration<>();

// Use LRU eviction policy to automatically evict entries
// from near-cache whenever it reaches 100_000 entries
nearCfg.setNearEvictionPolicyFactory(new LruEvictionPolicyFactory<>(100_000));

CacheConfiguration<Integer, Integer> cacheCfg = new CacheConfiguration<Integer, Integer>("myCache");

cacheCfg.setNearConfiguration(nearCfg);

// Create a distributed cache on server nodes
IgniteCache<Integer, Integer> cache = ignite.getOrCreateCache(cacheCfg);
var cacheCfg = new CacheConfiguration
{
    Name = "myCache",
    NearConfiguration = new NearCacheConfiguration
    {
        EvictionPolicy = new LruEvictionPolicy
        {
            MaxSize = 100_000
        }
    }
};

var cache = ignite.GetOrCreateCache<int, int>(cacheCfg);

Once configured in this way, the near cache will be created on any node that requests data from the underlying cache, including both server nodes and client nodes. When you get an instance of the cache, as shown in the following example, the data requests will go through the near cache.

IgniteCache<Integer, Integer> cache = ignite.cache("myCache");

int value = cache.get(1);

Most configuration parameters available in the cache configuration that make sense for the near cache are inherited from the underlying cache configuration. For example, if the underlying cache has an expiry policy configured, entries in the near cache will be expired based on the same policy.

The parameters listed in the table below are not inherited from the underlying cache configuration.

Parameter Description Default Value

nearEvictionPolicy

The eviction policy for the near cache. See the Eviction policies page for details.

none

nearStartSize

The initial capacity of the near cache (the number of entries it can hold).

375,000

Creating Near Cache Dynamically On Client Nodes

When making request from a client node to a cache that hasn’t been configured to use a near cache, you can create a near cache for that cache dynamically. This will increase performance by storing "hot" data locally on the client side. This cache will be operable only on the node where it was created.

To do this, create a near cache configuration and pass it as an argument to the method that gets the instance of the cache.

// Create a near-cache configuration
NearCacheConfiguration<Integer, String> nearCfg = new NearCacheConfiguration<>();

// Use LRU eviction policy to automatically evict entries
// from near-cache, whenever it reaches 100_000 in size.
nearCfg.setNearEvictionPolicyFactory(new LruEvictionPolicyFactory<>(100_000));

// get the cache named "myCache" and create a near cache for it
IgniteCache<Integer, String> cache = ignite.getOrCreateNearCache("myCache", nearCfg);

String value = cache.get(1);
var ignite = Ignition.Start(new IgniteConfiguration
{
    DiscoverySpi = new TcpDiscoverySpi
    {
        LocalPort = 48500,
        LocalPortRange = 20,
        IpFinder = new TcpDiscoveryStaticIpFinder
        {
            Endpoints = new[]
            {
                "127.0.0.1:48500..48520"
            }
        }
    },
    CacheConfiguration = new[]
    {
        new CacheConfiguration() {Name = "myCache"}
    }
});
var client = Ignition.Start(new IgniteConfiguration
{
    IgniteInstanceName = "clientNode",
    ClientMode = true,
    DiscoverySpi = new TcpDiscoverySpi
    {
        LocalPort = 48500,
        LocalPortRange = 20,
        IpFinder = new TcpDiscoveryStaticIpFinder
        {
            Endpoints = new[]
            {
                "127.0.0.1:48500..48520"
            }
        }
    }
});
// Create a near-cache configuration
var nearCfg = new NearCacheConfiguration
{
    // Use LRU eviction policy to automatically evict entries
    // from near-cache, whenever it reaches 100_000 in size.
    EvictionPolicy = new LruEvictionPolicy()
    {
        MaxSize = 100_000
    }
};


// get the cache named "myCache" and create a near cache for it
var cache = client.GetOrCreateNearCache<int, string>("myCache", nearCfg);