sqlite/ext/rtree
drh 5f0dfc00de Thoroughly reset the rtree cursor at the start of each VFilter operation,
including clearing its cache.  This prevents left over pages in the cache
which can cause problems on shutdown after a LEFT JOIN.
Ticket [5eadca17c4dde90c]

FossilOrigin-Name: 4c50afafce8416369f89477ba7fe7d9b047399a5ee5754c73d0e67bbea8d877c
2019-12-23 20:41:39 +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 Thoroughly reset the rtree cursor at the start of each VFilter operation, 2019-12-23 20:41:39 +00:00
README Fix another typo in the rtree README file. (CVS 5187) 2008-06-04 15:09:16 +00:00
rtree1.test Early detection and reporting of too few columns in an rtree CREATE VIRTUAL 2019-12-06 19:07:44 +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 Do not allow auxiliary columns in the rtree to interfere with query planning. 2018-05-16 19:07:07 +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 Fix a problem triggered by DELETE statements with WHERE clauses that use the 2019-01-15 14:31:01 +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 Add the SQLITE_DEFAULT_DEFENSIVE compile-time option. Fix up test cases 2018-11-07 02:17:01 +00:00
rtree9.test Add SQL scalar function rtreecheck() to the rtree module. For running checks 2017-10-25 16:38:34 +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 SQL scalar function rtreecheck() to the rtree module. For running checks 2017-10-25 16:38:34 +00:00
rtree.c Thoroughly reset the rtree cursor at the start of each VFilter operation, 2019-12-23 20:41:39 +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 Enable DEFENSIVE mode by default for tests. This requires lots of case of 2018-11-06 19:26:04 +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 Make sure the rowid of an RTREE virtual table has integer affinity. 2019-12-05 14:42:26 +00:00
rtreecheck.test Enable DEFENSIVE mode by default for tests. This requires lots of case of 2018-11-06 19:26:04 +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
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 Update some corruption test cases to take [724f4df9c] into account. 2019-08-13 17:27:43 +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
sqlite3rtree.h Fix a typo in a comment. No changes to code. 2018-11-30 20:59:00 +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.