基本操作

用户管理

表操作

数据操作

数据查询

权限管理

事务相关

区块信息

事件订阅

运算符

JavaScript 接口命令参考

基本操作

c

c -> c

ChainSQL的操作对象

a.使用前首先在package.json文件中引入"chainsql":"^0.6.20"; 然后执行npm install命令

b.直接执行npm install chainsql --save命令

Example:

const ChainsqlAPI = require('chainsql').ChainsqlAPI;
const c = new ChainsqlAPI();
					

connect

c.connect(url);

创建一个新的连接到ChainSQL节点;

如果无法建立连接,会抛出ReqlDriverError;

Example:连接指定的路径的主机。

c.connect("ws://127.0.0.1:6006");
					

as

c.as({"secret":"xxx","address": "xxx"});

提供操作者的身份;

Example:

c.as({
	"secret": "xcUd996waZzyaPEmeFVp4q5S3FZYB",
	"address": "zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M"
});
					

use

c.use(address);

切换表的所有者(即后续操作的上下文),默认表的所有者为操作者;

Example:

c.use("zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M");
					

setRestrict

c.setRestrict(true/false);

设置是否使用严格模式,默认为非严格模式;在严格模式下,语句共识通过的条件是期望的快照HASH与预期一致

Example:

c.setRestrict(true);
					

submit

c.submit() → promise
c.submit(options) → promise
c.submit(callback)

c.submit(options)相当于同步调用,可以通过options来指示操作执行的结果等于预期的值时才返回,查询操作带options参数时不起作用;

options格式:

{expect:"send_success"}或{expect:"validate_success"}或{expect:"db_success"}

示例一:
// 删除指定表
c.dropTable("marvel").submit()
.then(function(result) {

	console.log(result.status);
	console.log(result.tx_hash);

})
.catch(function(e) {

	console.log(e.error);
	console.log(e.tx_hash);

}
					
示例二:
// 删除指定表
c.dropTable("marvel").submit({expect:"validate_success"});
					
示例三:

// 删除指定表
c.dropTable("marvel").submit(function(err, result) {

});
					

用户管理

generateAddress

c.generateAddress();

创建用户,返回账户信息

{
	"secret":"xcUd996waZzyaPEmeFVp4q5S3FZYB",
	"address":"zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M",
	"publicKey":"02B2F836C47A36DE57C2AF2116B8E812B7C70E7F0FEB0906493B8476FC58692EBE"
}
					 

pay

c.pay(accountId,count).submit();

为创建的用户转账,新创建的用户在转账成功之后才能正常使用;其中accountId表示转账的用户地址,count转账金额,count最小值20;

根账户地址:zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh,私钥:xnoPBzXtMeMyMHUVTgbuqAfg1SUTb

Example: 给账户地址为 z9VF7yQPLcKgUoHwMbzmQBjvPsyMy19ubs 的用户转账20.

c.pay("z9VF7yQPLcKgUoHwMbzmQBjvPsyMy19ubs", 20);
					

表操作

createTable

c.createTable(tableName, raw, [options]).submit();

创建一个表;

tableName:所创建表名;

raw:创建表的字段名称必须为Json格式数据;例如:

"{'field':'id','type':'int','length':11,'PK':1,'NN':1,'UQ':1,'AI':1}",
"{'field':'name','type':'varchar','length':50,'default':null}",
"{'field':'age','type':'int'}"

operationRule:行级控制规则,不能与confidential一起使用

option:为表指定其它的参数,目前支持如下参数:

  confidential:true/false, 如果为true,表示该表是机密的,所有对该表的操作都是加密的,只有授权的用户才能解密查看

  operationRule:行级控制规则,不能与confidential一起使用

创建表参数说明:

  • field:表字段名
  • type:字段名类型,支持int/float/double/decimal/varchar/blob/text/datetime
  • length:字段值的字节长度
  • PK:值为1表示字段为主键
  • NN:值为1表示值不能为空,NOT NULL
  • UQ:值为1表示值唯一
  • AI:值为1表示值有自增特性
  • FK:值为1表示字段为某表的外键,必须配合REFERENCES使用
  • REFERENCES:值的格式为 {'table':'user','field':'id'}
Example: 创建表 "dc_universe"

c.createTable("dc_universe", [
	{
		'field':'id',
		'type':'int',
		'length':11,
		'PK':1,
		'NN':1,
		'UQ':1,
		'AI':1
	},
	{
		'field':'name',
		'type':'varchar',
		'length':50,
		'default':null
	},
	{
		'field':'age',
		'type':'int'
	}]
).submit();
					

renameTable

c.renameTable(tableName, tableNewName).submit();

修改数据库中表的名字.

tableName:表名;

tableNewName:新的表名,两个名字都不能为空;

Example: 将表"dc_universe"改为"dc_name"

c.renameTable("dc_universe", "dc_name").submit();
					

dropTable

c.dropTable(tableName).submit();

从数据库删除一个表。表和它的所有数据将被删除;

Example: 删除表 "dc_universe".

c.dropTable("dc_universe").submit();
					

数据操作

insert

c.table(tableName).insert(raw).submit();

向数据库中插入数据。raw类型必须是例子中的json格式的数据类型;

Example: 向表"posts"中插入一条记录.

c.table("posts").insert({name: 'peera',age: 22},{ name: 'peerb',age: 21}).submit();
					

update

c.table(tableName).get(raw).update(raw).submit();

更新表中数据。如果get添加为空,则更新表中所有记录;其中raw为json格式字符串;

Example: 更新 id 等于 1 的记录.

c.table("posts").get({id: 1}).update({age:'52',name:'lisi'}).submit();
					

delete

c.table(tableName).get(raw).delete().submit();

从表中删除对应条件的数据,如果get条件为空,则删除所有数据;

Example: 删除 id 等于 1 的记录.

c.table("comments").get({id: 1}).delete().submit();
					

数据查询

get

c.table(tableName).get(raw).submit();

从数据库查询数据,后面可以进行其他操作,例如update、delete等;

Example: 查询 name 等于 aa 的记录.

c..table("posts").get({name: 'aa'}).submit();
					

limit

c.table(tableName).get(raw).limit({index:0,total:10}).withFields([*]).submit();

对数据库进行分页查询.返回对应条件的数据;

Example: 查询 name 等于 aa 的前10条记录.

c..table("posts").get({name: 'aa'}).limit({index:0,total:10}).withFields([*]).submit();
					

order

c.table(tableName).get(raw).order([{id:1},{name:-1}]).withFields([*]).submit()

对查询的数据按指定字段进行排序;

Example: 按 id 升序,name 的降序排序

c..table("posts").get({name: 'aa'}).order({id:1}, {name:-1}).withFields([*]).submit();
					

withFields

c.table(tableName).get(raw).withFields([field1,dield2,...]).submit();

从数据库查询数据,并返回指定字段,必须个get配合使用;

Example: 查询 name 等于 aa 的记录.

c..table("posts").get({name: 'aa'}).withFields([*]).submit();
					

权限管理

grant

c.grant(tableName,user,rightInfo).submit();

向用户授予数据表操作权限;

tableName:授权的表名;

user:所要授权的账户地址;flags(array):所要授权的权限;

rightInfo:为授权字符串,例如:{select: true, insert: true, update: true,delete:false};

用户权限有以下几种:Select、Insert、Update、Delete;

Example1: 向用户授予Insert、Delete操作权限.

c.grant("Table", "zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M", {insert:true, delete:true})
.submit({expect:"validate_success"});
					
Example1: 取消用户Insert、Delete操作权限.

c.grant("Table", "zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M", {insert:false, delete:false})
.submit({expect:"validate_success"});
					

事务相关


在事务开始和结束之间的insert,update,delete,assert语句会包装在一个原子操作中执行

与数据库的事务类似,事务中执行的语句要么全部成功,要么全部失败

执行事务类型交易主要涉及两个api:beginTran,commit.

beginTran开启事务,commit提交事务,事务中的操作全部执行成功事务才成功,有一个执行失败,则事务事务会自动回滚

在事务上下文中,不在支持单个语句的submit

beginTran

c.beginTran();

事务开始;

assert

c.table(tableName).get(jsonObj1).assert(jsonObj2);

事务中的断言操作,assert为true则继续,false则回滚事务;

jsonObj1:查询条件;

jsonObj2:断言表达;

Example: 判断id等于1的记录age是否等于52并且name等于lisi,如果是则继续,如果有一个条件不满足或记录不存在,则回滚事务

c.table("posts").get({id: 1}).assert({age:'52',name:'lisi'});
					
Example: 判断id等于1的记录集的行数是否等于1,如果是则继续,如果不是或表不存在,则回滚事务

c.table("posts").get({id: 1}).assert({'$rowcount':1});
					
Example: 判断表posts是否存在,如果有则继续,如果不存在,则回滚事务

c.table("posts").assert({'$IsExisted':1});
					

commit

提交事务;

本次事务期间的所有操作都会打包提交到区块链网络

使用方法与submit类似:

c.commit() → promise
c.commit(options) → promise
c.commit(callback)

Example:

c.beginTran()

c.table("comments").insert({'name':'peersafe', age:20}, {'name': 'zongxiang', age: 21});
c.table("posts").get({id: 1}).assert({'age':22, name: 'peersafe'});
c.table("posts").get({id: 1}).update({'age':52, name: 'zongxiang'});
c.table("comments").delete({'id':1});

c.commit()
	     			

区块信息

getLedger

c.getLedger(option,cb)

option = {"ledger_index":LedgerVersion||"validated"}

回调函数 cb 如:

function() {
	//do something here
}
					

获取当前区块信息

getLedgerVersion

c.getLedgerVersion(cb)

获取当前的区块高度

回调函数 cb 如:

function() {
	//do something here
}
					

getTransactions

c.getTransactions(address,cb)

获取当前账户的所有交易;

回调函数 cb 如:

function() {
	//do something here
}
					

getTransaction

c.getTransaction(hash,cb)

获取某个hash下的交易信息;

回调函数 cb 如:

function() {
	//do something here
}
					

事件订阅

subscribeTable

c.subscribeTable(owner, tablename, callback);

1.订阅某张表

owner:表的所有者地址;

tablename:表名;

callback:回调函数;

Example: 用户订阅 TestName 表信息.

c.event.subscribeTable("zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M", "TestName",
	function(err,data) {
		//do something here
	}
)
	     			

unsubcribeTable

c.unsubcribeTable(owner, tablename);

2.取消订阅某张表

owner:表的所有者地址;

tablename:表名;

Example: 用户取消订阅 TestName 表信息.

c.event.unsubcribeTable("zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M", "TestName");	     				
	     			

subscribeTx

c.subscribeTx(txid, callback);

3.订阅某个交易

txid:交易Hash

callback回调函数;

Example: 用户订阅交易Hash信息.

c.event.subscribeTx(txid, function(err,data) {
		//do something here
	}
)
	     			

unsubscribeTx

c.unsubscribeTx(txid);

4.取消订阅某个交易

txid:交易Hash

Example: 用户取消订阅交易Hash信息.

c.event.unsubscribeTx(txid);   				
	     			

运算符

comparison operators

比较运算符

运算符 说明 语法
$ne 不等于 {field:{$ne:value}}
$eq 等于 {field:{$eq:value}} or {field:value}
$lt 小于 {field:{$lt:value}}
$le 小于等于 {field:{$le:value}}
$gt 大于 {field:{$gt:value}}
$ge 大于等于 {field:{$ge:value}}
$in 字段值在指定的数组中 {field:{$in:[v1, v2, ..., vn]}}
$nin 字段值不在指定的数组中 {field:{$nin:[v1, v2, ..., vn]}}

logical operators

逻辑符

逻辑符 说明 语法
$and 逻辑与 {$and:[{express1},{express2},...,{expressN}]}
$or 逻辑或 {$or:[{express1},{express2},...,{expressN}]}

fuzzy matching

模糊匹配

语法 说明
{"field":{"$regex":"/value/"}} like "%value%"
{"field":{"$regex":"/^value/"}} like "%value"

例子

where id > 10 and id < 100

对应 json 对象

{
	$and: [
		{
			id: {$gt: 10}
		},
		{
			id: {$lt: 100}
		}
	]
}
					
where id > 10 and id < 100

对应 json 对象

{
	$and: [
		{
			id: {$gt:10}
		},
		{
			id: {$lt:100}
		}
	]
}
					
where name = 'peersafe' or name = 'zongxiang'

对应 json 对象

{
	$or: [
		{
			name: {$eq:'peersafe'}
		},
		{
			name: {$eq:zongxiang}
		}
	]
}
					
where (id > 10 and name = 'peersafe') or name = 'zongxiang'

对应 json 对象

{
	$or: [
		{
			$and: [
				{
					id: {$gt:10}
				},
				{
					name:'peersafe'
				}]
		},
		{
			name:'zongxiang'
		}
	]
}
					
where name like '%peersafe%'

对应 json 对象

{
	name: {
		$regex:'/peersafe/'
	}
}
					
where name like '%peersafe'

对应 json 对象

{
	name: {
		$regex:'/^peersafe/'
	}
}