sqlite/ext/rtree
stephan 61cf538d27 Re-phrase some (#if !SQLITE_CORE) to (#ifndef SQLITE_CORE), as discussed in forum:cea40371c5e34b09 | for post cea40371c5e34b09].
FossilOrigin-Name: 5495b12569c318d5020b4b5a625a392ef8e777b81c0200624fbbc2a6b5eddef9
2024-11-06 12:58:31 +00:00
..
util Add the randomshape.tcl test-case generator script to the util subdirectory 2018-09-06 14:01:56 +00:00
geopoly.c Enable SQLITE_VTAB_INNOCUOUS for FTS3, FTS5, and RTREE. 2023-10-12 18:46:27 +00:00
README Fix another typo in the rtree README file. (CVS 5187) 2008-06-04 15:09:16 +00:00
rtree1.test Correction to the previous check-in. 2024-03-06 12:28:55 +00:00
rtree2.test In the rtree extension, actively suppress extra tokens on the column names, 2019-12-06 13:10:29 +00:00
rtree3.test Update the expected error messages in some OOM test cases to account for [44d77a7f807]. 2022-07-11 21:40:34 +00:00
rtree4.test In extensions rtree, fts3 and fts5, ensure that when dynamic buffers are bound 2018-02-07 18:02:50 +00:00
rtree5.test In extensions rtree, fts3 and fts5, ensure that when dynamic buffers are bound 2018-02-07 18:02:50 +00:00
rtree6.test Make the SQLITE_DBCONFIG_STMT_SCANSTATUS option on by default. 2023-03-03 21:17:12 +00:00
rtree7.test Add SQL scalar function rtreecheck() to the rtree module. For running checks 2017-10-25 16:38:34 +00:00
rtree8.test Omit the Reinsert algorithm from RTree. This causes most benchmarks to run 2023-09-13 17:30:12 +00:00
rtree9.test Fix harmless compiler warnings. Improve the independence of some TCL tests. 2021-10-22 11:17:29 +00:00
rtree_perf.tcl Remove the obsolete "$Id:$" RCS identifier strings from the source code. 2009-11-10 01:30:52 +00:00
rtree_util.tcl Add the xIntegrity method to the sqlite3_module object. Implement this 2023-09-06 12:52:00 +00:00
rtree.c Beginnings of rephrasing #if SQLITE_CORE to #ifdef/ifndef for consistency, as discussed in [forum:cea40371c5e34b09 | forum post cea40371c5e34b09]. 2024-10-24 07:44:13 +00:00
rtree.h Allow the shell to be built from the configure script with 2018-01-20 15:48:45 +00:00
rtreeA.test Omit the Reinsert algorithm from RTree. This causes most benchmarks to run 2023-09-13 17:30:12 +00:00
rtreeB.test Add SQL scalar function rtreecheck() to the rtree module. For running checks 2017-10-25 16:38:34 +00:00
rtreeC.test Show LEFT and RIGHT JOIN processing in the EXPLAIN QUERY PLAN output. 2022-04-11 14:26:37 +00:00
rtreecheck.test Ensure that the database encoding is detected before the code generator gets 2024-11-04 19:08:53 +00:00
rtreecirc.test Use SQLITE_PREPARE_NO_VTAB in rtree as well. 2018-12-21 19:55:20 +00:00
rtreeconnect.test Add test cases for ticket [be436a7f4587ce517] using virtual table modules fts5 2017-08-17 14:12:16 +00:00
rtreeD.test Change the error message text for SQLITE_ERROR to omit the part about 2017-07-07 19:43:23 +00:00
rtreedoc2.test Further tests for legacy rtree geom callbacks. 2021-09-18 16:15:54 +00:00
rtreedoc3.test Add new test file rtreedoc3.test. 2021-09-29 16:38:02 +00:00
rtreedoc.test Omit the Reinsert algorithm from RTree. This causes most benchmarks to run 2023-09-13 17:30:12 +00:00
rtreeE.test Add SQL scalar function rtreecheck() to the rtree module. For running checks 2017-10-25 16:38:34 +00:00
rtreeF.test Add SQL scalar function rtreecheck() to the rtree module. For running checks 2017-10-25 16:38:34 +00:00
rtreefuzz001.test Omit the Reinsert algorithm from RTree. This causes most benchmarks to run 2023-09-13 17:30:12 +00:00
rtreeG.test In extensions rtree, fts3 and fts5, ensure that when dynamic buffers are bound 2018-02-07 18:02:50 +00:00
rtreeH.test Be strict about type enforcement on rowid look-ups in the RTREE extension. 2019-12-05 13:34:13 +00:00
rtreeI.test Fix to the rowvalue logic that avoids disabling rowvalue inequality 2019-12-05 21:46:23 +00:00
rtreeJ.test Bring test cases into alignment with the latest enhancements. 2024-02-07 19:52:03 +00:00
sqlite3rtree.h Fix a typo in a comment. No changes to code. 2018-11-30 20:59:00 +00:00
test_rtreedoc.c First attempt at getting the build to work with Tcl 9.0. 2024-07-30 15:49:02 +00:00
tkt3363.test Fix a couple of memory leaks in r-tree that can occur following an OOM condition. 2010-08-26 14:15:37 +00:00
viewrtree.tcl Remove the obsolete "$Id:$" RCS identifier strings from the source code. 2009-11-10 01:30:52 +00:00
visual01.txt Add the geopoly_regular(X,Y,R,N) function to the geopoly extension. 2018-09-28 14:01:17 +00:00

This directory contains an SQLite extension that implements a virtual 
table type that allows users to create, query and manipulate r-tree[1] 
data structures inside of SQLite databases. Users create, populate 
and query r-tree structures using ordinary SQL statements.

    1.  SQL Interface

        1.1  Table Creation
        1.2  Data Manipulation
        1.3  Data Querying
        1.4  Introspection and Analysis

    2.  Compilation and Deployment

    3.  References


1. SQL INTERFACE

  1.1 Table Creation.

    All r-tree virtual tables have an odd number of columns between
    3 and 11. Unlike regular SQLite tables, r-tree tables are strongly 
    typed. 

    The leftmost column is always the pimary key and contains 64-bit 
    integer values. Each subsequent column contains a 32-bit real
    value. For each pair of real values, the first (leftmost) must be 
    less than or equal to the second. R-tree tables may be 
    constructed using the following syntax:

      CREATE VIRTUAL TABLE <name> USING rtree(<column-names>)

    For example:

      CREATE VIRTUAL TABLE boxes USING rtree(boxno, xmin, xmax, ymin, ymax);
      INSERT INTO boxes VALUES(1, 1.0, 3.0, 2.0, 4.0);

    Constructing a virtual r-tree table <name> creates the following three
    real tables in the database to store the data structure:

      <name>_node
      <name>_rowid
      <name>_parent

    Dropping or modifying the contents of these tables directly will
    corrupt the r-tree structure. To delete an r-tree from a database,
    use a regular DROP TABLE statement:

      DROP TABLE <name>;

    Dropping the main r-tree table automatically drops the automatically
    created tables. 

  1.2 Data Manipulation (INSERT, UPDATE, DELETE).

    The usual INSERT, UPDATE or DELETE syntax is used to manipulate data
    stored in an r-tree table. Please note the following:

      * Inserting a NULL value into the primary key column has the
        same effect as inserting a NULL into an INTEGER PRIMARY KEY
        column of a regular table. The system automatically assigns
        an unused integer key value to the new record. Usually, this
        is one greater than the largest primary key value currently
        present in the table.

      * Attempting to insert a duplicate primary key value fails with
        an SQLITE_CONSTRAINT error.

      * Attempting to insert or modify a record such that the value
        stored in the (N*2)th column is greater than that stored in
        the (N*2+1)th column fails with an SQLITE_CONSTRAINT error.

      * When a record is inserted, values are always converted to 
        the required type (64-bit integer or 32-bit real) as if they
        were part of an SQL CAST expression. Non-numeric strings are
        converted to zero.

  1.3 Queries.

    R-tree tables may be queried using all of the same SQL syntax supported
    by regular tables. However, some query patterns are more efficient
    than others.

    R-trees support fast lookup by primary key value (O(logN), like 
    regular tables).

    Any combination of equality and range (<, <=, >, >=) constraints
    on spatial data columns may be used to optimize other queries. This
    is the key advantage to using r-tree tables instead of creating 
    indices on regular tables.

  1.4 Introspection and Analysis.

    TODO: Describe rtreenode() and rtreedepth() functions.


2. COMPILATION AND USAGE

  The easiest way to compile and use the RTREE extension is to build
  and use it as a dynamically loadable SQLite extension. To do this
  using gcc on *nix:

    gcc -shared rtree.c -o libSqliteRtree.so

  You may need to add "-I" flags so that gcc can find sqlite3ext.h
  and sqlite3.h. The resulting shared lib, libSqliteRtree.so, may be
  loaded into sqlite in the same way as any other dynamicly loadable
  extension.


3. REFERENCES

  [1]  Atonin Guttman, "R-trees - A Dynamic Index Structure For Spatial 
       Searching", University of California Berkeley, 1984.

  [2]  Norbert Beckmann, Hans-Peter Kriegel, Ralf Schneider, Bernhard Seeger,
       "The R*-tree: An Efficient and Robust Access Method for Points and
       Rectangles", Universitaet Bremen, 1990.