帮助改进此文档
SSDB PHP 客户端 API 文档
- @作者: ideawu
- @更新: 2014-11-05
SSDB 是一个高性能 NoSQL 数据库, 支持 zset 数据结构, 用于替代 Redis. 官方网站是 http://ssdb.io. 本文档介绍了 SSDB 的 PHP 客户端 API.
注意: SSDB 所使用的名词 "hashmap", "hash", "map" 表示相同的意思.
类 SimpleSSDB
bitcount参数
-
key- -
start- 可选, 子串的字节偏移 -
end- 可选
返回值
返回位值为 1 的个数. 出错返回 false.
示例
$ssdb->bitcount('key', 2, 10);
substr()).
参数
-
key- -
start- 可选, int, 子串的字节偏移 -
size- 可选, int, 子串的长度(字节数), 默认为到字符串最后一个字节
返回值
字符串的子串.
示例
$ssdb->substr('key', 2, 10);
zscan().
参数
-
name- zset 的名字. -
key_start- 参见zscan(). -
score_start- 参见zscan(). -
score_end- 参见zscan(). -
limit- 最多返回这么多个元素.
返回值
如果出错则返回 false, 否则返回包含 key 的数组.
示例
$ssdb->zkeys('z', '', 1, 100, 10);
zkeys().
参数
-
name- zset 的名字. -
key_start- 参见zkeys(). -
score_start- 参见zkeys(). -
score_end- 参见zkeys(). -
limit- 最多返回这么多个元素.
返回值
如果出错则返回 false, 否则返回包含 key-score 的关联数组.
示例
$ssdb->zrscan('z', '', 100, 1, 10);
zrank, zrrank
说明
注意! 本方法可能会非常慢! 请在离线环境中使用.
返回指定 key 在 zset 中的排序位置(排名), 排名从 0 开始. zrrank 获取是是倒序排名.
参数
-
name- zset 的名字. -
key-
返回值
found.出错则返回 false, null 表示 key 不存在于 zset, 否则返回排名.
示例
$ssdb->zrank('z', 'k1');
zrange, zrrange
说明
注意! 本方法在 offset 越来越大时, 会越慢!
根据下标索引区间 [offset, offset + limit) 获取 key-score 对, 下标从 0 开始. zrrange 是反向顺序获取.
参数
-
name- zset 的名字. -
offset- 正整数, 从此下标处开始返回. 从 0 开始. -
limit- 正整数, 最多返回这么多个 key-score 对.
返回值
如果出错则返回 false, 否则返回包含 key-score 的关联数组.
示例
$ssdb->zrange('z', 0, 10);
zclear
说明
删除 zset 中的所有 key.
参数
-
name- zset 的名字.
返回值
如果出错则返回 false, 否则返回删除的 key 的数量.
示例
$ssdb->zclear('z');
zcount
说明
返回处于区间 [start,end] key 数量.
参数
-
name- zset 的名字. -
score_start- key 的最小权重值(包含), 空字符串表示 -inf. -
score_end- key 的最大权重值(包含), 空字符串表示 +inf.
返回值
如果出错则返回 false, 否则返回符合条件的 key 的数量.
示例
$ssdb->zcount('z', 0, 100);
zsum
说明
返回 key 处于区间 [start,end] 的 score 的和.
参数
-
name- zset 的名字. -
score_start- key 的最小权重值(包含), 空字符串表示 -inf. -
score_end- key 的最大权重值(包含), 空字符串表示 +inf.
返回值
如果出错则返回 false, 否则返回符合条件的 score 的求和.
示例
$ssdb->zsum('z', 0, 100);
zavg
说明
返回 key 处于区间 [start,end] 的 score 的平均值.
参数
-
name- zset 的名字. -
score_start- key 的最小权重值(包含), 空字符串表示 -inf. -
score_end- key 的最大权重值(包含), 空字符串表示 +inf.
返回值
如果出错则返回 false, 否则返回符合条件的 score 的平均值.
示例
$ssdb->zavg('z', 0, 100);
zremrangebyrank
说明
删除位置处于区间 [start,end] 的元素.
参数
-
name- zset 的名字. -
start- (包含). -
end-(包含).
返回值
出错则返回 false, 否则返回被删除的元素个数.
示例
$ssdb->zremrangebyrank('z', 1, 2);
zremrangebyscore
说明
删除权重处于区间 [start,end] 的元素.
参数
-
name- zset 的名字. -
start- (包含). -
end-(包含).
返回值
出错则返回 false, 否则返回被删除的元素个数.
示例
$ssdb->zremrangebyscore('z', 1, 2);
zpop_front
说明
从 zset 首部删除并返回 limit 个元素.
参数
-
name- zset 的名字. -
limit- 正整数, 最多要删除并返回这么多个 key-score 对.
返回值
如果出错则返回 false, 否则返回包含 key-score 的关联数组.
示例
$ssdb->zpop_front('z', 3);
zpop_back
说明
从 zset 尾部删除并返回 limit 个元素.
参数
-
name- zset 的名字. -
limit- 正整数, 最多要删除并返回这么多个 key-score 对.
返回值
如果出错则返回 false, 否则返回包含 key-score 的关联数组.
示例
$ssdb->zpop_back('z', 3);
multi_zset
说明
批量设置 zset 中的 key-score.
参数
-
name- zset 的名字. -
kvs- 包含 key-score 的关联数组 .
返回值
出错则返回 false, 其它值表示正常.
示例
$ssdb->multi_zset('z', array(
'a' => 1,
'b' => 2,
));
multi_zget
说明
批量获取 zset 中多个 key 对应的权重值.
参数
-
name- zset 的名字. -
keys- 包含 key 的数组 .
返回值
如果出错则返回 false, 否则返回包含 key-score 的关联数组, 如果某个 key 不存在, 则它不会出现在返回数组中.
示例
$ssdb->multi_zget('z', array('k1', 'k2'));
multi_zdel
说明
批量删除 zset 中的 key.
参数
-
name- zset 的名字. -
keys- 包含 key 的数组 .
返回值
出错则返回 false, 其它值表示正常.
示例
$ssdb->multi_zdel('z', array('k1', 'k2'));
qsize
说明
返回队列的长度.
参数
-
name-
返回值
出错返回 false, 否则返回一个整数, 0 表示队列不存在(或者为空).
示例
$ssdb->qsize('q');
qlist, qrlist
说明
列出名字处于区间 (name_start, name_end] 的 queue/list.
("", ""] 表示整个区间.
参数
-
name_start- 返回的起始名字(不包含), 空字符串表示 -inf. -
name_end- 返回的结束名字(包含), 空字符串表示 +inf. -
limit- 最多返回这么多个元素.
返回值
出错则返回 false, 返回返回包含名字的数组.
示例
$ssdb->qlist('a', 'z', 10);
qclear
说明
清空一个队列.
参数
-
name-
返回值
出错返回 false.
示例
$ssdb->qclear('q');
qfront
说明
返回队列的第一个元素.
参数
-
name-
返回值
出错返回 false, 队列不存在(或者为空)则返回 null, 否则返回一个元素.
示例
$ssdb->qfront('q');
qback
说明
返回队列的最后一个元素.
参数
-
name-
返回值
出错返回 false, 队列不存在(或者为空)则返回 null, 否则返回一个元素.
示例
$ssdb->qback('q');
qget
说明
返回指定位置的元素. 0 表示第一个元素, 1 是第二个 ... -1 是最后一个.
参数
-
name- -
index- 可传负数.
返回值
出错返回 false, 如果指定位置不存在一个元素, 则返回 null, 否则返回一个元素.
示例
$ssdb->qget('q', -2);
qset
Since: 1.7.0.0
说明
更新位于 index 位置的元素. 如果超过现有的元素范围, 会返回错误.
参数
-
name- -
index- 可传负数. -
val-
返回值
出错则返回 false, 其它值表示正常.
示例
$ssdb->qset('q', 0, 'new val');
qrange
说明
返回下标处于区域 [offset, offset + limit] 的元素.
参数
-
name- queue 的名字. -
offset- 整数, 从此下标处开始返回. 从 0 开始. 可以是负数, 表示从末尾算起. -
limit- 正整数, 最多返回这么多个元素.
返回值
如果出错则返回 false, 否则返回数组.
示例
$ssdb->qrange('q', 0, 10);
qslice
说明
返回下标处于区域 [begin, end] 的元素. begin 和 end 可以是负数
参数
-
name- -
begin- -
end-
返回值
出错返回 false, 否则返回包含元素的数组.
示例
$ssdb->qslice('q', 0, -1);
qpush
说明
本函数是 qpush_back() 的别名.
qpush_front
说明
往队列的首部添加一个或者多个元素
参数
-
name- -
item- 字符串或是字符串数组.
返回值
添加元素之后, 队列的长度, 出错返回 false.
示例
$ssdb->qpush_front('q', 'a');
qpush_back
说明
往队列的尾部添加一个或者多个元素
参数
-
name- -
item- 字符串或是字符串数组.
返回值
添加元素之后, 队列的长度, 出错返回 false.
示例
$ssdb->qpush_back('q', 'a');
qpop
说明
本函数是 qpop_front() 的别名.
qpop_front
说明
从队列首部弹出一个或者多个元素.
参数
-
name- -
size- 可选, 最多从队列弹出这么多个元素
返回值
出错返回 false. 当 size 未指定或者小于等于 1 时, 队列不存在(或者为空)则返回 null, 否则删除并返回一个元素. 当 size 大于等于 2 时, 返回一个数组包含弹出的元素.
示例
$ssdb->qpop_front('q');
qpop_back
说明
从队列尾部弹出一个或者多个元素.
参数
-
name- -
size- 可选, 最多从队列弹出这么多个元素
返回值
出错返回 false. 当 size 未指定或者小于等于 1 时, 队列不存在(或者为空)则返回 null, 否则删除并返回一个元素. 当 size 大于等于 2 时, 返回一个数组包含弹出的元素.
示例
$ssdb->qpop_back('q');
qtrim_front
说明
从队列头部删除多个元素.
参数
-
name- -
size- 最多从队列删除这么多个元素
返回值
出错返回 false. 返回被删除的元素数量.
示例
$ssdb->qtrim_front('q', 3);
qtrim_back
说明
从队列头部删除多个元素.
参数
-
name- -
size- 最多从队列删除这么多个元素
返回值
出错返回 false. 返回被删除的元素数量.
示例
$ssdb->qtrim_back('q', 3);
batch, exec
说明
批量执行一批命令. 批量命令可以减少客户端和服务器之间的交互延时, 能提高性能和响应速度.
这个特性是在客户端实现的, ssdb-server 不支持批量命令, 而是当作独立的一个命令一个命令地执行. 所有命令和参数的大小应小于 10MB.
参数
返回值
如果 exec() 出错则返回 false, 否则返回一个数组包含对应每一条命令的结果.
示例
$ret = $ssdb->batch()
->set('a', 1)
->get('a')
->exec();
// 或者
$ssdb->batch();
$ssdb->set('a', 1);
$ssdb->get('a');
$ret = $ssdb->exec();
dbsize
说明
返回数据库的估计大小, 以字节为单位. 如果服务器开启了压缩, 返回压缩后的大小.
参数
返回值
出错返回 false. 返回数据库大小.
示例
$ssdb->dbsize();
info
说明
返回服务器的信息.
参数
-
opt- 可选, 可以是cmd, leveldb
返回值
出错返回 false. 返回服务器信息的关联数组.
示例
$ssdb->info();