github.com/adoriasoft/tendermint@v0.34.0-dev1.0.20200722151356-96d84601a75a/docs/app-dev/indexing-transactions.md (about)

     1  ---
     2  order: 6
     3  ---
     4  
     5  # Indexing Transactions
     6  
     7  Tendermint allows you to index transactions and later query or subscribe
     8  to their results.
     9  
    10  Events can be used to index transactions and blocks according to what happened
    11  during their execution. Note that the set of events returned for a block from
    12  `BeginBlock` and `EndBlock` are merged. In case both methods return the same
    13  type, only the key-value pairs defined in `EndBlock` are used.
    14  
    15  Each event contains a type and a list of attributes, which are key-value pairs
    16  denoting something about what happened during the method's execution. For more
    17  details on `Events`, see the
    18  [ABCI]https://github.com/tendermint/spec/blob/master/spec/abci/abci.md#events)
    19  documentation.
    20  
    21  An Event has a composite key associated with it. A `compositeKey` is
    22  constructed by its type and key separated by a dot.
    23  
    24  For example:
    25  
    26  ```json
    27  "jack": [
    28    "account.number": 100
    29  ]
    30  ```
    31  
    32  would be equal to the composite key of `jack.account.number`.
    33  
    34  Let's take a look at the `[tx_index]` config section:
    35  
    36  ```toml
    37  ##### transactions indexer configuration options #####
    38  [tx_index]
    39  
    40  # What indexer to use for transactions
    41  #
    42  # Options:
    43  #   1) "null"
    44  #   2) "kv" (default) - the simplest possible indexer, backed by key-value storage (defaults to levelDB; see DBBackend).
    45  indexer = "kv"
    46  ```
    47  
    48  By default, Tendermint will index all transactions by their respective
    49  hashes using an embedded simple indexer. Note, we are planning to add
    50  more options in the future (e.g., PostgreSQL indexer).
    51  
    52  You can turn off indexing completely by setting `tx_index` to `null`.
    53  
    54  ## Adding Events
    55  
    56  Applications are free to define which events to index. Tendermint does not
    57  expose functionality to define which events to index and which to ignore. In
    58  your application's `DeliverTx` method, add the `Events` field with pairs of
    59  UTF-8 encoded strings (e.g. "transfer.sender": "Bob", "transfer.recipient":
    60  "Alice", "transfer.balance": "100").
    61  
    62  Example:
    63  
    64  ```go
    65  func (app *KVStoreApplication) DeliverTx(req types.RequestDeliverTx) types.Result {
    66      //...
    67      events := []abci.Event{
    68          {
    69              Type: "transfer",
    70              Attributes: []abci.EventAttribute{
    71                  {Key: []byte("sender"), Value: []byte("Bob"), Index: true},
    72                  {Key: []byte("recipient"), Value: []byte("Alice"), Index: true},
    73                  {Key: []byte("balance"), Value: []byte("100"), Index: true},
    74                  {Key: []byte("note"), Value: []byte("nothing"), Index: true},
    75              },
    76          },
    77      }
    78      return types.ResponseDeliverTx{Code: code.CodeTypeOK, Events: events}
    79  }
    80  ```
    81  
    82  The transaction will be indexed (if the indexer is not `null`) with a certain
    83  attribute if the attribute's `Index` field is set to `true`. In the above
    84  example, all attributes will be used.
    85  
    86  ## Querying Transactions
    87  
    88  You can query the transaction results by calling `/tx_search` RPC endpoint:
    89  
    90  ```bash
    91  curl "localhost:26657/tx_search?query=\"account.name='igor'\"&prove=true"
    92  ```
    93  
    94  Check out [API docs](https://docs.tendermint.com/master/rpc/#/Info/tx_search) for more information
    95  on query syntax and other options.
    96  
    97  ## Subscribing to Transactions
    98  
    99  Clients can subscribe to transactions with the given tags via WebSocket by providing
   100  a query to `/subscribe` RPC endpoint.
   101  
   102  ```json
   103  {
   104    "jsonrpc": "2.0",
   105    "method": "subscribe",
   106    "id": "0",
   107    "params": {
   108      "query": "account.name='igor'"
   109    }
   110  }
   111  ```
   112  
   113  Check out [API docs](https://docs.tendermint.com/master/rpc/#subscribe) for more information
   114  on query syntax and other options.