Category: Query Optimization

The Query Optimization category provides in-depth guidance on understanding, analyzing, and improving the performance of GQL queries in Geode. From query planner internals to practical optimization techniques, this collection helps you write efficient queries and troubleshoot performance issues. <h3 id="understanding-query-optimization" class="position-relative d-flex align-items-center group"> Understanding Query Optimization <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="understanding-query-optimization" aria-haspopup="dialog" aria-label="Share link: Understanding Query Optimization"> Share link </button> </h3><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"> </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"> </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"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> 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>Query optimization is the process of transforming a declarative GQL query into an efficient execution plan. Geode’s cost-based optimizer analyzes multiple execution strategies, estimates their costs using statistics, and selects the approach with minimal expected resource consumption. Understanding how the optimizer works enables you to write queries that produce optimal plans. The optimization process involves several phases: <ol> <li>Parsing: Converts GQL text into an Abstract Syntax Tree (AST)</li> <li>Logical Planning: Transforms AST into logical operators (scans, joins, filters)</li> <li>Optimization: Rewrites logical plan using optimization rules</li> <li>Physical Planning: Selects specific algorithms for each operator</li> <li>Execution: Runs the physical plan and returns results</li> </ol> <h3 id="the-query-planner" class="position-relative d-flex align-items-center group"> The Query Planner <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="the-query-planner" aria-haspopup="dialog" aria-label="Share link: The Query Planner"> Share link </button> </h3>Geode’s query planner uses cost-based optimization to choose execution strategies. The planner maintains statistics about your data - node counts, relationship cardinalities, property value distributions - and uses these to estimate the cost of different plans. <h4 id="cardinality-estimation" class="position-relative d-flex align-items-center group"> Cardinality Estimation <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="cardinality-estimation" aria-haspopup="dialog" aria-label="Share link: Cardinality Estimation"> Share link </button> </h4>The planner estimates how many rows each operator produces: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">MATCH (u:User {country: 'USA'})-[:PURCHASED]->(p:Product {category: 'Electronics'}) RETURN u.name, p.name </code></pre></div>The planner estimates: <ul> <li>How many users have <code>country = 'USA'</code></li> <li>How many products have <code>category = 'Electronics'</code></li> <li>How many purchase relationships connect them</li> <li>Which join order produces fewer intermediate results</li> </ul> Accurate cardinality estimates lead to better plan choices. Geode automatically updates statistics as data changes. <h4 id="join-ordering" class="position-relative d-flex align-items-center group"> Join Ordering <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="join-ordering" aria-haspopup="dialog" aria-label="Share link: Join Ordering"> Share link </button> </h4>For queries with multiple patterns, join order significantly impacts performance: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Three patterns to join MATCH (a:User)-[:FRIEND]->(b:User) -[:POSTED]->(p:Post) -[:TAGGED]->(t:Tag {name: 'database'}) RETURN a.name, p.title </code></pre></div>Possible join orders: <ol> <li>Tag → Post → User → User (start with selective tag filter)</li> <li>User → User → Post → Tag (start with social graph)</li> <li>Post → User → User → Tag (start with content)</li> </ol> The planner chooses based on estimated selectivity. Starting with the most selective pattern minimizes intermediate results. <h4 id="index-selection" class="position-relative d-flex align-items-center group"> Index Selection <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="index-selection" aria-haspopup="dialog" aria-label="Share link: Index Selection"> Share link </button> </h4>When multiple indexes could satisfy a pattern, the planner chooses based on selectivity: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Which index to use? MATCH (u:User) WHERE u.country = 'USA' AND u.premium = true RETURN u </code></pre></div>If you have indexes on both <code>country</code> and <code>premium</code>: <ul> <li>If 5% of users have <code>country = 'USA'</code> (low selectivity)</li> <li>And 1% have <code>premium = true</code> (high selectivity)</li> <li>The planner uses the premium index, then filters by country</li> </ul> Use <code>EXPLAIN</code> to verify index selection. <h3 id="using-explain" class="position-relative d-flex align-items-center group"> Using EXPLAIN <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="using-explain" aria-haspopup="dialog" aria-label="Share link: Using EXPLAIN"> Share link </button> </h3><code>EXPLAIN</code> shows the execution plan without running the query: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">EXPLAIN MATCH (u:User {email: $email})-[:PURCHASED]->(p:Product) WHERE p.price > 100 RETURN p.name, p.price ORDER BY p.price DESC </code></pre></div>Output includes: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Sort [p.price DESC] ├─ Project [p.name, p.price] ├─ Filter [p.price > 100] ├─ Expand [(u)-[:PURCHASED]->(p)] └─ IndexSeek [u:User WHERE email = $email] └─ Index: user_email_idx </code></pre></div>Key information: <ul> <li>Operator tree: Physical operators in execution order</li> <li>Index usage: Which indexes are used</li> <li>Estimated cardinalities: Expected rows at each step</li> <li>Estimated cost: Relative cost metric</li> </ul> <h4 id="interpreting-explain-output" class="position-relative d-flex align-items-center group"> Interpreting EXPLAIN Output <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="interpreting-explain-output" aria-haspopup="dialog" aria-label="Share link: Interpreting EXPLAIN Output"> Share link </button> </h4>IndexSeek: Uses an index for direct lookup (optimal for selective filters) IndexScan: Scans an entire index (useful for ordered retrieval) NodeScan: Scans all nodes with a label (expensive for large graphs) Expand: Traverses relationships from matched nodes Filter: Applies predicates to filter rows HashJoin: Joins patterns using hash table (for large joins) NestedLoopJoin: Joins patterns with nested iteration (for small inner sets) Sort: Orders results (expensive, avoid if possible) Distinct: Removes duplicates <h3 id="using-profile" class="position-relative d-flex align-items-center group"> Using PROFILE <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="using-profile" aria-haspopup="dialog" aria-label="Share link: Using PROFILE"> Share link </button> </h3><code>PROFILE</code> executes the query and reports actual metrics: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">PROFILE MATCH (u:User)-[:FOLLOWS*2..3]->(recommendation:User) WHERE NOT EXISTS { MATCH (u)-[:FOLLOWS]->(recommendation) } RETURN recommendation.name, COUNT(*) AS mutual_connections ORDER BY mutual_connections DESC LIMIT 10 </code></pre></div>Output includes everything from <code>EXPLAIN</code> plus: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Sort [mutual_connections DESC] LIMIT 10 ├─ Actual rows: 10 ├─ Actual time: 45ms ├─ Memory: 2.1MB └─ Aggregate [COUNT(*)] ├─ Actual rows: 1,247 ├─ Actual time: 42ms └─ Filter [NOT EXISTS ...] ├─ Actual rows: 1,247 (estimated: 1,500) ├─ Actual time: 38ms └─ ExpandVariableLength [(u)-[:FOLLOWS*2..3]->(recommendation)] ├─ Actual rows: 8,934 (estimated: 10,000) ├─ Actual time: 25ms └─ NodeScan [u:User] ├─ Actual rows: 1,000 └─ Actual time: 2ms </code></pre></div>Key metrics: <ul> <li>Actual rows: How many rows each operator produced</li> <li>Actual time: Wall-clock time per operator</li> <li>Memory usage: Memory consumed per operator</li> <li>Estimated vs. actual: Comparison of planner estimates to reality</li> </ul> <h4 id="identifying-problems-with-profile" class="position-relative d-flex align-items-center group"> Identifying Problems with PROFILE <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="identifying-problems-with-profile" aria-haspopup="dialog" aria-label="Share link: Identifying Problems with PROFILE"> Share link </button> </h4>Large cardinality misestimates: If estimated and actual rows differ by orders of magnitude, statistics may be outdated. Run <code>ANALYZE</code> to update them. Expensive operators: Operators consuming most time are optimization targets. Consider indexes, alternative query structures, or materialized views. Memory spikes: Large memory consumption may indicate sorting or aggregating too much data. Use filters earlier or add indexes. Full table scans: NodeScan operations on large label sets. Add property filters with indexes. <h3 id="optimization-techniques" class="position-relative d-flex align-items-center group"> Optimization Techniques <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="optimization-techniques" aria-haspopup="dialog" aria-label="Share link: Optimization Techniques"> Share link </button> </h3> <h4 id="index-based-optimization" class="position-relative d-flex align-items-center group"> Index-Based Optimization <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="index-based-optimization" aria-haspopup="dialog" aria-label="Share link: Index-Based Optimization"> Share link </button> </h4>Create indexes on properties used in filters: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Before: Full scan MATCH (u:User) WHERE u.email = $email RETURN u -- Create index CREATE INDEX user_email_idx ON User(email); -- After: Index seek MATCH (u:User) WHERE u.email = $email RETURN u </code></pre></div>Profile shows difference: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">-- Before (slow) NodeScan [u:User] └─ Filter [email = $email] Actual rows: 1, time: 500ms (scanned 1,000,000 nodes) -- After (fast) IndexSeek [u:User WHERE email = $email] └─ Index: user_email_idx Actual rows: 1, time: 1ms </code></pre></div> <h4 id="pattern-ordering" class="position-relative d-flex align-items-center group"> Pattern Ordering <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="pattern-ordering" aria-haspopup="dialog" aria-label="Share link: Pattern Ordering"> Share link </button> </h4>Order patterns from most to least selective: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Inefficient: Starts with broad pattern MATCH (u:User)-[:VIEWED]->(p:Product) WHERE u.id = $userId AND p.featured = true RETURN p.name -- Efficient: Starts with selective filter MATCH (u:User {id: $userId})-[:VIEWED]->(p:Product {featured: true}) RETURN p.name </code></pre></div>The efficient version filters early, reducing intermediate rows. <h4 id="predicate-pushdown" class="position-relative d-flex align-items-center group"> Predicate Pushdown <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="predicate-pushdown" aria-haspopup="dialog" aria-label="Share link: Predicate Pushdown"> Share link </button> </h4>Move filters close to data sources: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Less efficient MATCH (u:User)-[:POSTED]->(p:Post) WITH u, p WHERE p.published = true AND u.active = true RETURN u.name, p.title -- More efficient MATCH (u:User {active: true})-[:POSTED]->(p:Post {published: true}) RETURN u.name, p.title </code></pre></div>Filtering in <code>MATCH</code> patterns enables index usage and reduces intermediate results. <h4 id="limiting-variable-length-paths" class="position-relative d-flex align-items-center group"> Limiting Variable-Length Paths <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="limiting-variable-length-paths" aria-haspopup="dialog" aria-label="Share link: Limiting Variable-Length Paths"> Share link </button> </h4>Unbounded variable-length paths can be expensive: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Potentially expensive MATCH path = (a:Person)-[:KNOWS*]-(b:Person {name: 'Bob'}) RETURN path -- Better: Bounded depth MATCH path = (a:Person)-[:KNOWS*1..4]-(b:Person {name: 'Bob'}) RETURN path LIMIT 10 </code></pre></div>Limits prevent exponential expansion in dense graphs. <h4 id="avoiding-cartesian-products" class="position-relative d-flex align-items-center group"> Avoiding Cartesian Products <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="avoiding-cartesian-products" aria-haspopup="dialog" aria-label="Share link: Avoiding Cartesian Products"> Share link </button> </h4>Ensure patterns are connected: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Cartesian product (expensive!) MATCH (u:User), (p:Product) WHERE u.country = p.origin_country RETURN u.name, p.name -- Connected pattern (efficient) MATCH (u:User)-[:INTERESTED_IN]->(c:Country)<-[:ORIGIN]-(p:Product) RETURN u.name, p.name </code></pre></div>Disconnected patterns produce |Users| × |Products| intermediate rows. <h4 id="aggregation-optimization" class="position-relative d-flex align-items-center group"> Aggregation Optimization <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="aggregation-optimization" aria-haspopup="dialog" aria-label="Share link: Aggregation Optimization"> Share link </button> </h4>Filter before aggregating: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Less efficient: Aggregates then filters MATCH (u:User)-[:TRANSACTION]->(m:Merchant) WITH u, COUNT(m) AS transaction_count WHERE transaction_count > 10 RETURN u.name, transaction_count -- More efficient: Filters then aggregates MATCH (u:User)-[:TRANSACTION]->(m:Merchant) WHERE m.suspicious = false WITH u, COUNT(m) AS transaction_count WHERE transaction_count > 10 RETURN u.name, transaction_count </code></pre></div>Reducing data volume before aggregation improves performance. <h3 id="index-strategies" class="position-relative d-flex align-items-center group"> Index Strategies <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="index-strategies" aria-haspopup="dialog" aria-label="Share link: Index Strategies"> Share link </button> </h3> <h4 id="single-property-indexes" class="position-relative d-flex align-items-center group"> Single-Property Indexes <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="single-property-indexes" aria-haspopup="dialog" aria-label="Share link: Single-Property Indexes"> Share link </button> </h4>Index frequently queried properties: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">CREATE INDEX user_email_idx ON User(email); CREATE INDEX product_sku_idx ON Product(sku); CREATE INDEX order_timestamp_idx ON Order(timestamp); </code></pre></div> <h4 id="composite-indexes" class="position-relative d-flex align-items-center group"> Composite Indexes <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="composite-indexes" aria-haspopup="dialog" aria-label="Share link: Composite Indexes"> Share link </button> </h4>Index property combinations queried together: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Query pattern MATCH (p:Product) WHERE p.category = $category AND p.price > $min_price RETURN p -- Optimal index CREATE INDEX product_category_price_idx ON Product(category, price); </code></pre></div>Column order matters: put equality filters before range filters. <h4 id="covering-indexes" class="position-relative d-flex align-items-center group"> Covering Indexes <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="covering-indexes" aria-haspopup="dialog" aria-label="Share link: Covering Indexes"> Share link </button> </h4>Include all needed properties in the index: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Query needs name and email MATCH (u:User) WHERE u.country = 'USA' RETURN u.name, u.email -- Covering index (avoids table lookup) CREATE INDEX user_country_covering_idx ON User(country, name, email); </code></pre></div>The planner can satisfy the query entirely from the index. <h4 id="index-maintenance" class="position-relative d-flex align-items-center group"> Index Maintenance <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="index-maintenance" aria-haspopup="dialog" aria-label="Share link: Index Maintenance"> Share link </button> </h4>Monitor index usage: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Show index statistics SHOW INDEX STATISTICS; -- Identify unused indexes SELECT index_name, read_count, write_count FROM system.index_stats WHERE read_count = 0 AND created < current_timestamp() - INTERVAL '30' DAY; </code></pre></div>Drop unused indexes to reduce write overhead: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">DROP INDEX unused_index_name; </code></pre></div> <h3 id="query-rewriting-patterns" class="position-relative d-flex align-items-center group"> Query Rewriting Patterns <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-rewriting-patterns" aria-haspopup="dialog" aria-label="Share link: Query Rewriting Patterns"> Share link </button> </h3> <h4 id="subquery-materialization" class="position-relative d-flex align-items-center group"> Subquery Materialization <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="subquery-materialization" aria-haspopup="dialog" aria-label="Share link: Subquery Materialization"> Share link </button> </h4>Extract subqueries that don’t depend on outer variables: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Before: Subquery re-executes for each row MATCH (u:User) WHERE u.created > ( SELECT avg(created) FROM User ) RETURN u.name -- After: Materialize once WITH (SELECT avg(created) FROM User) AS avg_created MATCH (u:User) WHERE u.created > avg_created RETURN u.name </code></pre></div> <h4 id="exists-to-join-conversion" class="position-relative d-flex align-items-center group"> EXISTS to JOIN Conversion <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="exists-to-join-conversion" aria-haspopup="dialog" aria-label="Share link: EXISTS to JOIN Conversion"> Share link </button> </h4>Sometimes explicit joins outperform EXISTS: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Using EXISTS MATCH (u:User) WHERE EXISTS { MATCH (u)-[:PURCHASED]->(:Product {category: 'Electronics'}) } RETURN u.name -- Using explicit join MATCH (u:User)-[:PURCHASED]->(:Product {category: 'Electronics'}) RETURN DISTINCT u.name </code></pre></div>Profile both to determine which is faster for your data. <h4 id="common-table-expression-cte-optimization" class="position-relative d-flex align-items-center group"> Common Table Expression (CTE) Optimization <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="common-table-expression-cte-optimization" aria-haspopup="dialog" aria-label="Share link: Common Table Expression (CTE) Optimization"> Share link </button> </h4>Use <code>WITH</code> to materialize intermediate results: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Calculate once, use multiple times WITH ( MATCH (u:User) WHERE u.active = true RETURN collect(u.id) AS active_user_ids ) MATCH (u:User) WHERE u.id IN active_user_ids MATCH (u)-[:POSTED]->(p:Post) RETURN u.name, COUNT(p) AS posts </code></pre></div> <h3 id="troubleshooting-slow-queries" class="position-relative d-flex align-items-center group"> Troubleshooting Slow Queries <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="troubleshooting-slow-queries" aria-haspopup="dialog" aria-label="Share link: Troubleshooting Slow Queries"> Share link </button> </h3> <h4 id="step-1-profile-the-query" class="position-relative d-flex align-items-center group"> Step 1: Profile the Query <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="step-1-profile-the-query" aria-haspopup="dialog" aria-label="Share link: Step 1: Profile the Query"> Share link </button> </h4>Run <code>PROFILE</code> to identify expensive operators: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">PROFILE <your slow query> </code></pre></div>Look for: <ul> <li>Operators consuming >80% of time</li> <li>Large cardinality estimates vs. actuals</li> <li>Missing index usage</li> <li>Full table scans</li> </ul> <h4 id="step-2-check-index-usage" class="position-relative d-flex align-items-center group"> Step 2: Check Index Usage <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="step-2-check-index-usage" aria-haspopup="dialog" aria-label="Share link: Step 2: Check Index Usage"> Share link </button> </h4>Verify expected indexes are used: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">EXPLAIN <your slow query> </code></pre></div>If indexes aren’t used: <ul> <li>Ensure index exists: <code>SHOW INDEXES</code></li> <li>Check statistics are current: <code>ANALYZE</code></li> <li>Verify query predicates match index definition</li> </ul> <h4 id="step-3-analyze-cardinalities" class="position-relative d-flex align-items-center group"> Step 3: Analyze Cardinalities <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="step-3-analyze-cardinalities" aria-haspopup="dialog" aria-label="Share link: Step 3: Analyze Cardinalities"> Share link </button> </h4>Compare estimated vs. actual row counts. Large mismatches indicate: <ul> <li>Outdated statistics (run <code>ANALYZE</code>)</li> <li>Correlated predicates planner can’t model</li> <li>Need for query rewrite</li> </ul> <h4 id="step-4-simplify-and-test" class="position-relative d-flex align-items-center group"> Step 4: Simplify and Test <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="step-4-simplify-and-test" aria-haspopup="dialog" aria-label="Share link: Step 4: Simplify and Test"> Share link </button> </h4>Simplify the query to isolate the problem: <ul> <li>Remove complex subqueries</li> <li>Reduce variable-length path bounds</li> <li>Remove expensive filters</li> </ul> Test each component individually to identify the bottleneck. <h4 id="step-5-consider-alternatives" class="position-relative d-flex align-items-center group"> Step 5: Consider Alternatives <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="step-5-consider-alternatives" aria-haspopup="dialog" aria-label="Share link: Step 5: Consider Alternatives"> Share link </button> </h4>Sometimes structural changes help: <ul> <li>Materialize frequently computed results</li> <li>Denormalize for read-heavy workloads</li> <li>Add redundant indexes for specific queries</li> <li>Use query hints (if available)</li> </ul> <h3 id="best-practices" class="position-relative d-flex align-items-center group"> Best Practices <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"> Share link </button> </h3><ol> <li>Profile before optimizing: Measure actual performance, don’t guess</li> <li>Keep statistics current: Run <code>ANALYZE</code> regularly</li> <li>Index strategically: Cover common queries without over-indexing</li> <li>Start selective: Begin patterns with most selective filters</li> <li>Limit results: Always use <code>LIMIT</code> for exploration queries</li> <li>Bound paths: Limit variable-length path depth</li> <li>Avoid Cartesian products: Ensure patterns are connected</li> <li>Filter early: Push predicates into MATCH patterns</li> <li>Monitor production: Track slow queries and optimize frequently run ones</li> <li>Document optimizations: Explain why specific indexes or query structures exist</li> </ol> <h3 id="related-topics" class="position-relative d-flex align-items-center group"> Related Topics <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="related-topics" aria-haspopup="dialog" aria-label="Share link: Related Topics"> Share link </button> </h3><ul> <li><a href="/categories/performance-and-scaling/" >Performance and Scaling</a> - Overall performance strategy</li> <li><a href="/tags/indexing/" >Indexing</a> - Index design and management</li> <li><a href="/tags/explain/" >EXPLAIN Command</a> - Query plan analysis</li> <li><a href="/tags/profiling/" >PROFILE Command</a> - Performance measurement</li> <li><a href="/categories/query-language/" >Query Language</a> - GQL fundamentals</li> <li><a href="/categories/best-practices/" >Best Practices</a> - General optimization patterns</li> </ul> <h3 id="further-reading" class="position-relative d-flex align-items-center group"> Further Reading <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="further-reading" aria-haspopup="dialog" aria-label="Share link: Further Reading"> Share link </button> </h3><ul> <li><a href="/docs/architecture/query-execution/" >Query Execution</a> - Planner internals</li> <li><a href="/docs/reference/indexes/" >Index Types</a> - Index implementation details</li> <li><a href="/docs/reference/statistics/" >Statistics</a> - Statistics system</li> <li><a href="/docs/query/performance-tuning/" >Performance Tuning</a> - Advanced techniques</li> <li><a href="/docs/guides/performance-benchmarking/" >Performance Benchmarking</a> - Performance testing</li> </ul>

Popular

Related Articles

Query Performance Tuning Guide

Query Optimization

Full-Text Search with BM25 Ranking

Materialized Views System