Skip to main content

Rust ORM Partial Loading: SQL NULL vs NotLoaded

· 7 min read
Philip Z
Architect

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 resultApplication meaningNext step
Selected field with a valueThe value is available.Use it.
Selected field containing SQL NULLThe value is known to be absent.Apply the business rule for null.
Field omitted from the projectionIts 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.

StateWhat the runtime knowsStrict E behavior
Value(value)Selected and presentreturns the value
NullSelected and absentevaluates to None
NotLoadedNot selectedstructured 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​

  1. Read the missing-field path and find the application query that produced the entity.
  2. Check that the scalar and every required relation were selected. A relation preview may still be incomplete for the operation that follows.
  3. Obtain the current field selection from Assist, add it to the query and keep the existing authorization predicates and row bounds.
  4. 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.