Rust ORM Partial Loading: SQL NULL vs NotLoaded
In a Rust ORM, partial loading creates two different kinds of missing data: a selected column can contain SQL NULL, or the query can leave a field unselected. The application needs to preserve that distinction when reading an entity.
Rust's Option<T> is one of the language's best tools. It forces absence into
the type system and eliminates an entire class of null-pointer failures.
But an ORM or data runtime has another state that Option<T> cannot express on
its own: the field was not loaded.
If both SQL NULL and an unselected column become None, business logic cannot
tell a legitimate absence from an incomplete query. TeaQL Rust models the
missing state explicitly with EvalResult::Value, EvalResult::Null, and
EvalResult::NotLoaded.
SQL NULL vs an unloaded field: the short answer
SQL NULL is a value observed in a selected column. An unloaded field has no observed database value yet. A null default can handle the first state; it must not silently handle the second.
| Query result | Application meaning | Next step |
|---|---|---|
| Selected field with a value | The value is available. | Use it. |
| Selected field containing SQL NULL | The value is known to be absent. | Apply the business rule for null. |
| Field omitted from the projection | Its value is unknown to this read. | Select it before evaluating it. |
Rust's Option<T>
has Some and None variants. A single Option<String> cannot also encode
whether the column was selected. A nested option, separate projection type or
explicit load-state enum can carry that extra information. TeaQL chooses an
explicit load-state contract; the issue is preserving information, not replacing
Rust's null-safety model.
Why Option is not enough for partially loaded entities
Suppose an order may legitimately have no cancellation reason. This is a normal nullable value:
match order.eval_cancellation_reason() {
EvalResult::Null => println!("The order was not cancelled"),
EvalResult::Value(reason) => println!("Cancelled: {reason}"),
EvalResult::NotLoaded { .. } => unreachable!("query contract violation"),
}
Now suppose the query selected only the order ID. Returning None for the same
access would be false information: the runtime does not know whether a reason
exists.
TeaQL preserves that distinction until evaluation.
| State | What the runtime knows | Strict E behavior |
|---|---|---|
Value(value) | Selected and present | returns the value |
Null | Selected and absent | evaluates to None |
NotLoaded | Not selected | structured panic at the boundary |
Fluent E Expressions Without Cloning the Graph
The generated E API uses reference-bound wrappers, so a deep traversal does not clone the entity graph:
let merchant_name = E::merchant(&merchant)
.get_name()
.eval();
The result is Some(name) for Value and None for a loaded Null. If a required
relation or field is NotLoaded, the terminating operation panics with a
structured logic-bug diagnostic.
For a fallback that applies only to Null, the API is deliberately explicit:
let label = E::merchant(&merchant)
.get_name()
.or_if_null("Anonymous".to_string());
or_if_null, or_else_if_null, and or_default_if_null do not catch
NotLoaded. A default value must never turn an incomplete query into a plausible
business result.
Why Panic Is Appropriate Here
This is not an operational failure such as a timeout or unavailable database. It is a programming error: code accessed data outside the declared query contract.
At an application boundary, silently converting that error to None is more
dangerous than stopping the test. A strict panic makes the defect deterministic
and places it next to the expression that made the invalid assumption.
The diagnostic identifies:
- the root entity and identity;
- the complete attempted access path;
- the field or relation where traversal stopped;
- the missing preload;
- a query-builder correction to review.
This is especially useful in generated APIs because the repair can refer to real generated selection methods instead of asking a coding agent to invent one.
The Test Becomes a Query-Completeness Check
A conventional test often verifies only the final value. A TeaQL E-expression test also verifies that the value was obtained from data the query explicitly requested.
#[test]
fn display_name_requires_the_selected_field() {
let expression = ValueExpression::<'static, String>::new(
EvalResult::NotLoaded {
failed_node: "name".to_owned(),
attempted_path: "name".to_owned(),
},
std::sync::Arc::new("Merchant(id=42)".to_owned()),
);
let result = std::panic::catch_unwind(|| {
expression.or_if_null("Anonymous".to_string())
});
assert!(result.is_err());
}
After the request adds the generated display-name selection, the same test becomes evidence that both the query and the expression agree about their data contract.
Why AI Can Repair This Reliably
An AI agent is good at local transformations when the framework supplies exact evidence. It is much less reliable when a late failure could have originated in dozens of queries.
NotLoaded narrows the task:
root: Merchant(id=42)
access path: name
break point: name
suggested preload: select_name(...)
The agent uses the current model and field-scoped Assist to identify the exact
selection, changes the application query, compiles and reruns the affected test.
Business API discovery does not require reading generated-library source. Report
MISSING_ASSIST with the field and diagnostic when the contract is missing or
contradictory. That keeps the repair local to the query that omitted the data.
Fix a NotLoaded error without hiding it
- Read the missing-field path and find the application query that produced the entity.
- Check that the scalar and every required relation were selected. A relation preview may still be incomplete for the operation that follows.
- Obtain the current field selection from Assist, add it to the query and keep the existing authorization predicates and row bounds.
- Rerun the read and its business assertion. Test selected-null and omitted-field cases separately; adding a fallback should not turn the latter into success.
The retained Rust Order example makes this observable with note-null and
note-not-loaded: the first selects the nullable note, while the second omits
it and probes both evaluation and null-only fallback. Use the
complete native source,
Order walkthrough and
dated SQLite receipt
together. This Order workspace retains WORKSPACE PASS — RELEASE PENDING for
its pagination repairs; nullable/pagination Assist is pending generator
deployment. Those qualifications are separate from the original August
expression examples above.
The selected-note request is taken directly from that application, with its
existing context and number variables:
let order=Q::customer_orders_minimal().select_order_note().with_order_number_is(number).limit(2)
.comment("Select nullable order note").purpose("Verify loaded note and null-only default").execute_for_one(&context).await?.ok_or("Missing order")?;
The negative probe deliberately selects only the Order number:
let order=Q::customer_orders_minimal().select_order_number().with_order_number_is("ORD-2026-1001").limit(2)
.comment("Omit order note from projection").purpose("Expose missing-field errors").execute_for_one(&context).await?.ok_or("Missing order")?;
The complete application then evaluates the note and its null-only fallback. These are function-body excerpts, not standalone Rust files; retain the imports, startup and assertion handlers from the linked application.
Cross-Language Evidence
The original August implementation report and the newer Order receipts are different evidence scopes. The public Order source and dated receipt linked above record selected value, SQL NULL, empty text and omitted-field probes in seven native languages. Read each runtime's package/workspace qualification; one passing language or an old regression total is not evidence that every current published package has the same verified combination.
The key lesson is broader than TeaQL: a type-safe application should model not only whether a value exists, but whether the program had enough data to ask the question in the first place.
Apply the distinction in an Order query
The Rust Order tutorial shows a complete scalar/relation read and the native E result path. Its debugging guide helps trace a missing preload rather than masking it with a null default. Use the query API versus handwritten SQL comparison when deciding which layer should express the query.
This article records its original implementation and tests. The linked tutorials carry their own dated runtime qualifications, including pending-release markers.
