基本操作

用户管理

表操作

数据操作

数据查询

权限管理

事务相关

区块信息

事件订阅

运算符

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与预期一致

true:严格模式     false: 非严格模式

Example:

c.setRestrict(false);
					

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"}

返回状态值包括:

  send_success: option指定为:{expect:"send_success"},发送交易本地共识通过后触发

  validate_success: option指定为:{expect:"validate_success"}, 共识成功后触发

  db_success:: option指定为{expect:"db_success"},入库成功后触发

  validate_timeout::option指定为:{expect:"validate_success"} ,共识超时(出现这种情况一般是共识失败了)后触发

  db_timeout::option指定为{expect:"db_success"},入库超时触发

  db_error::option指定为{expect:"db_success"},入库失败后触发

  执行异常,需catch捕获


示例一:
// 删除指定表
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最小值5;

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

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

c.pay("z9VF7yQPLcKgUoHwMbzmQBjvPsyMy19ubs", 5);
					

表操作

createTable

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

创建一个表;

tableName:所创建表名,创建表不支持自增型;

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

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

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

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

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

创建表参数说明:

  • field:表字段名
  • type:字段名类型,支持int/float/double/decimal/varchar/blob/text/datetime
  • length:字段值的字节长度
  • PK:值为1表示字段为主键
  • NN:值为1表示值不能为空,NOT NULL
  • UQ:值为1表示值唯一
  • index:值为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
	},
	{
		'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([
	{id:1, name: 'peera',age: 22},
	{id:2, 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();
					
Example2: 查询表中记录数.
   
   var ret = c.table("posts").get({name: 'aa'}).withFields(["COUNT(*) as count"]).submit();
   var count = ret.lines[0].count; 
					   
Example3: 查询 name 包含 s 的记录.
   c.table("posts").get({ name: { $regex: '/s/' } }).submit();
						

权限管理

grant

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

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

tableName:授权的表名;

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

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

publicKey:被授权账户的公钥(选填字段,用于加密表);

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

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

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

c.grant("Table", "User.address", {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: string, options: Object, cb: callback)

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

参数说明:

可选项“options”:

options.counterparty: 返回以此账户为counterparty的交易

options.limit: 最多返回的交易条数

options.maxLedgerVersion: 获取此区块或低于此区块高度的区块中包含的交易

options.minLedgerVersion: 获取此区块或高于此区块高度的区块中包含的交易

options.start: 指定了start交易,minLedgerVersion或者maxLedgerVersion就会被内部指定,且返回的交易是以start交易为起始点的交易(不包含start)

options.types: 指定查询的交易类型

示例(一次获取10条交易信息,直到获取所有的交易信息):


let nLimit = 10;
var options = {
	limit: nLimit
};
while (true) {
	res = await c.api.getTransactions(account.address, options);
	
	if (res.length > 0) {
		console.log("   Txs:", res);
	}
	if (res.length < 1 || res.length != nLimit) {
		break;
	}
	options.start = res[nLimit - 1].id;
}
					

可选项“回调函数 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/'
	}
}