SDO_UTIL.ENABLE_VECTORTILE

Format

SDO_UTIL.ENABLE_VECTORTILE_CACHE(
  table_name     IN VARCHAR2,
  geom_col_name  IN VARCHAR2,                                
  ts_name        IN VARCHAR2 default NULL,                                
  min_zoom       IN NUMBER DEFAULT 0,                                
  max_zoom       IN NUMBER DEFAULT 23
);

Description

Enables cache for vector tiles built from a table using the geometry column.

Parameters

table_name

Name of the table or view containing the information used to build the vector tiles (a geometry column and zero or more attribute columns).

geom_col_name

Name of the SDO_GEOMETRY type column in table_name which is used to build the vector tiles.

ts_name

Name of the table space.

This is an optional parameter. If specified, the tables (SDO_VECTOR_TILE_CACHE$INFO and SDO_VECTOR_TILE_CACHE$TABLE) that are created for tile caching are created in the specified table space. Otherwise, the cache tables are created in the schema's default table space.

min_zoom

Minimum zoom level stored in the cache.

This is an optional parameter with a default value of zero. If a min_zoom of eight is specified, then only tiles with a zoom of eight or higher are cached. If a tile at min_zoom of six is requested, then the tile is computed and returned to the caller, but it is not cached.

max_zoom

Maximum zoom level stored in the cache.

This is an optional parameter with a default value of 23. If a max_zoom of 16 is specified, then only tiles with a zoom of 16 or less are cached. If a tile at zoom 20 is requested, then the tile is computed and returned to the caller, but it is not cached.

Usage Notes

Vector tile caching is not enabled by default. To enable a vector tile cache, you can call this SDO_UTIL.ENABLE_VECTORTILE_CACHE procedure.

Tile caching creates and maintains two tables in the schema that enabled the cache:

SDO_VECTOR_TILE_CACHE$INFO: This table contains the metadata. Every tile cache has one row in this table describing the table_name, geom_col_name, min_zoom, and max_zoom of the cache.
This table is small and is stored in the same table space as SDO_VECTOR_TILE_CACHE$TABLE.
SDO_VECTOR_TILE_CACHE$TABLE: This table contains vector tiles for all vector tile caches enabled in the schema. This table can get very large, and is owned by the schema that enabled the cache.
It is stored in the same table space as SDO_VECTOR_TILE_CACHE$INFO. It is because of the potential size of SDO_VECTOR_TILE_CACHE$TABLE that the ts_name parameter is required. It allows the user to place this table and the SDO_VECTOR_TILE_CACHE$INFO table in a table space large enough to handle the load.

Both SDO_VECTOR_TILE_CACHE$INFO and SDO_VECTOR_TILE_CACHE$TABLE are owned by the schema that enabled the cache. As such, the schema may query and manipulate the data within these tables. However, it is important to note that these tables are only to be manipulated through the vector cache API.

A call to SDO_UTIL.ENABLE_VECTORTILE_CACHE creates an entry in SDO_VECTOR_TILE_CACHE$INFO. Once enabled, the cache is populated when you use the SDO_UTIL.GET_VECTORTILE API. Over time, performance improves as more tiles are available in the cache and fewer need to be computed.

If the caching tables SDO_VECTOR_TILE_CACHE$INFO and SDO_VECTOR_TILE_CACHE$TABLE do not already exist, then they are created when SDO_UTIL.ENABLE_VECTORTILE_CACHE is called the first time.

Calling SDO_UTIL.ENABLE_VECTORTILE_CACHE on an already enabled cache with different min_zoom, max_zoom, or both adjusts those values for the cache. Any tiles already in the cache that violate the new min_zoom or max_zoom will remain in the cache but the newly computed tiles will follow the new configurations.

Changing a tile caches' tablespace requires you to disable all the caches. The SDO_VECTOR_TILE_CACHE$INFO and SDO_VECTOR_TILE_CACHE$TABLE cache tables must be dropped. You can then call SDO_UTIL.ENABLE_VECTORTILE_CACHE again with the desired tablespace as a parameter. Note that this is a disruptive process that eliminates all currently cached tiles.

Examples

The following example calls SDO_UTIL.ENABLE_VECTORTILE_CACHE to enable cache on the counties table.

-- Enable a cache on the Counties table using the Geometry column
EXEC SDO_UTIL.ENABLE_VECTORTILE_CACHE('counties', 'geom');

-- Compute a vector tile
SELECT SDO_UTIL.GET_VECTORTILE(TABLE_NAME=>'COUNTIES', GEOM_COL_NAME=>'GEOM',
                                 TILE_ZOOM=>8, TILE_X=>73, TILE_Y=>97,
                                 ATT_COL_NAMES=>sdo_string_array('COUNTY','LANDSQMI'))
FROM dual;

-- Confirm that the cache now contains a copy of the computed tile.
-- If the same tile is requested again, then this cached version is returned.
SELECT COUNT(*) FROM SDO_VECTOR_TILE_CACHE$TABLE WHERE table_name='counties';