ApexEloquent Guide
ApexEloquent is the central OSS of Apex Stem — handling SOQL and DML through a "typed, composable query builder" and a "DI-aware data access layer". Structured in four tiers: Setup (prerequisites and installation), Guide (how to use it in production code), API Reference (the full API of each class), and Deep Dives (the motivations behind the design).
About versions
There are two current lines, v3 and v2. The only difference is the execution mode: on the v3 line, SOQL and DML default to user mode, honouring the running user's field and object permissions. Everything else is the same.
These guides are written as shared content, calling out only the mode difference where it matters. You can check which version you are on with:
git -C force-app/main/default/classes/ApexEloquent describe --tagsSetup
The path to installing ApexEloquent into your org for the first time — starting from environment setup.
Prerequisites
Four steps to set up Salesforce CLI, the target org, and the make command before installing ApexEloquent.
Installation Guide
The two install paths side by side — one-command Unlocked Package install (recommended) and the Git Submodule + make install flow — plus how to update on each.
Guide
Typical scenarios in production code, explained in the context of Usecases / Handlers.
Building Queries with Scribe
How to use Scribe, the typed method-chain query builder. SELECT, WHERE, sorting, aggregation, and dynamic query construction — all in one piece.
Data Access, DML, IEntry, and Mock
Data retrieval and DML via the IEloquent interface, working with IEntry, and tests with MockEloquent. Integration with the Layered Constructor Pattern, plus Spy / failOn verification.
Parent Fields, Child Subqueries, and Many-to-Many
How to assemble parent relations, child subqueries, and many-to-many via junction objects with Scribe — plus how to mock parent-child structures using MockEntry setParent / setChildren.
API Reference
A detailed reference covering every API of each class with signatures.
Scribe
A detailed reference of the full Scribe query-builder API. Static factories, SELECT, WHERE, sorting, aggregate functions, GROUP BY / HAVING, and inspection methods — all covered.
IEloquent / Eloquent / MockEloquent
API reference for the data-access interface, its production implementation Eloquent, and the test implementation MockEloquent. Common contracts, Spy properties, and the failOn series — all covered.
IEntry / Entry / MockEntry
API reference for the record-wrapper interface, the production Entry, and the test MockEntry. Field / relation operations plus the test-side extension API (set / template / setParent / setChildren / autoId / alias / asAggregateResult and more).
Deep Dives
Reading material that digs into why ApexEloquent ended up in this form — the design philosophy, the Repository pattern's resting place in Apex, migration from raw SOQL, and more.
Query Delegation Pattern
The design philosophy of ApexEloquent. Starting from the long-term operational challenges of the Selector Pattern, the article lays out what problems are solved by separating query construction from execution, and how Scribe / IEloquent / IEntry embody that.
The Repository Pattern in Apex: Trial, Error, and Going Built-In
What happens when you write the Repository pattern naively in Apex, how it relates to Salesforce's official Selector Pattern, and why ApexEloquent ships a "built-in Repository" as IEloquent — contrasting the official benefits against long-term operational side effects.
From Raw SOQL to a Chained-Method ORM in Apex
A migration primer that walks through the cost we're paying in raw-SOQL-centric Apex development (readability / dynamic conditions / type safety / relations / testing), and how Scribe + IEloquent lighten that load — example-based.
MockEntry: How Apex Test Data Construction Becomes Possible
A comprehensive look at how MockEntry's override map, SELECT-omission detection, setParent / setChildren, the times placeholder, and aggregate-result mocking resolve the two great difficulties of Apex testing: non-writable fields (formula / rollup / auto-number / relationship names) and the difficulty of building parent-child structures.
Catching Mock-Test False Positives: A Safety Net for SELECT Omissions
Demonstrates how ApexEloquent structurally closes the "passes in tests, fails in production" type of false-positive problem through Scribe coordination — proven with real-code pairs of "buggy Usecase + the test that catches it" across four cases (primary object / parent relation / child subquery / aggregate alias).
Read Next
- Layered Constructor Pattern: the design for DI'ing
IEloquentinto a Usecase by role - Test Strategy: where Usecase unit tests centered on
MockEloquentsit - Apex Stem Introduction Guide: four steps with working code
- ApexEloquent on GitHub: source code and the latest info