Fix wording as recommended by Chris.

Added additional documentation about indexes.
This commit is contained in:
Rob Riddle 2015-10-16 12:29:16 +03:00
parent 46578659a8
commit 734a3554d5

View File

@ -38,7 +38,7 @@ Services correspond with a Node.js module as described in 'package.json', for ex
*Note:* If you already have a bitcore-node database, and you want to query data from previous blocks in the blockchain, you will need to reindex. Reindexing right now means deleting your bitcore-node database and resyncing.
## Using Services Programmatically
If instead you would like to run a custom node, you can include services by including them in your configuration object when initializing a new node.
If, instead, you would like to run a custom node, you can include services by including them in your configuration object when initializing a new node.
```js
//Require bitcore
@ -206,4 +206,60 @@ MyService.prototype.getTransactionIdsByDate = function(startDate, endDate, callb
callback(null, transactions);
});
};
```
```
If you're new to leveldb and would like to better understand how createReadStream works you can find [more
information here](https://github.com/Level/levelup#dbcreatereadstreamoptions).
### Understanding indexes
You may notice there are several pieces to the index itself. Let's take a look at each piece to make them easier
to understand.
#### Prefixes
Since leveldb is just a simple key-value store we need something to differentiate which keys are part of which index. If
we had two services trying to index on the same key, say a txid, they would overwrite each other and their queries would
return results from the other index. By introducing a unique prefix per index type that we can prepend our indexes with
prevents these collisions.
```js
//A simple example of indexing the number of inputs and ouputs given a transaction id
/** Wrong way **/
var index1key = new Buffer(transaction.id);
var index1value = transaction.inputs.length;
//Since this key has the same value it would just overwrite index1 when we write to the db
var index2key = new Buffer(transaction.id);
var index2value = transaction.outputs.length;
/** Right way **/
var index1prefix = new Buffer('11');
var index2prefix = new Buffer('12');
var index1key = Buffer.concat([index1prefix, new Buffer(transaction.id)]);
var index1value = transaction.inputs.length;
//Now that the keys are different, this won't overwrite the index
var index2key = Buffer.concat([index2prefix, new Buffer(transaction.id)]);
var index2value = transaction.outputs.length;
```
Remember that all indexes are global, so check to make sure no other services you are using make use of the same prefix
you plan to use in your service. We recommend documenting which prefixes you use and that you check for collisions with
popular services if you plan to release your service for others to use.
#### Index Key
The index key is the value you want to query by. This value should be deterministic so that it can be removed in the case
of a [re-org](https://en.bitcoin.it/wiki/Chain_Reorganization) resulting in a block removal. The value should be unique, as
no two indexes can be the same value. If you need two indexes with the same key value, consider adding a deterministic
differentiator, such as a position in an array, or instead storing multiple values within the same index data.
#### Index Data
This is the data which is returned when you search by the index's key. This can be whatever you would like to retrieve.
Try to be efficient by not storing data that is already available elsewhere, such as storing a transaction ID instead of
an entire transaction.