The Union function

The R-tree access method uses the Union function to find a new all-inclusive bounding box for the index entries on an index page when a new entry is added. The union of the old bounding box and the bounding box of the new entry is the new, possibly enlarged, bounding box for the entire index page.

The R-tree access method also uses the Union function when it calculates onto which index page it should put a new index entry. In conjunction with the Size function, the Union function shows how much the old bounding box must be enlarged to include the new index entry. In other words, the Union function tells the R-tree access method the data size of a bounding box.

The access method also uses the Union function after a page split to calculate the bounding box for the new page and to evaluate the new groupings between the old and new pages.

The SQL signature of the Union support function must be:

Union (UDT, UDT, UDT) RETURNS INTEGER

UDT refers to user-defined type, or the data type you want to index with the R-tree access method.

Write the Union function to calculate the overall bounding box of the bounding boxes of the objects in the first two parameters and to store the result in the third parameter.

The return value of the Union function is not used by the R-tree access method. The Union function should call the mi_db_error_raise() DataBlade® API to return errors.

For variable UDTs, the third parameter of the Union function is not initialized; it contains a valid mi_lvarchar data type with slightly more memory than necessary allocated to it. Be sure you set the size in the function to the size, in bytes, of the largest possible result.

The result returned in the third parameter of the Union function must be a fixed size and not a large object. Set its size large enough for any return value.

The R-tree access method implementation assumes that the size returned from the first call to the Union function is the size of all internal index keys. Therefore, when you write the code for the Union function, pick a maximum size for any internal index keys of an R-tree index and set the size of the union to that value.

For sample C code of the Union function, see Union support function. C code uses the DataBlade API to interact with the database server.