EOSIO MongoDB Queries

Quickly and easily create complex MongoDB Queries for the EOSIO blockchain.

Install

npm

$ yarn add eosio-mongodb-queries

web

<script src="https://wzrd.in/standalone/eosio-mongodb-queries@latest"></script>

Quickstart

import { MongoClient } from "mongodb";
import { getAccount } from "eosio-mongodb-queries";

(async () => {
    const client = await MongoClient.connect("mongodb://localhost:27017", { useNewUrlParser: true });

    // Optional Parameters
    const options = {
        gte_block_num: 0,
        lte_block_num: Infinity,
    };
    const result = await getAccount(client, "eosnationftw", options);
    // {
    //   name: 'eosnationftw',
    //   block_num: 6101090,
    //   stake_quantity: 2.8,
    //   stake_net_quantity: 0.4,
    //   stake_cpu_quantity: 2.4
    // }
})();

EOSIO Full Node

You must first enable the MongoDB plugin to your EOSIO full node by including the following to your configuration.

config.in

# Override default maximum ABI serialization time allowed in ms (eosio::chain_plugin)
abi-serializer-max-time-ms = 5000

# Plugin(s) to enable, may be specified multiple times
plugin = eosio::mongo_db_plugin

# MongoDB URI connection string, see: https://docs.mongodb.com/master/reference/connection-string/. If not specified then plugin is disabled. Default database 'EOS' is used if not specified in URI. Example: mongodb://127.0.0.1:27017/EOS (eosio::mongo_db_plugin)
mongodb-uri = mongodb://localhost:27017

Replay Blocks

To allow actions to be decoded from the ABI, you must replay all blocks from the genesis.

$ nodeos --replay-blockchain --hard-replay-blockchain --mongodb-wipe

More Information on EOSIO GitHub

Query Ideas

• [ ] Vote Tally for eosio.forum (submitted by Denis from EOS Nation)
• [ ] Block Producer votes & positions (submitted by Nathan from GenerEOS)
• [ ] Name auction for all-time bids or current bid (submitted by Syed from EOS Cafe)

References

MongoDB Pipeline

• https://docs.mongodb.com/manual/reference/operator/aggregation-pipeline/
• https://docs.mongodb.com/manual/reference/operator/aggregation/graphLookup/

Contributors

This is made with ♥ by:

• EOS Nation (eosnationftw)

Voting on the EOSIO mainnet helps build more awesome tools for the EOS community.

API

Table of Contents

• getActions
  • Parameters
  • Examples
• getBlocks
  • Parameters
  • Examples
• getAccountControls
  • Parameters
  • Examples
• setDefaultLimit
  • Parameters
  • Examples
• addBlockFiltersToPipeline
  • Parameters
• getAccount
  • Parameters
  • Examples
• getAccounts
  • Parameters
  • Examples

getActions

EOSIO MongoDB Actions

Parameters

• client MongoClient MongoDB Client
• options Object Optional Parameters (optional, default {})
  • options.account (string | Array<string>)? Filter by account contracts (eg: ["eosio","eosio.token"])
  • options.name (string | Array<string>)? Filter by action names (eg: ["undelegatebw", "delegatebw"])
  • options.limit number Limit the maximum amount of of actions returned (optional, default 25)
  • options.skip number? Skips number of documents
  • options.sort object? Sort by ascending order (1) or descending order (-1) (eg: {block_num: -1})
  • options.match object? Match by entries using MongoDB's $match (eg: {"data.from": "eosio"})
  • options.trx_id string? Filter by exact Transaction Id
  • options.irreversible boolean? Irreversible transaction (eg: true/false)
  • options.block_num number? Filter by exact Reference Block Number
  • options.block_id string? Filter by exact Reference Block ID
  • options.lte_block_num number? Filter by Less-than or equal (<=) the Reference Block Number
  • options.gte_block_num number? Filter by Greater-than or equal (>=) the Reference Block Number

Examples

const options = {
    account: "eosio",
    name: ["delegatebw", "undelegatebw"],
    match: {"data.from": "eosnationftw", "data.receiver": "eosnationftw"},
    irreversible: true,
    sort: {block_num: -1}
};
const results = await getActions(client, options);
console.log(await results.toArray());

Returns AggregationCursor<Actions> MongoDB Aggregation Cursor

getBlocks

EOSIO MongoDB Blocks

Parameters

• client MongoClient MongoDB Client
• options Object Optional Parameters (optional, default {})
  • options.limit number Limit the maximum amount of of actions returned (optional, default 25)
  • options.skip number? Skips number of documents
  • options.sort object? Sort by ascending order (1) or descending order (-1) (eg: {block_num: -1})
  • options.match object? Match by entries (eg: {"block.producer": "eosio"})
  • options.block_num number? Filter by exact Reference Block Number
  • options.block_id string? Filter by exact Reference Block ID
  • options.lte_block_num number? Filter by Less-than or equal (<=) the Reference Block Number
  • options.gte_block_num number? Filter by Greater-than or equal (>=) the Reference Block Number

Examples

const options = {
    match: {"block.producer": "eosnationftw"},
    sort: {block_num: -1}
};
const results = await getBlocks(client, options);
console.log(await results.toArray());

Returns AggregationCursor<Blocks> MongoDB Aggregation Cursor

getAccountControls

EOSIO MongoDB Account Controls

Parameters

• client MongoClient MongoDB Client
• options Object Optional Parameters (optional, default {})
  • options.limit number Limit the maximum amount of of actions returned (optional, default 25)
  • options.sort object? Sort by ascending order (1) or descending order (-1) (eg: {controlled_account: -1})
  • options.skip number? Skips number of documents
  • options.match object? Match by entries (eg: {controlled_account: "eosio.saving"})

Examples

const options = {
    match: {controlled_account: "eosio.saving"},
};
const results = await getAccounControls(client, options);
console.log(await results.toArray());

Returns AggregationCursor<AccountControls> MongoDB Aggregation Cursor

setDefaultLimit

Set default limit

Parameters

• options object Optional Parameters (optional, default {})

Examples

setDefaultLimit() //=> 25

Returns number Default Limit value

addBlockFiltersToPipeline

Add Block Filters to Pipeline

Parameters

• pipeline Array<object> MongoDB Pipeline
• options object Optional Parameters (optional, default {})
  • options.irreversible boolean? Irreversible transaction (eg: true/false)
  • options.block_num number? Filter by exact Reference Block Number
  • options.block_id string? Filter by exact Reference Block ID
  • options.lte_block_num number? Filter by Less-than or equal (<=) the Reference Block Number
  • options.gte_block_num number? Filter by Greater-than or equal (>=) the Reference Block Number

Returns void Appends results to pipeline

getAccount

Get Account Details

Parameters

• client MongoClient MongoDB Client
• name string Account Name
• options Object Optional Parameters (optional, default {})
  • options.lte_block_num number? Filter by Less-than or equal (<=) the Reference Block Number

Examples

const name = "eosnationftw";
const options = {
  block_num: 6000000,
};
const result = await getAccount(client, name, options);
// {
//   name: 'eosnationftw',
//   block_num: 2092984,
//   stake_quantity: 1.8,
//   stake_net_quantity: 0.9,
//   stake_cpu_quantity: 0.9,
//   actions: [...Actions]
// }

Returns Object Account Details

getAccounts

EOSIO MongoDB Accounts

Parameters

• client MongoClient MongoDB Client
• options Object Optional Parameters (optional, default {})
  • options.abi boolean? Does abi exist (eg: true/false)
  • options.limit number Limit the maximum amount of of actions returned (optional, default 25)
  • options.sort object? Sort by ascending order (1) or descending order (-1) (eg: {controlled_account: -1})
  • options.skip number? Skips number of documents
  • options.match object? Match by entries (eg: {controlled_account: "eosio.saving"})

Examples

const options = {
    match: {controlled_account: "eosio.saving"},
};
const results = await getAccounControls(client, options);
console.log(await results.toArray());

Returns AggregationCursor<AccountControls> MongoDB Aggregation Cursor