MATCH Clause

The MATCH clause is the primary mechanism for finding patterns in your graph data with Geode. As the foundation of GQL queries, MATCH allows you to declaratively specify the graph structures you want to retrieve, from simple node lookups to complex multi-hop traversals. <h3 id="what-is-match" class="position-relative d-flex align-items-center group"> What is MATCH? <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="what-is-match" aria-haspopup="dialog" aria-label="Share link: What is MATCH?"> 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>MATCH is a declarative graph pattern matching clause that: <ul> <li>Finds Patterns: Locates nodes and relationships matching specified patterns</li> <li>Binds Variables: Assigns names to matched elements for use in other clauses</li> <li>Traverses Graphs: Navigates relationships between nodes</li> <li>Filters Results: Combines with WHERE for property-based filtering</li> <li>Composes Queries: Chains multiple patterns together</li> </ul> MATCH is analogous to SQL’s FROM clause but designed specifically for graph structures. <h3 id="basic-syntax" class="position-relative d-flex align-items-center group"> Basic 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="basic-syntax" aria-haspopup="dialog" aria-label="Share link: Basic Syntax"> Share link </button> </h3> <h4 id="node-patterns" class="position-relative d-flex align-items-center group"> Node 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="node-patterns" aria-haspopup="dialog" aria-label="Share link: Node Patterns"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Match any single node MATCH (n) RETURN n // Match nodes with specific label MATCH (u:User) RETURN u // Match with inline property filter MATCH (u:User {verified: true}) RETURN u // Match with multiple properties MATCH (p:Product {category: 'electronics', in_stock: true}) RETURN p // Match with multiple labels MATCH (u:User:Premium:Verified) RETURN u // Anonymous node (no variable binding) MATCH (:User) RETURN COUNT(*) AS user_count </code></pre></div>Syntax Components: <ul> <li><code>(n)</code> - Parentheses denote nodes, <code>n</code> is variable name</li> <li><code>:Label</code> - Colon prefix for label constraint</li> <li><code>{prop: value}</code> - Curly braces for inline property filters</li> <li>Multiple labels are AND conditions (must have all labels)</li> </ul> <h4 id="relationship-patterns" class="position-relative d-flex align-items-center group"> Relationship 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="relationship-patterns" aria-haspopup="dialog" aria-label="Share link: Relationship Patterns"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Any directed relationship MATCH (a)-[r]->(b) RETURN a, r, b // Specific relationship type MATCH (u:User)-[:FOLLOWS]->(other:User) RETURN u.name, other.name // Relationship with variable binding MATCH (u:User)-[f:FOLLOWS]->(other:User) RETURN u.name, other.name, f.since // Relationship with properties MATCH (u:User)-[:RATED {score: 5}]->(m:Movie) RETURN u.name, m.title // Multiple relationship types (OR condition) MATCH (u:User)-[:FOLLOWS|:BLOCKS]->(other:User) RETURN u.name, other.name, TYPE(r) AS relationship_type // Undirected relationship (either direction) MATCH (a:Person)-[:KNOWS]-(b:Person) RETURN a.name, b.name // Reverse direction MATCH (post:Post)<-[:POSTED]-(author:User) RETURN post.title, author.name // No relationship variable needed MATCH (u:User)-[:FOLLOWS]->(:User) RETURN u.name </code></pre></div>Relationship Directions: <ul> <li><code>-></code> - Directed right (from left to right)</li> <li><code><-</code> - Directed left (from right to left)</li> <li><code>-</code> - Undirected (matches both directions)</li> </ul> <h4 id="complete-path-patterns" class="position-relative d-flex align-items-center group"> Complete Path 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="complete-path-patterns" aria-haspopup="dialog" aria-label="Share link: Complete Path Patterns"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Linear path (3 nodes, 2 relationships) MATCH (a:User)-[:FOLLOWS]->(b:User)-[:FOLLOWS]->(c:User) RETURN a.name, b.name, c.name // Triangle pattern MATCH (a:User)-[:FOLLOWS]->(b:User)-[:FOLLOWS]->(c:User) WHERE (a)-[:FOLLOWS]->(c) RETURN a, b, c // Star pattern (one center, multiple connections) MATCH (center:User)-[:FOLLOWS]->(f1:User), (center)-[:FOLLOWS]->(f2:User), (center)-[:FOLLOWS]->(f3:User) WHERE f1 <> f2 AND f2 <> f3 AND f1 <> f3 RETURN center.name, COLLECT([f1.name, f2.name, f3.name]) AS following // Bi-directional pattern MATCH (a:User)-[:FOLLOWS]->(b:User)<-[:FOLLOWS]-(a) RETURN a.name, b.name // Mutual followers </code></pre></div> <h3 id="variable-length-patterns" class="position-relative d-flex align-items-center group"> Variable-Length 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="variable-length-patterns" aria-haspopup="dialog" aria-label="Share link: Variable-Length Patterns"> Share link </button> </h3> <h4 id="basic-variable-length-syntax" class="position-relative d-flex align-items-center group"> Basic Variable-Length 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="basic-variable-length-syntax" aria-haspopup="dialog" aria-label="Share link: Basic Variable-Length Syntax"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Exactly N hops MATCH (a:User)-[:KNOWS*2]->(b:User) RETURN a.name, b.name // Friends of friends (2 hops exactly) // Range of hops (min..max) MATCH (a:User)-[:KNOWS*1..3]->(b:User) RETURN a.name, b.name // 1 to 3 hops away // Minimum hops only (N or more) MATCH (a:User)-[:KNOWS*2..]->(b:User) RETURN a.name, b.name // At least 2 hops // Maximum hops only (up to N) MATCH (a:User)-[:KNOWS*..4]->(b:User) RETURN a.name, b.name // Up to 4 hops // Unbounded (any number of hops - use with caution!) MATCH (a:User)-[:KNOWS*]->(b:User) RETURN a.name, b.name LIMIT 100 </code></pre></div>Important: Always use bounded variable-length patterns in production to prevent excessive graph traversal. <h4 id="path-variable-binding" class="position-relative d-flex align-items-center group"> Path Variable Binding <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="path-variable-binding" aria-haspopup="dialog" aria-label="Share link: Path Variable Binding"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Bind entire path to variable MATCH path = (a:User {name: 'Alice'})-[:KNOWS*1..3]->(b:User) RETURN path, LENGTH(path) AS hops, NODES(path) AS nodes_in_path, RELATIONSHIPS(path) AS rels_in_path // Path functions MATCH path = (a:City)-[:ROAD*]->(b:City) WHERE a.name = 'New York' AND b.name = 'Los Angeles' RETURN LENGTH(path) AS segments, [node IN NODES(path) | node.name] AS cities, [rel IN RELATIONSHIPS(path) | rel.distance] AS distances, REDUCE(total = 0, rel IN RELATIONSHIPS(path) | total + rel.distance) AS total_distance ORDER BY total_distance LIMIT 1 </code></pre></div> <h4 id="shortest-path" class="position-relative d-flex align-items-center group"> Shortest Path <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="shortest-path" aria-haspopup="dialog" aria-label="Share link: Shortest Path"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Single shortest path MATCH path = SHORTEST_PATH((a:User {id: 1})-[:KNOWS*]-(b:User {id: 100})) RETURN path, LENGTH(path) AS degrees_of_separation // Shortest path with relationship type constraint MATCH path = SHORTEST_PATH((a:Airport)-[:FLIGHT*]-(b:Airport)) WHERE a.code = 'JFK' AND b.code = 'LAX' RETURN path, [node IN NODES(path) | node.code] AS route, SUM([rel IN RELATIONSHIPS(path) | rel.distance]) AS total_miles // All shortest paths (if multiple exist) MATCH path = ALL_SHORTEST_PATHS((a:User)-[:KNOWS*]-(b:User)) WHERE a.id = 1 AND b.id = 100 RETURN path, LENGTH(path) AS hops // Shortest path with constraints MATCH path = SHORTEST_PATH((a:Station)-[:CONNECTED*]-(b:Station)) WHERE a.name = 'Central' AND b.name = 'Airport' AND ALL(rel IN RELATIONSHIPS(path) WHERE rel.operational = true) AND ALL(node IN NODES(path) WHERE node.status = 'open') RETURN path </code></pre></div> <h3 id="multiple-match-clauses" class="position-relative d-flex align-items-center group"> Multiple MATCH Clauses <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="multiple-match-clauses" aria-haspopup="dialog" aria-label="Share link: Multiple MATCH Clauses"> Share link </button> </h3> <h4 id="independent-patterns" class="position-relative d-flex align-items-center group"> Independent 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="independent-patterns" aria-haspopup="dialog" aria-label="Share link: Independent Patterns"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Sequential MATCH clauses MATCH (u:User) WHERE u.verified = true MATCH (u)-[:POSTED]->(p:Post) WHERE p.published = true RETURN u.name, p.title // Comma-separated patterns (same MATCH clause) MATCH (u:User {verified: true})-[:POSTED]->(p:Post), (p)-[:HAS_TAG]->(t:Tag) RETURN u.name, p.title, COLLECT(t.name) AS tags // Cartesian product (use with care!) MATCH (u:User), (p:Product) WHERE u.location = p.region RETURN u.name, p.name </code></pre></div> <h4 id="dependent-patterns" class="position-relative d-flex align-items-center group"> Dependent 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="dependent-patterns" aria-haspopup="dialog" aria-label="Share link: Dependent Patterns"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Second MATCH uses results from first MATCH (u:User {name: 'Alice'}) MATCH (u)-[:FOLLOWS]->(following:User)-[:POSTED]->(p:Post) WHERE p.created_at > DATE() - DURATION('P7D') RETURN following.name, COUNT(p) AS recent_posts ORDER BY recent_posts DESC // Chain multiple traversals MATCH (start:Category {name: 'Electronics'}) MATCH (start)-[:SUBCATEGORY*1..3]->(category:Category) MATCH (category)<-[:IN_CATEGORY]-(product:Product) WHERE product.in_stock = true RETURN category.name, COUNT(product) AS available_products ORDER BY available_products DESC </code></pre></div> <h3 id="optional-match" class="position-relative d-flex align-items-center group"> OPTIONAL MATCH <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="optional-match" aria-haspopup="dialog" aria-label="Share link: OPTIONAL MATCH"> Share link </button> </h3> <h4 id="left-outer-join" class="position-relative d-flex align-items-center group"> Left Outer Join <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="left-outer-join" aria-haspopup="dialog" aria-label="Share link: Left Outer Join"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Return users even if they have no posts MATCH (u:User) OPTIONAL MATCH (u)-[:POSTED]->(p:Post) RETURN u.name, COUNT(p) AS post_count ORDER BY post_count DESC // Multiple optional matches MATCH (u:User) OPTIONAL MATCH (u)-[:POSTED]->(p:Post) OPTIONAL MATCH (u)-[:FOLLOWS]->(f:User) OPTIONAL MATCH (u)-[:LIKED]->(liked:Post) RETURN u.name, COUNT(DISTINCT p) AS posts, COUNT(DISTINCT f) AS following, COUNT(DISTINCT liked) AS likes // Optional with WHERE filter MATCH (u:User) OPTIONAL MATCH (u)-[:POSTED]->(p:Post) WHERE p.published = true RETURN u.name, COLLECT(p.title) AS published_posts </code></pre></div> <h4 id="mixed-required-and-optional" class="position-relative d-flex align-items-center group"> Mixed Required and Optional <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="mixed-required-and-optional" aria-haspopup="dialog" aria-label="Share link: Mixed Required and Optional"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Required user, optional posts and followers MATCH (u:User {verified: true}) OPTIONAL MATCH (u)-[:POSTED]->(p:Post) OPTIONAL MATCH (u)<-[:FOLLOWS]-(follower:User) RETURN u.name, COUNT(DISTINCT p) AS posts, COUNT(DISTINCT follower) AS followers ORDER BY followers DESC // Required relationship, optional second level MATCH (u:User)-[:MEMBER_OF]->(g:Group) OPTIONAL MATCH (g)-[:PARENT_GROUP]->(parent:Group) RETURN u.name, g.name, parent.name AS parent_group_name </code></pre></div> <h3 id="match-with-where" class="position-relative d-flex align-items-center group"> MATCH with WHERE <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="match-with-where" aria-haspopup="dialog" aria-label="Share link: MATCH with WHERE"> Share link </button> </h3> <h4 id="property-filters" class="position-relative d-flex align-items-center group"> Property Filters <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="property-filters" aria-haspopup="dialog" aria-label="Share link: Property Filters"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Simple property conditions MATCH (u:User) WHERE u.age >= 18 AND u.verified = true AND u.status = 'active' RETURN u // String operations MATCH (p:Product) WHERE p.name STARTS WITH 'iPhone' OR p.name ENDS WITH 'Pro' OR p.name CONTAINS 'Max' RETURN p.name // Numeric ranges MATCH (p:Product) WHERE p.price BETWEEN 100 AND 500 AND p.rating >= 4.0 RETURN p.name, p.price, p.rating // IN operator MATCH (u:User) WHERE u.role IN ['admin', 'moderator', 'editor'] AND u.region IN ['US', 'CA', 'UK'] RETURN u.name, u.role, u.region // Regular expressions MATCH (u:User) WHERE u.email =~ '.*@(gmail|hotmail|yahoo)\\.com$' RETURN u.name, u.email // Null checks MATCH (u:User) WHERE u.phone_verified IS NOT NULL AND u.email_verified IS NULL RETURN u.name </code></pre></div> <h4 id="pattern-predicates" class="position-relative d-flex align-items-center group"> Pattern 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="pattern-predicates" aria-haspopup="dialog" aria-label="Share link: Pattern Predicates"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Existence check MATCH (u:User) WHERE (u)-[:POSTED]->(:Post) RETURN u.name // Users who have posted // Non-existence check MATCH (u:User) WHERE NOT (u)-[:POSTED]->(:Post) RETURN u.name // Users who haven't posted // Complex pattern predicates MATCH (u:User) WHERE (u)-[:POSTED]->(:Post {featured: true}) AND NOT (u)-[:SUSPENDED]->() AND SIZE((u)-[:FOLLOWS]->(:User)) > 100 RETURN u.name AS influencer // Pattern with property constraints MATCH (u:User) WHERE (u)-[:RATED {score: 5}]->(:Movie) RETURN u.name // Users who gave 5-star ratings // Counting in predicates MATCH (u:User) WHERE SIZE((u)-[:POSTED]->(:Post)) > 10 AND SIZE((u)<-[:FOLLOWS]-(:User)) > 100 RETURN u.name AS power_user </code></pre></div> <h4 id="collection-predicates" class="position-relative d-flex align-items-center group"> Collection 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="collection-predicates" aria-haspopup="dialog" aria-label="Share link: Collection Predicates"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// IN operator with property MATCH (u:User) WHERE 'python' IN u.skills RETURN u.name // ALL predicate MATCH (u:User) WHERE ALL(tag IN u.tags WHERE LENGTH(tag) > 2) RETURN u.name, u.tags // ANY predicate MATCH (u:User) WHERE ANY(score IN u.test_scores WHERE score > 90) RETURN u.name // NONE predicate MATCH (u:User) WHERE NONE(flag IN u.flags WHERE flag = 'banned') RETURN u.name // SINGLE predicate MATCH (u:User) WHERE SINGLE(email IN u.contact_emails WHERE email ENDS WITH '@company.com') RETURN u.name </code></pre></div> <h3 id="advanced-match-patterns" class="position-relative d-flex align-items-center group"> Advanced MATCH 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="advanced-match-patterns" aria-haspopup="dialog" aria-label="Share link: Advanced MATCH Patterns"> Share link </button> </h3> <h4 id="subquery-expressions" class="position-relative d-flex align-items-center group"> Subquery Expressions <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-expressions" aria-haspopup="dialog" aria-label="Share link: Subquery Expressions"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// EXISTS with subquery MATCH (u:User) WHERE EXISTS { MATCH (u)-[:POSTED]->(p:Post) WHERE p.likes > 100 } RETURN u.name // COUNT in subquery MATCH (u:User) WHERE COUNT { MATCH (u)-[:POSTED]->(p:Post) WHERE p.published = true } > 10 RETURN u.name // Nested patterns MATCH (u:User) WHERE EXISTS { MATCH (u)-[:FOLLOWS]->(f:User) WHERE EXISTS { MATCH (f)-[:POSTED]->(p:Post) WHERE p.featured = true } } RETURN u.name // Users following someone with featured posts </code></pre></div> <h4 id="list-comprehensions" class="position-relative d-flex align-items-center group"> List Comprehensions <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="list-comprehensions" aria-haspopup="dialog" aria-label="Share link: List Comprehensions"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Pattern-based list comprehension MATCH (u:User) RETURN u.name, [(u)-[:FOLLOWS]->(f:User) | f.name] AS following_names // With filtering MATCH (u:User) RETURN u.name, [(u)-[:FOLLOWS]->(f:User) WHERE f.verified = true | f.name] AS verified_following // With transformation MATCH (u:User) RETURN u.name, [(u)-[:POSTED]->(p:Post) | {title: p.title, likes: p.likes}] AS posts // Nested comprehensions MATCH (u:User) RETURN u.name, [(u)-[:MEMBER_OF]->(g:Group) | { group: g.name, members: [(g)<-[:MEMBER_OF]-(m:User) | m.name] } ] AS groups_and_members </code></pre></div> <h3 id="performance-optimization" class="position-relative d-flex align-items-center group"> Performance 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="performance-optimization" aria-haspopup="dialog" aria-label="Share link: Performance Optimization"> Share link </button> </h3> <h4 id="anchor-pattern-first" class="position-relative d-flex align-items-center group"> Anchor Pattern First <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="anchor-pattern-first" aria-haspopup="dialog" aria-label="Share link: Anchor Pattern First"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Good: Start with indexed property MATCH (u:User {email: 'alice@example.com'}) MATCH (u)-[:POSTED]->(p:Post) RETURN p.title // Avoid: Broad pattern first MATCH (u:User)-[:POSTED]->(p:Post) WHERE u.email = 'alice@example.com' RETURN p.title </code></pre></div> <h4 id="use-inline-filters" class="position-relative d-flex align-items-center group"> Use Inline Filters <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="use-inline-filters" aria-haspopup="dialog" aria-label="Share link: Use Inline Filters"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Good: Inline property filter MATCH (u:User {verified: true, active: true})-[:POSTED]->(p:Post) RETURN p // Less efficient: Separate WHERE clause MATCH (u:User)-[:POSTED]->(p:Post) WHERE u.verified = true AND u.active = true RETURN p </code></pre></div> <h4 id="specify-relationship-direction" class="position-relative d-flex align-items-center group"> Specify Relationship Direction <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="specify-relationship-direction" aria-haspopup="dialog" aria-label="Share link: Specify Relationship Direction"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Good: Known direction MATCH (author:User)-[:POSTED]->(p:Post) RETURN author, p // Slower: Undirected when direction is known MATCH (author:User)-[:POSTED]-(p:Post) RETURN author, p </code></pre></div> <h4 id="limit-variable-length-paths" class="position-relative d-flex align-items-center group"> Limit 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="limit-variable-length-paths" aria-haspopup="dialog" aria-label="Share link: Limit Variable-Length Paths"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Good: Bounded traversal MATCH (a:User)-[:KNOWS*1..4]->(b:User) RETURN b.name // Dangerous: Unbounded traversal MATCH (a:User)-[:KNOWS*]->(b:User) RETURN b.name </code></pre></div> <h3 id="common-patterns" class="position-relative d-flex align-items-center group"> Common 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="common-patterns" aria-haspopup="dialog" aria-label="Share link: Common Patterns"> Share link </button> </h3> <h4 id="social-network" class="position-relative d-flex align-items-center group"> Social Network <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="social-network" aria-haspopup="dialog" aria-label="Share link: Social Network"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Find friends of friends MATCH (me:User {id: $my_id})-[:KNOWS]->(:User)-[:KNOWS]->(fof:User) WHERE NOT (me)-[:KNOWS]->(fof) AND me <> fof RETURN DISTINCT fof.name, COUNT(*) AS mutual_friends ORDER BY mutual_friends DESC // Mutual followers MATCH (me:User {id: $my_id})-[:FOLLOWS]->(mutual)<-[:FOLLOWS]-(you:User {id: $your_id}) RETURN mutual.name // Influencer detection MATCH (u:User)<-[:FOLLOWS]-(follower) WITH u, COUNT(follower) AS follower_count WHERE follower_count > 1000 RETURN u.name, follower_count ORDER BY follower_count DESC </code></pre></div> <h4 id="recommendation" class="position-relative d-flex align-items-center group"> Recommendation <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="recommendation" aria-haspopup="dialog" aria-label="Share link: Recommendation"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Collaborative filtering MATCH (me:User {id: $my_id})-[:PURCHASED]->(p:Product) <-[:PURCHASED]-(other:User)-[:PURCHASED]->(rec:Product) WHERE NOT (me)-[:PURCHASED]->(rec) RETURN rec.name, COUNT(DISTINCT other) AS similar_users ORDER BY similar_users DESC LIMIT 10 // Content-based MATCH (item:Product {id: $product_id})-[:HAS_TAG]->(tag:Tag) <-[:HAS_TAG]-(similar:Product) WHERE item <> similar RETURN similar.name, COUNT(tag) AS shared_tags ORDER BY shared_tags DESC LIMIT 10 </code></pre></div> <h4 id="hierarchical" class="position-relative d-flex align-items-center group"> Hierarchical <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="hierarchical" aria-haspopup="dialog" aria-label="Share link: Hierarchical"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Organization chart MATCH path = (boss:Employee {title: 'CEO'})-[:MANAGES*]->(report:Employee) RETURN report.name, LENGTH(path) AS depth ORDER BY depth, report.name // Category tree MATCH path = (root:Category {name: 'Electronics'})-[:SUBCATEGORY*]->(leaf:Category) WHERE NOT (leaf)-[:SUBCATEGORY]->() RETURN leaf.name, [node IN NODES(path) | node.name] AS breadcrumb </code></pre></div> <h3 id="client-library-examples" class="position-relative d-flex align-items-center group"> Client Library 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="client-library-examples" aria-haspopup="dialog" aria-label="Share link: Client Library Examples"> Share link </button> </h3> <h4 id="python" class="position-relative d-flex align-items-center group"> Python <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="python" aria-haspopup="dialog" aria-label="Share link: Python"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import Client client = Client(host="localhost", port=3141) async with client.connection() as conn: # Simple MATCH result, _ = await conn.query(""" MATCH (u:User)-[:FOLLOWS]->(f:User) WHERE u.id = $user_id RETURN f.name, f.bio """, {"user_id": 123}) for row in result.rows: print(f"{row['name']}: {row['bio']}") # Variable-length path result, _ = await conn.query(""" MATCH path = (a:User)-[:KNOWS*1..3]->(b:User) WHERE a.id = $from AND b.id = $to RETURN [node IN NODES(path) | node.name] AS path_names ORDER BY LENGTH(path) LIMIT 1 """, {"from": 1, "to": 100}) </code></pre></div> <h4 id="go" class="position-relative d-flex align-items-center group"> Go <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="go" aria-haspopup="dialog" aria-label="Share link: Go"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">import "database/sql" import _ "geodedb.com/geode" db, _ := sql.Open("geode", "quic://localhost:3141") rows, _ := db.Query(` MATCH (u:User)-[:POSTED]->(p:Post)<-[:LIKED]-(liker:User) WHERE u.id = $1 RETURN p.title, COUNT(DISTINCT liker) AS likes ORDER BY likes DESC LIMIT 10 `, 123) for rows.Next() { var title string var likes int rows.Scan(&title, &likes) fmt.Printf("%s: %d likes\n", title, likes) } </code></pre></div> <h4 id="rust" class="position-relative d-flex align-items-center group"> Rust <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="rust" aria-haspopup="dialog" aria-label="Share link: Rust"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-rust" data-lang="rust">use geode_client::Client; let client = Client::connect("localhost:3141").await?; let result = client.query( r#" MATCH (u:User {verified: true})-[:POSTED]->(p:Post) WHERE p.published = true RETURN u.name, COUNT(p) AS posts ORDER BY posts DESC LIMIT 10 "#, &[], ).await?; for row in result.rows() { println!("{}: {} posts", row["name"], row["posts"]); } </code></pre></div> <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>Start Specific: Begin with indexed properties for anchoring</li> <li>Use Inline Filters: Apply property filters in MATCH when possible</li> <li>Know Directions: Specify relationship directions when known</li> <li>Bound Paths: Always limit variable-length pattern hops</li> <li>Filter Early: Apply WHERE conditions immediately after relevant MATCH</li> <li>Avoid Cartesian Products: Connect patterns with relationships</li> <li>Use OPTIONAL Carefully: Understand LEFT OUTER JOIN semantics</li> <li>Index Strategically: Create indexes on frequently matched properties</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>Pattern Matching: Deep dive into graph patterns</li> <li>Query Language: Complete GQL syntax</li> <li>WHERE Clause: Filtering and predicates</li> <li>EXPLAIN: Query execution analysis</li> <li>Performance: Query optimization</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="/tags/pattern-matching/" >Pattern Matching</a> - Graph pattern techniques</li> <li><a href="/tags/query-language/" >Query Language</a> - Full GQL guide</li> <li><a href="/tags/explain/" >EXPLAIN</a> - Query optimization</li> <li><a href="/tags/performance/" >Performance</a> - Performance tuning</li> <li><a href="/tags/gql-reference/" >GQL Reference</a> - Complete GQL documentation</li> </ul> The MATCH clause is the foundation of graph querying in Geode, enabling you to express complex graph patterns with simple, declarative syntax that scales from simple lookups to sophisticated graph analytics.

Popular

Related Articles

Graph Query Language (GQL) Guide