# Store Entities — Advanced Features

Advanced patterns for persistent state management with Sentio's entity store.

## Schema Definition (`schema.graphql`)

Define entities in `schema.graphql` (or `store.graphql`) in project root. Types are auto-generated by `sentio gen` into `src/schema/store.js`.

### Basic Entity

```graphql
type AccountSnapshot @entity {
  id: ID!
  timestampMilli: BigInt!
  balance: BigInt!
}
```

**Supported scalar types:** `Int`, `Float`, `String`, `Boolean`, `ID`, `BigInt`, `BigDecimal`

### Indexed Fields

Use `@index` for fast queries on frequently filtered fields:

```graphql
type User @entity {
  id: ID!
  name: String! @index
  balance: BigDecimal!
}
```

### Relationships (`@derivedFrom`)

```graphql
type Company @entity {
  id: ID!
  employees: [Employee!] @derivedFrom(field: "company")
}

type Employee @entity {
  id: ID!
  company: Company!
}
```

## CRUD Operations

```typescript
import { AccountSnapshot } from "./schema/store.js"

// Get by ID
const snapshot = await ctx.store.get(AccountSnapshot, accountId)

// Upsert (create or update)
await ctx.store.upsert(new AccountSnapshot({
  id: account,
  timestampMilli: BigInt(ctx.timestamp.getTime()),
  balance: newBalance,
}))

// Batch upsert
const snapshots = accounts.map(a => new AccountSnapshot({ ... }))
await ctx.store.upsert(snapshots)

// List with filters (loads all into memory)
const users = await ctx.store.list(AccountSnapshot, [
  { field: "balance", op: ">", value: 0 },
  { field: "name", op: "=", value: "Alice" },
])

// List all entities (empty filter required)
const allAccounts = await ctx.store.list(AccountSnapshot, [])

// Iterator (memory-efficient for large datasets)
for await (const user of ctx.store.listIterator(AccountSnapshot, [
  { field: "balance", op: ">", value: 0 },
])) {
  // process one at a time
}

// Delete
await ctx.store.delete(AccountSnapshot, accountId)
```

### Filter Operators

Multiple filters combine with AND.

| Operator | Description |
|----------|-------------|
| `=` | Equal |
| `!=` | Not equal |
| `>` | Greater than |
| `>=` | Greater than or equal |
| `<` | Less than |
| `<=` | Less than or equal |
| `in` | In array |
| `not in` | Not in array |

## Sequential Execution

**Critical:** When using store entities, enable sequential execution to prevent race conditions:

```typescript
import { GLOBAL_CONFIG } from "@sentio/runtime"

GLOBAL_CONFIG.execution = {
  sequential: true,
}
```

Without this, concurrent event handlers may read stale data and overwrite each other's changes.

## Multi-Entity Schema Examples

**Lending protocol (supply + borrow):**
```graphql
type AccountSnapshot @entity {
  id: String!
  timestampMilli: BigInt!
  supplyBalance: BigInt!
  borrowBalance: BigInt!
}
```

**NFT Position (concentrated liquidity):**
```graphql
type PositionSnapshot @entity {
  id: String!
  owner: String!
  tickLower: BigInt!
  tickUpper: BigInt!
  timestampMilli: BigInt!
  token0Balance: BigDecimal!
  token1Balance: BigDecimal!
}

type StakedPositionSnapshot @entity {
  id: String!
  owner: String!
}
```

**Pool entity:**
```graphql
type Pool @entity {
  id: ID!
  token0: String!
  token1: String!
  fee: BigInt!
  tvl: BigDecimal!
}
```