RTreeIndex

  • Welcome to YapDatabase! https://github.com/yapstudios/YapDatabase

    The project wiki has a wealth of documentation if you have any questions. https://github.com/yapstudios/YapDatabase/wiki

    YapDatabaseRTreeIndex is an extension which allows you to add an additional geometrical index for fast searching.

    That is, it allows you to create an index within sqlite for geometrical properties of your objects. You can then issue queries to find or enumerate objects. Examples:

    • enumerate all people in a bounding-box
    • enumerate all regions overlapping a bounding-box

    Note:

    The sqlite3 r-tree documentation https://www.sqlite.org/rtree.html states that

    By default, coordinates are stored in an RTree using 32-bit floating point values. When a coordinate cannot be exactly represented by a 32-bit floating point number, the lower-bound coordinates are rounded down and the upper-bound coordinates are rounded up. Thus, bounding boxes might be slightly larger than specified, but will never be any smaller. This is exactly what is desired for doing the more common overlapping queries where the application wants to find every entry in the RTree that overlaps a query bounding box. Rounding the entry bounding boxes outward might cause a few extra entries to appears in an overlapping query if the edge of the entry bounding box corresponds to an edge of the query bounding box. But the overlapping query will never miss a valid table entry.

    so coordinates in the r-tree might differ slightly from the ones you are giving the app, in particular if you are using Double values.

    For more information, see the wiki article about rtree indexes: https://github.com/yapstudios/YapDatabase/wiki/RTree-Indexes

    See more

    Declaration

    Objective-C

    @interface YapDatabaseRTreeIndex : YapDatabaseExtension

    Swift

    class YapDatabaseRTreeIndex : YapDatabaseExtension

  • Undocumented

    See more

    Declaration

    Objective-C

    @interface YapDatabaseRTreeIndexConnection : YapDatabaseExtensionConnection

/**
 * Returns the parent instance.
 */
@property (nonatomic, strong, readonly) YapDatabaseRTreeIndex *rTreeIndex;

/**
 * The queryCache speeds up the transaction methods. (enumerateXMatchingQuery:usingBlock:)
 *
 * In order for a query to be executed, it first has to be compiled by SQLite into an executable routine.
 * The queryCache stores these compiled reusable routines, so that repeated queries can be executed faster.
 *
 * Please note that, in terms of caching, only the queryString matters. The queryParameters do not.
 * That is, if you use the same queryString over and over, but with different parameters,
 * you will get a nice benefit from caching as it will be able to recyle the compiled routine,
 * and simply bind the different parameters each time.
 *
 * By default the queryCache is enabled and has a limit of 10.
 *
 * To disable the cache entirely, set queryCacheEnabled to NO.
 * To use an inifinite cache size, set the queryCacheLimit to ZERO.
 */
@property (atomic, assign, readwrite) BOOL queryCacheEnabled;
@property (atomic, assign, readwrite) NSUInteger queryCacheLimit;

@end

    Swift

    class YapDatabaseRTreeIndexConnection : YapDatabaseExtensionConnection

  • Undocumented

    See more

    Declaration

    Objective-C

    @interface YapDatabaseRTreeIndexTransaction : YapDatabaseExtensionTransaction

/**
 * These methods allow you to enumerates matches from the rtree index using a given query.
 *
 * The query that you input is an SQL style query (appropriate for SQLite semantics),
 * excluding the "SELECT ... FROM 'tableName'" component.
 *
 * For example:
 *
 * query = [YapDatabaseQuery queryWithFormat:@"WHERE minLon > 0 and maxLat <= 10"];
 * [[transaction ext:@"idx"] enumerateKeysMatchingQuery:query usingBlock:^(NSString *key, BOOL *stop) {
 *
 *     // ...
 * }];
 *
 * You can also pass parameters to the query using the standard SQLite placeholder:
 *
 * query = [YapDatabaseQuery queryWithFormat:@"WHERE minLon > ? AND maxLat <= ?", @(minLon), @(maxLat)];
 * [[transaction ext:@"idx"] enumerateKeysMatchingQuery:query usingBlock:^(NSString *key, BOOL *stop) {
 *
 *     // ...
 * }];
 *
 * For more information, and more examples, please see YapDatabaseQuery.
 *
 * @return NO if there was a problem with the given query. YES otherwise.
 *
 * @see YapDatabaseQuery
 */

- (BOOL)enumerateKeysMatchingQuery:(YapDatabaseQuery *)query
                        usingBlock:(void (NS_NOESCAPE^)(NSString *collection, NSString *key, BOOL *stop))block;

- (BOOL)enumerateKeysAndMetadataMatchingQuery:(YapDatabaseQuery *)query
                                   usingBlock:
                            (void (NS_NOESCAPE^)(NSString *collection, NSString *key, _Nullable id metadata, BOOL *stop))block;

- (BOOL)enumerateKeysAndObjectsMatchingQuery:(YapDatabaseQuery *)query
                                  usingBlock:
                            (void (NS_NOESCAPE^)(NSString *collection, NSString *key, id object, BOOL *stop))block;

- (BOOL)enumerateRowsMatchingQuery:(YapDatabaseQuery *)query
                        usingBlock:
                            (void (NS_NOESCAPE^)(NSString *collection, NSString *key, id object, _Nullable id metadata, BOOL *stop))block;
/**
 * Skips the enumeration process, and just gives you the count of matching rows.
 */
- (BOOL)getNumberOfRows:(NSUInteger *)count matchingQuery:(YapDatabaseQuery *)query;

/**
 * This method assists in performing a query over a subset of rows,
 * where the subset is a known set of keys.
 *
 * For example:
 *
 * Say you have a known set of items, and you want to figure out which of these items fit in the rectangle.
 *
 * NSArray *keys = [self itemKeys];
 * NSArray *rowids = [[[transaction ext:@"idx"] rowidsForKeys:keys inCollection:@"tracks"] allValues];
 *
 * YapDatabaseQuery *query =
 *   [YapDatabaseQuery queryWithFormat:@"WHERE minLon > 0 AND maxLat <= 10 AND rowid IN (?)", rowids];
  */
- (NSDictionary<NSString*, NSNumber*> *)rowidsForKeys:(NSArray<NSString *> *)keys
										 inCollection:(nullable NSString *)collection;

@end

    Swift

    class YapDatabaseRTreeIndexTransaction : YapDatabaseExtensionTransaction

  • The handler block handles extracting the column values for the rtree index.

    When you add or update rows in the databse the block is invoked. Your block can inspect the row and determine if it contains any values that should be added to the rtree index. If not, the block can simply return. Otherwise the block should add a min and max value (can be equal) for each indexed dimension to the given dictionary.

    After the block returns, the dictionary parameter will be inspected, and any set values will be automatically inserted/updated within the sqlite index.

    You should choose a block type that takes the minimum number of required parameters. The extension can make various optimizations based on required parameters of the block. For example, if metadata isn’t required, then the extension can ignore metadata-only updates.

    See more

    Declaration

    Objective-C

    @interface YapDatabaseRTreeIndexHandler : NSObject

    Swift

    class YapDatabaseRTreeIndexHandler : NSObject

  • Undocumented

    See more

    Declaration

    Objective-C

    @interface YapDatabaseRTreeIndexSetup : NSObject <NSCopying, NSFastEnumeration>

- (id)init;
- (id)initWithCapacity:(NSUInteger)capacity;

- (void)setColumns:(NSArray *)columnNames;

- (NSUInteger)count;
- (NSArray *)columnNames;

@end

    Swift

    class YapDatabaseRTreeIndexSetup : NSObject, NSCopying, NSFastEnumeration