Document atomicity and concurrency guarantees

[Copilot]

No documentation exists explaining FalkorDB's atomicity and concurrency model — critical for users building production applications who need to understand isolation guarantees without reading source code.

Adds design/concurrency.md covering:

• Single query atomicity — all write operations (CREATE/SET/DELETE/MERGE) within a query are atomic; no partial changes on failure
• Compound clauses — WITH, UNION queries execute as one atomic unit
• Write ordering — clauses execute sequentially; CREATE results available to subsequent SET in the same query
• Concurrent queries — reader-writer model per graph: concurrent readers, serialized writers, snapshot isolation for reads during writes
• Practical implications — when MULTI/EXEC is needed for multi-query transactions, performance considerations for read-heavy vs write-heavy workloads

Also adds atomicity and bottlenecked to .wordlist.txt for spellcheck CI.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Document atomicity and concurrency guarantees</issue_title>
<issue_description>## Context

Migrated from FalkorDB/FalkorDB#227 (originally from RedisGraph).

What's Missing

The documentation has no section explaining the atomicity and concurrency model of FalkorDB. Users need to understand:

1. Single query atomicity — Is everything within a single query with any combination of CREATE/SET/DELETE/MERGE atomic? If a query fails mid-execution, are partial changes rolled back?
2. Compound clauses — Does atomicity cover write queries with UNION or WITH? Are multiple clauses executed as one atomic unit?
3. Write ordering — What is the ordering of CREATE/SET/DELETE/MERGE operations within a single query? Can the results of a CREATE be used in a subsequent SET within the same query?
4. Concurrent queries — How does FalkorDB handle concurrent read and write queries? What isolation level is provided? The thread pool (THREAD_COUNT) config implies parallelism — what guarantees exist?

Suggested Location

A new page under /design/ or /getting-started/ (e.g., concurrency.html or atomicity.html), linked from the main Cypher clauses page.

Why This Matters

Users building production applications need to understand whether they need external locking, transactions (MULTI/EXEC), or if single queries provide sufficient guarantees for their use case.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Document atomicity and concurrency guarantees #393

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[Copilot]

Pull request overview

Adds a new design document describing FalkorDB’s atomicity and concurrency guarantees so users can understand query-level isolation and writer serialization without reading source code.

Changes:

• Introduces design/concurrency.md documenting single-query atomicity, clause ordering, and concurrent read/write behavior.
• Adds redirects for the new page and extends spellcheck allowlist with new terminology.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
design/concurrency.md	New design doc explaining atomicity/concurrency model, with redirects and configuration links.
.wordlist.txt	Adds atomicity and bottlenecked to satisfy spellcheck CI.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

redirect_from includes /design/concurrency.html but not the extensionless /design/concurrency. Other docs pages consistently include both forms (e.g., /design/result_structure + /design/result_structure.html), so /design/concurrency should be added to avoid a 404 for that common URL pattern.

Suggested change

	- /design/concurrency.html
	- /design/concurrency.html
	- /design/concurrency

[Copilot]

The docs typically link to the configuration page via /configuration#... (the canonical/redirected path used throughout commands/*). Here the link uses /getting-started/configuration#thread_count, which is inconsistent and makes link maintenance harder. Consider switching this to /configuration#thread_count to match existing docs conventions.

[Copilot]

Same as above: this second THREAD_COUNT link uses /getting-started/configuration#thread_count while the rest of the docs generally use /configuration#.... Aligning to the canonical /configuration#thread_count helps keep internal links consistent.

Suggested change

	- Tune [`THREAD_COUNT`](/getting-started/configuration#thread_count) to match the parallelism your hardware supports and your workload requires.
	- Tune [`THREAD_COUNT`](/configuration#thread_count) to match the parallelism your hardware supports and your workload requires.