Collections

Sometimes a plain-old key just doesn't cut it. Collisions become possible (multiple items with the same key). To get around this problem you'd normally have to use some kind of key-prefix scheme.

But many modern NoSQL databases have an extra level (besides just the key):

• MongoDb has collection / key / document
• Riak has bucket / key / value
• CouchDb has database / id / document
• Redis even has hashes

YapDatabase follows suite and provides an extra "level" besides just the key. This extra "level" is called the collection. Thus:

{collection="languages", key="java"} doesn't collide with {collection="beverages", key="java"}.

Another way to think about it is a "dictionary of dictionaries". So, from the example above, the "key" for the top-level dictionary is the collection. Thus "languages" yields a second-level dictionary. And from this second-level dictionary we apply the "java" key to get our final value.

Internally YapDatabase uses an extra column in the underlying sqlite database table to store the collection. As such, the queries can be optimized for the collection, key or both. And the API provides methods to deal with collections themselves. For example:

/**
 * Returns the total number of collections.
 * Each collection may have 1 or more key/object pairs.
**/
- (NSUInteger)numberOfCollections;

/**
 * Returns the total number of keys in the given collection.
 * Returns zero if the collection doesn't exist (or all key/object pairs from the collection have been removed).
**/
- (NSUInteger)numberOfKeysInCollection:(NSString *)collection;

/**
 * Object access.
 * Objects are automatically deserialized using database's configured deserializer.
**/
- (id)objectForKey:(NSString *)key inCollection:(NSString *)collection;

/**
 * Fast enumeration over all keys in the given collection.
 *
 * This uses a "SELECT key FROM database WHERE collection = ?" operation,
 * and then steps over the results invoking the given block handler.
**/
- (void)enumerateKeysInCollection:(NSString *)collection
                       usingBlock:(void (^)(NSString *key, BOOL *stop))block;

You can see the full API by looking at the YapDatabaseTransaction header file

When you have groups of related, but separate, data then collections become quite useful.

For example: You're storing top-level posts, and related comments. Each group of comments is related to a single post. So that group of comments could use the postId as its collection.

How many posts do I have?

NSUInteger postsCount = [transaction numberOfKeysInCollection:nil];

(Passing nil as the collection is the same as passing an empty string.)

How many comments are there for this post?

NSUInteger commentsForPostCount = [transaction numberOfKeysInCollection:post.uuid];

There are many possibilities for how one might use collections to help structure their data.