【11g】Guidelines for Using Client Result Cache 客户端结果缓存

Guidelines for Using Client Result Cache

您可以通过几种方式为应用程序启用客户机结果缓存，并根据所选择的方法确定使用客户机结果缓存的优先顺序。有关更多使用信息，请参阅“缓存示例用例”。

SQL Hints - 使用SQL提示/*+ result_cache */注释查询，以指示结果将存储在查询结果缓存中。使用SQL提示符是最高的优先级;它优先于表注释和会话参数。它适用于单个查询。此方法需要应用程序级更改。
Table Annotation - Annotate a table during deployment using result cache hints in the ALTER TABLE and CREATE TABLEstatements. Using table annotation is the next highest order of precedence below SQL hints and above session parameters when using MODE FORCE. It is applicable to all queries for that table. This method requires no application-level changes.
Session Parameters - Works across all tables for all queries; use this method when possible. You can either set the RESULT_CACHE_MODE initialization parameter in the server parameter file (init.ora) or use RESULT_CACHE_MODE clause in the ALTER SESSION and the ALTER SYSTEM statements. Using session parameters is the lowest order of precedence; both SQL hints and table annotations take precedence over session parameters usage. It is the most widely effective usage being applicable to all tables. This method requires no application-level changes.

Oracle建议应用程序使用结果缓存提示为只读或以读为主的数据库对象注释表和查询。如果对具有较大结果的查询进行结果缓存，这些结果可能会使用大量缓存内存。

由于应用程序指定的每一组绑定值都创建不同的缓存结果集(针对相同的SQL文本)，因此这些结果集可以一起使用大量客户机结果缓存内存。

当启用客户端结果缓存时，查询结果集可以缓存在客户端或服务器上，或者两者都缓存。即使禁用服务器结果缓存(默认启用)，也可以启用客户机结果缓存。

The first OCIStmtExecute() call of every OCI statement handle call always goes to the server even if there might be a valid cached result set. It is necessary that an OCIStmtExecute() call be made for each statement handle to be able to match a cached result set. Oracle recommends that applications have their own statement caching for OCI statement handles, or use OCI statement caching so that OCIStmtPrepare2() can return an OCI statement handle that has been executed once. Multiple OCI statement handles, from the same or different sessions, can simultaneously fetch data from the same cached result set.

For a result set to be cached, the OCIStmtExecute() or OCIStmtFetch2() calls that transparently create this cached result set must fetch rows until an ORA-01403 "No Data Found" error is returned. Subsequent OCIStmtExecute() or OCIStmtFetch2() calls that match a locally cached result set need not fetch to completion.

SQL Hints

Unless the RESULT_CACHE_MODE server initialization parameter is set to FORCE, you must explicitly specify the queries to be cached using SQL hints. The SQL /*+ result_cache */ or /*+ no_result_cache */ hint must be set in SQL text passed to OCIStmtPrepare() and OCIStmtPrepare2() calls.

除非将RESULT_CACHE_MODE服务器初始化参数设置为FORCE，否则必须显式指定使用SQL提示缓存的查询。必须在传递给OCIStmtPrepare()和OCIStmtPrepare2()调用的SQL文本中设置SQL /*+ result_cache */或/*+ no_result_cache */提示。

Table Annotation

The ALTER TABLE and CREATE TABLE statements enable you to annotate tables with result cache mode. There are also session parameters as mentioned in a later section. The matrix of table annotations and session parameters dictates the effective result cache mode for queries on that table. Note that SQL hints override table annotations and session parameters. The syntax is:

CREATE|ALTER TABLE [<schema>.]<table> ... [RESULT_CACHE (MODE {FORCE|DEFAULT})]

Here is an example of CREATE TABLE. It defines the table columns:

CREATE TABLE foo (a NUMBER, b VARCHAR2(20)) RESULT_CACHE (MODE FORCE);

Here is an example of ALTER TABLE:

ALTER TABLE foo RESULT_CACHE (MODE DEFAULT);

This ALTER TABLE statement is used to annotate tables so that results of statements or query blocks (for server result cache) using these tables are stored in the result cache. If a given query has a SQL hint /*+ result_cache / or /*+ no_result_cache */ or if the parameter RESULT_CACHE_MODE is set to FORCE, then the hint or session variable take precedence over the table annotation.

You should annotate all tables you want stored in the result cache. Then all SQL queries, whether single table selects or with joins, for these tables with cache hints, are considered for caching assuming they are cache-worthy.

See Also:

Oracle Database SQL Language Reference for more information about RESULT_CACHE clause, SQL hints, ALTERTABLE, and CREATE TABLE
Oracle Database Reference for more information about RESULT_CACHE_MODE

Table 10-1 summarizes the result cache annotation mode values.

Table 10-1 DDL Table Result Cache Annotation Modes

Mode Value	Description
`DEFAULT`	The default value. Result caching is not determined at the table level. You can use this value to clear any table annotations.
`FORCE`	If all table names in the query have this setting, then the query is always considered for caching unless the `NO_RESULT_CACHE`hint is specified for the query. If one or more tables named in the query are set to `DEFAULT`, then the effective table annotation for that query is `DEFAULT`.

Checking Table Annotation Mode

The RESULT_CACHE column in the DBA views DBA_TABLES, USER_TABLES, and ALL_TABLES shows the result cache mode annotation for the table. If the table has not been annotated, it shows DEFAULT.

Suppose that table emp is annotated as ALTER TABLE emp RESULT_CACHE (MODE FORCE).

Then execute the following query in the session:

SELECT table_name, result_cache FROM user_tables

The output is as follows:

TABLE_NAME    RESULT_CACHE
----------    ------------
   EMP           FORCE
   FOO           DEFAULT

The output shows that table FOO either has not been annotated or has been annotated using the following statement:

ALTER TABLE foo RESULT_CACHE (MODE DEFAULT);

See Also:

Oracle Database Reference for more information about the RESULT_CACHE column on these DBA views

Session Parameters

The RESULT_CACHE_MODE parameter enables you to decide result cache mode across tables in your queries. Use this clause in ALTERSESSION and ALTER SYSTEM statements, or inside the server parameter file (init.ora) to determine result caching.

RESULT_CACHE_MODE参数允许您在查询中跨表决定结果缓存模式。在ALTERSESSION和ALTER系统语句中使用该子句，或者在服务器参数文件(init.ora)中使用该子句来确定结果缓存。

See Also:

Oracle Database Reference for more information about RESULT_CACHE_MODE

Effective Result Cache Table Mode

The SQL query level result cache hints take precedence over the session parameter RESULT_CACHE_MODE and result cache table annotations. In addition, table annotation FORCE takes precedence over the session parameter MANUAL as indicated in Table 10-2. Table 10-2 compares modes (MANUAL and FORCE) for the session parameter RESULT_CACHE_MODE versus the comparable table annotation modes and shows the effective result cache mode.

Table 10-2 Effective Result Cache Table Mode

RESULT_CACHE_MODE Parameter	MANUAL	FORCE
Table Annotation = `FORCE`	`FORCE`	`FORCE`
Table Annotation = `DEFAULT`	`MANUAL`	`FORCE`

Note that when the effective mode is FORCE, then the actual caching depends on internal restrictions for client and server cache, query cache worthiness (for example, there is no SYSDATE in the query), and space available in the cache. This is similar to the SQL query hint /*+ result_cache */ because it is just a hint. It does not imply that the query is actually cached. Recall that table annotation DEFAULT indicates that result caching is not determined at the table level and session parameter mode MANUAL indicates that the query must be annotated with a SQL hint for the hint to take precedence, so in effect these are equivalent methods for this setting.

Cache Example Use Cases

The following are some use cases that show when SQL hints take precedence over table annotations and session parameter.

If the emp table is annotated as ALTER TABLE emp RESULT_CACHE (MODE FORCE) and the session parameter is not set, (it has its default value of MANUAL), this implies queries on table emp are considered for query caching.
If in an example, the SQL query is SELECT /*+ no_result_cache */ empno FROM emp, the query is not cached. This is because SQL hints take precedence over table annotations and session parameter.
If the emp table is not annotated or is annotated as ALTER TABLE emp RESULT_CACHE (MODE DEFAULT) and the session parameter is not set (it has a default value of MANUAL), this implies queries are not cached.
If in an example, the SQL query has the hint SELECT /*+ result_cache */ * FROM emp, then this query is considered for query caching.
If there is no table annotation and there is no SQL query hint, but the session or system parameter is set to FORCE, all queries on all tables are considered for query caching.

See Also:

Oracle Database SQL Language Reference for more about caching

Queries That Are Not Cached

There are queries that are not cached on the OCI client even if the result cache hint is specified. Such queries may be cached on the database if the server result cache feature is enabled (see the discussion of the SQL query result cache in Oracle Database Conceptsfor more information). If a SQL query includes any of the following, then the result set of that query is not cached in the OCI client result cache:

Remote objects
Complex types in the select list
Snapshot-based queries or flashback queries
Queries executed in a serializable, read-only transaction, or inside a flashback session
Queries that have PL/SQL functions in them
Queries that have virtual private database (VPD) policies enabled on the tables

客户端缓存一致性

客户机缓存透明地保持结果集与任何可能影响其缓存结果集的会话状态或数据库更改保持一致。

当事务修改用于构造缓存结果的任何数据库对象的数据或元数据时，在随后的到服务器的往返过程中，将向OCI客户机发送失效通知。如果OCI应用程序在一段时间内不调用数据库，那么客户机缓存延迟设置将强制下一次OCIStmtExecute()调用调用数据库，以检查此类失效。

The cached result sets relevant to database invalidations are immediately invalidated, and no subsequent OCIStmtExecute() calls can match such result sets. The OCI statement handles currently fetching from these cached result sets, at the time such invalidations are received, can continue fetching from this (invalidated) cached result set.

The next OCIStmtExecute() call by the process may cache the new result set if there is space available in the cache. The OCI client result cache periodically reclaims unused memory.

如果一个会话打开了一个事务，OCI将确保其引用在这个事务中更改的数据库对象的查询被发送到服务器，而不是客户机缓存。

这种一致性机制确保OCI缓存总是接近提交的数据库更改。如果OCI应用程序由于无法缓存的查询(如DMLs、OCILob调用等)而有相对频繁的调用，这些调用会透明地使客户机缓存与数据库更改保持最新。

注意，有时当一个表被修改时，触发器会导致另一个表被修改。OCI客户机结果缓存对所有这些更改都很敏感。

当会话状态被更改时，例如，如果NLS会话参数被修改，这可能导致查询结果不同。OCI结果缓存对这些更改很敏感，并且在随后的查询执行时，返回正确的查询结果集。否则，这些结果集将在一段时间后被“统治”。缓存了与新会话状态对应的新结果集。

如果应用程序必须跟踪所有此类数据库和会话更改，那么它可能很麻烦，并且容易出错。因此，OCI结果缓存透明地保持结果集与任何数据库或会话更改一致。

The OCI client result cache does not require thread support in the client.

客户端结果缓存的部署时间设置

The client result cache has server initialization parameters and client configuration parameters for its deployment time settings.

These are the server initialization parameters:

CLIENT_RESULT_CACHE_SIZE

The default value is zero, implying that the client cache feature is disabled. To enable the client result cache feature, set the size to 32768 bytes (32 Kilobytes (KB)) or greater. This is the minimum size of the client per-process result set cache. All OCI client processes get this minimum size. This can be overridden by the sqlnet.ora configuration parameter OCI_RESULT_CACHE_MAX_SIZE only if this feature is enabled on the server by the CLIENT_RESULT_CACHE_SIZE initialization parameter. 默认值为零，这意味着禁用了客户机缓存特性。要启用客户机结果缓存特性，请将大小设置为32768字节(32 KB)或更大。这是每个进程结果集缓存的客户机的最小大小。所有OCI客户机进程都得到这个最小大小。这可以被sqlnet覆盖。只有当客户机_result_cache_size初始化参数在服务器上启用该特性时，才可以使用配置参数OCI_RESULT_CACHE_MAX_SIZE。

You can view the current default maximum size by displaying the value of the CLIENT_RESULT_CACHE_SIZE parameter. To increase this maximum size, you can set CLIENT_RESULT_CACHE_SIZE. However, because CLIENT_RESULT_CACHE_SIZE is a static parameter, you must include the SCOPE = SPFILE clause if you use an ALTER SYSTEM statement, and you must restart the database before any changes to this parameter take effect. 通过显示CLIENT_RESULT_CACHE_SIZE参数的值，可以查看当前默认的最大大小。要增加这个最大大小，可以设置CLIENT_RESULT_CACHE_SIZE。但是，由于CLIENT_RESULT_CACHE_SIZE是一个静态参数，如果使用ALTER SYSTEM语句，则必须包含SCOPE = SPFILE子句，并且必须在对该参数的任何更改生效之前重新启动数据库。

Note that if the client result cache feature is disabled at the server, the client configuration parameter OCI_RESULT_CACHE_MAX_SIZE is ignored and the client result cache cannot be enabled at the client.意，如果在服务器上禁用了客户机结果缓存特性，则会忽略客户机配置参数OCI_RESULT_CACHE_MAX_SIZE，并且不能在客户机上启用客户机结果缓存。

The cache size can be set to the minimum of:

(available client memory) and

((the possible number of result sets to be cached)

* (the average size of a row in a result set)

* (the average number of rows in a result set)).

Note:
The client result cache has a maximum value of 2 GB; setting it higher causes a truncation to 2 GB.
Do not set the CLIENT_RESULT_CACHE_SIZE parameter during database creation, because that can cause errors.
CLIENT_RESULT_CACHE_LAG

The CLIENT_RESULT_CACHE_LAG initialization parameter enables you to specify the maximum amount of time in milliseconds that the client result cache can lag behind any changes in the database that affect its result sets. The default is 3000 milliseconds.CLIENT_RESULT_CACHE_LAG初始化参数使您能够指定客户机结果缓存可以滞后于数据库中任何影响其结果集的更改的最长时间(以毫秒为单位)。默认值是3000毫秒。

You can view the current lag by displaying the value of the CLIENT_RESULT_CACHE_LAG parameter. To change this value, you can set CLIENT_RESULT_CACHE_LAG. However, because CLIENT_RESULT_CACHE_LAG is a static parameter, you must include the SCOPE = SPFILE clause if you use an ALTER SYSTEM statement, and you must restart the database before any changes to this parameter take effect.
Table annotation. Optional. One can annotate read-only, read-mostly tables for result caching during deployment. No application-level changes are required. Note SQL result cache hints, if specified, override the table annotations. See Oracle Database SQL Language Reference for more information.
compatible

Specifies the release with which Oracle Database must maintain compatibility. This parameter must be set to 11.0.0.0 or higher for the client result cache to be enabled. If you want client caching on views, compatible must be set to 11.2.0.0 or higher.

Client Configuration File

A client configuration file is optional and overrides the cache parameters set in the server init.ora initialization file. These parameters are part of a sqlnet.ora file. The following optional parameters are available for client configuration:

OCI_RESULT_CACHE_MAX_SIZE (optional) - Maximum size in bytes for the per-process query cache. Specifying a size less than 32768 in the client sqlnet.ora file disables the client result cache feature for client processes reading this sqlnet.ora file.
OCI_RESULT_CACHE_MAX_RSET_SIZE (optional) - Maximum size of any result set in bytes in the per-process query cache.
OCI_RESULT_CACHE_MAX_RSET_ROWS (optional) - Maximum size of any result set in rows in the per-process query cache.

Note that the cache lag cannot be set on the client.

客户端缓存统计数据

On existing round-trips from the OCI client, OCI periodically sends statistics related to its client cache to the server. These statistics are stored in the CLIENT_RESULT_CACHE_STATS$ view. Information such as the number of result sets successfully cached, number of cache hits, and number of cached result sets invalidated are stored here. The number of cache misses for queries is at least equal to the number of Create Counts in client result cache statistics. More precisely, the cache miss count equals the number of server executions as seen in server Automatic Workload Repository (AWR) reports.

See Also:

Oracle Database Reference for information about the CLIENT_RESULT_CACHE_STAT$ view
Oracle Database Performance Tuning Guide to find the client process IDs and session IDs for the sessions doing client caching

Validation of the Client Result Cache

The following sections provide some more information about performing validations of the client result cache.

Timing Measurement

First, to determine the performance gain of adding result cache hints to the queries, measure the time taken to run the queries without the /*+ result_cache */ hints. Then add the /*+ result_cache */ hints to the query and measure the time again. The difference in time is your performance gain.

Using v$mystat

Query the v$mystat view. To query this view, you must be granted permissions. Perform these two queries

Query-1: Measures the "SQL*Net round-trips to and from the client" from v$mystat.

Query-2: Measures the "SQL*Net round-trips to and from the client" without the SQL result cache hint.

The difference between Query-2 and Query-1 queries is the number of round-trips that it usually takes without enabling client result cache.

Note that the Query-1 query itself would make some round-trips (approximately 2) in this calculation.

If you add a result cache hint to the query or add the FORCE table annotation to the query for table emp and perform the query again, the difference between Query-2 and Query-1 is much less.

Using v$sqlarea

Query the v$sqlarea view. To query this view, you must be granted permissions.

Run the following SQL statement:

SELECT COUNT(*) FROM emp

Reexecute this preceding SQL statement a few times.

Then query select executions, fetches, parse_calls from v$sqlarea where sql_text like '% from emp';

Next, add the result cache table hint for emp to the query.

Reexecute the query a few times.

With client caching, the values for column1, column2 are less.

Note that the preceding validations can also be performed with result cache table annotations.

OCI Client-Side Result Cache and Server Result Cache

The client-side result cache is a separate feature from the server result cache. The client-side result cache caches results of top-level SQL queries in OCI client memory, whereas the server result cache caches result sets in server SGA memory.

The server result cache may also cache query fragments. The client-side result caching can be enabled independently of the server result cache, though they both share the result cache SQL hints, table annotation, and session parameter RESULT_CACHE_MODE. See Oracle Database Concepts for more information about SQL query result cache. Table 10-3 shows the specific result cache association for client-site result cache or server result cache, or both, with regard to setting specific parameters, running particular PL/SQL packages, and querying specific Oracle database views.

Table 10-3 Setting Client-Side Result Cache and Server Result Cache

Parameters, PL/SQL Package, and Database Views	Result Cache Association
client_result_cache_* parameters client_result_cache_size, client_result_cache_lag	client result cache
SQL hints /+ result_cache /, /+ no_result_cache /	client result cache, server result cache
sqlnet.ora OCI_RESULT_CACHE* parameters: OCI_RESULT_CACHE_MAX_SIZE OCI_RESULT_CACHE_MAX_RSET_SIZE OCI_RESULT_CACHE_MAX_RSET_ROWS	client result cache
Statistics view: client_result_cache_stats$	client result cache
result_cache_mode parameter	client result cache, server result cache
All other result_cache* parameters, for example, result_cache_max_size	server result cache
Package DBMS_RESULT_CACHE	server result cache
Statistics views v$result_cache_, gv$result_cache_. For example, v$result_cache_statistics, gv$result_cache_memory	server result cache
create table annotation	client result cache, server result cache
alter table annotation	client result cache, server result cache

Client Result Cache Demo Files

See the files cdemoqc.sql, cdemoqc.c, and cdemoqc2.c (all are in the demo directory for your operating system) for demonstration files for this feature.

Compatibility with Previous Releases

To use client result cache, applications must be relinked with Oracle Database Release 11.1 or later client libraries and be connected to an Oracle Database Release 11.1 or later database server. This feature is available to all OCI applications including JDBC Type II driver, OCCI, Pro*C/C++, and ODP.NET. The OCI drivers automatically pass the result cache hint to OCIStmtPrepare() and OCIStmtPrepare2() calls, thereby getting the benefits of caching.