<!-- CANARY: REQ=REQ-ENGINE-005; FEATURE="Engine"; ASPECT=CostBasedOptimizer; STATUS=TESTED; OWNER=engine; UPDATED=2026-01-15 -->
<h2 id="query-execution-architecture" class="position-relative d-flex align-items-center group">
<span>Query Execution Architecture</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="query-execution-architecture"
aria-haspopup="dialog"
aria-label="Share link: Query Execution Architecture">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h2><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden>
<div class="hsm-dialog" role="document">
<div class="hsm-header">
<h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2>
<button type="button" class="hsm-close" aria-label="Close">
<i class="fa-solid fa-xmark"></i>
</button>
</div>
<div class="hsm-body">
<label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label>
<div class="input-group mb-4 hsm-url-group">
<input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" />
<button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy">
<i class="fa-duotone fa-clipboard" aria-hidden="true"></i>
</button>
</div>
<div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div>
<div class="hsm-share-grid">
<a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-twitter me-2"></i>Twitter
</a>
<a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-linkedin me-2"></i>LinkedIn
</a>
<a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-facebook me-2"></i>Facebook
</a>
</div>
</div>
</div>
</div>
<style>
.heading-share-modal {
position: fixed;
inset: 0;
display: flex;
justify-content: center;
align-items: center;
background: rgba(0, 0, 0, 0.6);
z-index: 1050;
padding: 1rem;
backdrop-filter: blur(4px);
-webkit-backdrop-filter: blur(4px);
}
.heading-share-modal[hidden] { display: none !important; }
.hsm-dialog {
max-width: 420px;
width: 100%;
background: var(--bs-body-bg, #fff);
color: var(--bs-body-color, #212529);
border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1));
border-radius: 1rem;
box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
overflow: hidden;
animation: hsm-fade-in 0.2s ease-out;
}
@keyframes hsm-fade-in {
from { opacity: 0; transform: scale(0.95); }
to { opacity: 1; transform: scale(1); }
}
[data-bs-theme="dark"] .hsm-dialog {
background: #1e293b;
border-color: rgba(255,255,255,0.1);
color: #f8f9fa;
}
.hsm-header {
display: flex;
justify-content: space-between;
align-items: center;
padding: 1rem 1.5rem;
border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1));
background: rgba(0,0,0,0.02);
}
[data-bs-theme="dark"] .hsm-header {
background: rgba(255,255,255,0.02);
border-color: rgba(255,255,255,0.1);
}
.hsm-close {
background: transparent;
border: none;
color: inherit;
opacity: 0.5;
padding: 0.25rem 0.5rem;
border-radius: 0.25rem;
font-size: 1.2rem;
line-height: 1;
transition: opacity 0.2s;
}
.hsm-close:hover {
opacity: 1;
}
.hsm-body {
padding: 1.5rem;
}
.hsm-url-group {
display: flex !important;
align-items: stretch;
}
.hsm-url-group .form-control {
flex: 1;
min-width: 0;
margin: 0;
background: var(--bs-secondary-bg, #f8f9fa);
border-color: var(--bs-border-color, #dee2e6);
border-top-right-radius: 0;
border-bottom-right-radius: 0;
height: 42px;
}
.hsm-url-group .btn {
flex: 0 0 auto;
margin: 0;
margin-left: -1px;
border-top-left-radius: 0;
border-bottom-left-radius: 0;
height: 42px;
display: flex;
align-items: center;
justify-content: center;
padding: 0 1.25rem;
z-index: 2;
}
[data-bs-theme="dark"] .hsm-url-group .form-control {
background: #0f172a;
border-color: #334155;
color: #e2e8f0;
}
.hsm-share-grid {
display: flex;
flex-direction: column;
gap: 0.5rem;
}
.hsm-share-grid .btn {
display: flex;
align-items: center;
justify-content: center;
font-size: 0.9rem;
padding: 0.6rem;
border-color: var(--bs-border-color);
width: 100%;
}
[data-bs-theme="dark"] .hsm-share-grid .btn {
color: #e2e8f0;
border-color: #475569;
}
[data-bs-theme="dark"] .hsm-share-grid .btn:hover {
background: #334155;
border-color: #cbd5e1;
}
</style>
<script>
(function(){
const modal = document.getElementById('headingShareModal');
if(!modal) return;
const input = modal.querySelector('#headingShareInput');
const copyBtn = modal.querySelector('.hsm-copy');
const twitter = modal.querySelector('#share-twitter');
const linkedin = modal.querySelector('#share-linkedin');
const facebook = modal.querySelector('#share-facebook');
const closeBtn = modal.querySelector('.hsm-close');
let lastFocus=null;
let trapBound=false;
function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; }
function isOpen(){ return !modal.hasAttribute('hidden'); }
function hydrate(id){
const url=buildUrl(id);
input.value=url;
const enc=encodeURIComponent(url);
const text=encodeURIComponent(document.title);
if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`;
if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`;
if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`;
}
function openModal(id){
lastFocus=document.activeElement;
hydrate(id);
if(!isOpen()){
modal.removeAttribute('hidden');
}
requestAnimationFrame(()=>{ input.focus(); });
trapFocus();
}
function closeModal(){
if(!isOpen()) return;
modal.setAttribute('hidden','');
if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus();
}
function copyCurrent(){
try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); }
catch(e){ fallback(); }
}
function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} }
function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); }
function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); }
function bindShareButtons(){
document.querySelectorAll('.h-share').forEach(btn=>{
if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; }
});
}
bindShareButtons();
if(document.readyState==='loading'){
document.addEventListener('DOMContentLoaded', bindShareButtons);
} else {
requestAnimationFrame(bindShareButtons);
}
document.addEventListener('click', function(e){
const shareBtn=e.target.closest && e.target.closest('.h-share');
if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); }
}, true);
document.addEventListener('click', e=>{
if(e.target===modal) closeModal();
if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); }
if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); }
});
document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); });
function trapFocus(){
if(trapBound) return;
trapBound=true;
modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } });
}
if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); });
})();
</script><p>This document provides a comprehensive overview of Geode’s query execution pipeline, from GQL parsing through distributed execution, covering the parser, planner, optimizer, and executor components.</p>
<h3 id="overview" class="position-relative d-flex align-items-center group">
<span>Overview</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="overview"
aria-haspopup="dialog"
aria-label="Share link: Overview">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><p>Geode’s query execution follows a sophisticated pipeline that transforms user GQL queries into optimized execution plans and distributed operations.</p>
<h4 id="execution-pipeline" class="position-relative d-flex align-items-center group">
<span>Execution Pipeline</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="execution-pipeline"
aria-haspopup="dialog"
aria-label="Share link: Execution Pipeline">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>```
┌─────────────┐
│ GQL Query │
└──────┬──────┘
│
▼
┌──────────────────┐
│ Parser (Lexer) │ ← Tokenization, syntax validation
└──────┬───────────┘
│
▼
┌──────────────────┐
│ AST Generation │ ← Abstract Syntax Tree construction
└──────┬───────────┘
│
▼
┌──────────────────┐
│ Semantic Analysis│ ← Type checking, validation
└──────┬───────────┘
│
▼
┌──────────────────┐
│ Query Planner │ ← Logical plan generation
└──────┬───────────┘
│
▼
┌──────────────────┐
│ Optimizer │ ← Cost-based optimization
└──────┬───────────┘
│
▼
┌──────────────────┐
│ Physical Planner │ ← Physical execution plan
└──────┬───────────┘
│
▼
┌──────────────────┐
│ Executor │ ← Query execution
└──────┬───────────┘
│
▼
┌──────────────────┐
│ Results │
└──────────────────┘
```</p>
<h3 id="component-1-parser-and-lexer" class="position-relative d-flex align-items-center group">
<span>Component 1: Parser and Lexer</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="component-1-parser-and-lexer"
aria-haspopup="dialog"
aria-label="Share link: Component 1: Parser and Lexer">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="lexical-analysis-lexer" class="position-relative d-flex align-items-center group">
<span>Lexical Analysis (Lexer)</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="lexical-analysis-lexer"
aria-haspopup="dialog"
aria-label="Share link: Lexical Analysis (Lexer)">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>The lexer (<code>src/gql/lexer.zig</code>) tokenizes the input GQL query into a stream of tokens.</p>
<p><strong>Implementation Location</strong>: <code>src/gql/lexer.zig</code></p>
<p><strong>Key Responsibilities</strong>:</p>
<ul>
<li>Tokenize input string</li>
<li>Recognize GQL keywords (105+ reserved keywords)</li>
<li>Handle literals (strings, numbers, booleans, null)</li>
<li>Process operators and symbols</li>
<li>Manage whitespace and comments</li>
</ul>
<p><strong>Example Tokenization</strong>:
```
Input: “MATCH (p:Person {age: 30}) RETURN p.name”</p>
<p>Tokens:</p>
<ol>
<li>MATCH (keyword)</li>
<li>( (left_paren)</li>
<li>p (identifier)</li>
<li>: (colon)</li>
<li>Person (identifier)</li>
<li>{ (left_brace)</li>
<li>age (identifier)</li>
<li>: (colon)</li>
<li>30 (integer_literal)</li>
<li>} (right_brace)</li>
<li>) (right_paren)</li>
<li>RETURN (keyword)</li>
<li>p (identifier)</li>
<li>. (dot)</li>
<li>name (identifier)
```</li>
</ol>
<p><strong>Performance</strong>:</p>
<ul>
<li><strong>Throughput</strong>: ~1M tokens/second</li>
<li><strong>Memory</strong>: O(n) where n is query length</li>
<li><strong>Complexity</strong>: O(n) linear scan</li>
</ul>
<h4 id="syntax-analysis-parser" class="position-relative d-flex align-items-center group">
<span>Syntax Analysis (Parser)</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="syntax-analysis-parser"
aria-haspopup="dialog"
aria-label="Share link: Syntax Analysis (Parser)">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>The parser (<code>src/gql/parser.zig</code>) builds an Abstract Syntax Tree (AST) from the token stream.</p>
<p><strong>Implementation Location</strong>: <code>src/gql/parser.zig</code></p>
<p><strong>Key Responsibilities</strong>:</p>
<ul>
<li>Construct AST from tokens</li>
<li>Validate GQL syntax</li>
<li>Handle operator precedence</li>
<li>Manage nested expressions</li>
<li>Error recovery and reporting</li>
</ul>
<p><strong>AST Structure</strong>:
```zig
pub const Statement = union(enum) {
Query: QueryStatement,
Create: CreateStatement,
Delete: DeleteStatement,
Set: SetStatement,
Merge: MergeStatement,
Explain: ExplainStatement,
Profile: ProfileStatement,
// … other statement types
};</p>
<p>pub const QueryStatement = struct {
match_clause: ?MatchClause,
where_clause: ?WhereClause,
return_clause: ReturnClause,
order_by: ?OrderBy,
limit: ?LimitClause,
offset: ?OffsetClause,
};</p>
<p>pub const MatchClause = struct {
patterns: []Pattern,
optional: bool,
};</p>
<p>pub const Pattern = struct {
nodes: []NodePattern,
relationships: []RelationshipPattern,
path_variable: ?[]const u8,
};
```</p>
<p><strong>Parser Techniques</strong>:</p>
<ol>
<li>
<p><strong>Recursive Descent Parsing</strong>:
```zig
fn parseStatement(self: *Parser) ParserError!Statement {
const token = self.peek();
return switch (token.type) {
.MATCH, .OPTIONAL => self.parseQueryStatement(),
.CREATE => self.parseCreateStatement(),
.DELETE => self.parseDeleteStatement(),
.MERGE => self.parseMergeStatement(),
.EXPLAIN => self.parseExplainStatement(),
.PROFILE => self.parseProfileStatement(),
else => error.UnexpectedToken,
};
}
```</p>
</li>
<li>
<p><strong>Operator Precedence Climbing</strong>:
```zig
fn parseExpression(self: *Parser, min_precedence: u8) ParserError!Expression {
var left = try self.parsePrimaryExpression();</p>
<p>while (true) {
const op = self.peek();
const precedence = getOperatorPrecedence(op.type);</p>
<pre><code> if (precedence < min_precedence) break;
_ = try self.expect(op.type);
const right = try self.parseExpression(precedence + 1);
left = Expression{
.Binary = BinaryExpression{
.left = left,
.operator = op.type,
.right = right,
},
};
</code></pre>
<p>}</p>
<p>return left;
}
```</p>
</li>
</ol>
<p><strong>Operator Precedence</strong> (highest to lowest):</p>
<ol>
<li>Member access (<code>.</code>), function calls</li>
<li>Unary operators (<code>NOT</code>, <code>-</code>)</li>
<li>Multiplicative (<code>*</code>, <code>/</code>, <code>%</code>)</li>
<li>Additive (<code>+</code>, <code>-</code>)</li>
<li>Comparison (<code>=</code>, <code><></code>, <code><</code>, <code>></code>, <code><=</code>, <code>>=</code>)</li>
<li>String matching (<code>STARTS WITH</code>, <code>ENDS WITH</code>, <code>CONTAINS</code>, <code>=~</code>)</li>
<li>IS NULL, IS NOT NULL</li>
<li>IN</li>
<li>AND</li>
<li>OR</li>
</ol>
<p><strong>Error Handling</strong>:
```zig
pub const ParserError = error{
UnexpectedToken,
UnexpectedEOF,
InvalidSyntax,
UnclosedString,
InvalidNumber,
TooManyNestedExpressions,
};</p>
<p>fn reportError(self: *Parser, err: ParserError) void {
const token = self.current_token;
std.log.err(
“Parse error at line {d}, column {d}: {s}”,
.{ token.line, token.column, @errorName(err) }
);
}
```</p>
<h4 id="gql-compliance" class="position-relative d-flex align-items-center group">
<span>GQL Compliance</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="gql-compliance"
aria-haspopup="dialog"
aria-label="Share link: GQL Compliance">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>ISO/IEC 39075:2024 Conformance Profile</strong>: ISO/IEC 39075:2024 compliance (see conformance profile)</p>
<p><strong>Supported Features</strong>:</p>
<ul>
<li>All GQL keywords (105+)</li>
<li>Graph pattern matching (nodes, relationships, paths)</li>
<li>Variable-length path patterns (<code>-[*1..5]-></code>)</li>
<li>Path quantifiers (SHORTEST, ANY, WALK, TRAIL, ACYCLIC, SIMPLE)</li>
<li>Complex expressions and operators</li>
<li>Aggregation functions (COUNT, SUM, AVG, MIN, MAX)</li>
<li>Subqueries and pattern comprehensions</li>
<li>Set operations (UNION, INTERSECT, EXCEPT)</li>
<li>Temporal data types (DATE, TIME, DATETIME)</li>
<li>Spatial data types (POINT)</li>
</ul>
<h3 id="component-2-query-planner" class="position-relative d-flex align-items-center group">
<span>Component 2: Query Planner</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="component-2-query-planner"
aria-haspopup="dialog"
aria-label="Share link: Component 2: Query Planner">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="logical-plan-generation" class="position-relative d-flex align-items-center group">
<span>Logical Plan Generation</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="logical-plan-generation"
aria-haspopup="dialog"
aria-label="Share link: Logical Plan Generation">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>The query planner (<code>src/planner/</code>) transforms the AST into a logical query plan.</p>
<p><strong>Implementation Location</strong>: <code>src/planner/</code></p>
<p><strong>Key Files</strong>:</p>
<ul>
<li><code>src/planner/optimizer.zig</code> - Query optimization</li>
<li><code>src/planner/cbo.zig</code> - Cost-based optimization</li>
<li><code>src/planner/cost_model.zig</code> - Cost estimation</li>
<li><code>src/planner/pipeline.zig</code> - Execution pipeline</li>
<li><code>src/planner/adaptive.zig</code> - Adaptive query execution</li>
</ul>
<p><strong>Logical Plan Structure</strong>:
```
┌─────────────────┐
│ Return (project)│
└────────┬────────┘
│
▼
┌─────────────────┐
│ OrderBy │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Filter (WHERE) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Expand (edges) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Scan (nodes) │
└─────────────────┘
```</p>
<p><strong>Plan Operators</strong>:</p>
<ol>
<li>
<p><strong>Scan Operators</strong>:</p>
<ul>
<li><code>NodeScan</code>: Full node label scan</li>
<li><code>IndexSeek</code>: Index-based lookup</li>
<li><code>VectorIndexScan</code>: HNSW vector search</li>
<li><code>SpatialIndexScan</code>: R-tree spatial search</li>
<li><code>FullTextScan</code>: Full-text index search</li>
</ul>
</li>
<li>
<p><strong>Join Operators</strong>:</p>
<ul>
<li><code>NestedLoopJoin</code>: Simple nested iteration</li>
<li><code>HashJoin</code>: Hash-based join</li>
<li><code>MergeJoin</code>: Sort-merge join</li>
<li><code>ExpandRelationships</code>: Graph edge traversal</li>
</ul>
</li>
<li>
<p><strong>Filter Operators</strong>:</p>
<ul>
<li><code>Filter</code>: Predicate evaluation</li>
<li><code>RLSFilter</code>: Row-level security enforcement</li>
</ul>
</li>
<li>
<p><strong>Aggregation Operators</strong>:</p>
<ul>
<li><code>HashAggregate</code>: Hash-based aggregation</li>
<li><code>SortAggregate</code>: Sort-based aggregation</li>
<li><code>StreamAggregate</code>: Streaming aggregation</li>
</ul>
</li>
<li>
<p><strong>Sort Operators</strong>:</p>
<ul>
<li><code>Sort</code>: General sorting</li>
<li><code>TopK</code>: Top-K optimization</li>
</ul>
</li>
<li>
<p><strong>Set Operators</strong>:</p>
<ul>
<li><code>Union</code>: Set union</li>
<li><code>Intersect</code>: Set intersection</li>
<li><code>Except</code>: Set difference</li>
</ul>
</li>
</ol>
<h4 id="semantic-analysis" class="position-relative d-flex align-items-center group">
<span>Semantic Analysis</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="semantic-analysis"
aria-haspopup="dialog"
aria-label="Share link: Semantic Analysis">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Type Checking</strong>:
```zig
fn checkTypes(expr: Expression, context: *SemanticContext) TypeError!Type {
return switch (expr) {
.Literal => |lit| inferLiteralType(lit),
.Property => |prop| checkPropertyAccess(prop, context),
.Binary => |bin| checkBinaryOperation(bin, context),
.FunctionCall => |call| checkFunctionCall(call, context),
// … other expression types
};
}</p>
<p>fn checkBinaryOperation(bin: BinaryExpression, context: *SemanticContext) TypeError!Type {
const left_type = try checkTypes(bin.left, context);
const right_type = try checkTypes(bin.right, context);</p>
<pre><code>return switch (bin.operator) {
.Plus, .Minus, .Multiply, .Divide => {
if (!isNumeric(left_type) or !isNumeric(right_type)) {
return error.TypeMismatch;
}
return promoteNumericTypes(left_type, right_type);
},
.And, .Or => {
if (left_type != .Boolean or right_type != .Boolean) {
return error.TypeMismatch;
}
return .Boolean;
},
// ... other operators
};
</code></pre>
<p>}
```</p>
<p><strong>Validation Checks</strong>:</p>
<ul>
<li>Variable binding validation</li>
<li>Property existence checking</li>
<li>Function signature validation</li>
<li>Aggregate function context validation</li>
<li>Constraint validation</li>
</ul>
<h3 id="component-3-query-optimizer" class="position-relative d-flex align-items-center group">
<span>Component 3: Query Optimizer</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="component-3-query-optimizer"
aria-haspopup="dialog"
aria-label="Share link: Component 3: Query Optimizer">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="cost-based-optimization-cbo" class="position-relative d-flex align-items-center group">
<span>Cost-Based Optimization (CBO)</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="cost-based-optimization-cbo"
aria-haspopup="dialog"
aria-label="Share link: Cost-Based Optimization (CBO)">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Implementation Location</strong>: <code>src/planner/cbo.zig</code></p>
<p><strong>Optimization Strategies</strong>:</p>
<ol>
<li><strong>Predicate Pushdown</strong>:
```
Before:
Filter (age > 30)
├─ Expand (KNOWS)
└─ Scan (Person)</li>
</ol>
<p>After:
Expand (KNOWS)
└─ Filter (age > 30) ← Pushed down
└─ Scan (Person)
```</p>
<ol start="2">
<li>
<p><strong>Index Selection</strong>:
```zig
fn selectIndex(scan: ScanOperator, stats: *Statistics) ?Index {
var best_index: ?Index = null;
var best_cost = std.math.inf(f64);</p>
<p>for (available_indexes) |index| {
const selectivity = estimateSelectivity(scan.predicate, index, stats);
const cost = estimateIndexCost(index, selectivity);</p>
<pre><code> if (cost < best_cost) {
best_cost = cost;
best_index = index;
}
</code></pre>
<p>}</p>
<p>return best_index;
}
```</p>
</li>
<li>
<p><strong>Join Order Optimization</strong>:
```zig
fn optimizeJoinOrder(joins: []Join, stats: *Statistics) []Join {
// Dynamic programming approach for join order
const n = joins.len;
var dp = std.ArrayList(JoinPlan).init(allocator);</p>
<p>// Initialize with single-table access
for (joins) |join| {
const plan = JoinPlan{
.tables = [1]Table{join.table},
.cost = estimateTableScanCost(join.table, stats),
};
dp.append(plan);
}</p>
<p>// Build up join combinations
var size: usize = 2;
while (size <= n) : (size += 1) {
// Find best join order for each subset of size ‘size’
// … dynamic programming logic
}</p>
<p>return dp.items[n - 1].plan;
}
```</p>
</li>
</ol>
<h4 id="cost-model" class="position-relative d-flex align-items-center group">
<span>Cost Model</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="cost-model"
aria-haspopup="dialog"
aria-label="Share link: Cost Model">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Implementation Location</strong>: <code>src/planner/cost_model.zig</code></p>
<p><strong>Cost Factors</strong>:</p>
<ol>
<li><strong>I/O Cost</strong>:
```zig
fn estimateIOCost(operator: Operator) f64 {
return switch (operator) {
.NodeScan => estimateFullScanCost(),
.IndexSeek => estimateIndexSeekCost(),
.ExpandRelationships => estimateEdgeTraversalCost(),
// … other operators
};
}</li>
</ol>
<p>fn estimateFullScanCost() f64 {
const pages = node_count / nodes_per_page;
return @intToFloat(f64, pages) * io_cost_per_page;
}</p>
<p>fn estimateIndexSeekCost(index: Index, selectivity: f64) f64 {
const tree_height = @log2(@intToFloat(f64, index.entry_count));
const leaf_pages = @intToFloat(f64, index.entry_count) <em>selectivity / entries_per_page;
return tree_height</em> io_cost_per_page + leaf_pages * io_cost_per_page;
}
```</p>
<ol start="2">
<li><strong>CPU Cost</strong>:
```zig
fn estimateCPUCost(operator: Operator) f64 {
return switch (operator) {
.Filter => |filter| estimateFilterCost(filter),
.HashJoin => |join| estimateHashJoinCost(join),
.Sort => |sort| estimateSortCost(sort),
// … other operators
};
}</li>
</ol>
<p>fn estimateFilterCost(filter: FilterOperator) f64 {
const rows = estimateRowCount(filter.input);
const complexity = estimatePredicateComplexity(filter.predicate);
return rows <em>complexity</em> cpu_cost_per_predicate;
}</p>
<p>fn estimateSortCost(sort: SortOperator) f64 {
const rows = estimateRowCount(sort.input);
return rows <em>@log2(@intToFloat(f64, rows))</em> cpu_cost_per_comparison;
}
```</p>
<ol start="3">
<li><strong>Memory Cost</strong>:
```zig
fn estimateMemoryCost(operator: Operator) f64 {
return switch (operator) {
.HashJoin => estimateHashTableSize(),
.Sort => estimateSortBufferSize(),
.HashAggregate => estimateAggregationHashTableSize(),
// … other operators
};
}
```</li>
</ol>
<h4 id="statistics-collection" class="position-relative d-flex align-items-center group">
<span>Statistics Collection</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="statistics-collection"
aria-haspopup="dialog"
aria-label="Share link: Statistics Collection">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Implementation Location</strong>: <code>src/server/index_optimizer.zig</code></p>
<p><strong>Collected Statistics</strong>:</p>
<ul>
<li>Node label cardinalities</li>
<li>Relationship type counts</li>
<li>Property value distributions</li>
<li>Index selectivity</li>
<li>Data skew metrics</li>
</ul>
<p><strong>Statistics Update</strong>:
```gql
– Manual statistics update
CALL db.stats.update()</p>
<p>– Automatic update (configured in server)
statistics:
auto_update: true
update_threshold: 10000 – Update after 10k modifications
```</p>
<h3 id="component-4-query-executor" class="position-relative d-flex align-items-center group">
<span>Component 4: Query Executor</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="component-4-query-executor"
aria-haspopup="dialog"
aria-label="Share link: Component 4: Query Executor">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="execution-engine" class="position-relative d-flex align-items-center group">
<span>Execution Engine</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="execution-engine"
aria-haspopup="dialog"
aria-label="Share link: Execution Engine">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Implementation Location</strong>: <code>src/execution/</code></p>
<p><strong>Key Files</strong>:</p>
<ul>
<li><code>src/execution.zig</code> - Main execution logic</li>
<li><code>src/execution/path_and_call_operations.zig</code> - Path operations</li>
<li><code>src/execution/match_operations.zig</code> - MATCH execution</li>
<li><code>src/execution/crud_operations.zig</code> - CREATE/UPDATE/DELETE</li>
</ul>
<p><strong>Execution Model</strong>:</p>
<p>Geode uses a <strong>volcano-style iterator model</strong> with pipelining:</p>
<p>```zig
pub const Executor = struct {
plan: ExecutionPlan,
context: *ExecutionContext,</p>
<pre><code>pub fn execute(self: *Executor) !ResultSet {
return self.executeOperator(self.plan.root);
}
fn executeOperator(self: *Executor, operator: Operator) !ResultSet {
return switch (operator) {
.Scan => self.executeScan(operator.Scan),
.Filter => self.executeFilter(operator.Filter),
.Expand => self.executeExpand(operator.Expand),
.Join => self.executeJoin(operator.Join),
.Aggregate => self.executeAggregate(operator.Aggregate),
.Sort => self.executeSort(operator.Sort),
.Project => self.executeProject(operator.Project),
};
}
</code></pre>
<p>};
```</p>
<p><strong>Execution Operators</strong>:</p>
<ol>
<li>
<p><strong>Node Scan</strong>:
```zig
fn executeScan(self: *Executor, scan: ScanOperator) !ResultSet {
var results = std.ArrayList(Row).init(self.allocator);</p>
<p>// Iterate through nodes
var iter = try self.context.storage.nodeIterator(scan.label);
while (try iter.next()) |node| {
// Apply filter if present
if (scan.filter) |filter| {
const matches = try self.evaluatePredicate(filter, node);
if (!matches) continue;
}</p>
<pre><code> try results.append(Row{ .node = node });
</code></pre>
<p>}</p>
<p>return ResultSet{ .rows = results.items };
}
```</p>
</li>
<li>
<p><strong>Index Seek</strong>:
```zig
fn executeIndexSeek(self: *Executor, seek: IndexSeekOperator) !ResultSet {
var results = std.ArrayList(Row).init(self.allocator);</p>
<p>// Use index to find matching nodes
const index = self.context.indexes.get(seek.index_name);
const keys = try self.extractIndexKeys(seek.predicate);</p>
<p>for (keys) |key| {
const node_ids = try index.lookup(key);
for (node_ids) |node_id| {
const node = try self.context.storage.getNode(node_id);
try results.append(Row{ .node = node });
}
}</p>
<p>return ResultSet{ .rows = results.items };
}
```</p>
</li>
<li>
<p><strong>Relationship Expansion</strong>:
```zig
fn executeExpand(self: *Executor, expand: ExpandOperator) !ResultSet {
var results = std.ArrayList(Row).init(self.allocator);</p>
<p>// Get source nodes
const input = try self.executeOperator(expand.input);</p>
<p>for (input.rows) |row| {
const source_node = row.node;</p>
<pre><code> // Expand relationships
var rel_iter = try self.context.storage.relationshipIterator(
source_node.id,
expand.direction,
expand.rel_type
);
while (try rel_iter.next()) |relationship| {
const target_node = try self.context.storage.getNode(
relationship.target_id
);
try results.append(Row{
.node = source_node,
.relationship = relationship,
.target = target_node,
});
}
</code></pre>
<p>}</p>
<p>return ResultSet{ .rows = results.items };
}
```</p>
</li>
<li>
<p><strong>Hash Join</strong>:
```zig
fn executeHashJoin(self: *Executor, join: HashJoinOperator) !ResultSet {
var results = std.ArrayList(Row).init(self.allocator);</p>
<p>// Build phase: build hash table from smaller input
const build_input = try self.executeOperator(join.build_side);
var hash_table = std.AutoHashMap(u64, []Row).init(self.allocator);</p>
<p>for (build_input.rows) |row| {
const key = try self.extractJoinKey(row, join.build_key);
const entry = hash_table.getOrPut(key) catch unreachable;
if (!entry.found_existing) {
entry.value_ptr.* = std.ArrayList(Row).init(self.allocator);
}
try entry.value_ptr.append(row);
}</p>
<p>// Probe phase: probe hash table with larger input
const probe_input = try self.executeOperator(join.probe_side);
for (probe_input.rows) |probe_row| {
const key = try self.extractJoinKey(probe_row, join.probe_key);
if (hash_table.get(key)) |build_rows| {
for (build_rows) |build_row| {
try results.append(try self.mergeRows(build_row, probe_row));
}
}
}</p>
<p>return ResultSet{ .rows = results.items };
}
```</p>
</li>
<li>
<p><strong>Aggregation</strong>:
```zig
fn executeAggregate(self: *Executor, agg: AggregateOperator) !ResultSet {
var results = std.ArrayList(Row).init(self.allocator);</p>
<p>// Get input rows
const input = try self.executeOperator(agg.input);</p>
<p>// Build hash table for grouping
var groups = std.AutoHashMap(GroupKey, AggregateState).init(self.allocator);</p>
<p>for (input.rows) |row| {
// Extract grouping key
const group_key = try self.extractGroupKey(row, agg.group_by);</p>
<pre><code> // Get or create aggregate state
const entry = groups.getOrPut(group_key) catch unreachable;
if (!entry.found_existing) {
entry.value_ptr.* = AggregateState.init(agg.aggregates);
}
// Update aggregate state
try entry.value_ptr.update(row, agg.aggregates);
</code></pre>
<p>}</p>
<p>// Produce output rows
var iter = groups.iterator();
while (iter.next()) |entry| {
const final_values = try entry.value_ptr.finalize();
try results.append(Row{
.group_key = entry.key_ptr.*,
.aggregates = final_values,
});
}</p>
<p>return ResultSet{ .rows = results.items };
}
```</p>
</li>
</ol>
<h4 id="expression-evaluation" class="position-relative d-flex align-items-center group">
<span>Expression Evaluation</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="expression-evaluation"
aria-haspopup="dialog"
aria-label="Share link: Expression Evaluation">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Implementation Location</strong>: <code>src/eval.zig</code></p>
<p><strong>Evaluator</strong>:
```zig
pub fn evaluateExpression(
expr: Expression,
context: *EvaluationContext
) EvaluationError!Value {
return switch (expr) {
.Literal => |lit| Value.fromLiteral(lit),
.Property => |prop| evaluatePropertyAccess(prop, context),
.Binary => |bin| evaluateBinaryExpression(bin, context),
.FunctionCall => |call| evaluateFunctionCall(call, context),
.CaseExpression => |case| evaluateCaseExpression(case, context),
.ListComprehension => |comp| evaluateListComprehension(comp, context),
// … other expression types
};
}</p>
<p>fn evaluateBinaryExpression(
bin: BinaryExpression,
context: *EvaluationContext
) EvaluationError!Value {
const left = try evaluateExpression(bin.left, context);
const right = try evaluateExpression(bin.right, context);</p>
<pre><code>return switch (bin.operator) {
.Plus => try addValues(left, right),
.Minus => try subtractValues(left, right),
.Multiply => try multiplyValues(left, right),
.Divide => try divideValues(left, right),
.Equal => Value.fromBool(try compareValues(left, right, .Equal)),
.NotEqual => Value.fromBool(try compareValues(left, right, .NotEqual)),
// ... other operators
};
</code></pre>
<p>}
```</p>
<h3 id="component-5-distributed-query-execution" class="position-relative d-flex align-items-center group">
<span>Component 5: Distributed Query Execution</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="component-5-distributed-query-execution"
aria-haspopup="dialog"
aria-label="Share link: Component 5: Distributed Query Execution">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="distributed-query-coordinator" class="position-relative d-flex align-items-center group">
<span>Distributed Query Coordinator</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="distributed-query-coordinator"
aria-haspopup="dialog"
aria-label="Share link: Distributed Query Coordinator">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Implementation Location</strong>: <code>src/distributed/enhanced_query_coordinator.zig</code></p>
<p><strong>Distributed Execution Flow</strong>:</p>
<p>```
┌───────────────────────┐
│ Distributed Coordinator│
└──────────┬────────────┘
│
▼
┌─────────────────┐
│ Query Analysis │ ← Determine distribution strategy
└─────────┬───────┘
│
▼
┌─────────────────┐
│ Shard Pruning │ ← Eliminate unnecessary shards
└─────────┬───────┘
│
▼
┌─────────────────┐
│ Scatter Phase │ ← Send sub-queries to shards
└─────────┬───────┘
│
┌───────┴───────┬───────┐
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│Shard 1 │ │Shard 2 │ │Shard N │
└────┬───┘ └────┬───┘ └────┬───┘
│ │ │
└───────┬──────┴───────────┘
│
▼
┌─────────────────┐
│ Gather Phase │ ← Collect results
└─────────┬───────┘
│
▼
┌─────────────────┐
│ Result Merging │ ← Merge and order results
└─────────┬───────┘
│
▼
┌─────────────────┐
│ Final Results │
└─────────────────┘
```</p>
<p><strong>Shard Pruning</strong>:
```zig
fn pruneShards(
query: QueryPlan,
shards: []Shard,
stats: *Statistics
) []Shard {
var relevant_shards = std.ArrayList(Shard).init(allocator);</p>
<pre><code>for (shards) |shard| {
// Analyze query predicates
const shard_matches = analyzeShardRelevance(query, shard, stats);
if (shard_matches) {
try relevant_shards.append(shard);
}
}
return relevant_shards.items;
</code></pre>
<p>}
```</p>
<p><strong>Result Merging Strategies</strong>:</p>
<ol>
<li>
<p><strong>Union All</strong> (Simple Concatenation):
```zig
fn unionAllMerge(shard_results: []ResultSet) ResultSet {
var merged = ResultSet.init(allocator);</p>
<p>for (shard_results) |result| {
try merged.append(result.rows);
}</p>
<p>return merged;
}
```</p>
</li>
<li>
<p><strong>Union Distinct</strong> (Deduplication):
```zig
fn unionDistinctMerge(shard_results: []ResultSet) ResultSet {
var seen = std.AutoHashMap(RowHash, void).init(allocator);
var merged = ResultSet.init(allocator);</p>
<p>for (shard_results) |result| {
for (result.rows) |row| {
const hash = hashRow(row);
if (!seen.contains(hash)) {
try seen.put(hash, {});
try merged.append(row);
}
}
}</p>
<p>return merged;
}
```</p>
</li>
<li>
<p><strong>Merge Sorted</strong> (K-way Merge):
```zig
fn mergeSorted(shard_results: []ResultSet, order_by: OrderBy) ResultSet {
var merged = ResultSet.init(allocator);
var heap = PriorityQueue(Row).init(allocator, compareRows(order_by));</p>
<p>// Initialize heap with first row from each shard
for (shard_results) |result| {
if (result.rows.len > 0) {
try heap.add(result.rows[0]);
}
}</p>
<p>// K-way merge
while (heap.removeOrNull()) |row| {
try merged.append(row);</p>
<pre><code> // Add next row from same shard
const shard_idx = row.shard_idx;
const next_idx = row.idx_in_shard + 1;
if (next_idx < shard_results[shard_idx].rows.len) {
try heap.add(shard_results[shard_idx].rows[next_idx]);
}
</code></pre>
<p>}</p>
<p>return merged;
}
```</p>
</li>
</ol>
<h4 id="distributed-transaction-coordination" class="position-relative d-flex align-items-center group">
<span>Distributed Transaction Coordination</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="distributed-transaction-coordination"
aria-haspopup="dialog"
aria-label="Share link: Distributed Transaction Coordination">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Two-Phase Commit</strong>:
```zig
fn executeDistributedTransaction(
queries: []QueryPlan,
shards: []Shard
) TransactionError!void {
// Phase 1: Prepare
for (shards) |shard| {
const prepared = try shard.prepare(queries);
if (!prepared) {
// Abort on all shards
for (shards) |s| {
try s.abort();
}
return error.TransactionAborted;
}
}</p>
<pre><code>// Phase 2: Commit
for (shards) |shard| {
try shard.commit();
}
</code></pre>
<p>}
```</p>
<h3 id="performance-characteristics" class="position-relative d-flex align-items-center group">
<span>Performance Characteristics</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="performance-characteristics"
aria-haspopup="dialog"
aria-label="Share link: Performance Characteristics">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="parser-performance" class="position-relative d-flex align-items-center group">
<span>Parser Performance</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="parser-performance"
aria-haspopup="dialog"
aria-label="Share link: Parser Performance">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><table>
<thead>
<tr>
<th>Input Size</th>
<th>Parse Time</th>
<th>Tokens/sec</th>
</tr>
</thead>
<tbody>
<tr>
<td>100 bytes</td>
<td>10μs</td>
<td>10M</td>
</tr>
<tr>
<td>1 KB</td>
<td>100μs</td>
<td>10M</td>
</tr>
<tr>
<td>10 KB</td>
<td>1ms</td>
<td>10M</td>
</tr>
<tr>
<td>100 KB</td>
<td>10ms</td>
<td>10M</td>
</tr>
</tbody>
</table>
<h4 id="optimizer-performance" class="position-relative d-flex align-items-center group">
<span>Optimizer Performance</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="optimizer-performance"
aria-haspopup="dialog"
aria-label="Share link: Optimizer Performance">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><table>
<thead>
<tr>
<th>Joins</th>
<th>Optimization Time</th>
<th>Considered Plans</th>
</tr>
</thead>
<tbody>
<tr>
<td>2</td>
<td><1ms</td>
<td>2</td>
</tr>
<tr>
<td>4</td>
<td>~5ms</td>
<td>12</td>
</tr>
<tr>
<td>6</td>
<td>~50ms</td>
<td>720</td>
</tr>
<tr>
<td>8</td>
<td>~500ms</td>
<td>40,320</td>
</tr>
</tbody>
</table>
<p><strong>Note</strong>: Uses dynamic programming for join order optimization with pruning.</p>
<h4 id="executor-performance" class="position-relative d-flex align-items-center group">
<span>Executor Performance</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="executor-performance"
aria-haspopup="dialog"
aria-label="Share link: Executor Performance">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><table>
<thead>
<tr>
<th>Operation</th>
<th>Throughput</th>
<th>Latency (P50)</th>
<th>Latency (P99)</th>
</tr>
</thead>
<tbody>
<tr>
<td>Index Seek</td>
<td>100k ops/s</td>
<td>0.01ms</td>
<td>0.1ms</td>
</tr>
<tr>
<td>Full Scan</td>
<td>1M nodes/s</td>
<td>1ms</td>
<td>10ms</td>
</tr>
<tr>
<td>Hash Join</td>
<td>500k rows/s</td>
<td>2ms</td>
<td>20ms</td>
</tr>
<tr>
<td>Aggregation</td>
<td>1M rows/s</td>
<td>1ms</td>
<td>10ms</td>
</tr>
</tbody>
</table>
<h4 id="distributed-query-performance" class="position-relative d-flex align-items-center group">
<span>Distributed Query Performance</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="distributed-query-performance"
aria-haspopup="dialog"
aria-label="Share link: Distributed Query Performance">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><table>
<thead>
<tr>
<th>Shards</th>
<th>Query Time</th>
<th>Speedup</th>
<th>Efficiency</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>100ms</td>
<td>1.0x</td>
<td>100%</td>
</tr>
<tr>
<td>2</td>
<td>60ms</td>
<td>1.67x</td>
<td>83%</td>
</tr>
<tr>
<td>4</td>
<td>35ms</td>
<td>2.86x</td>
<td>71%</td>
</tr>
<tr>
<td>8</td>
<td>20ms</td>
<td>5.0x</td>
<td>62%</td>
</tr>
</tbody>
</table>
<h3 id="monitoring-and-debugging" class="position-relative d-flex align-items-center group">
<span>Monitoring and Debugging</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="monitoring-and-debugging"
aria-haspopup="dialog"
aria-label="Share link: Monitoring and Debugging">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="explain-output" class="position-relative d-flex align-items-center group">
<span>EXPLAIN Output</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="explain-output"
aria-haspopup="dialog"
aria-label="Share link: EXPLAIN Output">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>```gql
EXPLAIN MATCH (p:Person)-[:KNOWS]->(f:Person)
WHERE p.age > 30 AND f.city = ‘San Francisco’
RETURN p.name, f.name
ORDER BY p.name
LIMIT 10
```</p>
<p><strong>Output</strong>:
```</p>
<table>
<thead>
<tr>
<th>plan</th>
</tr>
</thead>
<tbody>
<tr>
<td>EXPLAIN</td>
</tr>
<tr>
<td>TopK (limit: 10)</td>
</tr>
<tr>
<td>Sort (key: p.name)</td>
</tr>
<tr>
<td>Project (p.name, f.name)</td>
</tr>
<tr>
<td>Filter (f.city = ‘SF’)</td>
</tr>
<tr>
<td>Expand (KNOWS)</td>
</tr>
<tr>
<td>Filter (p.age > 30)</td>
</tr>
<tr>
<td>IndexSeek (Person)</td>
</tr>
<tr>
<td>```</td>
</tr>
</tbody>
</table>
<h4 id="profile-output" class="position-relative d-flex align-items-center group">
<span>PROFILE Output</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="profile-output"
aria-haspopup="dialog"
aria-label="Share link: PROFILE Output">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>```gql
PROFILE MATCH (p:Person)-[:KNOWS]->(f:Person)
WHERE p.age > 30 AND f.city = ‘San Francisco’
RETURN p.name, f.name
ORDER BY p.name
LIMIT 10
```</p>
<p><strong>Output</strong>:
```</p>
<table>
<thead>
<tr>
<th>metric</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>rows_returned</td>
<td>10</td>
</tr>
<tr>
<td>rows_scanned</td>
<td>5420</td>
</tr>
<tr>
<td>index_seeks</td>
<td>1</td>
</tr>
<tr>
<td>relationships_expanded</td>
<td>5420</td>
</tr>
<tr>
<td>execution_time_ms</td>
<td>15</td>
</tr>
<tr>
<td>```</td>
<td></td>
</tr>
</tbody>
</table>
<h4 id="query-logging" class="position-relative d-flex align-items-center group">
<span>Query Logging</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="query-logging"
aria-haspopup="dialog"
aria-label="Share link: Query Logging">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>Enable query logging for debugging:</p>
<p>```yaml</p>
<h2 id="geodeyaml" class="position-relative d-flex align-items-center group">
<span>geode.yaml</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="geodeyaml"
aria-haspopup="dialog"
aria-label="Share link: geode.yaml">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h2><p>logging:
query_log: true
slow_query_threshold_ms: 100
log_level: debug
```</p>
<p><strong>Log Output</strong>:
```
[2026-01-24T10:30:00Z] INFO Query received: MATCH (p:Person) WHERE p.age > 30 RETURN p
[2026-01-24T10:30:00Z] DEBUG Parse time: 0.5ms
[2026-01-24T10:30:00Z] DEBUG Plan time: 2.1ms
[2026-01-24T10:30:00Z] DEBUG Execute time: 12.3ms
[2026-01-24T10:30:00Z] INFO Query completed in 14.9ms, returned 42 rows
```</p>
<h3 id="best-practices" class="position-relative d-flex align-items-center group">
<span>Best Practices</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="best-practices"
aria-haspopup="dialog"
aria-label="Share link: Best Practices">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="query-optimization" class="position-relative d-flex align-items-center group">
<span>Query Optimization</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="query-optimization"
aria-haspopup="dialog"
aria-label="Share link: Query Optimization">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ol>
<li><strong>Use Indexes Wisely</strong>:
```gql
– Create index for frequent predicates
CREATE INDEX ON :Person(email)</li>
</ol>
<p>– Query uses index automatically
MATCH (p:Person {email: ‘<a
href="mailto:[email protected]"
>[email protected]</a>
’}) RETURN p
```</p>
<ol start="2">
<li><strong>Filter Early</strong>:
```gql
– Good: Filter before expansion
MATCH (p:Person)
WHERE p.age > 30
MATCH (p)-[:KNOWS]->(f)
RETURN f.name</li>
</ol>
<p>– Bad: Filter after expansion
MATCH (p:Person)-[:KNOWS]->(f)
WHERE p.age > 30
RETURN f.name
```</p>
<ol start="3">
<li>
<p><strong>Use LIMIT</strong>:
```gql
– Add LIMIT to prevent large result sets
MATCH (p:Person)
RETURN p
ORDER BY p.name
LIMIT 100
```</p>
</li>
<li>
<p><strong>Avoid Cartesian Products</strong>:
```gql
– Bad: Cartesian product
MATCH (p:Person), (c:Company)
RETURN p.name, c.name</p>
</li>
</ol>
<p>– Good: Use relationships
MATCH (p:Person)-[:WORKS_AT]->(c:Company)
RETURN p.name, c.name
```</p>
<h4 id="distributed-queries" class="position-relative d-flex align-items-center group">
<span>Distributed Queries</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="distributed-queries"
aria-haspopup="dialog"
aria-label="Share link: Distributed Queries">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ol>
<li>
<p><strong>Shard Pruning</strong>:
```gql
– Include shard key in predicates
MATCH (p:Person {shard_id: 1}) – Prunes to single shard
WHERE p.age > 30
RETURN p
```</p>
</li>
<li>
<p><strong>Local Aggregation</strong>:
```gql
– Aggregation pushes down to shards
MATCH (p:Person)
RETURN p.department, count(*) AS emp_count
GROUP BY p.department
```</p>
</li>
</ol>
<h3 id="next-steps" class="position-relative d-flex align-items-center group">
<span>Next Steps</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="next-steps"
aria-haspopup="dialog"
aria-label="Share link: Next Steps">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><ol>
<li><strong>Query Tuning</strong> - Use EXPLAIN/PROFILE to optimize queries</li>
<li><strong>Index Strategy</strong> - Create indexes for common queries</li>
<li><strong>Distributed Setup</strong> - Configure sharding for scale</li>
<li><strong>Monitoring</strong> - Set up query logging and metrics</li>
<li><strong>Performance Testing</strong> - Benchmark with realistic workloads</li>
</ol>
<p><strong>Related Documentation</strong>:</p>
<ul>
<li><a
href="/docs/query/performance-tuning"
>Query Optimization</a>
</li>
<li><a
href="/docs/tutorials/index-optimization"
>Index Optimization</a>
</li>
<li><a
href="/docs/architecture/distributed-architecture"
>Distributed Architecture</a>
</li>
<li><a
href="/docs/query/explain-profile"
>EXPLAIN/PROFILE</a>
</li>
</ul>
<hr>
<p><em>Last Updated: January 2026</em>
<em>Implementation: Geode <strong>v0.2.18</strong>+</em>
<em>Status: Production-ready - 100% GQL compliance</em></p>
Query Execution Architecture
Deep dive into Geode's query execution pipeline including parser, planner, optimizer, and executor with distributed query coordination