＼(・ω・＼)SAN値！(／・ω・)／ピンチ！

加油！尼亚子みんなW
2013年4月7日（周日）深夜1:05起在电视台东京等地首播！

MIT 许可证

NyaruDB 是 Objective-C 中的简单 NoSQL 数据库。它可以在 iOS 和 OS X 上运行。
它是一个键值对的 NoSQL 数据库。您可以通过文档的字段搜索数据。

功能

比 sqlite 更快。

NyaruDB 使用内存缓存、GCD 和二叉树来优化性能。

NoSQL with SQL:  
NyaruDB: NSDictionary <-- NyaruDB --> File  
sqlite: NSDictionary <-- converter --> SQL <-- sqlite3 function --> File  

	NyaruDB	sqlite
插入 1k 个文档	11,000 毫秒 500 毫秒（异步）	36,500 毫秒
检索 1k 个文档	300 毫秒 50 毫秒（在缓存中）	300 毫秒
在 1k 个文档中进行搜索 10 次	12 毫秒	40 毫秒

（此测试是在 iPhone4 上进行的）

NyaruDB 使用 GCD 来读写文档，所有访问都会在相同的调度器中处理。
写入：使用异步 GCD 处理
读取：使用同步 GCD 处理
将文档写入数据库将在异步调度器中处理。因此，您的代码不会等待写入文档。CPU 将处理下一个命令。
如果下一个命令是读取数据库中的文档，则该命令将在写入完成后进行处理。

干净的查询语法。

// where type == 1 order by update
NSArray *documents = [[[collection where:@"type" equal:@1] orderBy:@"update"] fetch];

---

安装

git

$ git clone git://github.com/kelp404/NyaruDB.git

CocoadPods

在项目路径中添加 Podfile

platform :ios
pod 'NyaruDB'

$ pod install

---

管理工具

NyaruDB Control

---

集合

集合类似 SQL 数据库的表。

创建索引

当您想根据字段搜索数据时，您应该创建一个索引。
如果您想根据 'email' 搜索数据，您应该先创建 'email' 索引。

文档

文档是集合中的数据。

文档中有一个名为 key 的成员。Key 是唯一的，数据类型是 NSString。如果文档在插入时没有 key，它将被自动生成。

• 常规字段数据类型： NSNull、NSNumber、NSDate、NSString、NSArray、NSDictionary
  (NSArray 仅允许 NSString、NSNumber、NSDate 和 NSNull)
  
• 索引字段数据类型： NSNull、NSNumber、NSDate、NSString
  

---

访问数据库

实例

iOS

[NyaruDB instance] 返回一个静态 NyaruDB 实例，数据库路径为 /your-app/Documents/NyaruDB。

NyaruDB *db = [NyaruDB instance];

OS X

[[NyaruDB alloc] initWithPath:@"/tmp/NyaruDB"].
NyaruDB 在 [NyaruDB init] 时会扫描集合中所有文档，因此请勿多次调用 init。
在 OS X 中，您应自行处理静态实例。

NyaruDB *db = [[NyaruDB alloc] initWithPath:@"/tmp/NyaruDB"];

创建集合

NyaruCollection *collectioin = [db collection:@"collectionName"];

创建索引

NyaruCollection *collection = [db collection:@"collectionName"];
[collection createIndex:@"email"];
[collection createIndex:@"number"];
[collection createIndex:@"date"];

插入文档

如果存在具有相同 'key' 的文档，它将被新文档替换。（更新文档）

NyaruCollection *collection = [db collection:@"collectionName"];
NSDictionary *document = @{@"email": @"[email protected]",
    @"name": @"Kelp",
    @"phone": @"0123456789",
    @"date": [NSDate date],
    @"text": @"(」・ω・)」うー！(／・ω・)／にゃー！",
    @"number": @100};
[collection put:document];

查询

支持搜索文档中的 key 或 index 字段。
key 支持相等（equal）。
index 支持相等（equal）、不等（notEqual）、小于（less）、小于等于（lessEqual）、大于（greater）、大于等于（greaterEqual）和类似（like）。

可以使用 and（交集）或 or 来附加查询。

// search the document the 'key' is equal to 'IjkhMGIT752091136'
NyaruCollection *co = [db collection:@"collectionName"];
NSArray *documents = [[co where:@"key" equal:@"IjkhMGIT752091136"] fetch];
for (NSMutableDictionary *document in documents) {
    NSLog(@"%@", document);
}

// search documents the 'date' is greater than now, and sort by date with DESC
NyaruCollection *co = [db collection:@"collectionName"];
NSDate *date = [NSDate date];
NSArray *documents = [[[co where:@"date" greater:date] orderByDESC:@"date"] fetch];
for (NSMutableDictionary *document in documents) {
    NSLog(@"%@", document);
}

// search documents the 'date' is greater than now, and 'type' is equal to 2
// then sort by date with ASC
NyaruCollection *co = [db collection:@"collectionName"];
NSDate *date = [NSDate date];
NSArray *documents = [[[[co where:@"date" greater:date] and:@"type" equal:@2] orderBy:@"date"] fetch];
for (NSMutableDictionary *document in documents) {
    NSLog(@"%@", document);
}

// search documents 'type' == 1 or 'type' == 3
NyaruCollection *co = [db collection:@"collectionName"];
NSArray *documents = [[[co where:@"type" equal:@1] or:@"type" equal:@3] fetch];
for (NSMutableDictionary *document in documents) {
    NSLog(@"%@", document);
}

// count documents 'type' == 1
NyaruCollection *co = [db collection:@"collectionName"];
NSUInteger count = [[co where:@"type" equal:@1] count];
NSLog(@"%u", count);

删除文档

NyaruCollection *co = [db collection:@"collectionName"];
[co createIndex:@"number"];
[co put:@{@"number": @100}];
[co put:@{@"number": @200}];
[co put:@{@"number": @10}];
// remove by query
[[co where:@"number" equal:@10] remove];
// remove all
[[co all] remove];

同步 & 异步

put 和 remove 将以异步方式运行。
fetch 和 count 将以同步方式运行。但所有命令都将在一个相同的调度器上处理。

自 1.4.1 以来，NyaruDB 具有关于异步获取和计数的新的消息。
[NyaruQuery fetchAsync:(void (^)(NSArray *))handler]
[NyaruQuery countAsync:(void (^)(NSUInteger))handler]

如果您想以同步方式插入文档，可以使用 [NyaruCollection waitForWriting]。

NyaruDB *db = [NyaruDB instance];
NyaruCollection *collection = [db collection:@"collection"];
NSDictionary *document = @{@"email": @"[email protected]",
    @"name": @"Kelp",
    @"phone": @"0123456789",
    @"date": [NSDate date],
    @"text": @"(」・ω・)」",
    @"number": @100};
[collection put:document];
[collection waitForWriting];  // sync

// be Careful
NyaruDB *db = [NyaruDB instance];
NyaruCollection *collection = [db collection:@"collection"];
NSDictionary *document = @{@"email": @"[email protected]",
    @"name": @"Kelp",
    @"phone": @"0123456789",
    @"date": [NSDate date],
    @"text": @"(」・ω・)」",
    @"number": @100};
for (NSUInteger index = 0; index < 1000; index++) {
    // put 1k documents
    [collection put:document];
}
// cpu will wait for documents write done.
// if this is main dispatch, it will be locked.
NSUInteger count = collection.count;
// you could try this
[collection countAsync:^(NSUInteger count) {
    // this block run in main dispatch
}];

---

类

NyaruDB 接口

#pragma mark - Instance
/**
 Get the shared instance for iOS.
 @return NyaruDB shared instance
 */
+ (id)instance;
/**
 Remove all database for iOS.
 if you init database error, maybe need to call this message.
 */
+ (void)reset;
/**
 Init NyaruDB for OS X.
 @param path Database files are in this path.
 @return NyaruDB instance
 */
- (id)initWithPath:(NSString *)path;
/**
 Close all file handles and collections for OS X.
 Before release instance you should invoke this method.
 */
- (void)close;
#pragma mark - Collection
- (NSArray *)collections;
- (NyaruCollection *)collection:(NSString *)name;
#pragma mark Remove
- (void)removeCollection:(NSString *)name;
- (void)removeAllCollections;

NyaruCollection 接口

#pragma mark - Index
- (NSArray *)allIndexes;
- (void)createIndex:(NSString *)indexName;
- (void)removeIndex:(NSString *)indexName;
- (void)removeAllindexes;
#pragma mark - Document
// put document
- (NSMutableDictionary *)put:(NSDictionary *)document;
// remove all documents (directly remove files)
- (void)removeAll;
// waiting for data writing
- (void)waitForWriting;
// clear cache
- (void)clearCache;
#pragma mark - Query
- (NyaruQuery *)all;
- (NyaruQuery *)where:(NSString *)indexName equal:(id)value;
- (NyaruQuery *)where:(NSString *)indexName notEqual:(id)value;
- (NyaruQuery *)where:(NSString *)indexName less:(id)value;
- (NyaruQuery *)where:(NSString *)indexName lessEqual:(id)value;
- (NyaruQuery *)where:(NSString *)indexName greater:(id)value;
- (NyaruQuery *)where:(NSString *)indexName greaterEqual:(id)value;
- (NyaruQuery *)where:(NSString *)indexName like:(NSString *)value;
#pragma mark - Count
- (NSUInteger)count;
- (void)countAsync:(void (^)(NSUInteger))handler;

NyaruQuery 接口

#pragma mark - Intersection
- (NyaruQuery *)and:(NSString *)indexName equal:(id)value;
- (NyaruQuery *)and:(NSString *)indexName notEqual:(id)value;
- (NyaruQuery *)and:(NSString *)indexName less:(id)value;
- (NyaruQuery *)and:(NSString *)indexName lessEqual:(id)value;
- (NyaruQuery *)and:(NSString *)indexName greater:(id)value;
- (NyaruQuery *)and:(NSString *)indexName greaterEqual:(id)value;
- (NyaruQuery *)and:(NSString *)indexName like:(NSString *)value;
#pragma mark - Union
- (NyaruQuery *)or:(NSString *)indexName equal:(id)value;
- (NyaruQuery *)or:(NSString *)indexName notEqual:(id)value;
- (NyaruQuery *)or:(NSString *)indexName less:(id)value;
- (NyaruQuery *)or:(NSString *)indexName lessEqual:(id)value;
- (NyaruQuery *)or:(NSString *)indexName greater:(id)value;
- (NyaruQuery *)or:(NSString *)indexName greaterEqual:(id)value;
- (NyaruQuery *)or:(NSString *)indexName like:(NSString *)value;
#pragma mark - Order By
- (NyaruQuery *)orderBy:(NSString *)indexName;
- (NyaruQuery *)orderByDESC:(NSString *)indexName;
#pragma mark - Count
- (NSUInteger)count;
- (void)countAsync:(void (^)(NSUInteger))handler;
#pragma mark - Fetch
- (NSArray *)fetch;
- (NSArray *)fetch:(NSUInteger)limit;
- (NSArray *)fetch:(NSUInteger)limit skip:(NSUInteger)skip;
- (NSMutableDictionary *)fetchFirst;
- (void)fetchAsync:(void (^)(NSArray *))handler;
- (void)fetch:(NSUInteger)limit async:(void (^)(NSArray *))handler;
- (void)fetch:(NSUInteger)limit skip:(NSUInteger)skip async:(void (^)(NSArray *))handler;
- (void)fetchFirstAsync:(void (^)(NSMutableDictionary *))handler;
#pragma mark - Remove
- (void)remove;

---

注意

• 字段名的最大长度为 255。
• 文档数量限制为 4,294,967,295。
• 文档文件大小限制为 4G。
• key 是唯一的，并且是 NSString。
• key 只提供相等（equal）搜索。
• key 区分大小写。
• 索引不区分大小写。
• 文档的字段数据类型应该与索引相同。
• 排序查询只允许一个

历史

• 1.3
  文件头 -> nyaruko
  用NyaruCollection.serialize()替换JSONKit

• 1.2
  文件头 -> (」・ω・)」うー！(／・ω・)／にゃー！1\n
  优化性能
  新的查询语法

• 1.1
  文件头 -> (」・ω・)」うー！(／・ω・)／にゃー！ \n