Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Query Cache"

(→‎Query Results Cache)
(→‎Query results cache query example)
 
(12 intermediate revisions by the same user not shown)
Line 7: Line 7:
 
|apis=
 
|apis=
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/QueryHints.html QueryHints]
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/QueryHints.html QueryHints]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/CacheType.html CacheType]
 
|nativeapi=y
 
|nativeapi=y
 
|nativeapis=
 
|nativeapis=
Line 16: Line 17:
 
The EclipseLink query results cache allows the results of named queries to be cached, similar to how objects are cached.
 
The EclipseLink query results cache allows the results of named queries to be cached, similar to how objects are cached.
  
−
By default in EclipseLink all queries that are not by Id, or not by cache indexed fields, access the database.  The resulting rows will still be resolved with the cache, and further queries for relationship will be avoided if the object is cached, but the original query will always access the database.  EclipseLink does have options for querying the cache, but these options cannot be used by default, as EclipseLink can not assume that all of the objects in the database are in the cache.  The query results cache allows for non-indexed and result list queries to still benefit from caching.
+
By default in EclipseLink all queries access the database, unless they are by Id, or by cache indexed fields.  The resulting rows will still be resolved with the cache, and further queries for relationship will be avoided if the object is cached, but the original query will always access the database.  EclipseLink does have options for querying the cache, but these options are not used by default, as EclipseLink cannot assume that all of the objects in the database are in the cache.  The query results cache allows for non-indexed and result list queries to still benefit from caching.
  
−
The query results cache are indexed by the name of the query, and the parameters of the query.  Only named queries can have their results cached, dynamic queries cannot use the query results cache.  As well, if you modify a named query before execution, such as setting hints or properties, then it cannot use the cache results.
+
The query results cache is indexed by the name of the query, and the parameters of the query.  Only named queries can have their results cached, dynamic queries cannot use the query results cache.  As well, if you modify a named query before execution, such as setting hints or properties, then it cannot use the cached results.
  
−
The query results cache does not pick up transactional changes from the application as the object cache does.  It should only be used to cache read-only objects, or should use an invalidation policy to avoid caching stale results.  Changes to the objects in the result set will still be picked up, by changes that affect the results set (such as new or changed objects that should be added/removed from the result set) will not be picked up.
+
The query results cache does not pick up committed changes from the application as the object cache does.  It should only be used to cache read-only objects, or should use an invalidation policy to avoid caching stale results.  Committed changes to the objects in the result set will still be picked up, by changes that affect the results set (such as new or changed objects that should be added/removed from the result set) will not be picked up.
  
 +
The query results cache supports a fixed size, cache type, and invalidation options.
 +
 +
==Configuring Query Results Cache==
 
The query results cache is configured through query hints.
 
The query results cache is configured through query hints.
 +
 +
{{EclipseLink_HintTable
 +
|caption=Query Results Cache Query Hints
 +
|content=
 +
<tr>
 +
<td><tt>eclipselink.query-results-cache</tt></td>
 +
<td>Enable query results cache for the named query.</td>
 +
<td>no cached results</td>
 +
<td>Required</td>
 +
</tr>
 +
<tr>
 +
<td><tt>eclipselink.query-results-cache.size</tt></td>
 +
<td>Sets the fixed size of the query results cache for the named query.  The size is the number of queries with unique parameters to cache.
 +
If the query has no parameters, a value of 1 should be used.</td>
 +
<td><tt>100</tt></td>
 +
<td>Optional</td>
 +
</tr>
 +
<tr>
 +
<td><tt>eclipselink.query-results-cache.expiry</tt></td>
 +
<td>Sets the expiry time in milliseconds of the cached results.</td>
 +
<td>no expiry</td>
 +
<td>Optional</td>
 +
</tr>
 +
<tr>
 +
<td><tt>eclipselink.query-results-cache.expiry-time-of-day</tt></td>
 +
<td>Configures the time of day expiry.  Valid values are string time format, "HH:MM:SS".</td>
 +
<td>no expiry</td>
 +
<td>Optional</td>
 +
</tr>
 +
<tr>
 +
<td><tt>eclipselink.query-results-cache.randomize-expiry</tt></td>
 +
<td>Set if the expiry time should be randomized by 10% of the set expiry time.  This can be used to avoid a bottleneck on a fixed expiry time.</td>
 +
<td><tt>false</tt></td>
 +
<td>Optional</td>
 +
</tr>
 +
<tr>
 +
<td><tt>eclipselink.query-results-cache.type</tt></td>
 +
<td>Set the cache type.  Valid values are defined in the <tt>CacheType</tt> enum. Normally an LRU fixed sized <tt>CACHE</tt> is used, a <tt>FULL</tt>, <tt>WEAK</tt> or <tt>SOFT</tt> cache can also be used.</td>
 +
<td><tt>CACHE</tt></td>
 +
<td>Optional</td>
 +
</tr>
 +
}}
  
 
======''Query results cache annotation example''======
 
======''Query results cache annotation example''======
Line 32: Line 78:
 
   query="Select e from Employee e where e.address.city = :city",
 
   query="Select e from Employee e where e.address.city = :city",
 
   hints={
 
   hints={
−
     @Hint(name="", value="")
+
     @Hint(name="eclipselink.query-results-cache", value="true")
 +
    @Hint(name="eclipselink.query-results-cache.size", value="500")
 
   })
 
   })
 
public class Employee {
 
public class Employee {
Line 48: Line 95:
 
version="2.4">
 
version="2.4">
 
     <entity name="Employee" class="org.acme.Employee" access="FIELD">
 
     <entity name="Employee" class="org.acme.Employee" access="FIELD">
−
         <named-query name="findAllEmployeesInCity">
+
         <named-query name="findAllEmployeesInCity" query="Select e from Employee e where e.address.city = :city">
−
             <hint name="" value=""/>
+
            <hint name="eclipselink.query-results-cache" value="true"/>
 +
             <hint name="eclipselink.query-results-cache.size" value="500"/>
 
         </named-query>
 
         </named-query>
 
         ...
 
         ...
Line 65: Line 113:
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
 
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Indexes|Cache Indexes]]
 
|previous= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Indexes|Cache Indexes]]
−
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Coordination|Clustering and Cache Coordination]]
+
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Query Options|Query Cache Options and In-memory Querying]]
 
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Caching]]
 
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching|Caching]]
 
|version=2.4 DRAFT}}
 
|version=2.4 DRAFT}}

Latest revision as of 12:02, 30 May 2012

EclipseLink JPA

Eclipselink-logo.gif
EclipseLink
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source

Query Results Cache

The EclipseLink query results cache allows the results of named queries to be cached, similar to how objects are cached.

By default in EclipseLink all queries access the database, unless they are by Id, or by cache indexed fields. The resulting rows will still be resolved with the cache, and further queries for relationship will be avoided if the object is cached, but the original query will always access the database. EclipseLink does have options for querying the cache, but these options are not used by default, as EclipseLink cannot assume that all of the objects in the database are in the cache. The query results cache allows for non-indexed and result list queries to still benefit from caching.

The query results cache is indexed by the name of the query, and the parameters of the query. Only named queries can have their results cached, dynamic queries cannot use the query results cache. As well, if you modify a named query before execution, such as setting hints or properties, then it cannot use the cached results.

The query results cache does not pick up committed changes from the application as the object cache does. It should only be used to cache read-only objects, or should use an invalidation policy to avoid caching stale results. Committed changes to the objects in the result set will still be picked up, by changes that affect the results set (such as new or changed objects that should be added/removed from the result set) will not be picked up.

The query results cache supports a fixed size, cache type, and invalidation options.

Configuring Query Results Cache

The query results cache is configured through query hints.

Query Results Cache Query Hints
Hint Description Default Required?
eclipselink.query-results-cache Enable query results cache for the named query. no cached results Required
eclipselink.query-results-cache.size Sets the fixed size of the query results cache for the named query. The size is the number of queries with unique parameters to cache. If the query has no parameters, a value of 1 should be used. 100 Optional
eclipselink.query-results-cache.expiry Sets the expiry time in milliseconds of the cached results. no expiry Optional
eclipselink.query-results-cache.expiry-time-of-day Configures the time of day expiry. Valid values are string time format, "HH:MM:SS". no expiry Optional
eclipselink.query-results-cache.randomize-expiry Set if the expiry time should be randomized by 10% of the set expiry time. This can be used to avoid a bottleneck on a fixed expiry time. false Optional
eclipselink.query-results-cache.type Set the cache type. Valid values are defined in the CacheType enum. Normally an LRU fixed sized CACHE is used, a FULL, WEAK or SOFT cache can also be used. CACHE Optional
Query results cache annotation example
...
@Entity
@NamedQuery(
  name="findAllEmployeesInCity",
  query="Select e from Employee e where e.address.city = :city",
  hints={
    @Hint(name="eclipselink.query-results-cache", value="true")
    @Hint(name="eclipselink.query-results-cache.size", value="500")
  })
public class Employee {
  ...
}
Query results cache XML example
<?xml version="1.0"?>
<entity-mappings
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
	version="2.4">
    <entity name="Employee" class="org.acme.Employee" access="FIELD">
        <named-query name="findAllEmployeesInCity" query="Select e from Employee e where e.address.city = :city">
            <hint name="eclipselink.query-results-cache" value="true"/>
            <hint name="eclipselink.query-results-cache.size" value="500"/>
        </named-query>
        ...
    </entity>
</entity-mappings>
Query results cache query example
Query query = em.createNamedQuery("findAllEmployeesInCity");
query.setParameter("city", "Ottawa");
List<Employee> employees = query.getResultList();

Eclipselink-logo.gif
Version: 2.4 DRAFT
Other versions...

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/UserGuide/JPA/Basic_JPA_Development/Caching/Query_Cache&oldid=304095"

This page was last modified 12:02, 30 May 2012 by James .

Back to the top