Merge pull request #28 from kylinsoong/master

update internal view page

caching/Internal_Materialization.adoc

@@ -1,37 +1,60 @@
 
+:toc: manual
+:toc-placement: preamble
+
 = Internal Materialization
 
-Internal materialization creates Teiid temporary tables to hold the materialized table. While these tables are not fully durable, they perform well in most circumstances and the data is present at each Teiid
-instance which removes the single point of failure and network overhead of an external database. Internal materialization also provides built-in facilities for refreshing and monitoring. See link:../admin/Memory_Management.adoc#_limitations[Memory Limitations] regarding size limitations.
+Internal materialization creates Teiid temporary tables to hold the materialized table. While these tables are not fully durable, they perform well in most circumstances and the data is present at each Teiid instance which removes the single point of failure and network overhead of an external database. Internal materialization also provides built-in facilities for refreshing and monitoring. See link:../admin/Memory_Management.adoc#_limitations[Memory Limitations] regarding size limitations.
+
+== View Options
 
 The materialized option must be set for the view to be materialized. The link:Hints_and_Options.adoc[Cache Hint], when used in the context of an internal materialized view transformation query, provides the ability to fine tune the materialized table. The caching options are also settable via extension metadata:
 
 |===
-|Property Name |Description
+|Property Name |Description |Optional |Default 
+
+|materialized
+|Set for the view to be materialized
+|false
+|true
+
+|UPDATABLE
+|Allow updating Materialized View via DDL `UPDATE`
+|true
+|false
 
 |teiid_rel:ALLOW_MATVIEW_MANAGEMENT
-|Allow Teiid based management of the ttl and initial load rather than the implicit behavior.  Defaults to false.
+|Allow Teiid based management of the ttl and initial load rather than the implicit behavior. 
+|true
+|false
 
 |teiid_rel:MATVIEW_PREFER_MEMEORY
-|Same as the pref_mem cache hint option. Defaults to false.
+|Same as the pref_mem cache hint option.
+|true
+|false
 
 |teiid_rel:MATVIEW_TTL
-|Same as the ttl cache hint option.  Unlimited by default.
+|Trigger a Scheduled ExecutorService which execute link:../reference/sysadmin_schema.adoc#_sysadmin_refreshmatview[refreshMatView] repeatedly with a specified time to live
+|true
+|null
 
 |teiid_rel:MATVIEW_UPDATABLE
-|Same as the updatable cache hint option.  Defaults to false.
+|Allow updating Materialized View via link:../reference/sysadmin_schema.adoc#_sysadmin_refreshmatview[refreshMatView], link:../reference/sysadmin_schema.adoc#_sysadmin_refreshmatviewrow[refreshMatViewRow], link:../reference/sysadmin_schema.adoc#_sysadmin_refreshmatviewrows[refreshMatViewRows]
+|true
+|false.
 
 |teiid_rel:MATVIEW_SCOPE
-|Same as the scope cache hint option.  Defaults to vdb.
+|Same as the scope cache hint option. 
+|true
+|VDB
 |===
 
 The pref_mem option also applies to internal materialized views. Internal table index pages already have a memory preference, so the perf_mem option indicates that the data pages should prefer memory as well.
 
 All internal materialized view refresh and updates happen atomically. Internal materialized views support READ_COMMITTED (used also for READ_UNCOMMITED) and SERIALIZABLE (used also for REPEATABLE_READ) transaction isolation levels.
 
-A sample Dynamic VDB defining an internal materialization:
-
 [source,xml]
+.*A sample Dynamic VDB defining an internal materialization*
 ----
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <vdb name="sakila" version="1">
@@ -47,8 +70,11 @@ A sample Dynamic VDB defining an internal materialization:
            first_name varchar(45) NOT NULL,
            last_name varchar(45) NOT NULL,
            last_update timestamp NOT NULL
-        ) OPTIONS (materialized true, "teiid_rel:MATVIEW_TTL" 120000,
+        ) OPTIONS (materialized true, 
+               UPDATABLE 'TRUE',
+               "teiid_rel:MATVIEW_TTL" 120000,
                "teiid_rel:MATVIEW_PREFER_MEMORY" 'true',
+               "teiid_rel:ALLOW_MATVIEW_MANAGEMENT" 'true', 
                "teiid_rel:MATVIEW_UPDATABLE" 'true',
                "teiid_rel:MATVIEW_SCOPE" 'vdb')
             AS SELECT actor_id, first_name, last_name, last_update from pg."public".actor;
@@ -60,8 +86,10 @@ A sample Dynamic VDB defining an internal materialization:
 
 == Loading And Refreshing
 
-An internal materialized view table is initially in an invalid state (there is no data). If teiid_rel:ALLOW_MATVIEW_MANAGEMENT is specified as true, then the initial load will occur on vdb startup.  
-If teiid_rel:ALLOW_MATVIEW_MANAGEMENT is not specified or false, then the load of the materialization table will occur on implicit on the first query that accesses the table.
+An internal materialized view table is initially in an invalid state (there is no data). 
+
+* If `teiid_rel:ALLOW_MATVIEW_MANAGEMENT` is specified as true, then the initial load will occur on vdb startup.  
+* If `teiid_rel:ALLOW_MATVIEW_MANAGEMENT` is not specified or false, then the load of the materialization table will occur on implicit on the first query that accesses the table.
 
 When a refresh happens while the materialization table is invalid all other queries against the materialized view will block until the load completes.
 
@@ -99,7 +127,7 @@ If you would rather that the ttl is enforced lazily, such that the current conte
 
 The resulting materialized view will be reloaded every hour (3600000 milliseconds).
 
-==== Limitations
+==== TTL Snapshot Refresh Limitations
 
 * The automatic ttl refresh may not be suitable for complex loading scenarios as nested materialized views will be used by the refresh query.
 * The non-managed ttl refresh is performed lazily, that is it is only trigger by using the table after the ttl has expired. For infrequently used tables with long load times, this means that data may be used well past the intended ttl.