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:), ortransaction(id:). - To find one record by a unique key, use the index for that key with an
eqfilter, such asCODEwithcode: { eq: "..." }orEXTERNAL_IDwithexternalId: { 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:
accountswith indexNAMEorSTATUS, or with indexCODEand noeqfilter oncode.accountSetswith indexNAME, or with indexCODEand noeqfilter oncode.AccountSet.members.- The
actions,executions, andsessionslists underactions.
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
programprogram.
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.