Extensions

The following article applies to version 2.0+

YapDatabase supports extensions. It ships with several useful extensions, and you can write your own as well. The following extensions are currently planned:

• Secondary Indexes
• Views
• Full Text Search
• R-Tree's

Extensions work rather seamlessly as they were designed to match the existing architecture of YapDatabase.

Overview

An extension implements a number of "hook" methods. YapDatabase automatically invokes these hooks in response to changes that are made to the database. Let's look at a concrete example:

[databaseConnection readWriteWithBlock:^(YapDatabaseReadWriteTransaction *transaction){

    [transaction setObject:myObject forKey:@"abc123"];
}];

The above code doesn't look any different from how you're used to interacting with the database. But internally, your change to the database is forwarded to any extension you may be using. Essentially, there is a hook method that corresponds to setObject:forKey: that extensions implement. They take part in the read-write transaction and have full access to the sqlite internals.

So an extension may create it's own sqlite table. Or perhaps multiple tables. Or perhaps it uses an existing sqlite module (which may in turn create its own virtual table). Or perhaps the extension resides fully in memory. It all depends on what the extension is trying to achieve.

Registration

Extensions are completely optional. You can use zero, or one, or multiple extensions. You can even use multiple instances of the same extension class. It's all up to you.

In order to use an extension, you must go through the registration process. Here's how it works.

1. Create an instance of your extension (configured however you like).

YapDatabaseView *salesView = [[YapDatabaseView alloc] initWith...];

2. Register the extension instance with the database. When you do this, you choose a name for the extension instance. This name can be whatever you want. (Recall that it's possible to register multiple instances of the same extension class.)

[database registerExtension:salesView withName:@"sales"];

3. Once registered, the extension can be accessed from within any transaction by simply using the registered name.

[databaseConnection readWithBlock:^(YapDatabaseReadTransaction *transaction){

    topUsaSale = [[transaction ext:@"sales"] objectAtIndex:0 inGroup:@"usa"];
}];

As you can imagine, each extension provides a number of new API's that allow you to interact with it. The YapDatabaseView extension (in the example above) provides a persistent "view" of the data. That is, imagine a SQL query which does something like:

SELECT ... FROM database WHERE (filtering criteria...) GROUP BY (grouping criteria...) ORDER BY (sorting criteria...)

You provide the filtering, grouping and sorting criteria to the view, and it handles the rest.

Internals