Author: shawkins Date: 2010-08-14 17:19:46 -0400 (Sat, 14 Aug 2010) New Revision: 2462 Added: trunk/documentation/caching-guide/src/main/docbook/en-US/main.xml Removed: trunk/documentation/caching-guide/src/main/docbook/en-US/DataCaching.xml Modified: trunk/documentation/caching-guide/pom.xml trunk/documentation/caching-guide/src/main/docbook/en-US/content/codetable.xml trunk/documentation/caching-guide/src/main/docbook/en-US/content/matviews.xml trunk/documentation/caching-guide/src/main/docbook/en-US/content/overview.xml trunk/documentation/caching-guide/src/main/docbook/en-US/content/resultset.xml trunk/documentation/reference/src/main/docbook/en-US/content/architecture.xml trunk/documentation/reference/src/main/docbook/en-US/content/scalar_functions.xml trunk/documentation/reference/src/main/docbook/en-US/content/sql_support.xml trunk/documentation/reference/src/main/docbook/en-US/content/translators.xml Log: TEIID-168 initial changes to the caching document. corrected the code table section mostly. Modified: trunk/documentation/caching-guide/pom.xml =================================================================== --- trunk/documentation/caching-guide/pom.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/caching-guide/pom.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -32,7 +32,7 @@ </dependency> </dependencies> <configuration> - <sourceDocumentName>DataCaching.xml</sourceDocumentName> + <sourceDocumentName>main.xml</sourceDocumentName> <imageResource> <directory>${basedir}/src/main/docbook/en-US</directory> <excludes> @@ -48,11 +48,11 @@ <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource> <finalName>teiid_caching_guide.pdf</finalName> </format> - <!-- <format> + <format> <formatName>html_single</formatName> <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource> <finalName>index.html</finalName> - </format> --> + </format> <format> <formatName>html</formatName> <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource> Deleted: trunk/documentation/caching-guide/src/main/docbook/en-US/DataCaching.xml =================================================================== --- trunk/documentation/caching-guide/src/main/docbook/en-US/DataCaching.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/caching-guide/src/main/docbook/en-US/DataCaching.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -1,53 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> -<!-- - - JBoss, Home of Professional Open Source. - Copyright (C) 2008 Red Hat, Inc. - Licensed to Red Hat, Inc. under one or more contributor - license agreements. See the copyright.txt file in the - distribution for a full listing of individual contributors. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - 02110-1301 USA. - ---> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> -%CustomDTD; -]> - -<book> - <bookinfo> - <title>Teiid - Scalable Information Integration</title> - <subtitle>Teiid Caching Guide</subtitle> - <releaseinfo>&versionNumber; - </releaseinfo> - <productnumber>&versionNumber; - </productnumber> - <issuenum>1</issuenum> - <copyright> - <year>&copyrightYear; - </year> - <holder>&copyrightHolder; - </holder> - </copyright> - <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </bookinfo> - <toc /> - <xi:include href="content/overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/matviews.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/resultset.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/codetable.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</book> \ No newline at end of file Modified: trunk/documentation/caching-guide/src/main/docbook/en-US/content/codetable.xml =================================================================== --- trunk/documentation/caching-guide/src/main/docbook/en-US/content/codetable.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/caching-guide/src/main/docbook/en-US/content/codetable.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -4,153 +4,77 @@ ]> <chapter id="codetable"> <title>Code Table Caching</title> - <para>MetaMatrix provides a means of caching small, frequently used - tables of data.  This is referred to as “code table caching” or - “reference data caching”.</para> - <para>Code table caching is done by using the lookup scalar function, - provided as a standard function with MetaMatrix. The lookup function - provides a way to get a value out of a table when a key value is + <para>Teiid provides a short cut to creating an internal materialized view table via the lookup function.</para> + <para>The lookup function provides a way to get a value out of a table when a key value is provided.  The function automatically caches all the values in the referenced table for the specified key/value pairs.  The cache is - created the first time it is used in a particular MetaMatrix process. + created the first time it is used in a particular Teiid process.  Subsequent lookups against the same table using the same key and value columns will use the cached information.</para> <para>This caching solution is appropriate for integration of - “reference data” with transactional or operational data.  Reference + "reference data" with transactional or operational data.  Reference data are static data sets – typically small – which are used very frequently in most enterprise applications.  Examples are ISO country codes, state codes, and different types of financial instrument - identifiers.  </para> + identifiers.</para> <section> - <title>Support Summary</title> - <orderedlist> - <listitem> - <para>Caching of small, frequently accessed tables</para> - </listitem> - <listitem> - <para>Administrative clearing of cached tables through command line - utility</para> - </listitem> - </orderedlist> - </section> - <section> <title>User Interaction</title> <para>This caching mechanism is automatically invoked when the lookup - scalar function is used.  Each time this function is called with a + scalar function is used.  The lookup function returns a scalar value, so it may be used anywhere an expression is expected. Each time this function is called with a unique combination of referenced table, key element, and returned - element (the first 3 arguments to the function), the MetaMatrix + element (the first 3 arguments to the function), the Teiid System caches the entire contents of the table being accessed.  Subsequent lookup function uses with the same combination of parameters uses the cached table data.</para> - <para>Note that the use of the lookup function automatically performs - caching; there is no option to use the lookup function and not - perform caching.  Once the values for a particular lookup are cached, - they will be used until the cache is cleared through the Console. - </para> - <para>Specification:</para> - <para>The following provides information on the use of the lookup - function.</para> - <informaltable frame="all"> - <tgroup cols="3"> - <thead> - <row> - <entry> - <para>Function</para> - </entry> - <entry> - <para>Definition</para> - </entry> - <entry> - <para>Datatype Constraint</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>LOOKUP(codeGroup, returnElement, keyElement, keyValue) - </para> - </entry> - <entry> - <para>In the lookup group codeGroup, find the row where - keyElement has the value keyValue and return the associated - returnElement.</para> - </entry> - <entry> - <para>codeGroup, returnElement, and keyElement must be string - literals containing metadata identifiers, keyValue datatype must - match datatype of the keyElement, return datatype matches that - of returnElement</para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - <para /> - <para>See the MetaMatrix Query Support Booklet for more information on - use of the lookup function.</para> - <para>Examples (can be used wherever scalar literal can be in query): - </para> - <para>lookup(‘ISOCountryCodes, ‘CountryName’, ‘CountryCode’, ‘US’) - </para> - <para>lookup(‘StatePostalCodes, ‘StateDisplayName’, ‘PostalCode’, - ‘63131’) </para> - <para>lookup(‘EmpIDs’, ‘Name’, ‘ID’, ‘m204815’) </para> + <para>See the Reference for more information on use of the lookup function.</para> + <example> + <title>Country Code Lookup</title> + <programlisting>lookup(‘ISOCountryCodes, ‘CountryName’, ‘CountryCode’, ‘US’)</programlisting> + </example> </section> <section> - <title>Cache Configuration</title> - <para>Cached lookup groups might consume significant memory.  You can - limit the number and maximum size of these code groups by setting - properties of the Query Service through the MetaMatrix Console.   - </para> - <para>The following are the properties that can be set at the query - service level to control reference data caching.</para> - <para /> - </section> - <section> - <title>Cache Characteristics</title> - <para>Cache Persistence Mechanism</para> - <para>Reference tables are persisted in object caches local to - individual Java processes (virtual machines or VMs).   They are - cached in the VM of the individual query services running on host - machines.  </para> - <para>Cache Loading Policy</para> - <para>When a user calls the lookup function for a unique combination - of table, key element, and returned element, the MetaMatrix System - caches all key-value pairs of that table for the specified elements. -    </para> - <para>The MetaMatrix System uses this cached map for all queries, in - all sessions, that later access this lookup group.</para> - <para>Cache Operational Policy</para> - <para>Cached tables are never proactively cleared.  They can only be - cleared through using the svcmgr utility script.</para> - </section> - <section> - <title>Cache Administration</title> - <para>The lookup cache can be cleared using the svcmgr utility script. -  To clear cached code tables, set expertmode on, and then pass in the - clearCodeTableCaches argument.</para> - </section> - <section> <title>Limitations</title> <orderedlist> <listitem> - <para>Cached code tables are not tied to specific virtual databases. -  This may result in an error when the same model is used in - multiple virtual databases while it has bindings to different - sources of data.  This may pose a security issue if a cached code - table is loaded in the context of one user but then accessed by - another user who should not have access to that data. [defect - 11629]</para> - </listitem> - <listitem> <para>The use of the lookup function automatically performs caching; there is no option to use the lookup function and not perform - caching.  [defect 14445]</para> + caching.</para> </listitem> + <listitem> + <para>No mechanism is provided to refresh code tables.</para> + </listitem> </orderedlist> - <para>Cached code tables are never proactively cleared by the Server. -  If a lot of code tables are loaded, or large code tables are loaded, - the Server’s available memory could be exceeded.</para> </section> + <section> + <title>Materialized View Alternative</title> + <para>The lookup function is a shortcut to create an internal materialized view. In many situations, it may be better to directly create the analogous materialized view rather than to use a code table.</para> + <itemizedlist> + <title>Reasons to use a materialized view:</title> + <listitem> + <para>More control of the possible return columns. Code tables will create a mat view for each key/value pair. If there are multiple return columns it would be better to have a single materialized view.</para> + </listitem> + <listitem> + <para>Proper materialized views have built-in system procedure/table support.</para> + </listitem> + <listitem> + <para>More control of the cache hint.</para> + </listitem> + <listitem> + <para>The ability to use option nocache.</para> + </listitem> + <listitem> + <para>Usage of a materialized view lookup as an uncorrelated subquery is no different than the use of the lookup function.</para> + </listitem> + </itemizedlist> + <orderedlist> + <title>Steps to create a materialized view:</title> + <listitem> + <para>Create a view selecting the appropriate columns from the desired table. In general, this view may have an arbitrarily complicated transformation query.</para> + <para>Designate the appropriate column(s) as the primary key.</para> + <para>Set the materailized property to true.</para> + <para>Add a cache hint to the transformation query. To mimic the behavior of the implicit internal materialized view created by the lookup function, use /*+ cache(pref_mem) */ to indicate that the table data pages should prefer to remain in memory.</para> + </listitem> + </orderedlist> + <para>Just as with the lookup function, the materialized view table will be created on first use and reused subsequently. See the <link linkend="matviews">Materialized View Chapter</link> for more on materialized views.</para> + </section> </chapter> \ No newline at end of file Modified: trunk/documentation/caching-guide/src/main/docbook/en-US/content/matviews.xml =================================================================== --- trunk/documentation/caching-guide/src/main/docbook/en-US/content/matviews.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/caching-guide/src/main/docbook/en-US/content/matviews.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -4,11 +4,11 @@ ]> <chapter id="matviews"> <title>Materialized Views</title> - <para>MetaMatrix supports Materialized Views.  These are Relational + <para>Teiid supports Materialized Views.  These are Relational virtual tables and views (‘virtual groups’) for which the transformations are pre-computed and the results are stored in an external database. When queries are issued against these virtual - groups through the MetaMatrix Server, the cached results are used. + groups through the Teiid Server, the cached results are used.  This saves the cost of accessing all the underlying data sources and re-computing the virtual group transforms each time a query is executed against the group.    </para> @@ -16,8 +16,8 @@ change rapidly, or when it is acceptable to retrieve data that is “stale” within some period of time, or when it is preferred for end-user queries to access staged data rather than placing additional - query load on operational sources.  MetaMatrix provides a utility to - refresh materialized tables.  This utility uses the MetaMatrix batched + query load on operational sources.  Teiid provides a utility to + refresh materialized tables.  This utility uses the Teiid batched update functionality.</para> <section> <title>Support Summary</title> @@ -43,7 +43,7 @@ <title>User Interaction</title> <para>When client applications issue queries against a Relational table or view that has been defined as a materialized view, the - MetaMatrix query engine automatically routes that query to obtain the + Teiid query engine automatically routes that query to obtain the results from the cache database.  </para> <para>Individual queries may override the use of materialized views by specifying OPTION NOCACHE on the query.  This parameter must specify @@ -94,8 +94,8 @@ then the Materialization physical cache model will not be created or included in the VDB.</para> <para>Virtual Database Deployment        </para> - <para>When deploying a virtual database (VDB) in the MetaMatrix - Console, the MetaMatrix administrator must define connector bindings + <para>When deploying a virtual database (VDB) in the Teiid + Console, the Teiid administrator must define connector bindings for all physical models in the VDB.  This is true for the well-known materialization cache model also.  In the New VDB or New VDB Version wizard, the materialization model will show up in the Connector @@ -103,7 +103,7 @@ appropriate JDBC connector for the data source where the materialized view cache will reside.  </para> <para>When deploying a VDB containing materialized views, the - MetaMatrix administrator will be presented with the option to save + Teiid administrator will be presented with the option to save administration scripts to the local file system.  This is in the New VDB, New VDB Version, and Import VDB wizards.  The administrator should save the scripts to a location where they can be accessed by a @@ -155,7 +155,7 @@ </orderedlist> <orderedlist> <listitem> - <para>Define username and password for connecting to MetaMatrix, to + <para>Define username and password for connecting to Teiid, to issue insert commands against the virtual groups during loading and reloading.</para> </listitem> @@ -190,10 +190,10 @@ <para>Cache Persistence Mechanism</para> <para>Materialized views cache their data in an external database system.  This database may be the same as the database used as the - MetaMatrix repository, or it may be a different one.   In general it - is recommended that the MetaMatrix repository not be used for + Teiid repository, or it may be a different one.   In general it + is recommended that the Teiid repository not be used for materialized view caching, as heavy use could impact the performance - of other core functionality of the MetaMatrix Server.  </para> + of other core functionality of the Teiid Server.  </para> <para>The following DBMS systems are supported for this purpose: </para> <orderedlist> @@ -209,18 +209,18 @@ </orderedlist> <para>Cache Operational Policy</para> <para>Since the actual physical cache for materialized views is - maintained external to the MetaMatrix system, there is no pre-defined + maintained external to the Teiid system, there is no pre-defined policy for clearing and managing the cache.  These policies will be - defined and enforced by administrators of the MetaMatrix system. + defined and enforced by administrators of the Teiid system. </para> <para>Cache Administration</para> <para>The cache used by materialized views is administered external to - MetaMatrix.  This provides a great deal of flexibility on how that + Teiid.  This provides a great deal of flexibility on how that cache is managed, refreshed, backed up, and otherwise administered along with other enterprise sources.</para> <para>Administrator Responsibilities</para> <para>These are the responsibilities of administrators with respect to - MetaMatrix’s materialized view data caching.</para> + Teiid’s materialized view data caching.</para> <informaltable frame="all"> <tgroup cols="3"> <colspec colnum="1" colname="c1" /> @@ -238,7 +238,7 @@ <para>Required Rights for Cache Database</para> </entry> <entry> - <para>Required Rights for MetaMatrix</para> + <para>Required Rights for Teiid</para> </entry> <entry> <para>Scripts Used</para> @@ -272,7 +272,7 @@ <para>Initially populate cache </para> </entry> <entry> - <para>Cache database and MetaMatrix</para> + <para>Cache database and Teiid</para> </entry> <entry> <para>Alter, Insert</para> @@ -294,7 +294,7 @@ <para>Refresh cache </para> </entry> <entry> - <para>Cache database and MetaMatrix</para> + <para>Cache database and Teiid</para> </entry> <entry> <para>Alter, Insert </para> @@ -318,14 +318,14 @@ <para>The refresh cache operation is recurring, basically at whatever frequency is appropriate for maintaining the desired data “freshness” for the VDB version.  This operation can be scheduled to execute the - MetaMatrix scripts, using standard scheduling mechanisms such as cron + Teiid scripts, using standard scheduling mechanisms such as cron on UNIX or the Windows scheduler.</para> <para>The truncate and swap scripts are used in the initial load.  The truncate is a no-op in this case, and the swap happens because data is always loaded to the staging table, which must then be swapped with the real cache table.  </para> - <para>MetaMatrix Administrative Scripts</para> - <para>To perform the administrative operations, MetaMatrix provides a + <para>Teiid Administrative Scripts</para> + <para>To perform the administrative operations, Teiid provides a set of 4 scripts.  Here is a summary of the scripts.  All the scripts use a similar template for their file names:  VDBName_VDBVersion_Name.ddl).</para> @@ -395,7 +395,7 @@ results into cache</para> </entry> <entry> - <para>MetaMatrix</para> + <para>Teiid</para> </entry> <entry> <para>Access user</para> @@ -422,108 +422,5 @@ </tbody> </tgroup> </informaltable> - <para /> - <para>In addition to these scripts, MetaMatrix provides a connection - properties file with encrypted passwords.</para> - <para>Materialized Database Creation</para> - <para>The cache for materialized views is maintained in a separate - database system.  Therefore, tables must be defined in the database - to hold the cached information for the materialized views in a VDB. -  Materialized views are scoped to a specific VDB version.  Therefore, - the cache tables should in general be segregated in the cache - database by VDB and version.  It is the responsibility of the - MetaMatrix and database administrators to ensure that the database is - defined appropriately for the VDB version, and to ensure that two - users are created with the appropriate privileges:</para> - <orderedlist> - <listitem> - <para>Script user – Used when executing Create/Truncate/Swap scripts - [note used for Load scripts, since that executes directly against - MetaMatrix with MetaMatrix user info].  Requires create/load/alter - privileges against the materialized view tables in the database. - </para> - </listitem> - <listitem> - <para>Access user – Used in connector binding definition both when - reading the cache for user queries, and when refreshing the cache - using the Load script.  Requires read and insert privileges against - the materialized view tables in the database.  </para> - </listitem> - </orderedlist> - <para>MetaMatrix provides a DDL script to create all the materialized - tables for a VDB.  This script is DBMS-specific.  When deploying a - VDB, the type of the DBMS is determined from the connector binding - used for the materialization physical model, and the appropriate - script for that DBMS is extracted from the VDB and saved to the local - file system.  </para> - <para>Script name: &lt;VDBName&gt;_&lt;VDBVersion&gt;_Create.ddl - </para> - <para>Example for “CustomerInfo” VDB, version 7: -  CustomerInfo_7_Create.ddl </para> - <para>The create script is a standard DDL script that can be executed - against the DBMS system using whatever mechanisms it supports.  The - script must be executed against a database schema/catalog with the - appropriate privileges as specified in the MetaMatrix Console. </para> - <para>Materialized Database Loading</para> - <para>MetaMatrix provides a set of 3 scripts to initially populate and - subsequently reload (“refresh”) all the materialized tables for a - VDB.  These scripts are DBMS-specific.  They are extracted from the - VDB when deploying that VDB, and saved by an administrator to the - local file system.  These scripts all assume that the cache tables - have been created, using the “Create” script described above.</para> - <para>These three scripts do the following for each materialized view: - </para> - <orderedlist> - <listitem> - <para>Truncate records in a temporary table (executed directly - against DBMS)</para> - </listitem> - <listitem> - <para>Load – execute query against virtual group, and insert into - temporary table (executed against MetaMatrix)</para> - </listitem> - <listitem> - <para>Swap temporary table with cache table (executed directly - against DBMS)</para> - </listitem> - </orderedlist> - <para>The second script uses the MetaMatrix batched inserts - functionality.  Therefore, the MetaMatrix Server must be running, and - the VDB must be deployed and activated.  The queries that are - executed all use the “cache override” option, so that the - transformations are executed.  </para> - <para>The first and third scripts execute DBMS-specific operations, to - more efficiently update the cache records.  These scripts are - standard DDL scripts that can be executed against the DBMS system - using whatever mechanisms it supports.  The scripts must be executed - against a database schema/catalog with the appropriate privileges as - specified in the MetaMatrix Console. </para> - <para>The three scripts can be executed together to perform initial - loading and subsequent refresh.  This can be done using the - loadscript.cmd (.sh on UNIX) command script, located in the server - materializedviews directory.  This script can be used to schedule - database loading activities.  </para> </section> - <section> - <title>Limitations</title> - <orderedlist> - <listitem> - <para>Materialization works only with Relational tables and views. -  It does not work with Data Access virtual groups or procedures.   - </para> - </listitem> - <listitem> - <para>A user cannot specify OPTION NOCACHE on virtual groups that - are not at the top level (in the user query).  The design does not - currently support this.</para> - </listitem> - </orderedlist> - </section> - <section> - <title>Outstanding Issues</title> - <para>Specifying OPTION NOCACHE within a transformation query is the - same as specifying it a user query – the identified virtual groups - will always be re-computed in the context of the virtual group - containing the transformation query with the override option.</para> - </section> </chapter> \ No newline at end of file Modified: trunk/documentation/caching-guide/src/main/docbook/en-US/content/overview.xml =================================================================== --- trunk/documentation/caching-guide/src/main/docbook/en-US/content/overview.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/caching-guide/src/main/docbook/en-US/content/overview.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -4,184 +4,14 @@ ]> <chapter id="overview"> <title>Overview</title> - <para>Teiid provides three capabilities for caching - data: materialized views, result set caching, and code table caching. + <para>Teiid provides several capabilities for caching + data including: materialized views, result set caching, and code table caching.  These can be used to significantly improve performance in many situations. </para> - <para>Following is a summary comparison of these three data caching - options.</para> - <informaltable frame="all"> - <tgroup cols="4"> - <tbody> - <row> - <entry> - <para /> - </entry> - <entry> - <para>Materialized Views</para> - </entry> - <entry> - <para>Result Set Caching</para> - </entry> - <entry> - <para>Code Table Caching</para> - </entry> - </row> - <row> - <entry> - <para>Best For</para> - </entry> - <entry> - <para>Complex transformations</para> - </entry> - <entry> - <para>Complex frequently issued user queries</para> - </entry> - <entry> - <para>Key based lookups on small, frequently accessed tables</para> - </entry> - </row> - <row> - <entry> - <para>Data Change Rate</para> - </entry> - <entry> - <para>Static</para> - </entry> - <entry> - <para>Static</para> - </entry> - <entry> - <para>Static</para> - </entry> - </row> - <row> - <entry> - <para>Data Size</para> - </entry> - <entry> - <para>Any size</para> - </entry> - <entry> - <para>Small-Medium</para> - </entry> - <entry> - <para>Small</para> - </entry> - </row> - <row> - <entry> - <para>Cache Defined By</para> - </entry> - <entry> - <para>External scripts</para> - </entry> - <entry> - <para>Query execution</para> - </entry> - <entry> - <para>Scalar function (lookup) execution</para> - </entry> - </row> - <row> - <entry> - <para>Cache Scope</para> - </entry> - <entry> - <para>VDB</para> - </entry> - <entry> - <para>VDB or session</para> - </entry> - <entry> - <para>VDB within Query service</para> - </entry> - </row> - <row> - <entry> - <para>Cache Key</para> - </entry> - <entry> - <para /> - </entry> - <entry> - <para>Based upon the user query</para> - </entry> - <entry> - <para>VDB + table + key column + value column</para> - </entry> - </row> - <row> - <entry> - <para>Cache Removal Policy</para> - </entry> - <entry> - <para>None (discretion of administrator)</para> - </entry> - <entry> - <para>Least-recently used removed first</para> - </entry> - <entry> - <para>None (discretion of administrator)</para> - </entry> - </row> - <row> - <entry> - <para>Cache Configuration</para> - </entry> - <entry> - <para>Model properties</para> - </entry> - <entry> - <para>DQP Configuration</para> - </entry> - <entry> - <para>DQP Configuration</para> - </entry> - </row> - <row> - <entry> - <para>Cache Administration</para> - </entry> - <entry> - <para>External to Teiid</para> - </entry> - <entry> - <para></para> - </entry> - <entry> - <para></para> - </entry> - </row> - <row> - <entry> - <para>Access Method</para> - </entry> - <entry> - <para>Query against materialized view</para> - </entry> - <entry> - <para>Query with caching enabled</para> - </entry> - <entry> - <para>Query containing scalar “lookup” function</para> - </entry> - </row> - <row> - <entry> - <para>User Override?</para> - </entry> - <entry> - <para>Yes</para> - </entry> - <entry> - <para>Yes</para> - </entry> - <entry> - <para>No – must explicitly specify whether to use</para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> + + <section id="cache_hint"> + <title>Cache Hint</title> + <para>Non-update user commands may be preceded with a cache hint, e.g. /*+ cache */ select ..., to inform the engine that the results of command should be cached. The scope of the result, either session or global, will be deteremined automatically from the determinism level of the source queries and functions executed.</para> + <para>ResultSet caching must be enabled for this hint to have an effect.</para> + </section> </chapter> Modified: trunk/documentation/caching-guide/src/main/docbook/en-US/content/resultset.xml =================================================================== --- trunk/documentation/caching-guide/src/main/docbook/en-US/content/resultset.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/caching-guide/src/main/docbook/en-US/content/resultset.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -4,11 +4,11 @@ ]> <chapter id="resultset"> <title>Result Set Caching</title> - <para>MetaMatrix provides the capability to store the results of - specific queries.  MetaMatrix can be configured to store the results + <para>Teiid provides the capability to store the results of + specific queries.  Teiid can be configured to store the results for end-user queries, or to cache the results of atomic queries issued to data sources in response to end-user queries, or both.  When the - exact same user query is submitted to the MetaMatrix Server, the + exact same user query is submitted to the Teiid Server, the cached results will be returned.  Similarly, if the exact same atomic query is encountered while processing an end-user query, the cached results will be used in processing that query, even if the end-user @@ -62,8 +62,8 @@ </section> <section> <title>Cache Configuration</title> - <para>Result set caching in the MetaMatrix Server is configured in the - MetaMatrix Console.  By default, result set caching is disabled. + <para>Result set caching in the Teiid Server is configured in the + Teiid Console.  By default, result set caching is disabled.  When enabled, the default caching scope is restricted to a particular VDB.</para> <para>Result set caching can be enabled and configured in two places: @@ -71,7 +71,7 @@ <orderedlist> <listitem> <para>End-user queries – In Configuration Deployment panel, - QueryEngine PSC, QueryService properties (per MetaMatrix process) + QueryEngine PSC, QueryService properties (per Teiid process) </para> </listitem> <listitem> @@ -229,7 +229,7 @@ </listitem> <listitem> <para>Caches are not distributed; they are bound to a particular - MetaMatrix process.  So, if the same query is routed to two + Teiid process.  So, if the same query is routed to two different host machines, the query will be executed twice, and cached independently on each machine. </para> </listitem> Copied: trunk/documentation/caching-guide/src/main/docbook/en-US/main.xml (from rev 2450, trunk/documentation/caching-guide/src/main/docbook/en-US/DataCaching.xml) =================================================================== --- trunk/documentation/caching-guide/src/main/docbook/en-US/main.xml (rev 0) +++ trunk/documentation/caching-guide/src/main/docbook/en-US/main.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -0,0 +1,53 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + + JBoss, Home of Professional Open Source. + Copyright (C) 2008 Red Hat, Inc. + Licensed to Red Hat, Inc. under one or more contributor + license agreements. See the copyright.txt file in the + distribution for a full listing of individual contributors. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301 USA. + +--> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../../../../../docbook/custom.dtd"> +%CustomDTD; +]> + +<book> + <bookinfo> + <title>Teiid - Scalable Information Integration</title> + <subtitle>Teiid Caching Guide</subtitle> + <releaseinfo>&versionNumber; + </releaseinfo> + <productnumber>&versionNumber; + </productnumber> + <issuenum>1</issuenum> + <copyright> + <year>&copyrightYear; + </year> + <holder>&copyrightHolder; + </holder> + </copyright> + <xi:include href="../../../../../docbook/en-US/legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </bookinfo> + <toc /> + <xi:include href="content/overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- <xi:include href="content/matviews.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> + <xi:include href="content/resultset.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/codetable.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</book> \ No newline at end of file Property changes on: trunk/documentation/caching-guide/src/main/docbook/en-US/main.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Modified: trunk/documentation/reference/src/main/docbook/en-US/content/architecture.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/content/architecture.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/reference/src/main/docbook/en-US/content/architecture.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -23,9 +23,7 @@ <itemizedlist> <listitem> <para>Session – the Session service manages active - session information.  Active sessions are stored in a - distributed cache and shared between Session services in each - VM. + session information. </para> </listitem> <listitem> Modified: trunk/documentation/reference/src/main/docbook/en-US/content/scalar_functions.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/content/scalar_functions.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/reference/src/main/docbook/en-US/content/scalar_functions.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -1777,7 +1777,16 @@ <para>The Lookup function allows you to cache a key value pair table and access it through a scalar function. This caching accelerates response time to queries that use the lookup tables, known in business terminology as lookup tables or code tables.</para> - <para>A StatePostalCodes table used to translate postal codes to + <para><synopsis>LOOKUP(codeTable, returnColumn, keyColumn, keyValue)</synopsis></para> + <para>In the lookup table codeTable, find the row where + keyColumn has the value keyValue and return the + associated returnColumn. codeTable must be a fully-qualified string + literal containing metadata identifiers, keyValue datatype + must match datatype of the keyColumn, return datatype + matches that of returnColumn. returnColumn and + keyColumn parameters should use their shortened names. + </para> + <para>For example, a StatePostalCodes table used to translate postal codes to complete state names might represent an example of this type of lookup table. One column, PostalCode, represents a key column. Other tables refer to this two-letter code. A @@ -1788,10 +1797,7 @@ <para>When you call this function for any combination of codeTable, returnColumn, and keyColumn for the first time, the Teiid System caches the result. The Teiid System uses this cache for all - queries, in all sessions, that later access this lookup table. The - codeTable requires use of the fully-qualified name, and the - returnColumn and keyColumn parameters should use shortened column - names.</para> + queries, in all sessions, that later access this lookup table.</para> <para>The Teiid System unloads these cached lookup tables when you stop and restart the Teiid System. Thus, you should not use this function for data that is subject to updates. Instead, you can use it against @@ -1799,49 +1805,11 @@ <note> <itemizedlist> <listitem> - <para>The keyColumn is expected to contain unique key + <para>The keyColumn is expected to contain unique values. If the column contains duplicate values, an exception will be thrown.</para> </listitem> </itemizedlist> </note> - <informaltable frame="all"> - <tgroup cols="3"> - <thead> - <row> - <entry> - <para>Function</para> - </entry> - <entry> - <para>Definition</para> - </entry> - <entry> - <para>Datatype Constraint</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <para>LOOKUP(codeTable, returnColumn, - keyColumn, keyValue)</para> - </entry> - <entry> - <para>In the lookup table codeTable, find the row where - keyColumn has the value keyValue and return the - associated returnColumn</para> - </entry> - <entry> - <para>codeTable must be a fully-qualified string - literal containing metadata identifiers, keyValue datatype - must match datatype of the keyColumn, return datatype - matches that of returnColumn. returnColumn and - keyColumn parameters should use their shortened names. - </para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> </section> <section> <title>System Functions</title> Modified: trunk/documentation/reference/src/main/docbook/en-US/content/sql_support.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/content/sql_support.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/reference/src/main/docbook/en-US/content/sql_support.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -560,11 +560,6 @@ </listitem> </itemizedlist> </section> - <section id="cache_hint"> - <title>Cache Hint</title> - <para>Non-update user commands may be preceded with a cache hint, e.g. /*+ cache */ select ..., to inform the engine that the results of command should be cached. The scope of the result, either session or global, will be deteremined automatically from the determinism level of the source queries and functions executed.</para> - <para>ResultSet caching must be enabled for this hint to have an effect.</para> - </section> <section id="procedural_relational"> <title>Procedural Relational Command</title> <para> Procedural relational commands use the syntax of a SELECT to Modified: trunk/documentation/reference/src/main/docbook/en-US/content/translators.xml =================================================================== --- trunk/documentation/reference/src/main/docbook/en-US/content/translators.xml 2010-08-13 17:35:16 UTC (rev 2461) +++ trunk/documentation/reference/src/main/docbook/en-US/content/translators.xml 2010-08-14 21:19:46 UTC (rev 2462) @@ -137,7 +137,7 @@ <para><emphasis>metamatrix</emphasis> - for use with MetaMatrix 5.5.0 or later.</para> </listitem> <listitem> -<para><emphasis>mysql</emphasis>/<emphasis>mysql5</emphasis> - for use with MySQL version 4.x and 5 or later respectively. <note>The MySQL Translators expect the database or session to be using ANSI mode. If the database is not using ANSI mode, an initialization query should be used on the pool to set ANSI mode: <programlisting>set SESSION sql_mode = 'ANSI'</programlisting></note></para> +<para><emphasis>mysql</emphasis>/<emphasis>mysql5</emphasis> - for use with MySQL version 4.x and 5 or later respectively. <note><para>The MySQL Translators expect the database or session to be using ANSI mode. If the database is not using ANSI mode, an initialization query should be used on the pool to set ANSI mode: <programlisting>set SESSION sql_mode = 'ANSI'</programlisting></para></note></para> </listitem> <listitem> <para><emphasis>oracle</emphasis> - for use with Oracle 9i or later. Sequences may be used with the Oracle translator.