RETURN Clause in GQL

<h2 id="return-clause-in-gql" class="position-relative d-flex align-items-center group"> RETURN Clause in GQL <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="return-clause-in-gql" aria-haspopup="dialog" aria-label="Share link: RETURN Clause in GQL"> 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>The RETURN clause specifies what data your GQL query produces as output. It defines which variables, properties, expressions, and aggregations appear in the result set. Understanding RETURN is essential for crafting effective queries that deliver precisely the data your application needs. Geode implements the RETURN clause according to the ISO/IEC 39075:2024 GQL standard. <h3 id="introduction-to-return" class="position-relative d-flex align-items-center group"> Introduction to RETURN <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="introduction-to-return" aria-haspopup="dialog" aria-label="Share link: Introduction to RETURN"> Share link </button> </h3>Every read query in GQL must end with a RETURN clause (or use a writing clause like CREATE). The RETURN clause acts as the projection layer, determining which columns appear in your result and how they are formatted. Key characteristics of RETURN: <ul> <li>Projection: Select specific properties or entire elements</li> <li>Aliasing: Rename columns with AS for clarity</li> <li>Expressions: Return computed values and transformations</li> <li>Ordering: Control result order with ORDER BY</li> <li>Pagination: Limit results with SKIP and LIMIT</li> <li>Deduplication: Remove duplicates with DISTINCT</li> <li>Aggregation: Combine with aggregation functions</li> </ul> <h3 id="basic-return-syntax" class="position-relative d-flex align-items-center group"> Basic RETURN 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-return-syntax" aria-haspopup="dialog" aria-label="Share link: Basic RETURN Syntax"> Share link </button> </h3> <h4 id="returning-nodes-and-relationships" class="position-relative d-flex align-items-center group"> Returning Nodes and Relationships <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="returning-nodes-and-relationships" aria-haspopup="dialog" aria-label="Share link: Returning Nodes and Relationships"> Share link </button> </h4>Return complete graph elements with all their properties. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Return all properties of matched nodes MATCH (p:Person) RETURN p; -- Return relationship MATCH (a:Person)-[r:KNOWS]->(b:Person) RETURN r; -- Return multiple elements MATCH (a:Person)-[r:KNOWS]->(b:Person) RETURN a, r, b; </code></pre></div> <h4 id="returning-specific-properties" class="position-relative d-flex align-items-center group"> Returning Specific Properties <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="returning-specific-properties" aria-haspopup="dialog" aria-label="Share link: Returning Specific Properties"> Share link </button> </h4>Select individual properties instead of entire nodes. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Return single property MATCH (p:Person) RETURN p.name; -- Return multiple properties MATCH (p:Person) RETURN p.name, p.age, p.email; -- Return properties from multiple nodes MATCH (a:Person)-[:FRIEND]->(b:Person) RETURN a.name, b.name; </code></pre></div> <h4 id="using-aliases" class="position-relative d-flex align-items-center group"> Using Aliases <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-aliases" aria-haspopup="dialog" aria-label="Share link: Using Aliases"> Share link </button> </h4>Rename columns for clarity and to resolve naming conflicts. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Simple alias MATCH (p:Person) RETURN p.name AS person_name; -- Descriptive aliases MATCH (e:Employee)-[:WORKS_IN]->(d:Department) RETURN e.name AS employee_name, e.title AS job_title, d.name AS department_name; -- Resolve naming conflicts MATCH (a:Person)-[:FRIEND]->(b:Person) RETURN a.name AS person, b.name AS friend; </code></pre></div> <h3 id="expressions-in-return" class="position-relative d-flex align-items-center group"> Expressions in RETURN <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="expressions-in-return" aria-haspopup="dialog" aria-label="Share link: Expressions in RETURN"> Share link </button> </h3> <h4 id="mathematical-expressions" class="position-relative d-flex align-items-center group"> Mathematical 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="mathematical-expressions" aria-haspopup="dialog" aria-label="Share link: Mathematical Expressions"> Share link </button> </h4>Perform calculations in the RETURN clause. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Basic arithmetic MATCH (p:Product) RETURN p.name, p.price, p.price * 1.1 AS price_with_tax, p.price * p.quantity AS total_value; -- Using mathematical functions MATCH (p:Point) RETURN p.name, sqrt(p.x * p.x + p.y * p.y) AS distance_from_origin, round(p.value, 2) AS rounded_value; </code></pre></div> <h4 id="string-operations" class="position-relative d-flex align-items-center group"> String Operations <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="string-operations" aria-haspopup="dialog" aria-label="Share link: String Operations"> Share link </button> </h4>Manipulate string values. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- String concatenation MATCH (p:Person) RETURN p.firstName + ' ' + p.lastName AS full_name; -- String functions MATCH (p:Person) RETURN toUpper(p.name) AS name_upper, toLower(p.email) AS email_lower, substring(p.bio, 0, 100) AS bio_preview; -- String formatting MATCH (u:User) RETURN u.name, 'User: ' + u.name + ' (' + u.email + ')' AS formatted; </code></pre></div> <h4 id="conditional-expressions" class="position-relative d-flex align-items-center group"> Conditional 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="conditional-expressions" aria-haspopup="dialog" aria-label="Share link: Conditional Expressions"> Share link </button> </h4>Use CASE for conditional logic. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Simple CASE MATCH (p:Product) RETURN p.name, p.price, CASE WHEN p.price < 10 THEN 'Budget' WHEN p.price < 50 THEN 'Standard' WHEN p.price < 100 THEN 'Premium' ELSE 'Luxury' END AS price_tier; -- CASE with equality MATCH (o:Order) RETURN o.id, CASE o.status WHEN 'pending' THEN 'Awaiting Processing' WHEN 'shipped' THEN 'On the Way' WHEN 'delivered' THEN 'Complete' ELSE 'Unknown' END AS status_display; -- Conditional with NULL handling MATCH (u:User) RETURN u.name, COALESCE(u.nickname, u.name) AS display_name, CASE WHEN u.verified IS NULL THEN false ELSE u.verified END AS is_verified; </code></pre></div> <h4 id="date-and-time-expressions" class="position-relative d-flex align-items-center group"> Date and Time 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="date-and-time-expressions" aria-haspopup="dialog" aria-label="Share link: Date and Time Expressions"> Share link </button> </h4>Work with temporal values. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Date calculations MATCH (e:Event) RETURN e.name, e.start_date, e.end_date, duration.between(e.start_date, e.end_date).days AS duration_days; -- Date formatting MATCH (u:User) RETURN u.name, u.created_at, u.created_at.year AS join_year, u.created_at.month AS join_month; -- Relative dates MATCH (p:Post) WHERE p.created_at > datetime() - duration('P7D') RETURN p.title, p.created_at AS posted_at; </code></pre></div> <h3 id="structuring-results" class="position-relative d-flex align-items-center group"> Structuring Results <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="structuring-results" aria-haspopup="dialog" aria-label="Share link: Structuring Results"> Share link </button> </h3> <h4 id="returning-maps" class="position-relative d-flex align-items-center group"> Returning Maps <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="returning-maps" aria-haspopup="dialog" aria-label="Share link: Returning Maps"> Share link </button> </h4>Create structured objects in results. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Return a map MATCH (p:Person)-[:LIVES_IN]->(c:City) RETURN { name: p.name, age: p.age, city: c.name, country: c.country } AS person_info; -- Nested maps MATCH (e:Employee)-[:WORKS_IN]->(d:Department)-[:PART_OF]->(c:Company) RETURN { employee: {name: e.name, title: e.title}, organization: {department: d.name, company: c.name} } AS employment_details; </code></pre></div> <h4 id="returning-lists" class="position-relative d-flex align-items-center group"> Returning Lists <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="returning-lists" aria-haspopup="dialog" aria-label="Share link: Returning Lists"> Share link </button> </h4>Construct lists in the result. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Simple list MATCH (p:Person) RETURN [p.name, p.email, p.phone] AS contact_info; -- List from properties MATCH (p:Product) RETURN p.name, [p.color, p.size, p.material] AS attributes; -- List comprehension MATCH (u:User)-[:PURCHASED]->(p:Product) RETURN u.name, [p.name] AS product_names; </code></pre></div> <h4 id="returning-paths" class="position-relative d-flex align-items-center group"> Returning 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="returning-paths" aria-haspopup="dialog" aria-label="Share link: Returning Paths"> Share link </button> </h4>Return complete traversal paths. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Return entire path MATCH path = (a:Person)-[:KNOWS*1..3]->(b:Person) WHERE a.name = 'Alice' AND b.name = 'Diana' RETURN path; -- Path components MATCH path = shortestPath((a:City)-[:CONNECTED*]-(b:City)) WHERE a.name = 'NYC' AND b.name = 'LA' RETURN path, length(path) AS hops, [n IN nodes(path) | n.name] AS cities, [r IN relationships(path) | r.distance] AS distances; </code></pre></div> <h3 id="ordering-results" class="position-relative d-flex align-items-center group"> Ordering Results <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="ordering-results" aria-haspopup="dialog" aria-label="Share link: Ordering Results"> Share link </button> </h3> <h4 id="order-by-basics" class="position-relative d-flex align-items-center group"> ORDER BY Basics <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="order-by-basics" aria-haspopup="dialog" aria-label="Share link: ORDER BY Basics"> Share link </button> </h4>Sort results by one or more columns. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Ascending order (default) MATCH (p:Product) RETURN p.name, p.price ORDER BY p.price; -- Descending order MATCH (p:Product) RETURN p.name, p.price ORDER BY p.price DESC; -- Multiple sort keys MATCH (e:Employee) RETURN e.department, e.name, e.salary ORDER BY e.department ASC, e.salary DESC; </code></pre></div> <h4 id="order-by-expressions" class="position-relative d-flex align-items-center group"> ORDER BY 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="order-by-expressions" aria-haspopup="dialog" aria-label="Share link: ORDER BY Expressions"> Share link </button> </h4>Sort by computed values. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Sort by expression MATCH (p:Product) RETURN p.name, p.price, p.quantity ORDER BY p.price * p.quantity DESC; -- Sort by alias MATCH (u:User)-[:PURCHASED]->(p:Product) RETURN u.name, count(p) AS purchase_count ORDER BY purchase_count DESC; -- Sort by string function MATCH (p:Person) RETURN p.name ORDER BY toLower(p.name); </code></pre></div> <h4 id="null-handling-in-order-by" class="position-relative d-flex align-items-center group"> NULL Handling in ORDER BY <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="null-handling-in-order-by" aria-haspopup="dialog" aria-label="Share link: NULL Handling in ORDER BY"> Share link </button> </h4>Control how NULL values sort. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- NULLs sort last in ascending order by default MATCH (p:Product) RETURN p.name, p.discount ORDER BY p.discount; -- Handle NULLs explicitly MATCH (p:Product) RETURN p.name, COALESCE(p.discount, 0) AS discount ORDER BY discount; </code></pre></div> <h3 id="pagination" class="position-relative d-flex align-items-center group"> Pagination <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="pagination" aria-haspopup="dialog" aria-label="Share link: Pagination"> Share link </button> </h3> <h4 id="limit" class="position-relative d-flex align-items-center group"> LIMIT <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" aria-haspopup="dialog" aria-label="Share link: LIMIT"> Share link </button> </h4>Restrict the number of results returned. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Get first 10 results MATCH (p:Product) RETURN p.name, p.price ORDER BY p.price DESC LIMIT 10; -- Top N pattern MATCH (u:User)<-[:FOLLOWS]-(follower) RETURN u.name, count(follower) AS followers ORDER BY followers DESC LIMIT 5; </code></pre></div> <h4 id="skip" class="position-relative d-flex align-items-center group"> SKIP <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="skip" aria-haspopup="dialog" aria-label="Share link: SKIP"> Share link </button> </h4>Skip a number of results for pagination. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Skip first 20, get next 10 MATCH (p:Product) RETURN p.name, p.price ORDER BY p.name SKIP 20 LIMIT 10; -- Page 3 (0-indexed pages of 25) MATCH (p:Post) RETURN p.title, p.created_at ORDER BY p.created_at DESC SKIP 50 -- Page 2 * 25 LIMIT 25; </code></pre></div> <h4 id="pagination-with-parameters" class="position-relative d-flex align-items-center group"> Pagination with Parameters <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="pagination-with-parameters" aria-haspopup="dialog" aria-label="Share link: Pagination with Parameters"> Share link </button> </h4>Dynamic pagination using parameters. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Parameterized pagination MATCH (p:Product) RETURN p.name, p.price ORDER BY p.price SKIP $offset LIMIT $limit; -- In application code: -- offset = (page_number - 1) * page_size -- limit = page_size </code></pre></div> <h3 id="distinct-results" class="position-relative d-flex align-items-center group"> DISTINCT Results <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="distinct-results" aria-haspopup="dialog" aria-label="Share link: DISTINCT Results"> Share link </button> </h3> <h4 id="basic-distinct" class="position-relative d-flex align-items-center group"> Basic DISTINCT <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-distinct" aria-haspopup="dialog" aria-label="Share link: Basic DISTINCT"> Share link </button> </h4>Remove duplicate rows from results. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Distinct values MATCH (p:Person)-[:LIVES_IN]->(c:City) RETURN DISTINCT c.name; -- Distinct combinations MATCH (p:Person)-[:WORKS_IN]->(d:Department) RETURN DISTINCT d.name, d.location; </code></pre></div> <h4 id="distinct-with-expressions" class="position-relative d-flex align-items-center group"> DISTINCT with 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="distinct-with-expressions" aria-haspopup="dialog" aria-label="Share link: DISTINCT with Expressions"> Share link </button> </h4>Deduplicate based on computed values. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Distinct computed values MATCH (p:Product) RETURN DISTINCT CASE WHEN p.price < 50 THEN 'Low' WHEN p.price < 100 THEN 'Medium' ELSE 'High' END AS price_range; -- Distinct after transformation MATCH (p:Person) RETURN DISTINCT toLower(p.email) AS email; </code></pre></div> <h3 id="aggregation-with-return" class="position-relative d-flex align-items-center group"> Aggregation with RETURN <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-with-return" aria-haspopup="dialog" aria-label="Share link: Aggregation with RETURN"> Share link </button> </h3> <h4 id="aggregation-functions" class="position-relative d-flex align-items-center group"> Aggregation Functions <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-functions" aria-haspopup="dialog" aria-label="Share link: Aggregation Functions"> Share link </button> </h4>Use aggregation functions in RETURN. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Count MATCH (p:Product) RETURN count(p) AS total_products; -- Multiple aggregations MATCH (o:Order) RETURN count(o) AS order_count, sum(o.total) AS total_revenue, avg(o.total) AS average_order, min(o.total) AS smallest_order, max(o.total) AS largest_order; </code></pre></div> <h4 id="grouping-with-aggregation" class="position-relative d-flex align-items-center group"> Grouping with Aggregation <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="grouping-with-aggregation" aria-haspopup="dialog" aria-label="Share link: Grouping with Aggregation"> Share link </button> </h4>Non-aggregated columns create implicit groups. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Group by category MATCH (p:Product)-[:IN_CATEGORY]->(c:Category) RETURN c.name AS category, count(p) AS product_count, avg(p.price) AS avg_price ORDER BY product_count DESC; -- Multiple grouping columns MATCH (s:Sale) RETURN s.year, s.month, s.region, sum(s.amount) AS total_sales ORDER BY s.year, s.month, s.region; </code></pre></div> <h4 id="collect-aggregation" class="position-relative d-flex align-items-center group"> COLLECT Aggregation <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="collect-aggregation" aria-haspopup="dialog" aria-label="Share link: COLLECT Aggregation"> Share link </button> </h4>Gather values into a list. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Collect names MATCH (u:User)-[:MEMBER_OF]->(g:Group) RETURN g.name, collect(u.name) AS members; -- Collect with distinct MATCH (p:Person)-[:TAGGED]->(t:Tag) RETURN p.name, collect(DISTINCT t.name) AS unique_tags; -- Collect maps MATCH (c:Customer)-[:PLACED]->(o:Order) RETURN c.name, collect({ order_id: o.id, total: o.total, date: o.date }) AS orders; </code></pre></div> <h3 id="advanced-return-patterns" class="position-relative d-flex align-items-center group"> Advanced RETURN 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-return-patterns" aria-haspopup="dialog" aria-label="Share link: Advanced RETURN Patterns"> Share link </button> </h3> <h4 id="returning-element-ids" class="position-relative d-flex align-items-center group"> Returning Element IDs <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="returning-element-ids" aria-haspopup="dialog" aria-label="Share link: Returning Element IDs"> Share link </button> </h4>Get internal identifiers for elements. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Element ID function MATCH (p:Person) RETURN elementId(p) AS id, p.name; -- For relationships MATCH (a)-[r:KNOWS]->(b) RETURN elementId(r) AS rel_id, a.name, b.name; </code></pre></div> <h4 id="returning-labels-and-types" class="position-relative d-flex align-items-center group"> Returning Labels and Types <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="returning-labels-and-types" aria-haspopup="dialog" aria-label="Share link: Returning Labels and Types"> Share link </button> </h4>Inspect element metadata. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Get node labels MATCH (n) WHERE n.name = $name RETURN n.name, labels(n) AS node_labels; -- Get relationship type MATCH (a)-[r]->(b) WHERE a.name = $name RETURN a.name, type(r) AS relationship_type, b.name; </code></pre></div> <h4 id="subqueries-in-return" class="position-relative d-flex align-items-center group"> Subqueries in RETURN <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="subqueries-in-return" aria-haspopup="dialog" aria-label="Share link: Subqueries in RETURN"> Share link </button> </h4>Use subqueries for complex projections. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Existential subquery MATCH (p:Person) RETURN p.name, EXISTS { MATCH (p)-[:MANAGES]->(:Person) } AS is_manager; -- Count subquery MATCH (d:Department) RETURN d.name, COUNT { MATCH (d)<-[:WORKS_IN]-(e:Employee) } AS employee_count; </code></pre></div> <h4 id="union-of-results" class="position-relative d-flex align-items-center group"> UNION of Results <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="union-of-results" aria-haspopup="dialog" aria-label="Share link: UNION of Results"> Share link </button> </h4>Combine results from multiple queries. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Union of different queries MATCH (e:Employee) WHERE e.salary > 100000 RETURN e.name AS person, 'High Earner' AS category UNION MATCH (m:Manager) RETURN m.name AS person, 'Manager' AS category; -- Union all (keep duplicates) MATCH (a:Person {name: 'Alice'})-[:FRIEND]->(f) RETURN f.name UNION ALL MATCH (b:Person {name: 'Bob'})-[:FRIEND]->(f) RETURN f.name; </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> <h4 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> </h4><ol> <li>Return Only What You Need: Avoid returning entire nodes when only properties are needed</li> </ol> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Good: Return specific properties MATCH (p:Person) RETURN p.name, p.email; -- Avoid: Returning entire node with many properties MATCH (p:Person) RETURN p; -- May include large unused properties </code></pre></div><ol start="2"> <li>Apply LIMIT Early: When you only need a subset</li> </ol> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Good: Limit before expensive operations MATCH (p:Product) WITH p ORDER BY p.created_at DESC LIMIT 10 RETURN p.name, p.price; </code></pre></div><ol start="3"> <li>Use Aliases for Clarity: Make results self-documenting</li> </ol> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">RETURN u.name AS user_name, count(o) AS total_orders, sum(o.total) AS lifetime_value; </code></pre></div> <h4 id="result-formatting" class="position-relative d-flex align-items-center group"> Result Formatting <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="result-formatting" aria-haspopup="dialog" aria-label="Share link: Result Formatting"> Share link </button> </h4><ol> <li>Consistent Naming: Use consistent alias conventions</li> </ol> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- snake_case for database-like results RETURN p.name AS product_name, p.price AS unit_price; -- camelCase for API responses RETURN p.name AS productName, p.price AS unitPrice; </code></pre></div><ol start="2"> <li>Handle NULLs: Use COALESCE for default values</li> </ol> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">RETURN p.name, COALESCE(p.description, 'No description') AS description, COALESCE(p.discount, 0) AS discount; </code></pre></div><ol start="3"> <li>Format for Consumption: Structure results for your application</li> </ol> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- API-friendly format RETURN { id: elementId(p), name: p.name, price: p.price, metadata: { created: p.created_at, updated: p.updated_at } } AS product; </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="existence-check" class="position-relative d-flex align-items-center group"> Existence Check <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="existence-check" aria-haspopup="dialog" aria-label="Share link: Existence Check"> Share link </button> </h4>Check if data exists. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Return boolean for existence MATCH (u:User {email: $email}) RETURN count(u) > 0 AS user_exists; </code></pre></div> <h4 id="summary-statistics" class="position-relative d-flex align-items-center group"> Summary Statistics <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="summary-statistics" aria-haspopup="dialog" aria-label="Share link: Summary Statistics"> Share link </button> </h4>Compute multiple statistics. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">MATCH (o:Order) RETURN { total_orders: count(o), total_revenue: sum(o.total), average_order: avg(o.total), min_order: min(o.total), max_order: max(o.total) } AS order_statistics; </code></pre></div> <h4 id="hierarchical-results" class="position-relative d-flex align-items-center group"> Hierarchical Results <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-results" aria-haspopup="dialog" aria-label="Share link: Hierarchical Results"> Share link </button> </h4>Return nested structures. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">MATCH (c:Category)-[:CONTAINS]->(p:Product) RETURN { category: c.name, products: collect({ name: p.name, price: p.price }) } AS catalog; </code></pre></div> <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="/tags/where/" >WHERE Clause</a> : Filtering before RETURN</li> <li><a href="/tags/with/" >WITH Clause</a> : Intermediate projections</li> <li><a href="/tags/aggregation/" >Aggregation</a> : Aggregation functions</li> <li><a href="/tags/order-by/" >ORDER BY</a> : Sorting results</li> <li><a href="/tags/match/" >MATCH Clause</a> : Pattern matching</li> <li><a href="/tags/gql-reference/" >GQL Reference</a> : Complete GQL language reference</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>GQL Tutorial - Querying Data: <code>/docs/gql-tutorial/querying-data/</code></li> <li>Query Patterns Cookbook: <code>/docs/guides/query-patterns/</code></li> <li>Performance Guide: <code>/docs/performance/query-optimization/</code></li> <li>Functions Reference: <code>/docs/gql-reference/functions/</code></li> <li>GQL Specification: <code>/docs/gql-reference/specification/</code></li> </ul>

Popular

Related Articles