Temporal Data and Time-Series

<h2 id="temporal-data-and-time-series-in-geode" class="position-relative d-flex align-items-center group"> Temporal Data and Time-Series in Geode <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="temporal-data-and-time-series-in-geode" aria-haspopup="dialog" aria-label="Share link: Temporal Data and Time-Series in Geode"> 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>Temporal data management is essential for tracking when events occur, how entities change over time, and analyzing time-based patterns. Geode provides comprehensive support for temporal data types, functions, and query patterns aligned with the ISO/IEC 39075:2024 GQL standard. Whether you are building audit systems, tracking user activity, analyzing time-series data, or implementing bi-temporal data models, Geode offers the primitives and query capabilities to handle temporal requirements effectively. <h3 id="temporal-data-types" class="position-relative d-flex align-items-center group"> Temporal Data 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="temporal-data-types" aria-haspopup="dialog" aria-label="Share link: Temporal Data Types"> Share link </button> </h3>Geode supports the following temporal types: <h4 id="date" class="position-relative d-flex align-items-center group"> DATE <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" aria-haspopup="dialog" aria-label="Share link: DATE"> Share link </button> </h4>Represents a calendar date without time information. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create nodes with DATE properties CREATE (event:Event { id: 'evt_001', name: 'Product Launch', event_date: DATE '2025-03-15' }); -- Date from components CREATE (holiday:Holiday { name: 'Independence Day', date: date(2025, 7, 4) }); -- Current date CREATE (log:AuditLog { action: 'USER_CREATED', log_date: current_date() }); </code></pre></div> <h4 id="time" class="position-relative d-flex align-items-center group"> TIME <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="time" aria-haspopup="dialog" aria-label="Share link: TIME"> Share link </button> </h4>Represents time of day without date information. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Store time values CREATE (schedule:Schedule { store_id: 'store_001', opens_at: TIME '09:00:00', closes_at: TIME '21:00:00' }); -- Time with timezone CREATE (meeting:Meeting { title: 'Team Standup', scheduled_time: TIME '10:30:00-05:00' -- EST }); -- Current time CREATE (entry:TimeEntry { clock_in: current_time() }); </code></pre></div> <h4 id="datetime--timestamp" class="position-relative d-flex align-items-center group"> DATETIME / TIMESTAMP <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="datetime--timestamp" aria-haspopup="dialog" aria-label="Share link: DATETIME / TIMESTAMP"> Share link </button> </h4>Represents a specific point in time with date, time, and optional timezone. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Full datetime with timezone CREATE (order:Order { id: 'order_001', placed_at: datetime('2025-01-15T14:30:00Z'), status: 'pending' }); -- Datetime from components CREATE (appointment:Appointment { datetime: datetime(2025, 6, 15, 10, 30, 0) }); -- Current timestamp CREATE (session:Session { user_id: 'user_001', started_at: datetime(), last_activity: datetime() }); -- Parse from ISO 8601 string MATCH (o:Order {id: 'order_001'}) SET o.shipped_at = datetime('2025-01-16T09:00:00-08:00'); </code></pre></div> <h4 id="duration" class="position-relative d-flex align-items-center group"> DURATION <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="duration" aria-haspopup="dialog" aria-label="Share link: DURATION"> Share link </button> </h4>Represents a time span or interval. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Duration literals CREATE (subscription:Subscription { plan: 'annual', duration: DURATION 'P1Y', -- 1 year created_at: datetime() }); -- Duration components -- P = period, T = time separator -- Y=years, M=months, D=days, H=hours, M=minutes, S=seconds CREATE (trial:Trial { name: 'Free Trial', length: DURATION 'P14D' -- 14 days }); CREATE (timeout:Config { name: 'session_timeout', value: DURATION 'PT30M' -- 30 minutes }); -- Duration arithmetic MATCH (s:Subscription {plan: 'annual'}) SET s.expires_at = s.created_at + s.duration; </code></pre></div> <h3 id="temporal-functions" class="position-relative d-flex align-items-center group"> Temporal 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="temporal-functions" aria-haspopup="dialog" aria-label="Share link: Temporal Functions"> Share link </button> </h3> <h4 id="datetime-component-extraction" class="position-relative d-flex align-items-center group"> Date/Time Component Extraction <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="datetime-component-extraction" aria-haspopup="dialog" aria-label="Share link: Date/Time Component Extraction"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Extract components from datetime MATCH (o:Order) RETURN o.id, year(o.placed_at) AS order_year, month(o.placed_at) AS order_month, day(o.placed_at) AS order_day, hour(o.placed_at) AS order_hour, minute(o.placed_at) AS order_minute, second(o.placed_at) AS order_second; -- Day of week (1=Monday, 7=Sunday) MATCH (e:Event) RETURN e.name, dayOfWeek(e.event_date) AS weekday, dayOfYear(e.event_date) AS day_of_year; -- Week and quarter MATCH (s:Sale) RETURN week(s.sale_date) AS week_number, quarter(s.sale_date) AS quarter; </code></pre></div> <h4 id="datetime-arithmetic" class="position-relative d-flex align-items-center group"> Date/Time Arithmetic <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="datetime-arithmetic" aria-haspopup="dialog" aria-label="Share link: Date/Time Arithmetic"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Add duration to datetime MATCH (s:Subscription) SET s.renewal_date = s.start_date + DURATION 'P1Y'; -- Subtract duration MATCH (u:User) WHERE u.last_login < datetime() - DURATION 'P30D' SET u.status = 'inactive'; -- Difference between dates (returns duration) MATCH (o:Order) WHERE o.delivered_at IS NOT NULL RETURN o.id, o.delivered_at - o.placed_at AS delivery_time; -- Add specific time units MATCH (t:Task) SET t.due_date = t.created_at + DURATION 'P7D'; -- 7 days later </code></pre></div> <h4 id="truncation-and-rounding" class="position-relative d-flex align-items-center group"> Truncation and Rounding <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="truncation-and-rounding" aria-haspopup="dialog" aria-label="Share link: Truncation and Rounding"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Truncate to start of period MATCH (e:Event) RETURN e.name, date_trunc('month', e.event_date) AS month_start, date_trunc('year', e.event_date) AS year_start, date_trunc('week', e.event_date) AS week_start; -- Truncate datetime MATCH (l:LoginEvent) RETURN date_trunc('hour', l.timestamp) AS hour, COUNT(*) AS login_count ORDER BY hour; -- Round to nearest interval MATCH (m:Measurement) RETURN date_trunc('minute', m.recorded_at) AS minute, AVG(m.value) AS avg_value ORDER BY minute; </code></pre></div> <h4 id="formatting-and-parsing" class="position-relative d-flex align-items-center group"> Formatting and Parsing <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="formatting-and-parsing" aria-haspopup="dialog" aria-label="Share link: Formatting and Parsing"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Format datetime as string MATCH (o:Order) RETURN o.id, format_datetime(o.placed_at, 'YYYY-MM-DD') AS date_str, format_datetime(o.placed_at, 'YYYY-MM-DD HH:mm:ss') AS full_str; -- Parse string to datetime MATCH (import:ImportRecord) SET import.parsed_date = parse_datetime(import.date_string, 'MM/DD/YYYY'); </code></pre></div> <h3 id="time-based-query-patterns" class="position-relative d-flex align-items-center group"> Time-Based Query 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="time-based-query-patterns" aria-haspopup="dialog" aria-label="Share link: Time-Based Query Patterns"> Share link </button> </h3> <h4 id="range-queries" class="position-relative d-flex align-items-center group"> Range 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="range-queries" aria-haspopup="dialog" aria-label="Share link: Range Queries"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Events within date range MATCH (e:Event) WHERE e.event_date >= DATE '2025-01-01' AND e.event_date < DATE '2025-04-01' RETURN e.name, e.event_date ORDER BY e.event_date; -- Orders in last 30 days MATCH (o:Order) WHERE o.placed_at >= datetime() - DURATION 'P30D' RETURN o.id, o.total, o.placed_at; -- Activity within time window MATCH (s:Session) WHERE s.started_at >= datetime() - DURATION 'PT1H' RETURN COUNT(s) AS active_sessions; </code></pre></div> <h4 id="time-based-aggregations" class="position-relative d-flex align-items-center group"> Time-Based Aggregations <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="time-based-aggregations" aria-haspopup="dialog" aria-label="Share link: Time-Based Aggregations"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Daily order totals MATCH (o:Order) WHERE o.placed_at >= datetime() - DURATION 'P7D' RETURN date(o.placed_at) AS order_date, COUNT(o) AS order_count, SUM(o.total) AS daily_revenue ORDER BY order_date; -- Hourly traffic analysis MATCH (v:PageView) WHERE v.timestamp >= datetime() - DURATION 'P1D' RETURN date_trunc('hour', v.timestamp) AS hour, COUNT(v) AS views ORDER BY hour; -- Monthly user signups MATCH (u:User) WHERE u.created_at >= datetime() - DURATION 'P1Y' RETURN year(u.created_at) AS year, month(u.created_at) AS month, COUNT(u) AS new_users ORDER BY year, month; -- Weekly active users MATCH (u:User)-[:PERFORMED]->(a:Activity) WHERE a.timestamp >= datetime() - DURATION 'P7D' RETURN COUNT(DISTINCT u) AS weekly_active_users; </code></pre></div> <h4 id="period-comparisons" class="position-relative d-flex align-items-center group"> Period Comparisons <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="period-comparisons" aria-haspopup="dialog" aria-label="Share link: Period Comparisons"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Compare current period to previous WITH datetime() AS now, datetime() - DURATION 'P7D' AS week_ago, datetime() - DURATION 'P14D' AS two_weeks_ago MATCH (o:Order) WHERE o.placed_at >= two_weeks_ago WITH now, week_ago, two_weeks_ago, SUM(CASE WHEN o.placed_at >= week_ago THEN o.total ELSE 0 END) AS current_week, SUM(CASE WHEN o.placed_at < week_ago THEN o.total ELSE 0 END) AS previous_week RETURN current_week, previous_week, (current_week - previous_week) / previous_week * 100 AS percent_change; -- Year-over-year comparison MATCH (s:Sale) WHERE year(s.sale_date) IN [2024, 2025] AND month(s.sale_date) = 1 RETURN year(s.sale_date) AS year, SUM(s.amount) AS january_sales ORDER BY year; </code></pre></div> <h3 id="temporal-data-modeling-patterns" class="position-relative d-flex align-items-center group"> Temporal Data Modeling 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="temporal-data-modeling-patterns" aria-haspopup="dialog" aria-label="Share link: Temporal Data Modeling Patterns"> Share link </button> </h3> <h4 id="event-timestamps" class="position-relative d-flex align-items-center group"> Event Timestamps <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-timestamps" aria-haspopup="dialog" aria-label="Share link: Event Timestamps"> Share link </button> </h4>Track when events occur with immutable timestamps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Audit trail pattern CREATE (al:AuditLog { id: randomUUID(), entity_type: 'User', entity_id: $user_id, action: 'UPDATE', changes: $change_json, performed_by: $actor_id, performed_at: datetime() }); -- Query audit history MATCH (al:AuditLog {entity_type: 'User', entity_id: $user_id}) RETURN al.action, al.changes, al.performed_by, al.performed_at ORDER BY al.performed_at DESC LIMIT 50; </code></pre></div> <h4 id="temporal-relationships" class="position-relative d-flex align-items-center group"> Temporal 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="temporal-relationships" aria-haspopup="dialog" aria-label="Share link: Temporal Relationships"> Share link </button> </h4>Add time bounds to relationships: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Employment with date range CREATE (person)-[:EMPLOYED_AT { role: 'Software Engineer', start_date: DATE '2022-03-15', end_date: null -- Current position }]->(company); -- Query current employment MATCH (p:Person)-[e:EMPLOYED_AT]->(c:Company) WHERE e.end_date IS NULL OR e.end_date > current_date() RETURN p.name, c.name, e.role, e.start_date; -- Query employment at specific date MATCH (p:Person)-[e:EMPLOYED_AT]->(c:Company) WHERE e.start_date <= $target_date AND (e.end_date IS NULL OR e.end_date >= $target_date) RETURN p.name, c.name, e.role; -- Employment history MATCH (p:Person {id: $person_id})-[e:EMPLOYED_AT]->(c:Company) RETURN c.name, e.role, e.start_date, e.end_date ORDER BY e.start_date DESC; </code></pre></div> <h4 id="bi-temporal-modeling" class="position-relative d-flex align-items-center group"> Bi-Temporal Modeling <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="bi-temporal-modeling" aria-haspopup="dialog" aria-label="Share link: Bi-Temporal Modeling"> Share link </button> </h4>Track both valid time (when true in reality) and transaction time (when recorded): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Bi-temporal price record CREATE (price:PriceRecord { product_id: 'prod_001', amount: 29.99, -- Valid time: when this price is/was effective valid_from: DATE '2025-01-01', valid_to: DATE '2025-06-30', -- Transaction time: when recorded in system recorded_at: datetime(), superseded_at: null -- Current record }); -- Query current price (valid now, current record) MATCH (pr:PriceRecord {product_id: $product_id}) WHERE pr.valid_from <= current_date() AND (pr.valid_to IS NULL OR pr.valid_to > current_date()) AND pr.superseded_at IS NULL RETURN pr.amount AS current_price; -- Query price at past point in time MATCH (pr:PriceRecord {product_id: $product_id}) WHERE pr.valid_from <= $query_date AND (pr.valid_to IS NULL OR pr.valid_to > $query_date) AND pr.recorded_at <= $as_of_time AND (pr.superseded_at IS NULL OR pr.superseded_at > $as_of_time) RETURN pr.amount AS price_at_time; -- Update price (create new record, supersede old) MATCH (old:PriceRecord {product_id: $product_id}) WHERE old.superseded_at IS NULL SET old.superseded_at = datetime(); CREATE (new:PriceRecord { product_id: $product_id, amount: $new_price, valid_from: $effective_date, valid_to: null, recorded_at: datetime(), superseded_at: null }); </code></pre></div> <h4 id="time-series-data" class="position-relative d-flex align-items-center group"> Time-Series Data <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="time-series-data" aria-haspopup="dialog" aria-label="Share link: Time-Series Data"> Share link </button> </h4>Model time-series measurements: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Sensor readings CREATE (reading:SensorReading { sensor_id: 'sensor_001', timestamp: datetime(), temperature: 23.5, humidity: 45.2, pressure: 1013.25 }); -- Link readings to sensor MATCH (s:Sensor {id: 'sensor_001'}) CREATE (r:SensorReading { timestamp: datetime(), temperature: $temp, humidity: $humidity }) CREATE (s)-[:RECORDED]->(r); -- Query time-series data MATCH (s:Sensor {id: $sensor_id})-[:RECORDED]->(r:SensorReading) WHERE r.timestamp >= datetime() - DURATION 'PT24H' RETURN r.timestamp, r.temperature, r.humidity ORDER BY r.timestamp; -- Downsampled aggregation (hourly averages) MATCH (s:Sensor {id: $sensor_id})-[:RECORDED]->(r:SensorReading) WHERE r.timestamp >= datetime() - DURATION 'P7D' RETURN date_trunc('hour', r.timestamp) AS hour, AVG(r.temperature) AS avg_temp, MIN(r.temperature) AS min_temp, MAX(r.temperature) AS max_temp, COUNT(r) AS sample_count ORDER BY hour; </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>Store events with timestamps for complete history: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create domain events CREATE (evt:OrderEvent { order_id: 'order_001', event_type: 'ORDER_PLACED', timestamp: datetime(), data: $event_data, sequence: 1 }); -- Append new event MATCH (prev:OrderEvent {order_id: $order_id}) WHERE NOT EXISTS { (prev)-[:FOLLOWED_BY]->() } CREATE (new:OrderEvent { order_id: $order_id, event_type: $event_type, timestamp: datetime(), data: $data, sequence: prev.sequence + 1 }) CREATE (prev)-[:FOLLOWED_BY]->(new); -- Replay events in order MATCH (e:OrderEvent {order_id: $order_id}) RETURN e.event_type, e.timestamp, e.data ORDER BY e.sequence; -- Get latest event MATCH (e:OrderEvent {order_id: $order_id}) WHERE NOT EXISTS { (e)-[:FOLLOWED_BY]->() } RETURN e.event_type AS current_status, e.timestamp; </code></pre></div> <h3 id="timezone-handling" class="position-relative d-flex align-items-center group"> Timezone Handling <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="timezone-handling" aria-haspopup="dialog" aria-label="Share link: Timezone Handling"> Share link </button> </h3> <h4 id="working-with-timezones" class="position-relative d-flex align-items-center group"> Working with Timezones <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="working-with-timezones" aria-haspopup="dialog" aria-label="Share link: Working with Timezones"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Store with explicit timezone CREATE (meeting:Meeting { title: 'Global Standup', scheduled_at: datetime('2025-03-15T10:00:00-05:00') -- EST }); -- Convert timezone MATCH (m:Meeting {title: 'Global Standup'}) RETURN m.title, m.scheduled_at AS est_time, m.scheduled_at AT TIME ZONE 'UTC' AS utc_time, m.scheduled_at AT TIME ZONE 'America/Los_Angeles' AS pst_time; -- Store as UTC, display in local CREATE (event:Event { name: 'Product Launch', utc_time: datetime('2025-06-01T18:00:00Z') }); MATCH (e:Event {name: 'Product Launch'}) RETURN e.name, e.utc_time AT TIME ZONE $user_timezone AS local_time; </code></pre></div> <h4 id="best-practices-for-timezones" class="position-relative d-flex align-items-center group"> Best Practices for Timezones <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-for-timezones" aria-haspopup="dialog" aria-label="Share link: Best Practices for Timezones"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- RECOMMENDED: Store all times in UTC CREATE (order:Order { id: $id, placed_at: datetime() -- Server time should be UTC }); -- Convert to user's timezone for display MATCH (o:Order {id: $id}) RETURN o.placed_at AT TIME ZONE $display_timezone AS display_time; -- For date-specific queries, be aware of timezone boundaries MATCH (o:Order) WHERE date(o.placed_at AT TIME ZONE $user_tz) = $target_date RETURN o.id; </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="indexing-temporal-properties" class="position-relative d-flex align-items-center group"> Indexing Temporal 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="indexing-temporal-properties" aria-haspopup="dialog" aria-label="Share link: Indexing Temporal Properties"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Index frequently queried temporal columns CREATE INDEX idx_order_placed ON Order(placed_at); CREATE INDEX idx_event_date ON Event(event_date); CREATE INDEX idx_session_started ON Session(started_at); -- Composite index for entity + time queries CREATE INDEX idx_user_activity ON Activity(user_id, timestamp); -- Use indexes in range queries MATCH (o:Order) WHERE o.placed_at >= $start_date AND o.placed_at < $end_date RETURN o.id, o.total; -- Uses idx_order_placed </code></pre></div> <h4 id="partitioning-strategies" class="position-relative d-flex align-items-center group"> Partitioning Strategies <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="partitioning-strategies" aria-haspopup="dialog" aria-label="Share link: Partitioning Strategies"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Add partition key to temporal data CREATE (log:AuditLog { entity_id: $id, action: $action, timestamp: datetime(), partition_key: format_datetime(datetime(), 'YYYY-MM') -- Monthly }); -- Query within partition MATCH (log:AuditLog {partition_key: '2025-01'}) WHERE log.entity_id = $entity_id RETURN log.action, log.timestamp; </code></pre></div> <h4 id="retention-and-archival" class="position-relative d-flex align-items-center group"> Retention and Archival <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="retention-and-archival" aria-haspopup="dialog" aria-label="Share link: Retention and Archival"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Archive old data MATCH (log:AuditLog) WHERE log.timestamp < datetime() - DURATION 'P1Y' SET log:ArchivedAuditLog REMOVE log:AuditLog; -- Delete truly old data MATCH (log:ArchivedAuditLog) WHERE log.timestamp < datetime() - DURATION 'P7Y' DELETE log; -- Aggregate before archiving MATCH (reading:SensorReading) WHERE reading.timestamp < datetime() - DURATION 'P30D' WITH date(reading.timestamp) AS day, reading.sensor_id AS sensor, AVG(reading.value) AS avg_value, MIN(reading.value) AS min_value, MAX(reading.value) AS max_value, COUNT(reading) AS sample_count CREATE (summary:DailySensorSummary { sensor_id: sensor, date: day, avg_value: avg_value, min_value: min_value, max_value: max_value, sample_count: sample_count }) WITH reading DELETE reading; </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-client" class="position-relative d-flex align-items-center group"> Python Client <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-client" aria-haspopup="dialog" aria-label="Share link: Python Client"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import Client from datetime import datetime, timedelta, date async def temporal_operations(): client = Client(host="localhost", port=3141) async with client.connection() as conn: # Create event with timestamp await conn.execute(""" CREATE (e:Event { id: $id, name: $name, event_date: $event_date, created_at: datetime() }) """, { 'id': 'evt_001', 'name': 'Conference', 'event_date': date(2025, 6, 15) }) # Query events in date range start_date = date(2025, 6, 1) end_date = date(2025, 6, 30) result, _ = await conn.query(""" MATCH (e:Event) WHERE e.event_date >= $start AND e.event_date <= $end RETURN e.name, e.event_date ORDER BY e.event_date """, {'start': start_date, 'end': end_date}) for row in result.rows: print(f"Event: {row['e.name']} on {row['e.event_date']}") # Time-based aggregation result, _ = await conn.query(""" MATCH (o:Order) WHERE o.placed_at >= datetime() - DURATION 'P30D' RETURN date(o.placed_at) AS order_date, SUM(o.total) AS daily_total ORDER BY order_date """) for row in result.rows: print(f"{row['order_date']}: ${row['daily_total']:.2f}") </code></pre></div> <h4 id="go-client" class="position-relative d-flex align-items-center group"> Go Client <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-client" aria-haspopup="dialog" aria-label="Share link: Go Client"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">package main import ( "context" "database/sql" "log" "time" _ "geodedb.com/geode" ) func temporalQueries(ctx context.Context, db *sql.DB) error { // Insert with timestamp _, err := db.ExecContext(ctx, ` CREATE (log:AuditLog { action: $1, entity_id: $2, timestamp: datetime($3), user_id: $4 }) `, "UPDATE", "user_123", time.Now().UTC().Format(time.RFC3339), "admin") if err != nil { return err } // Query recent activity cutoff := time.Now().Add(-24 * time.Hour) rows, err := db.QueryContext(ctx, ` MATCH (log:AuditLog) WHERE log.timestamp >= datetime($1) RETURN log.action, log.entity_id, log.timestamp ORDER BY log.timestamp DESC `, cutoff.Format(time.RFC3339)) if err != nil { return err } defer rows.Close() for rows.Next() { var action, entityID string var timestamp time.Time rows.Scan(&action, &entityID, &timestamp) log.Printf("%s: %s at %v", action, entityID, timestamp) } return nil } </code></pre></div> <h4 id="rust-client" class="position-relative d-flex align-items-center group"> Rust Client <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-client" aria-haspopup="dialog" aria-label="Share link: Rust Client"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-rust" data-lang="rust">use geode_client::{Client, Value}; use chrono::{Utc, Duration, NaiveDate}; async fn temporal_analytics(client: &Client) -> Result<(), Box<dyn std::error::Error>> { // Create time-series data let now = Utc::now(); client.execute( r#" CREATE (r:Reading { sensor_id: $sensor_id, timestamp: datetime($timestamp), value: $value }) "#, &[ ("sensor_id", Value::String("temp_001".into())), ("timestamp", Value::String(now.to_rfc3339())), ("value", Value::Float(23.5)), ], ).await?; // Query hourly averages for past week let week_ago = (now - Duration::days(7)).to_rfc3339(); let results = client.query( r#" MATCH (r:Reading {sensor_id: $sensor_id}) WHERE r.timestamp >= datetime($since) RETURN date_trunc('hour', r.timestamp) AS hour, AVG(r.value) AS avg_value, COUNT(r) AS samples ORDER BY hour "#, &[ ("sensor_id", Value::String("temp_001".into())), ("since", Value::String(week_ago)), ], ).await?; for row in results.rows() { println!( "Hour: {:?}, Avg: {:.2}, Samples: {}", row.get::<String>("hour")?, row.get::<f64>("avg_value")?, row.get::<i64>("samples")? ); } Ok(()) } </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="timestamp-conventions" class="position-relative d-flex align-items-center group"> Timestamp Conventions <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="timestamp-conventions" aria-haspopup="dialog" aria-label="Share link: Timestamp Conventions"> Share link </button> </h4><ul> <li>Store all timestamps in UTC</li> <li>Use datetime() for current timestamp (returns UTC)</li> <li>Convert to local timezone only for display</li> <li>Include timezone in datetime literals when not UTC</li> </ul> <h4 id="data-modeling" class="position-relative d-flex align-items-center group"> Data Modeling <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="data-modeling" aria-haspopup="dialog" aria-label="Share link: Data Modeling"> Share link </button> </h4><ul> <li>Add created_at/updated_at to all entities</li> <li>Use immutable timestamps for audit events</li> <li>Consider bi-temporal for regulated domains</li> <li>Partition time-series data by time period</li> </ul> <h4 id="query-optimization" class="position-relative d-flex align-items-center group"> Query Optimization <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="query-optimization" aria-haspopup="dialog" aria-label="Share link: Query Optimization"> Share link </button> </h4><ul> <li>Index temporal properties used in WHERE clauses</li> <li>Use date_trunc for aggregations to leverage indexes</li> <li>Limit time ranges in queries</li> <li>Consider pre-aggregating historical data</li> </ul> <h4 id="retention" class="position-relative d-flex align-items-center group"> Retention <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="retention" aria-haspopup="dialog" aria-label="Share link: Retention"> Share link </button> </h4><ul> <li>Define retention policies early</li> <li>Archive before delete for compliance</li> <li>Aggregate old data to summaries</li> <li>Monitor storage growth</li> </ul> <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/functions/" >Functions</a> - Built-in GQL functions</li> <li><a href="/tags/types/" >Types</a> - Geode data types</li> <li><a href="/tags/query-optimization/" >Query Optimization</a> - Query performance</li> <li><a href="/tags/aggregation/" >Aggregations</a> - Aggregation functions</li> <li><a href="/tags/data-modeling/" >Data Modeling</a> - Schema design patterns</li> <li><a href="/tags/analytics/" >Analytics</a> - Analytical queries</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>ISO/IEC 39075:2024 - Temporal Data Types</li> <li>Time-Series Data Best Practices</li> <li>Bi-Temporal Data Modeling Guide</li> <li>Geode Performance Tuning for Temporal Queries</li> <li>Data Retention and Archival Strategies</li> </ul> Browse tagged content for complete temporal data documentation and examples.

Popular

Related Articles