Making a Cache Searchable
Caches can be made searchable, on a per cache basis, either by configuration or programmatically.
By Configuration
Caches are made searchable by adding a <searchable/> tag to the cache definition in the ehcache.xml file.
Note:
Size-based cache capacity constraints at heap tier (maxBytesLocalHeap) is deprecated now and not expected to work from Java 17 onwards. Consider maxEntriesLocalHeap instead.
This configuration will scan keys and values and, if they are of supported search types, add them as attributes called "key" and "value," respectively. If you do not want automatic indexing of keys and values, you can disable it using:
<cache name="cacheName" ...>
<searchable keys="false" values="false">
...
</searchable>
</cache>
You might want to do this if you have a mix of types for your keys or values. The automatic indexing will throw an exception if types are mixed.
If you think that you will want to add search attributes after the cache is initialized, you can explicitly indicate the dynamic search configuration. Set the
allowDynamicIndexing attribute to "true" to enable use of the Dynamic Attributes extractor. For more information about the Dynamic Attributes extractor, see
Defining Attributes.
<cache name="cacheName" ...>
<searchable allowDynamicIndexing="true">
...
</searchable>
</cache>
Often keys or values will not be directly searchable and instead you will need to extract searchable attributes from the keys or values. The following example shows a more typical case. Attribute extractors are explained in more detail in
Defining Attributes.
Programmatically
The following example shows how to programmatically create the cache configuration with search attributes.
Configuration cacheManagerConfig = new Configuration();
CacheConfiguration cacheConfig = new CacheConfiguration("myCache", 0).eternal(true);
Searchable searchable = new Searchable();
cacheConfig.addSearchable(searchable);
// Create attributes to use in queries.
searchable.addSearchAttribute(new SearchAttribute().name("age"));
// Use an expression for accessing values.
searchable.addSearchAttribute(new SearchAttribute()
.name("first_name")
.expression("value.getFirstName()"));
searchable.addSearchAttribute(new SearchAttribute()
.name("last_name")
.expression("value.getLastName()"));
searchable.addSearchAttribute(new SearchAttribute()
.name("zip_code")
.className("net.sf.ehcache.search.TestAttributeExtractor"));
cacheManager = new CacheManager(cacheManagerConfig);
cacheManager.addCache(new Cache(cacheConfig));
Ehcache myCache = cacheManager.getEhcache("myCache");
// Now create the attributes and queries, then execute.
...
To learn more about the Search API, see the net.sf.ehcache.search* packages in the Ehcache Javadoc at
http://www.ehcache.org/apidocs/2.10.1/.
Disk usage with the Terracotta Server Array
Search indexes are stored on Terracotta server disks. The default path is the same directory as the configured <data> location. You can customize the path using the <index> element in the server's tc-config.xml configuration file.
The Terracotta Server Array can be configured to be restartable in addition to including searchable caches, but both of these features require disk storage. When both are enabled, be sure that enough disk space is available. Depending upon the number of searchable attributes, the amount of disk storage required might be 3 times the amount of in-memory data.
It is highly recommended to store the search index (<index>) and the Fast Restart data (<data>) on separate disks.