Indexes

Queries against the ledger are done via database indexes. This document explains how to use them.

List queries such as accounts, accountSets, tranCodes, and transactions read records through an index. The index argument picks the index, and where filters on the fields that index uses. A filter on a field the index does not use is an error, such as where 'name' not allowed on this index.

For the indexes available on each record type, and for creating your own, see the ledger Indexes reference.

Choosing an Index

  • To read one record, use its ID: account(id:), accountSet(id:), tranCode(id:), or transaction(id:).
  • To find one record by a unique key, use the index for that key with an eq filter, such as CODE with code: { eq: "..." } or EXTERNAL_ID with externalId: { eq: "..." }.
  • To list many records, use the index whose sort order you want, and narrow it with where.

Consistency of Reads

Reads by ID and lookups by unique key are strongly consistent. They see every committed write, and inside a transaction they also see the transaction's own earlier writes.

Some listings read from asynchronous indexes, which Twisp updates after a write commits:

  • accounts with index NAME or STATUS, or with index CODE and no eq filter on code.
  • accountSets with index NAME, or with index CODE and no eq filter on code.
  • AccountSet.members.
  • The actions, executions, and sessions lists under actions.

Through these listings:

  • A record that was just created or changed can be missing for a short time after the write commits, usually under a second.
  • Inside one transaction, records the same transaction wrote are not included. One transaction covers every operation in a GraphQL request, a tool call, and an MCP program program.

The Built-In Async Indexes table has the full list. To get a record you just wrote, read it by ID or by unique key. Use listings to browse and report, and allow for a short delay after a write.

Example

This request creates an account, then reads it in the same transaction. The queries field runs query operations inside a mutation, after the operations before it. The read by ID and the lookup by code return the new account. The NAME listing does not, even with an eq filter, because NAME is an asynchronous index.

mutation CreateThenRead {
  createAccount(
    input: {
      accountId: "2f6fa0c2-9b8e-4d8e-9a43-2a1d3c5e7f10"
      code: "WALLET-ALICE"
      name: "Alice"
      normalBalanceType: CREDIT
    }
  ) {
    accountId
  }
  queries {
    byId: account(id: "2f6fa0c2-9b8e-4d8e-9a43-2a1d3c5e7f10") {
      code
    }
    byCode: accounts(
      index: { name: CODE }
      where: { code: { eq: "WALLET-ALICE" } }
      first: 1
    ) {
      nodes {
        code
      }
    }
    byName: accounts(
      index: { name: NAME }
      where: { name: { eq: "Alice" } }
      first: 1
    ) {
      nodes {
        code
      }
    }
  }
}
{
  "data": {
    "createAccount": {
      "accountId": "2f6fa0c2-9b8e-4d8e-9a43-2a1d3c5e7f10"
    },
    "queries": {
      "byId": { "code": "WALLET-ALICE" },
      "byCode": { "nodes": [{ "code": "WALLET-ALICE" }] },
      "byName": { "nodes": [] }
    }
  }
}

The same NAME query, sent in a new request a moment after this one commits, returns the account.

Previous
Pagination