Querying, Indexing, and Query Optimization

<h2 id="querying-indexing-and-query-optimization" class="position-relative d-flex align-items-center group"> Querying, Indexing, and 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="querying-indexing-and-query-optimization" aria-haspopup="dialog" aria-label="Share link: Querying, Indexing, and Query Optimization"> Share link </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"> </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>Learn how Geode executes queries, how to create indexes for different access patterns, and how to use EXPLAIN/PROFILE to tune performance. <h3 id="index-overview" class="position-relative d-flex align-items-center group"> Index Overview <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-overview" aria-haspopup="dialog" aria-label="Share link: Index Overview"> Share link </button> </h3>Indexes accelerate queries by providing efficient data structures for specific access patterns. When to index: <ul> <li>Columns used in <code>WHERE</code> predicates</li> <li>Properties used in <code>ORDER BY</code> clauses</li> <li>Join/match columns for relationship traversal</li> <li>Full-text search on text fields</li> <li>Vector similarity search on embeddings</li> <li>Spatial queries on geographic data</li> </ul> Cost: Indexes consume disk space and slow down writes (insert/update/delete). Choose indexes based on your query patterns, not preemptively. <h3 id="creating-indexes" class="position-relative d-flex align-items-center group"> Creating 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="creating-indexes" aria-haspopup="dialog" aria-label="Share link: Creating Indexes"> Share link </button> </h3> <h4 id="syntax" class="position-relative d-flex align-items-center group"> Syntax <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" aria-haspopup="dialog" aria-label="Share link: Syntax"> Share link </button> </h4>From <code>API_REFERENCE.md</code>: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">CREATE INDEX [index_name] ON label(property) USING index_type; </code></pre></div>Index types: <ul> <li><code>btree</code> - B-tree (default)</li> <li><code>hash</code> - Hash table</li> <li><code>fulltext</code> - Full-text search with BM25</li> <li><code>spatial</code> - R-tree for geographic data</li> <li><code>vector</code> - HNSW for vector similarity (ANN)</li> </ul> <h4 id="examples" class="position-relative d-flex align-items-center group"> Examples <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="examples" aria-haspopup="dialog" aria-label="Share link: Examples"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- B-tree index (default, supports range queries) CREATE INDEX person_age_idx ON Person(age) USING btree; -- Hash index (fast equality lookups) CREATE INDEX person_email_idx ON Person(email) USING hash; -- Full-text index CREATE INDEX document_content_idx ON Document(content) USING fulltext; -- Spatial index (geographic queries) CREATE INDEX location_coords_idx ON Location(coords) USING spatial; -- Vector index (similarity search) CREATE INDEX doc_embedding_idx ON Document(embedding) USING vector; </code></pre></div> <h4 id="dropping-indexes" class="position-relative d-flex align-items-center group"> Dropping 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="dropping-indexes" aria-haspopup="dialog" aria-label="Share link: Dropping Indexes"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">DROP INDEX person_age_idx; </code></pre></div> <h3 id="index-types-when-to-use" class="position-relative d-flex align-items-center group"> Index Types: When to Use <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-types-when-to-use" aria-haspopup="dialog" aria-label="Share link: Index Types: When to Use"> Share link </button> </h3> <h4 id="b-tree-indexes" class="position-relative d-flex align-items-center group"> B-tree 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="b-tree-indexes" aria-haspopup="dialog" aria-label="Share link: B-tree Indexes"> Share link </button> </h4>Best for: <ul> <li>Range queries (<code>></code>, <code><</code>, <code>BETWEEN</code>)</li> <li>Sorting (<code>ORDER BY</code>)</li> <li>Prefix matching (<code>STARTS WITH</code>)</li> </ul> Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create index CREATE INDEX person_age_idx ON Person(age) USING btree; -- Queries that benefit MATCH (p:Person) WHERE p.age > 25 AND p.age < 50 RETURN p.name ORDER BY p.age; MATCH (p:Person) WHERE p.name STARTS WITH "Al" RETURN p.name; </code></pre></div>Performance: O(log N) lookups, efficient range scans <h4 id="hash-indexes" class="position-relative d-flex align-items-center group"> Hash 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="hash-indexes" aria-haspopup="dialog" aria-label="Share link: Hash Indexes"> Share link </button> </h4>Best for: <ul> <li>Exact equality (<code>=</code>)</li> <li>High-cardinality columns (emails, UUIDs)</li> </ul> Not suitable for: <ul> <li>Range queries</li> <li>Sorting</li> <li>Prefix matching</li> </ul> Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create index CREATE INDEX user_email_idx ON User(email) USING hash; -- Query that benefits MATCH (u:User) WHERE u.email = "[email protected]" RETURN u; </code></pre></div>Performance: O(1) lookups for exact matches <h4 id="full-text-indexes" class="position-relative d-flex align-items-center group"> Full-text 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="full-text-indexes" aria-haspopup="dialog" aria-label="Share link: Full-text Indexes"> Share link </button> </h4>Best for: <ul> <li>Text search with ranking</li> <li>Natural language queries</li> <li>Document search</li> </ul> Features (from <code>BM25_INDEX_OPTIMIZER_INTEGRATION.md</code>): <ul> <li>BM25 relevance scoring</li> <li>Tokenization and stemming</li> <li>Stop word filtering</li> <li>Optimizer integration for ranking queries</li> </ul> Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create full-text index CREATE INDEX article_content_idx ON Article(content) USING fulltext; -- Full-text search with ranking MATCH (a:Article) WHERE fulltext_match(a.content, "graph database performance") RETURN a.title, bm25_score(a.content, "graph database performance") AS score ORDER BY score DESC LIMIT 10; </code></pre></div>BM25 Scoring: Balances term frequency (TF) and inverse document frequency (IDF) for relevance ranking. See also: <a href="/docs/query/full-text-search/" >BM25 Integration</a> for tuning parameters (k1, b). <h4 id="spatial-indexes" class="position-relative d-flex align-items-center group"> Spatial 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="spatial-indexes" aria-haspopup="dialog" aria-label="Share link: Spatial Indexes"> Share link </button> </h4>Best for: <ul> <li>Geographic queries (distance, containment)</li> <li>Location-based search</li> <li>Geofencing</li> </ul> Implementation: R-tree spatial indexing Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create spatial index CREATE INDEX store_location_idx ON Store(location) USING spatial; -- Find stores within 5km MATCH (s:Store) WHERE geo_distance(s.location, latlon(40.7128, -74.0060)) < 5000 RETURN s.name, geo_distance(s.location, latlon(40.7128, -74.0060)) AS meters ORDER BY meters LIMIT 5; -- Bounding box query MATCH (s:Store) WHERE geo_within_box(s.location, latlon(40.7, -74.1), latlon(40.8, -74.0)) RETURN s.name; </code></pre></div>Performance: O(log N) for point queries, efficient range queries <h4 id="vector-indexes-hnsw" class="position-relative d-flex align-items-center group"> Vector Indexes (HNSW) <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="vector-indexes-hnsw" aria-haspopup="dialog" aria-label="Share link: Vector Indexes (HNSW)"> Share link </button> </h4>Best for: <ul> <li>Vector similarity search</li> <li>Approximate Nearest Neighbor (ANN)</li> <li>Embedding-based search (ML models)</li> </ul> Implementation: HNSW (Hierarchical Navigable Small World) with SIMD acceleration Characteristics: <ul> <li>SIMD-optimized distance metrics</li> <li>Sub-linear search time O(log N)</li> </ul> Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create vector index CREATE INDEX doc_embedding_idx ON Document(embedding) USING vector; -- Similarity search (k-NN) MATCH (d:Document) WHERE vector_distance_l2(d.embedding, '[0.1, 0.2, ..., 0.512]'::vector_f32) < 0.5 RETURN d.title, vector_distance_l2(d.embedding, '[0.1, 0.2, ..., 0.512]'::vector_f32) AS distance ORDER BY distance LIMIT 10; </code></pre></div>Distance metrics: <ul> <li><code>vector_distance_l2()</code> - Euclidean distance</li> <li><code>vector_distance_cosine()</code> - Cosine similarity</li> <li><code>vector_distance_dot()</code> - Dot product</li> </ul> See also: <a href="/docs/analytics/graph-algorithms" >Graph Algorithms and Analytics</a> for embeddings <h3 id="specialized-indexes" class="position-relative d-flex align-items-center group"> Specialized 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="specialized-indexes" aria-haspopup="dialog" aria-label="Share link: Specialized Indexes"> Share link </button> </h3>From <code>SERVER_FEATURES.md</code>, Geode implements additional specialized indexes: <table> <thead> <tr> <th>Index Type</th> <th>Purpose</th> <th>User-Facing</th> </tr> </thead> <tbody> <tr> <td>JSONB inverted index</td> <td>Path queries in JSON</td> <td>🔧 Via <code>jsonb</code> type</td> </tr> <tr> <td>Interval tree</td> <td>Temporal overlap queries</td> <td>🔧 Via <code>interval</code> type</td> </tr> <tr> <td>Patricia trie</td> <td>IP prefix/subnet queries</td> <td>🔧 Via <code>ipaddr</code>/<code>subnet</code> types</td> </tr> <tr> <td>Domain trie</td> <td>Hierarchical domain queries</td> <td>📋 Planned</td> </tr> </tbody> </table> Example: JSONB path indexing: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Implicit JSONB indexing CREATE INDEX doc_metadata_idx ON Document(metadata) USING btree; -- Path queries (automatically use index) MATCH (d:Document) WHERE d.metadata->'author' = '"Alice"' RETURN d.title; -- Array indexing MATCH (d:Document) WHERE d.metadata->'tags'->0 = '"ml"' RETURN d.title; </code></pre></div> <h3 id="cost-based-optimizer-cbo" class="position-relative d-flex align-items-center group"> Cost-Based Optimizer (CBO) <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-optimizer-cbo" aria-haspopup="dialog" aria-label="Share link: Cost-Based Optimizer (CBO)"> Share link </button> </h3>Geode’s Cost-Based Optimizer selects the best execution plan based on: <ul> <li>Statistics: Row counts, cardinality estimates, value distributions</li> <li>Index availability: Which indexes exist and their selectivity</li> <li>Predicate selectivity: Estimated fraction of rows matching <code>WHERE</code> clause</li> <li>Join cost: Cost of expanding relationships</li> </ul> How it works: <ol> <li>Parse query into logical plan</li> <li>Generate alternative physical plans (different index choices, join orders)</li> <li>Estimate cost for each plan (I/O, CPU, memory)</li> <li>Select plan with lowest estimated cost</li> </ol> IndexOptimizer (from <code>SERVER_FEATURES.md</code>): <ul> <li>Specialized component for index selection</li> <li>Evaluates index applicability for each predicate</li> <li>Combines multiple indexes via bitmap operations</li> <li>Integrates with CBO for holistic plan selection</li> </ul> User control: Currently automatic. Future: query hints for manual override. <h3 id="explain-and-profile" class="position-relative d-flex align-items-center group"> EXPLAIN and 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="explain-and-profile" aria-haspopup="dialog" aria-label="Share link: EXPLAIN and PROFILE"> Share link </button> </h3> <h4 id="explain-query-plan" class="position-relative d-flex align-items-center group"> EXPLAIN: Query Plan <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-query-plan" aria-haspopup="dialog" aria-label="Share link: EXPLAIN: Query Plan"> Share link </button> </h4>Show query execution plan without running: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">EXPLAIN MATCH (p:Person)-[:KNOWS]->(friend) WHERE p.age > 25 RETURN p.name, friend.name; </code></pre></div>Sample output: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Project [p.name, friend.name] Expand [(p)-[:KNOWS]->(friend)] Filter [p.age > 25] Scan [Person] (uses index: person_age_idx) </code></pre></div>Plan operators: <ul> <li><code>Scan</code> - Read nodes/relationships (with or without index)</li> <li><code>Filter</code> - Apply predicates</li> <li><code>Expand</code> - Traverse relationships</li> <li><code>Project</code> - Select output columns</li> <li><code>Sort</code> - Order results</li> <li><code>Aggregate</code> - Group and aggregate</li> </ul> Index usage: Look for “uses index: <name>” to confirm index selection. <h4 id="profile-execution-metrics" class="position-relative d-flex align-items-center group"> PROFILE: Execution Metrics <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-execution-metrics" aria-haspopup="dialog" aria-label="Share link: PROFILE: Execution Metrics"> Share link </button> </h4>Run query and show actual performance metrics: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">PROFILE MATCH (p:Person)-[:KNOWS]->(friend) WHERE p.age > 25 RETURN p.name, friend.name; </code></pre></div>Sample output: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Project [p.name, friend.name] Rows: 150 | Time: 0.5ms Expand [(p)-[:KNOWS]->(friend)] Rows: 200 | Time: 1.2ms Filter [p.age > 25] Rows: 500 | Time: 0.8ms Scan [Person] (uses index: person_age_idx) Rows: 1000 | Time: 0.3ms | Index: person_age_idx </code></pre></div>Metrics: <ul> <li>Rows: Actual rows processed at each operator</li> <li>Time: Execution time per operator</li> <li>Index: Index used (if any)</li> </ul> Performance analysis: <ul> <li>High row counts early → poor selectivity, consider better indexes</li> <li>High time in <code>Expand</code> → relationship fanout, consider materialized views</li> <li>No index usage → add index for <code>WHERE</code>/<code>ORDER BY</code> columns</li> </ul> See also: <code>EXPLAIN_PROFILE.md</code> for detailed usage patterns <h3 id="full-text-search-with-bm25" class="position-relative d-flex align-items-center group"> Full-text Search with BM25 <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="full-text-search-with-bm25" aria-haspopup="dialog" aria-label="Share link: Full-text Search with BM25"> Share link </button> </h3>From <code>BM25_INDEX_OPTIMIZER_INTEGRATION.md</code>: BM25 scoring provides relevance ranking for full-text queries. Formula: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">BM25(d, q) = Σ IDF(qi) * (f(qi, d) * (k1 + 1)) / (f(qi, d) + k1 * (1 - b + b * |d| / avgdl)) </code></pre></div>Where: <ul> <li><code>f(qi, d)</code> = term frequency of query term qi in document d</li> <li><code>|d|</code> = document length</li> <li><code>avgdl</code> = average document length</li> <li><code>k1</code> = term frequency saturation (default: 1.2)</li> <li><code>b</code> = length normalization (default: 0.75)</li> </ul> Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Full-text search with BM25 ranking CREATE INDEX article_content_idx ON Article(content) USING fulltext; MATCH (a:Article) WHERE fulltext_match(a.content, "graph database") RETURN a.title, bm25_score(a.content, "graph database") AS score ORDER BY score DESC LIMIT 10; </code></pre></div>Optimizer integration: When <code>ORDER BY bm25_score(...)</code> is present, the optimizer selects full-text index automatically. <h3 id="performance-checklist" class="position-relative d-flex align-items-center group"> Performance Checklist <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-checklist" aria-haspopup="dialog" aria-label="Share link: Performance Checklist"> Share link </button> </h3> <h4 id="1-index-key-predicates" class="position-relative d-flex align-items-center group"> 1. Index Key Predicates <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="1-index-key-predicates" aria-haspopup="dialog" aria-label="Share link: 1. Index Key Predicates"> Share link </button> </h4>Before: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Sequential scan of all Person nodes MATCH (p:Person) WHERE p.email = "[email protected]" RETURN p; </code></pre></div>After: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create hash index CREATE INDEX person_email_idx ON Person(email) USING hash; -- Now uses index MATCH (p:Person) WHERE p.email = "[email protected]" RETURN p; </code></pre></div> <h4 id="2-use-selective-predicates" class="position-relative d-flex align-items-center group"> 2. Use Selective Predicates <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="2-use-selective-predicates" aria-haspopup="dialog" aria-label="Share link: 2. Use Selective Predicates"> Share link </button> </h4>Selectivity = fraction of rows matching predicate. Good (high selectivity, few matches): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">WHERE p.email = "[email protected]" -- Selectivity ~0.0001% </code></pre></div>Bad (low selectivity, many matches): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">WHERE p.active = true -- Selectivity ~90% </code></pre></div>Tip: Filter on high-selectivity predicates first, then apply low-selectivity filters. <h4 id="3-order-deterministically" class="position-relative d-flex align-items-center group"> 3. Order Deterministically <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="3-order-deterministically" aria-haspopup="dialog" aria-label="Share link: 3. Order Deterministically"> Share link </button> </h4>From <code>match_tutorial.md</code>: Geode enforces deterministic ordering for pagination. Explicit ordering (required): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">MATCH (p:Person) RETURN p.name ORDER BY p.created_at DESC, p.id ASC -- Deterministic LIMIT 10; </code></pre></div>Unordered pagination (rejected with <code>US001</code>): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">MATCH (p:Person) RETURN p.name LIMIT 10; </code></pre></div> <h4 id="4-use-explain-before-profile" class="position-relative d-flex align-items-center group"> 4. Use EXPLAIN Before 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="4-use-explain-before-profile" aria-haspopup="dialog" aria-label="Share link: 4. Use EXPLAIN Before PROFILE"> Share link </button> </h4>Workflow: <ol> <li>Write query</li> <li>Run <code>EXPLAIN</code> to check plan and index usage</li> <li>Add/adjust indexes if needed</li> <li>Run <code>PROFILE</code> to verify performance</li> </ol> Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Step 1: Check plan EXPLAIN MATCH (p:Person) WHERE p.age > 30 RETURN p.name ORDER BY p.age; -- Step 2: See "Scan [Person] (no index)" → add index CREATE INDEX person_age_idx ON Person(age) USING btree; -- Step 3: Re-check plan EXPLAIN MATCH (p:Person) WHERE p.age > 30 RETURN p.name ORDER BY p.age; -- Now shows "Scan [Person] (uses index: person_age_idx)" -- Step 4: Profile actual performance PROFILE MATCH (p:Person) WHERE p.age > 30 RETURN p.name ORDER BY p.age; </code></pre></div> <h4 id="5-optimize-relationship-traversal" class="position-relative d-flex align-items-center group"> 5. Optimize Relationship Traversal <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="5-optimize-relationship-traversal" aria-haspopup="dialog" aria-label="Share link: 5. Optimize Relationship Traversal"> Share link </button> </h4>High fanout (many relationships per node) can be expensive. Before: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Expands all KNOWS relationships (potentially millions) MATCH (p:Person {name: "Alice"})-[:KNOWS*]->(friend) RETURN friend.name; </code></pre></div>After: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Limit depth MATCH (p:Person {name: "Alice"})-[:KNOWS*1..3]->(friend) RETURN DISTINCT friend.name; -- Or use specific path patterns MATCH (p:Person {name: "Alice"})-[:KNOWS]->(f1)-[:KNOWS]->(f2) WHERE NOT (p)-[:KNOWS]->(f2) -- Friends of friends only RETURN DISTINCT f2.name; </code></pre></div> <h3 id="federation-and-distributed-queries" class="position-relative d-flex align-items-center group"> Federation and Distributed 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="federation-and-distributed-queries" aria-haspopup="dialog" aria-label="Share link: Federation and Distributed Queries"> Share link </button> </h3>From <code>DISTRIBUTED_QUERY_COORDINATION.md</code>: EXPLAIN FEDERATION: Show distributed query plan <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">EXPLAIN FEDERATION MATCH (p:Person)-[:KNOWS]->(friend) WHERE p.city = "NYC" RETURN p.name, friend.name; </code></pre></div>Output: <ul> <li>Shows which shards/instances are queried</li> <li>Merge operator for combining results</li> <li>Network cost estimates</li> </ul> Distributed optimization: <ul> <li>Push predicates to remote instances (reduce network transfer)</li> <li>Parallelize shard queries</li> <li>Merge results with deterministic ordering</li> </ul> See also: <a href="/docs/architecture/performance-and-scaling" >Performance and Scalability</a> for distributed patterns <h3 id="next-steps" class="position-relative d-flex align-items-center group"> Next Steps <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"> Share link </button> </h3><ul> <li><a href="/docs/query/explain-profile/" >EXPLAIN and PROFILE Reference</a> - Detailed operator reference</li> <li><a href="/docs/architecture/performance-and-scaling" >Performance and Scalability</a> - Architecture and scaling patterns</li> <li><a href="/docs/query/full-text-search/" >BM25 Integration</a> - Full-text search tuning</li> <li><a href="/docs/model/data-model-and-types" >Data Model and Types</a> - Type-specific indexing guidance</li> <li><a href="/docs/tutorials/overview" >Tutorials</a> - Performance tuning tutorial</li> </ul>