Merge "[FAB-7834] Add couchdb index to marbles02 sample"

chaincode/marbles02/go/META-INF/statedb/couchdb/indexes/indexOwner.json

@@ -0,0 +1 @@
+{"index":{"fields":["data.docType","data.owner"]},"ddoc":"indexOwnerDoc", "name":"indexOwner","type":"json"}

chaincode/marbles02/go/marbles_chaincode.go

@@ -36,35 +36,60 @@ under the License.
 //   peer chaincode query -C myc1 -n marbles -c '{"Args":["queryMarblesByOwner","tom"]}'
 //   peer chaincode query -C myc1 -n marbles -c '{"Args":["queryMarbles","{\"selector\":{\"owner\":\"tom\"}}"]}'
 
-//The following examples demonstrate creating indexes on CouchDB
-//Example hostname:port configurations
+// INDEXES TO SUPPORT COUCHDB RICH QUERIES
 //
-//Docker or vagrant environments:
+// Indexes in CouchDB are required in order to make JSON queries efficient and are required for
+// any JSON query with a sort. As of Hyperledger Fabric 1.1, indexes may be packaged alongside
+// chaincode in a META-INF/statedb/couchdb/indexes directory. Each index must be defined in its own
+// text file with extension *.json with the index definition formatted in JSON following the
+// CouchDB index JSON syntax as documented at:
+// http://docs.couchdb.org/en/2.1.1/api/database/find.html#db-index
+//
+// This marbles02 example chaincode demonstrates a packaged
+// index which you can find in META-INF/statedb/couchdb/indexes/indexOwner.json.
+// For deployment of chaincode to production environments, it is recommended
+// to define any indexes alongside chaincode so that the chaincode and supporting indexes
+// are deployed automatically as a unit, once the chaincode has been installed on a peer and
+// instantiated on a channel. See Hyperledger Fabric documentation for more details.
+//
+// If you have access to the your peer's CouchDB state database in a development environment,
+// you may want to iteratively test various indexes in support of your chaincode queries.  You
+// can use the CouchDB Fauxton interface or a command line curl utility to create and update
+// indexes. Then once you finalize an index, include the index definition alongside your
+// chaincode in the META-INF/statedb/couchdb/indexes directory, for packaging and deployment
+// to managed environments.
+//
+// In the examples below you can find index definitions that support marbles02
+// chaincode queries, along with the syntax that you can use in development environments
+// to create the indexes in the CouchDB Fauxton interface or a curl command line utility.
+//
+
+//Example hostname:port configurations to access CouchDB.
+//
+//To access CouchDB docker container from within another docker container or from vagrant environments:
 // http://couchdb:5984/
 //
 //Inside couchdb docker container
 // http://127.0.0.1:5984/
 
-// Index for chaincodeid, docType, owner.
+// Index for docType, owner.
 // Note that docType and owner fields must be prefixed with the "data" wrapper
-// chaincodeid must be added for all queries
 //
-// Definition for use with Fauxton interface
-// {"index":{"fields":["chaincodeid","data.docType","data.owner"]},"ddoc":"indexOwnerDoc", "name":"indexOwner","type":"json"}
+// Index definition for use with Fauxton interface
+// {"index":{"fields":["data.docType","data.owner"]},"ddoc":"indexOwnerDoc", "name":"indexOwner","type":"json"}
 //
-// example curl definition for use with command line
-// curl -i -X POST -H "Content-Type: application/json" -d "{\"index\":{\"fields\":[\"chaincodeid\",\"data.docType\",\"data.owner\"]},\"name\":\"indexOwner\",\"ddoc\":\"indexOwnerDoc\",\"type\":\"json\"}" http://hostname:port/myc1/_index
+// Example curl command line to define index in the CouchDB channel_chaincode database
+// curl -i -X POST -H "Content-Type: application/json" -d "{\"index\":{\"fields\":[\"data.docType\",\"data.owner\"]},\"name\":\"indexOwner\",\"ddoc\":\"indexOwnerDoc\",\"type\":\"json\"}" http://hostname:port/myc1_marbles/_index
 //
 
-// Index for chaincodeid, docType, owner, size (descending order).
+// Index for docType, owner, size (descending order).
 // Note that docType, owner and size fields must be prefixed with the "data" wrapper
-// chaincodeid must be added for all queries
 //
-// Definition for use with Fauxton interface
-// {"index":{"fields":[{"data.size":"desc"},{"chaincodeid":"desc"},{"data.docType":"desc"},{"data.owner":"desc"}]},"ddoc":"indexSizeSortDoc", "name":"indexSizeSortDesc","type":"json"}
+// Index definition for use with Fauxton interface
+// {"index":{"fields":[{"data.size":"desc"},{"data.docType":"desc"},{"data.owner":"desc"}]},"ddoc":"indexSizeSortDoc", "name":"indexSizeSortDesc","type":"json"}
 //
-// example curl definition for use with command line
-// curl -i -X POST -H "Content-Type: application/json" -d "{\"index\":{\"fields\":[{\"data.size\":\"desc\"},{\"chaincodeid\":\"desc\"},{\"data.docType\":\"desc\"},{\"data.owner\":\"desc\"}]},\"ddoc\":\"indexSizeSortDoc\", \"name\":\"indexSizeSortDesc\",\"type\":\"json\"}" http://hostname:port/myc1/_index
+// Example curl command line to define index in the CouchDB channel_chaincode database
+// curl -i -X POST -H "Content-Type: application/json" -d "{\"index\":{\"fields\":[{\"data.size\":\"desc\"},{\"data.docType\":\"desc\"},{\"data.owner\":\"desc\"}]},\"ddoc\":\"indexSizeSortDoc\", \"name\":\"indexSizeSortDesc\",\"type\":\"json\"}" http://hostname:port/myc1_marbles/_index
 
 // Rich Query with index design doc and index name specified (Only supported if CouchDB is used as state database):
 //   peer chaincode query -C myc1 -n marbles -c '{"Args":["queryMarbles","{\"selector\":{\"docType\":\"marble\",\"owner\":\"tom\"}, \"use_index\":[\"_design/indexOwnerDoc\", \"indexOwner\"]}"]}'

chaincode/marbles02/node/META-INF/statedb/couchdb/indexes/indexOwner.json

@@ -0,0 +1 @@
+{"index":{"fields":["data.docType","data.owner"]},"ddoc":"indexOwnerDoc", "name":"indexOwner","type":"json"}