FT_QuerySpatialIndex#

Summary#

FT_QuerySpatialIndex executes a spatial query using a given spatial index. It returns a set of spatial objects that either corresponds to the filter step or refinement step (i.e., final result) of the spatial query processing.

Signatures#

setof query_result FT_QuerySpatialIndex(text index_name, text index_directory, integer query_type, Geometry search_obj, integer predicate, integer proc_option=1);

setof query_result FT_QuerySpatialIndex(text apath, , integer query_type, Geometry search_obj, integer predicate, integer proc_option=1);

Description#

FT_QuerySpatialIndex executes a spatial query using a given spatial index. It returns a set of spatial objects that either corresponds to the filter step or refinement step (i.e., final result) of the spatial query processing.

Note

FT_QuerySpatialIndex does not automatically collect statistical data of the spatial query. To do this collection, make use of its equivalent atomic operation or construct workloads with auxiliary operations.

FT_QuerySpatialIndex is a set-returning function of the PostgreSQL. It returns query_result rows, formed by a primary key value (id) and a spatial object (geom) of the indexed dataset. FT_QuerySpatialIndex has two versions and its parameters are:

index_name is the name of the index file.
index_directory is the directory path that stores the index file.
apath is the absolute path of the index file.
query_type is the type of spatial query to be processed. The value 1 corresponds to selection query, 2 corresponds to range query, and 3 corresponds to point query. Spatial selection is a general type of query that returns a set of spatial objects that satisfy some topological predicate (indicated by the paramerter predicate) for a given spatial object (indicated by the parameter search_obj). Range query specializes spatial selection by allowing rectangular-shaped search objects. Point query specializes spatial selection by allowing only the use of intersects as the topological predicate and points as search objects. More information regarding types of spatial queries is given in Gaede and Günther (1998).
search_obj is the spatial object (i.e., a PostGIS object) corresponding to the search object of the spatial query.
predicate is the topological predicate to be used in the spatial query: 1 corresponds to Intersects, 2 corresponds to Overlap, 3 corresponds to Disjoint, 4 corresponds to Meet, 5 corresponds to Inside, 6 corresponds to CoveredBy, 6 corresponds to Contains, 7 corresponds to Covers, and 8 corresponds to Equals. These predicates are processed according to the 9-Intersection Model (Schneider and Behr, 2006).
proc_option refers to the type of the result of the spatial query. If it has the value equal to 1, FT_QuerySpatialIndex returns the final result of the spatial query (i.e., process both filter and refinement steps, if needed (Gaede and Günther, 1998)) If it has the value equal to 2, FT_QuerySpatialIndex returns the candidates returned by the spatial index (i.e., the filter step results).

Note

Some restrictions with respect to the geometric format of search_obj may be applicable. If query_type is equal to 2, the bounding box of search_obj is considered. If query_type is equal to 3, search_obj must be a point object.
If proc_option if equal to 2, the attribute geom of the query_result is equal to null.

Caution

The connected user of the database must be permission to read in the directory storing the index file. Otherwise, an error is returned.

Warning

It is important to keep the correspondence between the spatial index and its underlying spatial dataset. Hence, make sure that every indexed spatial object also exists in its underlying spatial dataset. This kind of control is out of scope of FESTIval.

Examples#

-- range query considering the predicate Overlap
select * from FT_QuerySpatialIndex('r-tree', '/opt/festival_indices/', 2, 
    ST_GeomFromText('POLYGON((-6349160.26886151 -751965.038197354,-6349160.26886151 -606557.85245731,-6211936.96741955 -606557.85245731,-6211936.96741955 -751965.038197354,-6349160.26886151 -751965.038197354))', 3857), 2);

-- point query, returning only the ids of the returned objects
select id from FT_QuerySpatialIndex('/opt/festival_indices/r-tree', 3, 
    ST_GeomFromText('POINT(-6349160.26886151 -751965.038197354)', 3857), 1);