Fabric链码开发——富查询

常见的链码使用PutState和GetState就可以进行简单的增加和查找了，再不济就加入DelState。因为fabric底层都是KV数据库，所以这三个接口就可以进行增删改查的基本需求了。但是，这都是单个数据的操作如果要进行功能较为强大的数据操作，只使用这个是完全不够的。查询时一切数据操作的开始，通过官方文档，找到了这两个支持富查询的函数。（富查询只支持在CouchDB 中使用）

源代码

func (s *ChaincodeStub) GetQueryResult(query string) (StateQueryIteratorInterface, error)

func (s *ChaincodeStub) GetQueryResultWithPagination(query string, pageSize int32,bookmark string) (StateQueryIteratorInterface, *pb.QueryResponseMetadata, error)

第一个是一个简单的富查询函数，第二个是一个支持富查询的分页查询函数

// GetQueryResult documentation can be found in interfaces.go
func (s *ChaincodeStub) GetQueryResult(query string) (StateQueryIteratorInterface, error) {// Access public data by setting the collection to empty stringcollection := ""// ignore QueryResponseMetadata as it is not applicable for a rich query without paginationiterator, _, err := s.handleGetQueryResult(collection, query, nil)return iterator, err
}

// GetQueryResultWithPagination ...
func (s *ChaincodeStub) GetQueryResultWithPagination(query string, pageSize int32,bookmark string) (StateQueryIteratorInterface, *pb.QueryResponseMetadata, error) {// Access public data by setting the collection to empty stringcollection := ""metadata, err := createQueryMetadata(pageSize, bookmark)if err != nil {return nil, nil, err}return s.handleGetQueryResult(collection, query, metadata)
}

以上是他们的源码，实际上可以发现，他们都是调用handleGetQueryResult这个函数，分页查询函数知识多了一步创建metadata,将范围打包。之后可以和GetStateByRange(startKey, endKey string) 的函数做比较。

bookmark是书签，内容是一个无序的字符数组，如果为空则会重头查询，如果不为空，则会从会从它所代表的位置开始查询，在每次分页查询的时候都可以得到一个bookmark，也就是说，下一页的查询需要带上一页的bookmark。

func (s *ChaincodeStub) handleGetQueryResult(collection, query string,metadata []byte) (StateQueryIteratorInterface, *pb.QueryResponseMetadata, error) {//获取查询结果，这一步就使用了metadata进行分页response, err := s.handler.handleGetQueryResult(collection, query, metadata, s.ChannelID, s.TxID)if err != nil {return nil, nil, err}//创建迭代器iterator := s.createStateQueryIterator(response)//进行再次封装responseMetadata, err := createQueryResponseMetadata(response.Metadata)if err != nil {return nil, nil, err}return iterator, responseMetadata, nil
}

和这两个富查询函数一起使用handleGetQueryResult的，还有一个GetPrivateDataQueryResult函数。这个函数看起来是查询私有数据，但私有数据是什么暂且不知道，按下不提。这四个函数都是在shim/stub.go中。

索引及数据结构

富查询目前只有couchDB支持，这是一个比较依赖数据库的功能，那就必须要有考虑一个问题：索引。参考Fabric的中文文档可以建立索引。

特别注意两点：

1.索引是依据需求来的，如果太多的索引会影响查询速率

2.索引的目录是固定的，链码同目录下的META-INF/statedb/couchdb/indexes

一个完整的索引如下：

{"index":{//要查询的字段名称，一般情况下要包含docType，对于docType的解释在后面"fields":["docType","owner"] // Names of the fields to be queried},// (可选）将创建索引的设计文件的名称。如果是一个文件包含一个索引可以不使用，官方建议也是单个索引"ddoc":"indexOwnerDoc", "name":"indexOwner","type":"json"
}

我在官方文档中还看到了一个数据结构的规范写法

type marble struct {//docType用于区分状态数据库中的各种类型的对象ObjectType string `json:"docType"` //以下的正常的数据结构Name       string `json:"name"` Color      string `json:"color"`Size       int    `json:"size"`Owner      string `json:"owner"`
}

docType 用来识别这个文档的数据类型。同时在链码数据库中也可能存在其他文档。数据库中的文档对于这些属性值来说都是可查询的。

常用函数

以下是我根据文档中给出的示例总结的富查询常用函数，主要使用getQueryResultForQueryString和getQueryResultForQueryStringWithPagination，后两个函数是为分页富查询函数使用的。可以写在智能合约中调用。

=========================================================================================
// getQueryResultForQueryString执行传入的查询字符串。
// 结果集被建立并作为一个字节数组返回，其中包含JSON结果。
=========================================================================================
func getQueryResultForQueryString(APIstub shim.ChaincodeStubInterface, queryString string) ([]byte, error) {fmt.Printf("- getQueryResultForQueryString queryString:\n%s\n", queryString)resultsIterator, err := APIstub.GetQueryResult(queryString)if err != nil {return nil, err}defer resultsIterator.Close()buffer, err := constructQueryResponseFromIterator(resultsIterator)if err != nil {return nil, err}fmt.Printf("- getQueryResultForQueryString queryResult:\n%s\n", buffer.String())return buffer.Bytes(), nil
}=========================================================================================
// getQueryResultForQueryStringWithPagination执行传入的查询字符串，其中包括
// 分页信息。结果集被建立并作为一个字节数组返回，其中包含JSON结果。
=========================================================================================
func getQueryResultForQueryStringWithPagination(APIstub shim.ChaincodeStubInterface, queryString string, pageSize int32, bookmark string) ([]byte, error) {fmt.Printf("- getQueryResultForQueryStringWithPagination queryString:\n%s\n", queryString)resultsIterator, responseMetadata, err := APIstub.GetQueryResultWithPagination(queryString, pageSize, bookmark)if err != nil {return nil, err}defer resultsIterator.Close()buffer, err := constructQueryResponseFromIterator(resultsIterator)if err != nil {return nil, err}bufferWithPaginationInfo := addPaginationMetadataToQueryResults(buffer, responseMetadata)fmt.Printf("- getQueryResultForQueryStringWithPagination queryResult:\n%s\n", bufferWithPaginationInfo.String())return buffer.Bytes(), nil
}

=========================================================================================
// constructQueryResponseFromIterator构建一个JSON数组，其中包含来自给定结果迭代器的查询结果。
// 一个给定的结果迭代器=========================================================================================
func constructQueryResponseFromIterator(resultsIterator shim.StateQueryIteratorInterface) (*bytes.Buffer, error) {// buffer is a JSON array containing QueryResultsvar buffer bytes.Bufferbuffer.WriteString("[")bArrayMemberAlreadyWritten := falsefor resultsIterator.HasNext() {queryResponse, err := resultsIterator.Next()if err != nil {return nil, err}// Add a comma before array members, suppress it for the first array memberif bArrayMemberAlreadyWritten == true {buffer.WriteString(",")}buffer.WriteString("{\"Key\":")buffer.WriteString("\"")buffer.WriteString(queryResponse.Key)buffer.WriteString("\"")buffer.WriteString(", \"Record\":")// Record is a JSON object, so we write as-isbuffer.WriteString(string(queryResponse.Value))buffer.WriteString("}")bArrayMemberAlreadyWritten = true}buffer.WriteString("]")return &buffer, nil
}=========================================================================================
// addPaginationMetadataToQueryResults 将包含分页的QueryResponseMetadata
// 的信息，添加到构建的查询结果中。
=========================================================================================
func addPaginationMetadataToQueryResults(buffer *bytes.Buffer, responseMetadata *pb.QueryResponseMetadata) *bytes.Buffer {buffer.WriteString("[{\"ResponseMetadata\":{\"RecordsCount\":")buffer.WriteString("\"")buffer.WriteString(fmt.Sprintf("%v", responseMetadata.FetchedRecordsCount))buffer.WriteString("\"")buffer.WriteString(", \"Bookmark\":")buffer.WriteString("\"")buffer.WriteString(responseMetadata.Bookmark)buffer.WriteString("\"}}]")return buffer
}

下面是我写的一个调用分页函数的合约函数（我把可以在SDK中调用的智能合约函数叫做合约函数）示例

func (s *SmartContract) queryCourseWithPagination(APIstub shim.ChaincodeStubInterface, args []string) pb.Response {fmt.Println("func queryCourseWithPagination start")fmt.Printf("args:%v\n", args)if len(args) != 3 {return shim.Error("arguments num not enough," + strconv.Itoa(len(args)))}queryString := args[0]//return type of ParseInt is int64pageSize, err := strconv.ParseInt(args[1], 10, 32)if err != nil {return shim.Error(err.Error())}bookmark := args[2]//之前是获取参数，在这一步调用分页富查询函数，查询出结果后转为字节流返回queryResults, err := getQueryResultForQueryStringWithPagination(APIstub, queryString, int32(pageSize), bookmark)if err != nil {return shim.Error(err.Error())}return shim.Success(queryResults)
}

chaincode常用包shim链接