Entity storage for MongoDB

Entity mode is used to store entities in the collection. Entities represent the state of an object at a specific point in time.


You can index entities by setting the entityMode option to true. When you set this option, the indexer expects the transform function to return a list of update operations. An update operation is a JavaScript object with an entity property used to filter which entities should be updated, and an update property with either an update document or an aggregation pipeline.


In this example, the indexer tracks token ownership for an ERC-721 smart contract together with the number of transactions for each token.

We enable entity storage by setting the entityMode option to true. The transform function returns the entities that need update, together with the operation to update their state.

export const config = {
  sinkType: "mongo",
  sinkOptions: {
    entityMode: true,
    collectionName: "owners",

export default function transform(block: Block) {
  // Example to show the shape of data returned by transform.
  return [
      entity: { contract, tokenId: "1" },
      update: { $set: { owner: "0xA" }, $inc: { txCount: 1 } },
      entity: { contract, tokenId: "2" },
      update: { $set: { owner: "0xB" }, $inc: { txCount: 3 } },

The integration will iterate through the new entities and update the existing values (if any) using the following MongoDB pseudo-query:

for (const doc of returnValue) {
    filter: doc.entity,
    update: doc.update,
    options: {
      upsert: true,

Notice that in reality the query is more complex.

Last modified
Edit on GitHub

Apibara is the fastest platform to build production-grade indexers that connect onchain data to web2 services.

© 2024 GNC Labs Limited. All rights reserved.