FT_AUpdate#

Summary#

FT_AUpdate is the atomic version of FT_Update. It makes the update of a spatial object indexed in a spatial index, and collects and stores related statistical data. It returns the primary key value that corresponds to the identifier of the row inserted into the table Execution.

Signatures#

integer FT_AUpdate(text index_name, text index_directory, integer old_pointer, Geometry old_geom, integer new_pointer, Geometry new_geom, integer statistic_option=1, integer loc_stat_data=1, text file=NULL);

integer FT_AUpdate(text apath, integer old_pointer, Geometry old_geom, integer new_pointer, Geometry new_geom, integer statistic_option=1, integer loc_stat_data=1, text file=NULL);

Description#

FT_AUpdate is the atomic version of FT_Update. It makes the update of a spatial object indexed in a spatial index, and collects and stores related statistical data. It returns the primary key value that corresponds to the identifier of the row inserted into the table Execution.

Note

FT_AUpdate is atomic because it executes three SQL functions as a unique operation.

FT_AUpdate 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.
  • old_pointer is the primary key value of the spatial object to be updated. That is, the unique identifier that provides direct access to the register storing the spatial object.
  • old_geom is the spatial object (i.e., a PostGIS object) to be updated.
  • new_pointer is the new primary key value of the spatial object being updated.
  • new_geom is the new spatial object (i.e., a PostGIS object) that will replace the old_geom.
  • 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

  • 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

  • new_pointer should not be previously used by an indexed spatial object. Otherwise, spatial queries on this spatial index might return duplicate results.
  • 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#

--using the first version of FT_Update to update the rectangular shaped object of the FT_Insert example
--only the spatial object is being updated
SELECT FT_AUpdate('r-tree', '/opt/festival_indices/', 50, 
    ST_GeomFromText('POLYGON((-6349160.26886151 -751965.038197354,-6349160.26886151 -606557.85245731,-6211936.96741955 -606557.85245731,-6211936.96741955 -751965.038197354,-6349160.26886151 -751965.038197354))', 3857), 50, 
    ST_GeomFromText('POLYGON((-6349100.26886151 -751965.038197354,-6349100.26886151 -606557.85245731,-6211936.96741955 -606557.85245731,-6211936.96741955 -751965.038197354,-6349100.26886151 -751965.038197354))', 3857)
    );

--using the second version of FT_Update. The spatial object is obtained from the underlying spatial dataset of the spatial index. It is transformed by using the function st_buffer.
SELECT FT_AUpdate('/opt/festival_indices/rstartree-brazil_points2017', 1000, 
    (SELECT way FROM brazil_points2017 WHERE id = 1000), 1000, 
    (SELECT ST_Buffer(way, 50) FROM brazil_points2017 WHERE id = 1000),
    4, 2, '/opt/statistical_data.sql'
    );

See Also#