Docs
Search⌘ K
  • Home
  • About The Graph
  • Supported Networks
  • Protocol Contracts
  • AI Tooling
  • Subgraphs
    • Substreams
      • Indexer Software
        • Gateway Software
          • Data Services
            • Resources
              Subgraphs > Guides & Best Practices

              4 minutes

              Use Immutable Entities and Bytes as IDs

              Two schema changes significantly improve indexing speed, query performance, and storage: marking entities that never change as immutable, and using Bytes for IDs.

              Immutable Entities

              To make an entity immutable, add (immutable: true) to it:

              1type Transfer @entity(immutable: true) {2  id: Bytes!3  from: Bytes!4  to: Bytes!5  value: BigInt!6}

              When the Transfer entity is immutable, Graph Node processes it more efficiently, which speeds up indexing and queries.

              An immutable entity never changes after it is created. The best candidates are entities that log onchain event data directly, such as a Transfer event stored as a Transfer entity.

              Under the Hood

              Mutable entities have a ‘block range’ indicating their validity. Updating these entities requires Graph Node to adjust the block range of previous versions, increasing database workload. Queries also need filtering to find only live entities. Immutable entities are faster because they are all live and since they won’t change, no checks or updates are required while writing, and no filtering is required during queries.

              When Not to Use Immutable Entities

              If an entity has a field that changes over time, such as status, do not make it immutable: a write to an immutable entity causes an indexing error. Otherwise, use immutable entities whenever possible.

              Bytes as IDs

              Every entity requires an ID. In the previous example, the ID is already of type Bytes.

              1type Transfer @entity(immutable: true) {2  id: Bytes!3  from: Bytes!4  to: Bytes!5  value: BigInt!6}

              Other ID types, such as String and Int8, are possible, but use Bytes for all IDs where you can. Character strings take twice as much space as byte strings to store binary data, and comparing UTF-8 strings must take the locale into account, which costs much more than the bytewise comparison used for Bytes.

              Reasons to Not Use Bytes as IDs

              1. Entity IDs must be human-readable, such as auto-incremented numbers or readable strings.
              2. The Subgraph’s data must integrate with another data model that does not use Bytes IDs.
              3. Indexing and query performance are not a concern for this entity.

              Concatenating With Bytes as IDs

              It is a common practice in many Subgraphs to use string concatenation to combine two properties of an event into a single ID, such as using event.transaction.hash.toHex() + "-" + event.logIndex.toString(). Because this returns a string, it significantly slows indexing and queries.

              Instead, use the concatI32() method to concatenate event properties. The result is a Bytes ID that is much faster to store and compare.

              1export function handleTransfer(event: TransferEvent): void {2  let entity = new Transfer(event.transaction.hash.concatI32(event.logIndex.toI32()))3  entity.from = event.params.from4  entity.to = event.params.to5  entity.value = event.params.value67  entity.blockNumber = event.block.number8  entity.blockTimestamp = event.block.timestamp9  entity.transactionHash = event.transaction.hash1011  entity.save()12}

              Sorting With Bytes as IDs

              Sorting by a Bytes ID does not give numeric order, as this example query and response show.

              Query:

              1{2  transfers(first: 3, orderBy: id) {3    id4    from5    to6    value7  }8}

              Query response:

              1{2  "data": {3    "transfers": [4      {5        "id": "0x00010000",6        "from": "0xabcd...",7        "to": "0x1234...",8        "value": "256"9      },10      {11        "id": "0x00020000",12        "from": "0xefgh...",13        "to": "0x5678...",14        "value": "512"15      },16      {17        "id": "0x01000000",18        "from": "0xijkl...",19        "to": "0x9abc...",20        "value": "1"21      }22    ]23  }24}

              The IDs are returned and sorted as hex.

              To sort by a number, add a BigInt field to the entity:

              1type Transfer @entity {2  id: Bytes!3  from: Bytes! # address4  to: Bytes! # address5  value: BigInt! # unit2566  tokenId: BigInt! # uint2567}

              Then order by that field:

              Query:

              1{2  transfers(first: 3, orderBy: tokenId) {3    id4    tokenId5  }6}

              Query Response:

              1{2  "data": {3    "transfers": [4      {5        "id": "0x…",6        "tokenId": "1"7      },8      {9        "id": "0x…",10        "tokenId": "2"11      },12      {13        "id": "0x…",14        "tokenId": "3"15      }16    ]17  }18}

              Results

              In a controlled test, using immutable entities and Bytes IDs together cut time per block by 28%, sync time by 26%, and storage by 48%. See Benchmarks and Evidence for the full comparison.

              Learn More

              • Two Simple Subgraph Performance Improvements: the original benchmark by David Lutterkort.
              • Guides & Best Practices overview: the full checklist and how this page fits with the rest of the section.
              ⁠Edit on GitHub⁠

              Avoid eth_callsArrays with @derivedFrom
              On this page
              • Immutable Entities
              • Under the Hood
              • When Not to Use Immutable Entities
              • Bytes as IDs
              • Reasons to Not Use Bytes as IDs
              • Concatenating With Bytes as IDs
              • Sorting With Bytes as IDs
              • Results
              • Learn More
              The GraphStatusTestnetBrand AssetsForumSecurityPrivacy PolicyTerms of Service