Graph Modeling Guide | Geode Database

<h2 id="graph-modeling-guide" class="position-relative d-flex align-items-center group"> Graph Modeling Guide <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="graph-modeling-guide" aria-haspopup="dialog" aria-label="Share link: Graph Modeling Guide"> 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>Designing an effective graph schema is crucial for query performance and application maintainability. This guide covers best practices, common patterns, and anti-patterns for modeling data in Geode. <h3 id="graph-thinking" class="position-relative d-flex align-items-center group"> Graph Thinking <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="graph-thinking" aria-haspopup="dialog" aria-label="Share link: Graph Thinking"> Share link </button> </h3> <h4 id="shift-from-tables-to-graphs" class="position-relative d-flex align-items-center group"> Shift from Tables to Graphs <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="shift-from-tables-to-graphs" aria-haspopup="dialog" aria-label="Share link: Shift from Tables to Graphs"> Share link </button> </h4>Relational Thinking: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql">-- Tables with foreign keys Users (id, name, email) Posts (id, user_id, content) Likes (user_id, post_id, timestamp) </code></pre></div>Graph Thinking: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Entities as nodes, connections as relationships (:User {id, name, email}) (:Post {id, content}) (User)-[:POSTED]->(Post) (User)-[:LIKES {timestamp}]->(Post) </code></pre></div>Key Differences: <ul> <li>Relationships are first-class: Not just foreign keys</li> <li>Traversal is natural: Follow relationships directly</li> <li>Flexible schema: Add new relationships easily</li> </ul> <h3 id="core-principles" class="position-relative d-flex align-items-center group"> Core Principles <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="core-principles" aria-haspopup="dialog" aria-label="Share link: Core Principles"> Share link </button> </h3> <h4 id="1-nodes-for-entities" class="position-relative d-flex align-items-center group"> 1. Nodes for Entities <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-nodes-for-entities" aria-haspopup="dialog" aria-label="Share link: 1. Nodes for Entities"> Share link </button> </h4>Rule: Use nodes for entities you’ll query independently. Good: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:Person {name, age, email}) (:Company {name, industry}) (:Product {name, price}) </code></pre></div>Bad: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Don't use nodes for simple values (:Email {address}) // Just use property (:Age {value}) // Just use property </code></pre></div> <h4 id="2-relationships-for-connections" class="position-relative d-flex align-items-center group"> 2. Relationships for Connections <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-relationships-for-connections" aria-haspopup="dialog" aria-label="Share link: 2. Relationships for Connections"> Share link </button> </h4>Rule: Use relationships to connect entities with meaningful semantics. Good: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:Person)-[:WORKS_AT {since, role}]->(:Company) (:Person)-[:KNOWS {since, context}]->(:Person) (:Person)-[:PURCHASED {date, price}]->(:Product) </code></pre></div>Bad: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Don't use properties for relationships (:Person {company_id}) // Use relationship instead // Don't use generic relationships (:Person)-[:RELATED_TO]->(:Company) // Be specific </code></pre></div> <h4 id="3-properties-for-attributes" class="position-relative d-flex align-items-center group"> 3. Properties for Attributes <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-properties-for-attributes" aria-haspopup="dialog" aria-label="Share link: 3. Properties for Attributes"> Share link </button> </h4>Rule: Use properties for intrinsic attributes of entities. Good: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:Person { name: "Alice", age: 30, email: "[email protected]", created_at: timestamp() }) </code></pre></div>Bad: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Don't create nodes for attributes (:Person)-[:HAS_NAME]->(:Name {value: "Alice"}) // Don't duplicate data unnecessarily (:Person { name: "Alice", uppercase_name: "ALICE", // Compute on demand name_length: 5 // Compute on demand }) </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="pattern-1-hierarchies" class="position-relative d-flex align-items-center group"> Pattern 1: Hierarchies <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-1-hierarchies" aria-haspopup="dialog" aria-label="Share link: Pattern 1: Hierarchies"> Share link </button> </h4>Use Case: Organizational structures, categories, taxonomies Implementation: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Tree structure (:Category {name: "Electronics"}) -[:PARENT]->(:Category {name: "Computers"}) -[:PARENT]->(:Category {name: "Laptops"}) -[:PARENT]->(:Category {name: "Desktops"}) // Query: Find all descendants MATCH (root:Category {name: "Electronics"})-[:PARENT*]->(child) RETURN child.name // Query: Find path to root MATCH path = (leaf:Category {name: "Laptops"})-[:PARENT*]->(root) WHERE NOT (root)-[:PARENT]->() RETURN path </code></pre></div>Best Practices: <ul> <li>Consider max depth when querying (<code>[:PARENT*1..5]</code>)</li> <li>Add level property for quick filtering</li> <li>Cache common paths if frequently accessed</li> </ul> <h4 id="pattern-2-timelineactivity" class="position-relative d-flex align-items-center group"> Pattern 2: Timeline/Activity <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-2-timelineactivity" aria-haspopup="dialog" aria-label="Share link: Pattern 2: Timeline/Activity"> Share link </button> </h4>Use Case: Events, posts, messages, logs Implementation: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Timeline with linked list (:Post {content, created_at})-[:NEXT]->(:Post) // Or time-based relationships (:User)-[:POSTED {timestamp}]->(:Post) // Query: Recent activity MATCH (u:User)-[p:POSTED]->(post:Post) WHERE p.timestamp > timestamp() - duration('P7D') RETURN post ORDER BY p.timestamp DESC LIMIT 20 </code></pre></div>Best Practices: <ul> <li>Index timestamp properties</li> <li>Consider time-bucketing for very active users</li> <li>Use LIMIT to control result size</li> </ul> <h4 id="pattern-3-recommendations" class="position-relative d-flex align-items-center group"> Pattern 3: Recommendations <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-3-recommendations" aria-haspopup="dialog" aria-label="Share link: Pattern 3: Recommendations"> Share link </button> </h4>Use Case: Friend suggestions, product recommendations Implementation: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Collaborative filtering MATCH (me:User)-[:PURCHASED]->(p:Product)<-[:PURCHASED]-(other) MATCH (other)-[:PURCHASED]->(recommendation) WHERE NOT (me)-[:PURCHASED]->(recommendation) RETURN recommendation, count(other) AS score ORDER BY score DESC LIMIT 10 // Content-based MATCH (me:User)-[:LIKES]->(item) WITH me, collect(item.category) AS my_categories MATCH (recommendation) WHERE recommendation.category IN my_categories AND NOT (me)-[:LIKES]->(recommendation) RETURN recommendation </code></pre></div>Best Practices: <ul> <li>Limit traversal depth</li> <li>Use aggregations for scoring</li> <li>Consider pre-computing for popular items</li> </ul> <h4 id="pattern-4-access-control" class="position-relative d-flex align-items-center group"> Pattern 4: Access Control <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-4-access-control" aria-haspopup="dialog" aria-label="Share link: Pattern 4: Access Control"> Share link </button> </h4>Use Case: Permissions, privacy, authorization Implementation: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Role-based access (:User)-[:HAS_ROLE]->(:Role {name: "admin"}) (:Role)-[:CAN_ACCESS]->(:Resource) // Permission check MATCH (user:User {id: $user_id})-[:HAS_ROLE]->(:Role) -[:CAN_ACCESS]->(resource:Resource {id: $resource_id}) RETURN count(resource) > 0 AS has_access // Ownership (:User)-[:OWNS]->(:Document) // Sharing (:User)-[:CAN_VIEW]->(:Document) (:User)-[:CAN_EDIT]->(:Document) </code></pre></div>Best Practices: <ul> <li>Cache permission checks</li> <li>Use groups/roles instead of individual permissions</li> <li>Consider separate authorization service for complex cases</li> </ul> <h4 id="pattern-5-versioning" class="position-relative d-flex align-items-center group"> Pattern 5: Versioning <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-5-versioning" aria-haspopup="dialog" aria-label="Share link: Pattern 5: Versioning"> Share link </button> </h4>Use Case: Document history, audit trails Implementation: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Version chain (:Document {current_version: 3}) -[:HAS_VERSION]->(:Version {number: 3, content, timestamp}) -[:PREVIOUS]->(:Version {number: 2}) -[:PREVIOUS]->(:Version {number: 1}) // Query: Get history MATCH (doc:Document {id: $id})-[:HAS_VERSION]->(v:Version) MATCH path = (v)-[:PREVIOUS*0..]->(older) RETURN older ORDER BY older.number DESC // Query: Diff versions MATCH (doc:Document {id: $id})-[:HAS_VERSION]->(current) MATCH (current)-[:PREVIOUS*3]->(old) RETURN current.content, old.content </code></pre></div>Best Practices: <ul> <li>Limit history depth or archive old versions</li> <li>Consider external storage for large content</li> <li>Add version metadata (author, timestamp, message)</li> </ul> <h3 id="schema-design-process" class="position-relative d-flex align-items-center group"> Schema Design Process <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="schema-design-process" aria-haspopup="dialog" aria-label="Share link: Schema Design Process"> Share link </button> </h3> <h4 id="step-1-identify-entities" class="position-relative d-flex align-items-center group"> Step 1: Identify Entities <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="step-1-identify-entities" aria-haspopup="dialog" aria-label="Share link: Step 1: Identify Entities"> Share link </button> </h4>List the main entities in your domain: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">E-commerce example: - Users (customers, sellers) - Products - Categories - Orders - Reviews - Addresses </code></pre></div> <h4 id="step-2-model-relationships" class="position-relative d-flex align-items-center group"> Step 2: Model 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="step-2-model-relationships" aria-haspopup="dialog" aria-label="Share link: Step 2: Model Relationships"> Share link </button> </h4>Determine how entities connect: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:User)-[:SELLS]->(:Product) (:User)-[:PURCHASED]->(:Product) (:User)-[:REVIEWED]->(:Product) (:Product)-[:IN_CATEGORY]->(:Category) (:Order)-[:CONTAINS]->(:Product) (:User)-[:PLACED]->(:Order) (:User)-[:HAS_ADDRESS]->(:Address) </code></pre></div> <h4 id="step-3-add-properties" class="position-relative d-flex align-items-center group"> Step 3: Add 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="step-3-add-properties" aria-haspopup="dialog" aria-label="Share link: Step 3: Add Properties"> Share link </button> </h4>Determine what data belongs on each entity: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:User { id: INTEGER, email: STRING, name: STRING, created_at: TIMESTAMP }) (:Product { id: INTEGER, name: STRING, price: FLOAT, description: STRING, stock: INTEGER }) (:Order { id: INTEGER, total: FLOAT, status: STRING, created_at: TIMESTAMP }) </code></pre></div> <h4 id="step-4-add-relationship-properties" class="position-relative d-flex align-items-center group"> Step 4: Add Relationship 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="step-4-add-relationship-properties" aria-haspopup="dialog" aria-label="Share link: Step 4: Add Relationship Properties"> Share link </button> </h4>Capture context about connections: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:User)-[:REVIEWED { rating: INTEGER, comment: STRING, timestamp: TIMESTAMP }]->(:Product) (:User)-[:PURCHASED { quantity: INTEGER, price: FLOAT, timestamp: TIMESTAMP }]->(:Product) </code></pre></div> <h4 id="step-5-plan-for-queries" class="position-relative d-flex align-items-center group"> Step 5: Plan for 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="step-5-plan-for-queries" aria-haspopup="dialog" aria-label="Share link: Step 5: Plan for Queries"> Share link </button> </h4>Design schema to support your queries efficiently: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Query: Products in category // Ensure relationship direction supports this MATCH (cat:Category)<-[:IN_CATEGORY]-(product:Product) RETURN product // Query: User's purchase history // Add timestamp for ordering MATCH (user:User)-[p:PURCHASED]->(product:Product) RETURN product ORDER BY p.timestamp DESC </code></pre></div> <h3 id="advanced-patterns" class="position-relative d-flex align-items-center group"> Advanced 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-patterns" aria-haspopup="dialog" aria-label="Share link: Advanced Patterns"> Share link </button> </h3> <h4 id="hypernodes" class="position-relative d-flex align-items-center group"> Hypernodes <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="hypernodes" aria-haspopup="dialog" aria-label="Share link: Hypernodes"> Share link </button> </h4>Problem: Some nodes have millions of relationships (celebrity accounts, popular products) Solution: Introduce intermediate nodes Bad: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Popular product with 10M likes (:Product {id: 1})<-[:LIKES]-(:User) // x10,000,000 </code></pre></div>Good: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Bucket by time (:Product)-[:LIKES_2024_01]->(:LikeBucket) (:LikeBucket)<-[:LIKES]->(:User) // x1,000 // Query with bucket MATCH (product:Product {id: 1})-[:LIKES_2024*]->(bucket) MATCH (bucket)<-[:LIKES]-(user) RETURN count(user) </code></pre></div> <h4 id="denormalization" class="position-relative d-flex align-items-center group"> Denormalization <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="denormalization" aria-haspopup="dialog" aria-label="Share link: Denormalization"> Share link </button> </h4>When: Read performance critical, data rarely changes Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Normalized (:User)-[:LIVES_IN]->(:City)-[:IN_STATE]->(:State)-[:IN_COUNTRY]->(:Country) // Denormalized for fast queries (:User { city: "San Francisco", state: "California", country: "USA" }) // Trade-off: Faster queries, but updates affect multiple nodes </code></pre></div> <h4 id="materialized-paths" class="position-relative d-flex align-items-center group"> Materialized 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="materialized-paths" aria-haspopup="dialog" aria-label="Share link: Materialized Paths"> Share link </button> </h4>When: Frequent queries on hierarchies Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Store full path (:Category { name: "Laptops", path: ["Electronics", "Computers", "Laptops"], level: 3 }) // Fast queries MATCH (cat:Category) WHERE "Electronics" IN cat.path RETURN cat // Fast level queries MATCH (cat:Category {level: 2}) RETURN cat </code></pre></div> <h4 id="event-sourcing" class="position-relative d-flex align-items-center group"> Event Sourcing <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="event-sourcing" aria-haspopup="dialog" aria-label="Share link: Event Sourcing"> Share link </button> </h4>When: Need complete audit trail Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Events as nodes (:User)-[:TRIGGERED]->(:Event { type: "user.created", timestamp: timestamp(), data: {...} }) (:User)-[:TRIGGERED]->(:Event { type: "user.updated", timestamp: timestamp(), data: {...} }) // Rebuild state from events MATCH (user:User)-[:TRIGGERED]->(event:Event) WHERE event.type STARTS WITH "user." RETURN event ORDER BY event.timestamp </code></pre></div> <h3 id="anti-patterns" class="position-relative d-flex align-items-center group"> Anti-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="anti-patterns" aria-haspopup="dialog" aria-label="Share link: Anti-Patterns"> Share link </button> </h3> <h4 id="1-deep-nesting" class="position-relative d-flex align-items-center group"> 1. Deep Nesting <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-deep-nesting" aria-haspopup="dialog" aria-label="Share link: 1. Deep Nesting"> Share link </button> </h4>Bad: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Too many levels (:Person)-[:KNOWS]->(:Person)-[:KNOWS]->(:Person)-[:KNOWS*10]->(:Person) </code></pre></div>Solution: Limit depth or add shortcuts <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Add direct connections for common paths (:Person)-[:KNOWS_INDIRECTLY {hops: 3}]->(:Person) </code></pre></div> <h4 id="2-property-explosions" class="position-relative d-flex align-items-center group"> 2. Property Explosions <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-property-explosions" aria-haspopup="dialog" aria-label="Share link: 2. Property Explosions"> Share link </button> </h4>Bad: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:User { friend_1_id: 123, friend_2_id: 456, friend_3_id: 789, // ... friend_1000_id: 999 }) </code></pre></div>Solution: Use relationships <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:User)-[:FRIENDS_WITH]->(:User) </code></pre></div> <h4 id="3-generic-relationships" class="position-relative d-flex align-items-center group"> 3. Generic 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="3-generic-relationships" aria-haspopup="dialog" aria-label="Share link: 3. Generic Relationships"> Share link </button> </h4>Bad: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:Person)-[:RELATED_TO]->(:Company) (:Person)-[:RELATED_TO]->(:Product) </code></pre></div>Solution: Specific relationship types <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:Person)-[:WORKS_AT]->(:Company) (:Person)-[:PURCHASED]->(:Product) </code></pre></div> <h4 id="4-nodes-for-properties" class="position-relative d-flex align-items-center group"> 4. Nodes for 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="4-nodes-for-properties" aria-haspopup="dialog" aria-label="Share link: 4. Nodes for Properties"> Share link </button> </h4>Bad: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:Person)-[:HAS_EMAIL]->(:Email {address: "[email protected]"}) (:Person)-[:HAS_PHONE]->(:Phone {number: "555-0123"}) </code></pre></div>Solution: Use properties <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">(:Person { email: "[email protected]", phone: "555-0123" }) </code></pre></div> <h4 id="5-bi-directional-duplication" class="position-relative d-flex align-items-center group"> 5. Bi-directional Duplication <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-bi-directional-duplication" aria-haspopup="dialog" aria-label="Share link: 5. Bi-directional Duplication"> Share link </button> </h4>Bad: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Creating both directions unnecessarily (:Person)-[:KNOWS]->(:Person) (:Person)<-[:KNOWN_BY]-(:Person) </code></pre></div>Solution: Use one direction, query both ways <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Create one direction (:Person)-[:KNOWS]->(:Person) // Query either direction MATCH (p1:Person)-[:KNOWS]-(p2:Person) RETURN p2 </code></pre></div> <h3 id="migration-strategy" class="position-relative d-flex align-items-center group"> Migration Strategy <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="migration-strategy" aria-haspopup="dialog" aria-label="Share link: Migration Strategy"> Share link </button> </h3> <h4 id="from-relational" class="position-relative d-flex align-items-center group"> From Relational <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="from-relational" aria-haspopup="dialog" aria-label="Share link: From Relational"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql">-- SQL Schema CREATE TABLE users ( id SERIAL PRIMARY KEY, name VARCHAR, email VARCHAR ); CREATE TABLE friendships ( user_id INT REFERENCES users(id), friend_id INT REFERENCES users(id), since DATE ); </code></pre></div>To Graph: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">// Import users LOAD CSV WITH HEADERS FROM 'file:///users.csv' AS row CREATE (:User { id: toInteger(row.id), name: row.name, email: row.email }) // Import friendships LOAD CSV WITH HEADERS FROM 'file:///friendships.csv' AS row MATCH (u1:User {id: toInteger(row.user_id)}) MATCH (u2:User {id: toInteger(row.friend_id)}) CREATE (u1)-[:KNOWS {since: date(row.since)}]->(u2) </code></pre></div> <h4 id="incremental-migration" class="position-relative d-flex align-items-center group"> Incremental Migration <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="incremental-migration" aria-haspopup="dialog" aria-label="Share link: Incremental Migration"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Dual-write to both systems during migration async def create_user(data): # Write to PostgreSQL await pg_conn.execute( "INSERT INTO users (name, email) VALUES ($1, $2)", data['name'], data['email'] ) # Write to Geode await geode_client.query( "CREATE (:User {name: $name, email: $email})", params=data ) </code></pre></div> <h3 id="testing-your-schema" class="position-relative d-flex align-items-center group"> Testing Your Schema <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="testing-your-schema" aria-haspopup="dialog" aria-label="Share link: Testing Your Schema"> Share link </button> </h3> <h4 id="unit-tests" class="position-relative d-flex align-items-center group"> Unit Tests <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="unit-tests" aria-haspopup="dialog" aria-label="Share link: Unit Tests"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import pytest @pytest.mark.asyncio async def test_user_creation(): await client.query( "CREATE (:User {id: 1, name: 'Test'})" ) result, _ = await client.query( "MATCH (u:User {id: 1}) RETURN u.name" ) user = result.rows[0] if result.rows else None assert user['u.name'] == 'Test' @pytest.mark.asyncio async def test_friendship(): # Create users await client.query( "CREATE (:User {id: 1, name: 'Alice'})" ) await client.query( "CREATE (:User {id: 2, name: 'Bob'})" ) # Create friendship await client.query(""" MATCH (a:User {id: 1}) MATCH (b:User {id: 2}) CREATE (a)-[:KNOWS]->(b) """) # Verify result, _ = await client.query(""" MATCH (a:User {id: 1})-[:KNOWS]->(b) RETURN b.name """) friend = result.rows[0] if result.rows else None assert friend['b.name'] == 'Bob' </code></pre></div> <h3 id="documentation" class="position-relative d-flex align-items-center group"> Documentation <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="documentation" aria-haspopup="dialog" aria-label="Share link: Documentation"> Share link </button> </h3>Document your schema: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"># Schema Documentation ## Nodes ### User Represents a user account. Properties: - `id` (INTEGER): Unique identifier - `username` (STRING): Unique username - `email` (STRING): Email address - `created_at` (TIMESTAMP): Account creation time Relationships: - `[:KNOWS]->(:User)`: Friend connections - `[:POSTED]->(:Post)`: Created posts - `[:LIKES]->(:Post)`: Liked posts Constraints: - `user_id_unique`: Unique user ID - `user_username_unique`: Unique username Indexes: - `user_username`: B-tree on username - `user_email`: B-tree on email </code></pre></div> <h3 id="conclusion" class="position-relative d-flex align-items-center group"> Conclusion <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="conclusion" aria-haspopup="dialog" aria-label="Share link: Conclusion"> Share link </button> </h3>Good graph modeling: <ul> <li>Makes queries natural and efficient</li> <li>Evolves with requirements</li> <li>Balances normalization and performance</li> <li>Documents design decisions</li> </ul> Start simple, iterate based on usage patterns, and always profile your queries. <h3 id="resources" class="position-relative d-flex align-items-center group"> Resources <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="resources" aria-haspopup="dialog" aria-label="Share link: Resources"> Share link </button> </h3><ul> <li><a href="/docs/gql-reference/" >GQL Reference</a> </li> <li><a href="/docs/performance/" >Performance Guide</a> </li> <li><a href="/docs/guides/migration-guide/" >Migration Guide</a> </li> <li><a href="https://gitlab.com/devnw/codepros/geode/examples" aria-label="Example Schemas – opens in new window" target="_blank" rel="noopener noreferrer" >Example Schemas ↗ </a> </li> </ul> <hr> Questions? Discuss schema design in our <a href="https://forum.geodedb.com" aria-label="forum – opens in new window" target="_blank" rel="noopener noreferrer" >forum ↗ </a> .

Related Guides

Graph Schema Design Guide

Data Model and Types