indexer-schema

name	indexer-schema
description	Use when defining or editing schema.graphql. Entity types, scalar types, enums, relationships, @derivedFrom, @index, @config directives, array rules, naming conventions, and schema-to-TypeScript type mapping.
metadata	{"managed-by":"envio"}

Schema Reference (schema.graphql)

Entity Rules

• Every type is an entity — no @entity decorator (unlike TheGraph)
• Must have an id field first — ID! (recommended), or String!, Int!, BigInt!
• Names: 1-63 chars, alphanumeric + underscore, no reserved words
• Relationship fields use the entity type directly: collection: NftCollection! — never add _id in the schema field name
• The _id suffix only appears in TypeScript handlers (added by codegen): schema field collection → handler field collection_id, typed as the referenced entity's id

Scalar Types

Schema Type	TypeScript Type	Notes
ID!	string	Recommended entity id; String!/Int!/BigInt! also allowed as id
String!	string
Int!	number
Float!	number
Boolean!	boolean
BigInt!	bigint	Use @config(precision: N) for custom precision
BigDecimal!	BigDecimal	Use @config(precision: N, scale: M)
Bytes!	string	Hex-encoded
Timestamp!	Date
Json!	any

Enums

enum Status {
  Active
  Inactive
  Paused
}

type Pool {
  id: ID!
  status: Status!
  allowedStatuses: [Status!]!  # enum arrays supported
}

@derivedFrom

Virtual reverse-lookup — cannot access in handlers, only in API queries:

type Pool {
  id: ID!
  swaps: [Swap!]! @derivedFrom(field: "pool")
}

type Swap {
  id: ID!
  pool: Pool!  # entity reference — field name matches @derivedFrom "field" arg
}

Critical rules:

• The field argument must match the schema field name on the child entity — which is the entity reference name ("pool"), not "pool_id"
• In TypeScript handlers, set this relationship using the _id suffix: pool_id: poolEntity.id — codegen transforms pool: Pool! → pool_id in the TypeScript type
• Never write pool_id: String! in the schema when using @derivedFrom(field: "pool"). The schema field must be pool: Pool!; the _id is a codegen artifact for handlers only

@index

Single-field index for faster queries:

type Transfer {
  id: ID!
  from: String! @index
  to: String! @index
  timestamp: BigInt! @index
}

Composite index with optional DESC direction:

type Trade @index(fields: ["poolId", ["date", "DESC"]]) {
  id: ID!
  poolId: String!
  date: BigInt!
  volume: BigDecimal!
}

• Fields default to ASC; use ["field", "DESC"] for descending
• IDs and @derivedFrom fields are automatically indexed
• Any non-derived field is queryable via context.Entity.getWhere(). Indexes are never created up front: @index fields are built together when the backfill finishes, before the indexer reports ready, and any field — marked or not — is indexed on the spot if a getWhere needs it earlier, pausing indexing while it builds

@config

Customize precision for numeric types:

type Token {
  id: ID!
  totalSupply: BigInt! @config(precision: 100)
  price: BigDecimal! @config(precision: 30, scale: 15)
}

• BigInt default precision: 76 digits
• BigDecimal default: precision 76, scale 32

Array Rules

• Supported: [Type!]! — non-nullable elements, non-nullable array
• Not supported: [Type]! (nullable elements), nested arrays, [Boolean!]!, [Timestamp!]!
• Entity arrays require @derivedFrom — bare [Swap!]! without it causes a codegen error

Example

enum PoolType {
  UniswapV2
  UniswapV3
}

type Token {
  id: ID!
  symbol: String!
}

type Pool @index(fields: ["token0", "token1"]) {
  id: ID!
  poolType: PoolType!
  token0: Token!   # entity reference — handler uses token0_id
  token1: Token!   # entity reference — handler uses token1_id
  reserve0: BigInt!
  reserve1: BigInt!
  totalValueLocked: BigDecimal! @config(precision: 30, scale: 15)
  swaps Swap    


 Swap 
   ID
   Pool    
   String 
   BigInt
   BigInt
   BigInt 

Schema vs handler field names (entity refs to ID!-keyed entities):

Schema field	Schema type	TypeScript handler field
pool	Pool!	pool_id: string
token0	Token!	token0_id: string
collection	NftCollection!	collection_id: string

Codegen appends _id to entity reference fields (never add it in the schema), typed as the referenced entity's id.

If something is unclear, use the envio-docs skill to search and read the latest documentation.