发布于 2014-10-14 09:53:47 | 2935 次阅读 | 评论: 0 | 来源: 网友投递
SSDB NoSQL 数据库
SSDB是一个开源的高性能数据库服务器, 使用Google LevelDB作为存储引擎, 支持T级别的数据, 同时支持类似Redis中的zset和hash等数据结构, 在同时需求高性能和大数据的条件下, 作为Redis的替代方案.
SSDB 是一个高性能 NoSQL 数据库, 支持 zset 数据结构, 用于替代 Redis. 官方网站是 http://ssdb.io. 本文档介绍了 SSDB 的 PHP 客户端 API.
注意: SSDB 所使用的名词 "hashmap" 是指 "hash", "map".
<?php
include_once('SSDB.php');
try{
$ssdb = new SimpleSSDB('127.0.0.1', 8888);
}catch(SSDBException $e){
die(__LINE__ . ' ' . $e->getMessage());
}
$ret = $ssdb->set('key', 'value');
if($ret === false){
// error!
}
echo $ssdb->get('key');
如果无法连接到 SSDB 服务器, SimpleSSDB 将抛出异常. 大多数的方法(除了少数几个例外)通过返回 false 来标明出错. 所以要使用强制等于(===)来判断返回值.
如果出现网络错误, 所有的方法将会抛出 SSDBException 异常.
注意: 因为实现的原因, 请保证所有的参数加起来不超过 10MB 大小.
创建 SimpleSSDB 的实例, 并连接到 SSDB 服务器. 如果无法连接到服务器, 将抛出异常.
host - SSDB 服务器的主机名或者 IP.port - SSDB 服务器的端口号.timeout_ms - 可选, 连接超时时间, 和发送接收数据的超时时间, 单位毫秒. 默认是 2000 ms.SimpleSSDB 的实例.
$ssdb = new SimpleSSDB('127.0.0.1', 8888);
Since: 1.7.0.0
配置密码, 之后将用于向服务器校验. 这个校验不是立即进行的, 而是等你执行第一条命令的时候才发给服务器. 注意, 密码是明文传输的!
password -出错则返回 false, 否则返回 null.
$ssdb->auth('very-strong-password');
设置指定 key 的值内容.
key -value -出错则返回 false, 其它值表示正常.
$ssdb->set('key', 'value');
设置指定 key 的值内容, 同时设置存活时间.
key -value -ttl - 存活时间(秒)出错则返回 false, 其它值表示正常.
$ssdb->setx('key', 'value', 60);
设置 key(只针对 KV 类型) 的存活时间.
key -ttl - 存活时间(秒)出错则返回 false. 如果 key 存在并设置成功, 返回 1, 如果 key 不存在, 返回 0.
$ssdb->expire('key', 60);
返回 key(只针对 KV 类型) 的存活时间.
key -出错则返回 false, 否则返回 key 的存活时间(秒), -1 表示没有设置存活时间.
$ssdb->ttl('key');
当 key 不存在时, 设置指定 key 的值内容. 如果已存在, 则不设置.
key -value -出错则返回 false, 1: value 已经设置, 0: key 已经存在, 不更新.
$ssdb->setnx('key', 'value');
获取指定 key 的值内容.
key -如果 key 不存在则返回 null, 如果出错则返回 false, 否则返回 key 对应的值内容.
$ssdb->get('key');
更新 key 对应的 value, 并返回更新前的旧的 value.
key -value -如果 key 不存在则返回 null, 如果出错则返回 false, 否则返回 key 对应的值内容.
$ssdb->getset('key', 'value');
删除指定的 key.
key -如果出错则返回 false, 其它值表示正常. 你无法通过返回值来判断被删除的 key 是否存在.
$ssdb->del('key');
使 key 对应的值增加 num. 参数 num 可以为负数. 如果原来的值不是整数(字符串形式的整数), 它会被先转换成整数.
key -num - 必须是有符号整数.如果出错则返回 false, 否则返回新的值.
$ssdb->incr('key', 1);
判断指定的 key 是否存在.
key -如果存在, 返回 true, 否则返回 false.
$ssdb->exists('key');
获取字符串内指定位置的位值(BIT).
key -offset - 位偏移返回位值(0 或 1), 如果 key 不存在或者偏移超过活字符串长度范围, 返回 0.
$ssdb->getbit('key', 9);
设置字符串内指定位置的位值(BIT), 字符串的长度会自动扩展.
key -offset - 位偏移val - 0 或 1返回原来的位值. 如果 val 不是 0 或者 1, 返回 false.
$ssdb->setbit('key', 9, 1);
计算字符串的子串所包含的位值为 1 的个数. 若 start 是负数, 则从字符串末尾算起. 若 size 是负数, 则表示从字符串末尾算起, 忽略掉那么多字节.
key -start - 可选, 子串的字节偏移size - 可选, 子串的长度(字节数), 默认为到字符串最后一个字节返回位值为 1 的个数. 出错返回 false.
$ssdb->countbit('key', 2, 10);
获取字符串的子串. 若 start 是负数, 则从字符串末尾算起. 若 size 是负数, 则表示从字符串末尾算起, 忽略掉那么多字节.
key -start - 可选, int, 子串的字节偏移size - 可选, int, 子串的长度(字节数), 默认为到字符串最后一个字节字符串的子串.
$ssdb->substr('key', 2, 10);
计算字符串的长度(字节数).
key -返回字符串的长度, key 不存在则返回 0.
$ssdb->strlen('key');
列出处于区间 (key_start, key_end] 的 key 列表.
("", ""] 表示整个区间.
key_start - 返回的起始 key(不包含), 空字符串表示 -inf.key_end - 返回的结束 key(包含), 空字符串表示 +inf.limit - 最多返回这么多个元素.如果出错则返回 false, 否则返回包含 key 的数组.
$ssdb->keys('a', 'z', 10);
列出处于区间 (key_start, key_end] 的 key-value 列表.
("", ""] 表示整个区间.
key_start - 返回的起始 key(不包含), 空字符串表示 -inf.key_end - 返回的结束 key(包含), 空字符串表示 +inf.limit - 最多返回这么多个元素.如果出错则返回 false, 否则返回包含 key-value 的数关联组.
$ssdb->scan('a', 'z', 10);
遍历 key-value 对列表
$start = '';
$limit = 1000;
while(1){
$kvs = $ssdb->scan($start, '', $limit);
if(!$kvs){
break;
}
// do something on key-value pairs...
$keys = array_keys(array_slice($kvs, -1, 1, true));
$max_key = $keys[0];
$start = $max_key;
}
列出处于区间 (key_start, key_end] 的 key-value 列表, 反向顺序.
("", ""] 表示整个区间.
key_start - 返回的起始 key(不包含), 空字符串表示 +inf.key_end - 返回的结束 key(包含), 空字符串表示 -inf.limit - 最多返回这么多个元素.如果出错则返回 false, 否则返回包含 key-value 的数关联组.
$ssdb->rscan('a', 'z', 10);
批量设置一批 key-value.
kvs - 包含 key-value 的关联数组 .出错则返回 false, 其它值表示正常.
$ssdb->multi_set(array( 'a' => 1, 'b' => 2, ));
批量获取一批 key 对应的值内容.
keys - 包含 key 的数组 .如果出错则返回 false, 否则返回包含 key-value 的关联数组, 如果某个 key 不存在, 则它不会出现在返回数组中.
$ssdb->multi_get(array('k1', 'k2'));
批量删除一批 key 和其对应的值内容.
keys - 包含 key 的数组 .出错则返回 false, 其它值表示正常.
$ssdb->multi_del(array('k1', 'k2'));
设置 hashmap 中指定 key 对应的值内容.
name - hashmap 的名字.key - hashmap 中的 key.value - key 对应的值内容.出错则返回 false, 其它值表示正常.
$ssdb->hset('h', 'key', 'value');
获取 hashmap 中指定 key 的值内容.
name - hashmap 的名字.key - hashmap 中的 key.如果 key 不存在则返回 null, 如果出错则返回 false, 否则返回 key 对应的值内容.
$ssdb->hget('h', 'key');
获取 hashmap 中的指定 key.
name - hashmap 的名字.key - hashmap 中的 key.如果出错则返回 false, 其它值表示正常. 你无法通过返回值来判断被删除的 key 是否存在.
$ssdb->hdel('h', 'key');
使 hashmap 中的 key 对应的值增加 num. 参数 num 可以为负数. 如果原来的值不是整数(字符串形式的整数), 它会被先转换成整数.
name - hashmap 的名字.key -num - 必须是有符号整数.如果出错则返回 false, 否则返回新的值.
$ssdb->hincr('h', 'key', 1);
判断指定的 key 是否存在于 hashmap 中.
name - hashmap 的名字.key -如果存在, 返回 true, 否则返回 false.
$ssdb->hexists('h', 'key');
返回 hashmap 中的元素个数.
name - hashmap 的名字.出错则返回 false, 否则返回元素的个数, 0 表示不存在 hashmap(空).
$ssdb->hsize('h');
列出名字处于区间 (name_start, name_end] 的 hashmap.
("", ""] 表示整个区间.
name_start - 返回的起始名字(不包含), 空字符串表示 -inf.name_end - 返回的结束名字(包含), 空字符串表示 +inf.limit - 最多返回这么多个元素.出错则返回 false, 返回返回包含名字的数组.
$ssdb->hlist('a', 'z', 10);
列出 hashmap 中处于区间 (key_start, key_end] 的 key 列表.
("", ""] 表示整个区间.
name - hashmap 的名字.key_start - 起始 key(不包含), 空字符串表示 -inf.key_end - 结束 key(包含), 空字符串表示 +inf.limit - 最多返回这么多个元素.如果出错则返回 false, 否则返回包含 key 的数组.
$ssdb->hkeys('h', 'a', 'z', 10);
返回整个 hashmap.
name - hashmap 的名字.如果出错则返回 false, 否则返回包含 key-value 的关联数组.
$ssdb->hgetall('h');
列出 hashmap 中处于区间 (key_start, key_end] 的 key-value 列表.
("", ""] 表示整个区间.
name - hashmap 的名字.key_start - 返回的起始 key(不包含), 空字符串表示 -inf.key_end - 返回的结束 key(包含), 空字符串表示 +inf.limit - 最多返回这么多个元素.如果出错则返回 false, 否则返回包含 key-value 的关联数组.
$ssdb->hscan('h', 'a', 'z', 10);
列出 hashmap 中处于区间 (key_start, key_end] 的 key-value 列表, 反向顺序.
("", ""] 表示整个区间.
name - hashmap 的名字.key_start - 返回的起始 key(不包含), 空字符串表示 +inf.key_end - 返回的结束 key(包含), 空字符串表示 -inf.limit - 最多返回这么多个元素.如果出错则返回 false, 否则返回包含 key-score 的关联数组.
$ssdb->hrscan('h', 'a', 'z', 10);
删除 hashmap 中的所有 key.
name - hashmap 的名字.如果出错则返回 false, 否则返回删除的 key 的数量.
$ssdb->hclear('h');
批量设置 hashmap 中的 key-value.
name - hashmap 的名字.kvs - 包含 key-value 的关联数组 .出错则返回 false, 其它值表示正常.
$ssdb->multi_zset('z', array(
'a' => 1,
'b' => 2,
));
批量获取 hashmap 中多个 key 对应的权重值.
name - hashmap 的名字.keys - 包含 key 的数组 .如果出错则返回 false, 否则返回包含 key-value 的关联数组, 如果某个 key 不存在, 则它不会出现在返回数组中.
$ssdb->multi_hget('h', array('k1', 'k2'));
指删除 hashmap 中的 key.
name - hashmap 的名字.keys - 包含 key 的数组 .出错则返回 false, 其它值表示正常.
$ssdb->multi_hdel('h', array('k1', 'k2'));
设置 zset 中指定 key 对应的权重值.
name - zset 的名字.key - zset 中的 key.score - 整数, key 对应的权重值出错则返回 false, 其它值表示正常.
$ssdb->zset('z', 'key', 100);
获取 zset 中指定 key 的权重值.
name - zset 的名字.key - zset 中的 key.如果 key 不存在则返回 null, 如果出错则返回 false, 否则返回 key 对应的权重值.
$ssdb->zget('z', 'key');
获取 zset 中的指定 key.
name - zset 的名字.key - zset 中的 key.如果出错则返回 false, 其它值表示正常. 你无法通过返回值来判断被删除的 key 是否存在.
$ssdb->zdel('hz, 'key');
使 zset 中的 key 对应的值增加 num. 参数 num 可以为负数. 如果原来的值不是整数(字符串形式的整数), 它会被先转换成整数.
name - zset 的名字.key -num - 必须是有符号整数.如果出错则返回 false, 否则返回新的值.
$ssdb->zincr('z', 'key', 1);
判断指定的 key 是否存在于 zset 中.
name - zset 的名字.key -如果存在, 返回 true, 否则返回 false.
$ssdb->zexists('z', 'key');
返回 zset 中的元素个数.
name - zset 的名字.出错则返回 false, 否则返回元素的个数, 0 表示不存在 zset(空).
$ssdb->zsize('z');
列出名字处于区间 (name_start, name_end] 的 zset.
("", ""] 表示整个区间.
name_start - 返回的起始名字(不包含), 空字符串表示 -inf.name_end - 返回的结束名字(包含), 空字符串表示 +inf.limit - 最多返回这么多个元素.出错则返回 false, 否则返回包含名字的数组.
$ssdb->zlist('a', 'z', 10);
列出 zset 中的 key 列表. 参见 zscan().
name - zset 的名字.key_start - 参见 zscan().score_start - 参见 zscan().score_end - 参见 zscan().limit - 最多返回这么多个元素.如果出错则返回 false, 否则返回包含 key 的数组.
$ssdb->zkeys('z', '', 1, 100, 10);
列出 zset 中处于区间 (key_start+score_start, score_end] 的 key-score 列表. 如果 key_start 为空, 那么对应权重值大于或者等于 score_start 的 key 将被返回. 如果 key_start 不为空, 那么对应权重值大于 score_start 的 key, 和大于 key_start 且对应权重值等于 score_start 的 key 将被返回.
也就是说, 返回的 key 在 (key.score == score_start && key > key_start || key.score > score_start), 并且 key.score <= score_end 区间.
("", ""] 表示整个区间.
name - zset 的名字.key_start - score_start 对应的 key.score_start - 返回 key 的最小权重值(可能不包含, 依赖 key_start), 空字符串表示 -inf.score_end - 返回 key 的最大权重值(包含), 空字符串表示 +inf.limit - 最多返回这么多个元素.如果出错则返回 false, 否则返回包含 key-score 的关联数组.
$ssdb->zscan('z', '', 1, 100, 10);
遍历 zset:
$key_start = '';
$score_start = '';
while(1){
$items = $ssdb->zscan($zname, $key_start, $score_start, '', 10);
if(!$items){
break;
}
foreach($items as $key=>$score){
// process($key, $score)...
// 记住最大的元素和它的权重
$key_start = $key;
$score_start = $score;
}
}
列出 zset 中的 key-score 列表, 反向顺序. 参见 zkeys().
name - zset 的名字.key_start - 参见 zkeys().score_start - 参见 zkeys().score_end - 参见 zkeys().limit - 最多返回这么多个元素.如果出错则返回 false, 否则返回包含 key-score 的关联数组.
$ssdb->zrscan('a', 'z', 10);
注意! 本方法可能会非常慢! 请在离线环境中使用.
返回指定 key 在 zset 中的排序位置(排名), 排名从 0 开始. zrrank 获取是是倒序排名.
name - zset 的名字.key -found.
出错则返回 false, -1 表示 key 不存在于 zset, 否则返回排名.
$ssdb->zrank('z', 'k1');
注意! 本方法在 offset 越来越大时, 会越慢!
根据下标索引区间 [offset, offset + limit) 获取 key-score 对, 下标从 0 开始. zrrange 是反向顺序获取.
name - zset 的名字.offset - 正整数, 从此下标处开始返回. 从 0 开始.limit - 正整数, 最多返回这么多个 key-score 对.如果出错则返回 false, 否则返回包含 key-score 的关联数组.
$ssdb->zrange('z', 0, 10);
删除 zset 中的所有 key.
name - zset 的名字.如果出错则返回 false, 否则返回删除的 key 的数量.
$ssdb->zclear('z');
返回处于区间 [start,end] key 数量.
name - zset 的名字.score_start - key 的最小权重值(包含), 空字符串表示 -inf.score_end - key 的最大权重值(包含), 空字符串表示 +inf.如果出错则返回 false, 否则返回符合条件的 key 的数量.
$ssdb->zcount('z', 0, 100);
返回 key 处于区间 [start,end] 的 score 的和.
name - zset 的名字.score_start - key 的最小权重值(包含), 空字符串表示 -inf.score_end - key 的最大权重值(包含), 空字符串表示 +inf.如果出错则返回 false, 否则返回符合条件的 score 的求和.
$ssdb->zsum('z', 0, 100);
返回 key 处于区间 [start,end] 的 score 的平均值.
name - zset 的名字.score_start - key 的最小权重值(包含), 空字符串表示 -inf.score_end - key 的最大权重值(包含), 空字符串表示 +inf.如果出错则返回 false, 否则返回符合条件的 score 的平均值.
$ssdb->zavg('z', 0, 100);
删除位置处于区间 [start,end] 的元素.
name - zset 的名字.start - (包含).end -(包含).出错则返回 false, 否则返回被删除的元素个数.
$ssdb->zremrangebyrank('z', 1, 2);
删除权重处于区间 [start,end] 的元素.
name - zset 的名字.start - (包含).end -(包含).出错则返回 false, 否则返回被删除的元素个数.
$ssdb->zremrangebyscore('z', 1, 2);
批量设置 zset 中的 key-score.
name - zset 的名字.kvs - 包含 key-score 的关联数组 .出错则返回 false, 其它值表示正常.
$ssdb->multi_zset('z', array(
'a' => 1,
'b' => 2,
));
批量获取 zset 中多个 key 对应的权重值.
name - zset 的名字.keys - 包含 key 的数组 .如果出错则返回 false, 否则返回包含 key-score 的关联数组, 如果某个 key 不存在, 则它不会出现在返回数组中.
$ssdb->multi_zget('z', array('k1', 'k2'));
指删除 zset 中的 key.
name - zset 的名字.keys - 包含 key 的数组 .出错则返回 false, 其它值表示正常.
$ssdb->multi_zdel('z', array('k1', 'k2'));
返回队列的长度.
name -出错返回 false, 否则返回一个整数, 0 表示队列不存在(或者为空).
$ssdb->qsize('q');
列出名字处于区间 (name_start, name_end] 的 queue/list.
("", ""] 表示整个区间.
name_start - 返回的起始名字(不包含), 空字符串表示 -inf.name_end - 返回的结束名字(包含), 空字符串表示 +inf.limit - 最多返回这么多个元素.出错则返回 false, 返回返回包含名字的数组.
$ssdb->qlist('a', 'z', 10);
清空一个队列.
name -出错返回 false.
$ssdb->qclear('q');
返回队列的第一个元素.
name -出错返回 false, 队列不存在(或者为空)则返回 null, 否则返回一个元素.
$ssdb->qfront('q');
返回队列的最后一个元素.
name -出错返回 false, 队列不存在(或者为空)则返回 null, 否则返回一个元素.
$ssdb->qback('q');
返回指定位置的元素. 0 表示第一个元素, 1 是第二个 ... -1 是最后一个.
name -index -出错返回 false, 如果指定位置不存在一个元素, 则返回 null, 否则返回一个元素.
$ssdb->qget('q', -2);
返回下标处于区域 [offset, offset + limit] 的元素.
name - queue 的名字.offset - 整数, 从此下标处开始返回. 从 0 开始. 可以是负数, 表示从末尾算起.limit - 正整数, 最多返回这么多个元素.如果出错则返回 false, 否则返回数组.
$ssdb->qrange('q', 0, 10);
返回下标处于区域 [begin, end] 的元素. begin 和 end 可以是负数
name -begin -end -出错返回 false, 否则返回包含元素的数组.
$ssdb->qslice('q', 0, -1);
本函数是 qpush_back() 的别名.
往队列的首部添加一个或者多个元素
name -item - 字符串或是字符串数组.添加元素之后, 队列的长度, 出错返回 false.
$ssdb->qpush_front('q', 'a');
往队列的尾部添加一个或者多个元素
name -item - 字符串或是字符串数组.添加元素之后, 队列的长度, 出错返回 false.
$ssdb->qpush_back('q', 'a');
本函数是 qpop_front() 的别名.
从队列首部弹出最后一个或者多个元素.
name -size - 可选, 最多从队列弹出这么多个元素出错返回 false. 当 size 未指定或者小于等于 1 时, 队列不存在(或者为空)则返回 null, 否则删除并返回一个元素. 当 size 大于等于 2 时, 返回一个数组包含弹出的元素.
$ssdb->qpop_front('q');
从队列尾部弹出最后一个或者多个元素.
name -size - 可选, 最多从队列弹出这么多个元素出错返回 false. 当 size 未指定或者小于等于 1 时, 队列不存在(或者为空)则返回 null, 否则删除并返回一个元素. 当 size 大于等于 2 时, 返回一个数组包含弹出的元素.
$ssdb->qpop_back('q');
批量执行一批命令. 批量命令可以减少客户端和服务器之间的交互延时, 能提高性能和响应速度.
如果 exec() 出错则返回 false, 否则返回一个数组包含对应每一条命令的结果.
$ssdb->batch()
->set('a', 1)
->get('a')
->exec();
// 或者
$ssdb->batch();
$ssdb->set('a', 1);
$ssdb->get('a');
$ssdb->exec();