Nullable Fields & NULL Handling

<h2 id="nullable-fields--null-handling" class="position-relative d-flex align-items-center group"> Nullable Fields &amp; NULL 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="nullable-fields--null-handling" aria-haspopup="dialog" aria-label="Share link: Nullable Fields &amp; NULL Handling"> 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>Nullable fields in Geode allow properties to contain NULL values, representing missing, unknown, or inapplicable data. Understanding NULL semantics is critical for correct graph queries, data modeling, and application logic. Geode implements three-valued logic according to the GQL standard, where expressions can evaluate to TRUE, FALSE, or NULL. <h3 id="understanding-null-in-graph-databases" class="position-relative d-flex align-items-center group"> Understanding NULL in Graph Databases <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="understanding-null-in-graph-databases" aria-haspopup="dialog" aria-label="Share link: Understanding NULL in Graph Databases"> Share link </button> </h3>NULL is not a value—it represents the absence of a value. In graph databases, NULL has specific semantic meanings: <ul> <li>Missing Information: Data not yet collected (e.g., middle name)</li> <li>Inapplicable Data: Property doesn’t apply (e.g., retirement date for active employees)</li> <li>Unknown Values: Information exists but is unknown (e.g., exact birth date)</li> <li>Optional Relationships: Edge properties that may not exist</li> </ul> Unlike relational databases where NULL handling is often an afterthought, graph databases require explicit modeling of optionality because NULL values affect traversals, aggregations, and pattern matching. <h3 id="defining-nullable-vs-not-null-properties" class="position-relative d-flex align-items-center group"> Defining Nullable vs NOT NULL 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="defining-nullable-vs-not-null-properties" aria-haspopup="dialog" aria-label="Share link: Defining Nullable vs NOT NULL Properties"> Share link </button> </h3>By default in Geode, all properties are nullable unless explicitly declared as NOT NULL. This default-nullable behavior requires careful consideration during schema design. <h4 id="explicit-nullability" class="position-relative d-flex align-items-center group"> Explicit Nullability <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="explicit-nullability" aria-haspopup="dialog" aria-label="Share link: Explicit Nullability"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Best practice: explicitly declare nullability intent CREATE NODE TYPE Person ( id STRING NOT NULL, -- Required: primary identifier name STRING NOT NULL, -- Required: every person has a name middle_name STRING NULL, -- Explicitly nullable (optional) nickname STRING, -- Implicitly nullable email STRING NOT NULL, -- Required for communication phone STRING NULL, -- Optional contact method date_of_birth DATE, -- May be unknown date_of_death DATE -- NULL for living persons ); -- Edge with required and optional properties CREATE EDGE TYPE WORKS_FOR ( start_date DATE NOT NULL, -- Employment must have start date end_date DATE, -- NULL = currently employed position STRING NOT NULL, salary DECIMAL, -- May be confidential/unknown department STRING NOT NULL ); </code></pre></div> <h4 id="not-null-constraints" class="position-relative d-flex align-items-center group"> NOT NULL Constraints <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="not-null-constraints" aria-haspopup="dialog" aria-label="Share link: NOT NULL Constraints"> Share link </button> </h4>NOT NULL constraints ensure data completeness for critical properties: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">CREATE NODE TYPE Product ( sku STRING NOT NULL, -- Must have identifier name STRING NOT NULL, -- Must be named price DECIMAL NOT NULL, -- Must have price description TEXT, -- Optional manufacturer STRING, -- May be unknown discontinued_date DATE -- NULL = still active ); </code></pre></div>Using NOT NULL with defaults provides sensible fallbacks: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">CREATE NODE TYPE User ( id STRING NOT NULL DEFAULT gen_random_uuid(), email STRING NOT NULL, created_at TIMESTAMP NOT NULL DEFAULT NOW(), status STRING NOT NULL DEFAULT 'active', last_login TIMESTAMP, -- NULL until first login preferences JSONB NOT NULL DEFAULT '{}'::JSONB -- Empty but not NULL ); </code></pre></div> <h3 id="null-in-gql-queries" class="position-relative d-flex align-items-center group"> NULL in GQL 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="null-in-gql-queries" aria-haspopup="dialog" aria-label="Share link: NULL in GQL Queries"> Share link </button> </h3> <h4 id="testing-for-null-values" class="position-relative d-flex align-items-center group"> Testing for NULL Values <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-for-null-values" aria-haspopup="dialog" aria-label="Share link: Testing for NULL Values"> Share link </button> </h4>The only correct way to test for NULL is using <code>IS NULL</code> or <code>IS NOT NULL</code>: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Find people without middle names MATCH (p:Person) WHERE p.middle_name IS NULL RETURN p.name; -- Find people with known phone numbers MATCH (p:Person) WHERE p.phone IS NOT NULL RETURN p.name, p.phone; -- Find current employees (no end_date) MATCH (p:Person)-[e:WORKS_FOR]->(c:Company) WHERE e.end_date IS NULL RETURN p.name, c.name, e.start_date; </code></pre></div>Common mistake: Using equality operators with NULL: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- WRONG: This will NEVER match anything, even NULL values MATCH (p:Person) WHERE p.middle_name = NULL -- Always evaluates to NULL (unknown), never TRUE RETURN p; -- WRONG: This also doesn't work as expected MATCH (p:Person) WHERE p.middle_name != NULL -- Also always NULL RETURN p; </code></pre></div>Why? In three-valued logic, <code>NULL = NULL</code> is NULL (unknown), not TRUE. You can’t compare unknown to unknown. <h4 id="coalesce-providing-fallback-values" class="position-relative d-flex align-items-center group"> COALESCE: Providing Fallback Values <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="coalesce-providing-fallback-values" aria-haspopup="dialog" aria-label="Share link: COALESCE: Providing Fallback Values"> Share link </button> </h4>COALESCE returns the first non-NULL value from a list of expressions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Use nickname if available, otherwise use formal name MATCH (p:Person) RETURN p.name, COALESCE(p.nickname, p.name) AS display_name; -- Multi-level fallback MATCH (p:Person) RETURN COALESCE(p.mobile_phone, p.home_phone, p.work_phone, 'No phone') AS contact_number; -- Default to zero for calculations MATCH (p:Product) RETURN p.name, p.base_price, COALESCE(p.discount_amount, 0) AS discount, p.base_price - COALESCE(p.discount_amount, 0) AS final_price; </code></pre></div>Python client example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Python - COALESCE in queries from geode_client import Client client = Client(host="localhost", port=3141) async with client.connection() as conn: # Get user display names with fallback logic result, _ = await conn.query(""" MATCH (u:User) RETURN u.id, COALESCE(u.display_name, u.username, u.email) AS name, COALESCE(u.avatar_url, '/default-avatar.png') AS avatar ORDER BY name """) for row in result.bindings: print(f"{row['name']} - Avatar: {row['avatar']}") </code></pre></div> <h4 id="nullif-converting-values-to-null" class="position-relative d-flex align-items-center group"> NULLIF: Converting Values to NULL <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="nullif-converting-values-to-null" aria-haspopup="dialog" aria-label="Share link: NULLIF: Converting Values to NULL"> Share link </button> </h4>NULLIF returns NULL if two expressions are equal, otherwise returns the first expression. Useful for treating specific values as NULL: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Treat empty strings as NULL MATCH (p:Person) RETURN p.name, NULLIF(p.middle_name, '') AS middle_name, NULLIF(p.phone, 'N/A') AS phone; -- Treat zero as NULL for optional numeric fields MATCH (p:Product) RETURN p.name, NULLIF(p.discount_pct, 0) AS discount; </code></pre></div>Combined with COALESCE: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Normalize empty strings to NULL, then provide default MATCH (p:Person) RETURN COALESCE(NULLIF(p.bio, ''), 'No bio provided') AS bio; </code></pre></div> <h3 id="null-in-comparisons-and-three-valued-logic" class="position-relative d-flex align-items-center group"> NULL in Comparisons and Three-Valued Logic <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-in-comparisons-and-three-valued-logic" aria-haspopup="dialog" aria-label="Share link: NULL in Comparisons and Three-Valued Logic"> Share link </button> </h3>Geode implements three-valued logic (TRUE, FALSE, NULL) for all boolean expressions. Understanding this is crucial for correct query behavior. <h4 id="comparison-truth-table" class="position-relative d-flex align-items-center group"> Comparison Truth Table <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="comparison-truth-table" aria-haspopup="dialog" aria-label="Share link: Comparison Truth Table"> Share link </button> </h4><table> <thead> <tr> <th>Expression</th> <th>p.age IS NULL</th> <th>p.age IS NOT NULL</th> </tr> </thead> <tbody> <tr> <td><code>p.age = 25</code></td> <td>NULL</td> <td>TRUE or FALSE</td> </tr> <tr> <td><code>p.age > 18</code></td> <td>NULL</td> <td>TRUE or FALSE</td> </tr> <tr> <td><code>p.age IS NULL</code></td> <td>TRUE</td> <td>FALSE</td> </tr> </tbody> </table> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Three-valued logic in action MATCH (p:Person) WHERE p.age > 18 -- Excludes NULL ages (NULL > 18 = NULL, not TRUE) RETURN p.name; -- Include people with unknown age MATCH (p:Person) WHERE p.age > 18 OR p.age IS NULL RETURN p.name, COALESCE(p.age, 'Unknown') AS age; </code></pre></div> <h4 id="null-propagation-in-expressions" class="position-relative d-flex align-items-center group"> NULL Propagation in 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="null-propagation-in-expressions" aria-haspopup="dialog" aria-label="Share link: NULL Propagation in Expressions"> Share link </button> </h4>NULL propagates through most expressions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">MATCH (p:Person) RETURN p.name, p.age, p.age + 5, -- NULL if age is NULL p.age * 1.1, -- NULL if age is NULL p.age > 18, -- NULL if age is NULL p.first_name || ' ' || p.middle_name || ' ' || p.last_name -- NULL if any part is NULL ; </code></pre></div>Safe string concatenation: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">MATCH (p:Person) RETURN -- Handles NULL middle names p.first_name || ' ' || COALESCE(p.middle_name || ' ', '') || p.last_name AS full_name; </code></pre></div> <h3 id="null-in-aggregations" class="position-relative d-flex align-items-center group"> NULL in 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="null-in-aggregations" aria-haspopup="dialog" aria-label="Share link: NULL in Aggregations"> Share link </button> </h3>Aggregate functions (except COUNT(*)) ignore NULL values: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- These ignore NULL values MATCH (p:Person) RETURN COUNT(*) AS total_people, -- Counts all nodes COUNT(p.age) AS people_with_age, -- Counts non-NULL ages AVG(p.age) AS average_age, -- Average of non-NULL ages MIN(p.age) AS youngest, -- Minimum non-NULL age MAX(p.age) AS oldest; -- Maximum non-NULL age -- Count NULL values explicitly MATCH (p:Person) RETURN COUNT(*) AS total, COUNT(p.phone) AS with_phone, COUNT(*) - COUNT(p.phone) AS without_phone; </code></pre></div>Go client example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">// Go client - handling NULL in aggregations package main import ( "context" "database/sql" "fmt" "geodedb.com/geode" ) func analyzeUserData(ctx context.Context, db *geode.DB) error { var total, withAge, avgAge sql.NullFloat64 err := db.QueryRowContext(ctx, ` MATCH (u:User) RETURN COUNT(*) AS total, COUNT(u.age) AS with_age, AVG(u.age) AS avg_age `).Scan(&total, &withAge, &avgAge) if err != nil { return err } fmt.Printf("Total users: %.0f\n", total.Float64) fmt.Printf("Users with age: %.0f\n", withAge.Float64) if avgAge.Valid { fmt.Printf("Average age: %.1f\n", avgAge.Float64) } else { fmt.Println("Average age: No data") } return nil } </code></pre></div> <h3 id="null-in-sorting" class="position-relative d-flex align-items-center group"> NULL in Sorting <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-in-sorting" aria-haspopup="dialog" aria-label="Share link: NULL in Sorting"> Share link </button> </h3>NULL values require explicit handling in ORDER BY clauses: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- NULL values sort last by default (in ascending order) MATCH (p:Person) RETURN p.name, p.age ORDER BY p.age ASC; -- NULL values first MATCH (p:Person) RETURN p.name, p.age ORDER BY p.age ASC NULLS FIRST; -- NULL values last MATCH (p:Person) RETURN p.name, p.age ORDER BY p.age DESC NULLS LAST; -- Use COALESCE to control NULL sorting MATCH (p:Person) RETURN p.name, p.age ORDER BY COALESCE(p.age, 999) ASC; -- Treat NULL as 999 </code></pre></div> <h3 id="application-level-null-handling" class="position-relative d-flex align-items-center group"> Application-Level NULL 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="application-level-null-handling" aria-haspopup="dialog" aria-label="Share link: Application-Level NULL Handling"> Share link </button> </h3> <h4 id="rust-client-with-option-types" class="position-relative d-flex align-items-center group"> Rust Client with Option 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="rust-client-with-option-types" aria-haspopup="dialog" aria-label="Share link: Rust Client with Option Types"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-rust" data-lang="rust">// Rust client - type-safe NULL handling with Option<T> use geode_client::{Client, Value}; use std::collections::HashMap; #[derive(Debug)] struct Person { id: String, name: String, middle_name: Option<String>, // NULL maps to None age: Option<i32>, phone: Option<String>, } async fn get_person(client: &Client, id: &str) -> Result<Person, geode_client::Error> { let mut params = HashMap::new(); params.insert("id", Value::String(id.to_string())); let result = client.execute( "MATCH (p:Person {id: $id}) RETURN p.id, p.name, p.middle_name, p.age, p.phone", &params ).await?; let row = result.bindings.first().ok_or(geode_client::Error::NotFound)?; Ok(Person { id: row["p.id"].as_str().unwrap().to_string(), name: row["p.name"].as_str().unwrap().to_string(), middle_name: row["p.middle_name"].as_str().map(String::from), // NULL → None age: row["p.age"].as_i64().map(|i| i as i32), phone: row["p.phone"].as_str().map(String::from), }) } fn format_full_name(person: &Person) -> String { match &person.middle_name { Some(middle) => format!("{} {} {}", person.name, middle, person.name), None => person.name.clone(), } } </code></pre></div> <h4 id="python-client-with-none" class="position-relative d-flex align-items-center group"> Python Client with None <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-with-none" aria-haspopup="dialog" aria-label="Share link: Python Client with None"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Python - NULL handling with None from typing import Optional from dataclasses import dataclass from geode_client import Client @dataclass class User: id: str email: str phone: Optional[str] = None bio: Optional[str] = None last_login: Optional[str] = None async def create_user(client: Client, email: str, phone: Optional[str] = None): """Create user with optional phone number.""" params = {"email": email} if phone is not None: params["phone"] = phone query = "INSERT (u:User {email: $email, phone: $phone}) RETURN u" else: query = "INSERT (u:User {email: $email}) RETURN u" result, _ = await client.query(query, params) return result.bindings[0]["u"] async def get_contact_info(client: Client, user_id: str) -> str: """Get contact info with NULL-safe formatting.""" result, _ = await client.query( "MATCH (u:User {id: $id}) RETURN u.email, u.phone", {"id": user_id} ) row = result.bindings[0] email = row["u.email"] phone = row.get("u.phone") # May be None if phone: return f"{email} (Phone: {phone})" else: return f"{email} (No phone)" </code></pre></div> <h3 id="best-practices-for-null-handling" class="position-relative d-flex align-items-center group"> Best Practices for NULL 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="best-practices-for-null-handling" aria-haspopup="dialog" aria-label="Share link: Best Practices for NULL Handling"> Share link </button> </h3><ol> <li>Explicit Nullability: Always declare whether properties can be NULL in schema</li> <li>NOT NULL by Default for Key Properties: IDs, timestamps, required business fields</li> <li>Use COALESCE for Display: Provide fallback values in user-facing queries</li> <li>Document NULL Semantics: Explain what NULL means for each nullable property</li> <li>Test NULL Cases: Write tests for NULL value handling in queries</li> <li>Avoid NULL in Calculations: Use COALESCE to provide numeric defaults</li> <li>Prefer DEFAULT over NULL: When sensible defaults exist, use them</li> <li>Type-Safe Clients: Use Option<T> (Rust), Optional (Python), sql.NullString (Go)</li> </ol> <h3 id="common-anti-patterns" class="position-relative d-flex align-items-center group"> Common 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="common-anti-patterns" aria-haspopup="dialog" aria-label="Share link: Common Anti-Patterns"> Share link </button> </h3>Anti-pattern: Using empty strings instead of NULL <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- BAD: Empty string is not NULL UPDATE Person SET middle_name = '' WHERE id = '123'; -- Use NULL instead -- GOOD: NULL represents absence of middle name UPDATE Person SET middle_name = NULL WHERE id = '123'; </code></pre></div>Anti-pattern: Comparing with NULL using <code>=</code> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- BAD: Never TRUE, always NULL WHERE p.middle_name = NULL -- GOOD: Use IS NULL WHERE p.middle_name IS NULL </code></pre></div>Anti-pattern: Ignoring NULL in business logic <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># BAD: age might be None, causing TypeError def is_adult(person): return person.age >= 18 # GOOD: Handle NULL explicitly def is_adult(person): return person.age is not None and person.age >= 18 </code></pre></div> <h3 id="troubleshooting" class="position-relative d-flex align-items-center group"> Troubleshooting <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="troubleshooting" aria-haspopup="dialog" aria-label="Share link: Troubleshooting"> Share link </button> </h3>Query returns no results despite data existing: Check for NULL comparisons using <code>=</code> instead of <code>IS NULL</code> Aggregations showing unexpected results: Remember that COUNT, SUM, AVG ignore NULL values String concatenation producing NULL: Use COALESCE to handle NULL components Type errors in application: Ensure client code handles NULL with appropriate types (Option, Optional, Nullable) <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/defaults" >Defaults</a> - Default values as alternative to NULL</li> <li><a href="/tags/constraints" >Constraints</a> - NOT NULL constraints and schema rules</li> <li><a href="/tags/validation" >Validation</a> - Validating optional vs required data</li> <li><a href="/tags/data-quality" >Data Quality</a> - Managing data completeness</li> <li><a href="/tags/schema/" >Schemas</a> - Schema design with nullability</li> <li><a href="/tags/gql" >GQL</a> - GQL standard three-valued logic semantics</li> </ul>

Popular

Related Articles