FT_AQuerySpatialIndex#

Summary#

FT_AQuerySpatialIndex is the atomic version of FT_QuerySpatialIndex. It executes a spatial query using a given spatial index, and collects and stores related statistical data. 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_AQuerySpatialIndex(text index_name, text index_directory, integer query_type, Geometry search_obj, integer predicate, integer proc_option=1, integer statistic_option=1, integer loc_stat_data=1, text file=NULL);

setof query_result FT_AQuerySpatialIndex(text apath, , integer query_type, Geometry search_obj, integer predicate, integer proc_option=1, integer statistic_option=1, integer loc_stat_data=1, text file=NULL);

Description#

FT_AQuerySpatialIndex is the atomic version of FT_QuerySpatialIndex. It executes a spatial query using a given spatial index, and collects and stores related statistical data. 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.

FT_AQuerySpatialIndex 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_AQuerySpatialIndex 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).
  • statistic_option refers to the type of statistical data to be collected and stored. If statistic_option is equal to 1, its default value, FESTIval collects standard statistical data to be inserted as a new tuple in the table Execution. If statistic_option is equal to 2 or 4, FESTIval collects statistical data related to the structure of the index to be inserted as a new tuple in the table IndexSnapshot. If statistic_option is equal to 3 or 4, FESTIval collects the nodes of the index to be inserted as new tuples in the table PrintIndex. Note that the value 4 indicates, therefore, that all types of statistical data is collected and stored.
  • loc_stat_data defines where the statistical data should be stored. If its value is equal to 1, its default value, the statistical data is stored directly in the FESTIval’s data schema. If its value is equal to 2, the statistical data is stored in a SQL file that can be latter loaded into the FESTIval’s data schema.
  • file is the absolute path of the SQL file that will store the statistical data, if loc_stat_data is equal to 2. This file will be created if it does not exist. This parameter is not used if loc_stat_data is equal to 1.

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.
  • We recommend that you see the FESTIval's data schema in order to understand the types of statistical data that can be managed.
  • If loc_stat_data is equal to 2, the returning value is invalid since the insertion is not made directly on the table Execution. A valid treatment is performed on the file storing the statistical data.

Caution

  • The connected user of the database must be permission to read and write in the directory storing the index file. Otherwise, an error is returned.
  • If loc_stat_data is equal to 2, the connected user of the database must be permission to write in the directory storing this SQL 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_AQuerySpatialIndex('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_AQuerySpatialIndex('/opt/festival_indices/r-tree', 3, 
    ST_GeomFromText('POINT(-6349160.26886151 -751965.038197354)', 3857), 1, 1, 2, '/opt/statistical_data.sql');

See Also#

  1. V. Gaede, O. Günther, Multidimensional access methods, ACM Computing Surveys 30 (2) (1998) 170–231. ↩

  2. M. Schneider, T. Behr, Topological relationships between complex spatial objects, ACM Transactions on Database Systems 31 (1) (2006) 39–81. ↩