FaunaDB FQL v10 UDFs and client driver: serializability guarantees across regions

Direct answer

In Fauna FQL v10, a UDF invocation is executed server-side as part of the transaction that carries the query. Strict serializability is a property of that transaction. It is not reported as a REST header or response field, and official client drivers do not expose a per-request read-consistency or isolation-level option. If your code contains a consistency, readConcern, or isolation setting, treat it as custom or inherited from another database until proven otherwise.

What the REST response actually contains

FQL v10 sends the entire query—including the UDF call—over the HTTP query API. The response is primarily the query result. It may include telemetry such as a transaction timestamp or operation summary/stats, but these describe execution, not a negotiated isolation mode. A timestamp should be read as the transaction visibility point, not as evidence of a consistency level. Do not infer serializability from latency or stats; those are telemetry and may omit internal coordination details.

Driver behavior

Official drivers are transport wrappers: they manage endpoint, credentials, timeouts, retries, and result decoding. They do not alter the consistency applied to a UDF. To confirm for your version, inspect the driver's exported options or type definitions for names like consistency, readConcern, isolation, or lastWrite. Their absence supports fixed server-side behavior.

Reasoning about index reads inside a UDF

Index access inside a UDF is transactional. Latency and compute scale with the number of entries scanned and pages fetched, not with a client-side consistency setting. Prefer exact ref/id lookups or bounded index pages. Push selection into index terms where possible, and avoid unbounded scans. Across regions, do not assume a local-replica read path: a read may still need to observe the latest committed serializable state, so global latency is transaction visibility plus index work.

Verification steps

1. In a non-production database, call the same read-only UDF from two regions immediately after a write and confirm the later call observes it. Record any timestamp or summary fields returned.
2. Inspect the installed driver's type definitions for consistency-related options. Example (Node.js):

   grep -rE "consistency|readConcern|isolation|lastWrite" node_modules/fauna/dist/*.d.ts

3. Capture the raw HTTP response for one UDF call, or enable driver logging, and check whether any header or field names a consistency level. Example:

   curl -s -D - -X POST "$FAUNA_DOMAIN" \
     -H "Authorization: Bearer $FAUNA_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"query":"MyUdf()"}'

   If none appears, treat serializability as implicit.
4. Define a UDF returning a bounded index page plus an exact lookup, then compare latency and operation stats as page size grows to confirm cost tracks entries read.

Version and retry caveats

FQL v4 and v10 are not interchangeable. Verify the driver major, UDF syntax, and query shape before generalizing behavior. Retries of UDF calls that write can duplicate side effects unless the operation is idempotent; prefer idempotent UDF design or client-side deduplication. If you are using a custom REST client rather than an official driver, response field names may be normalized or dropped—capture raw responses before relying on them. Because driver surfaces and response fields can vary by version, confirm the specifics in your environment before treating them as settled.