Tag: Python Async Client

The Geode Python client library (<code>geode-client-python</code>) provides a modern, fully async Python interface for connecting to Geode graph databases. Built on asyncio with aioquic for QUIC transport, it delivers high-performance concurrent operations while maintaining Pythonic idioms and comprehensive type hints for excellent IDE support. The Python client is designed for developers building data pipelines, web applications, and analytical tools who need reliable async database access. With features like connection pooling, query builders, and Row-Level Security (RLS) support, it provides enterprise-grade capabilities for production deployments. <h3 id="key-features" class="position-relative d-flex align-items-center group"> Key Features <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="key-features" aria-haspopup="dialog" aria-label="Share link: Key Features"> Share link </button> </h3><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script>Fully Async: Built from the ground up with asyncio and <code>async/await</code> patterns for non-blocking operations. QUIC + TLS 1.3: Secure, high-performance networking using aioquic with mandatory TLS 1.3. Full GQL Support: 98.6% ISO/IEC 39075:2024 compliance for comprehensive GQL query capabilities. Query Builders: Programmatic query construction with <code>QueryBuilder</code>, <code>PatternBuilder</code>, and <code>PredicateBuilder</code>. Connection Pooling: High-throughput concurrent workloads with 1000+ queries per second capability. Rich Type System: Full type hints with support for Decimal, temporal types, and complex GQL types. Authentication & RLS: Complete authentication with RBAC and Row-Level Security policy management. <h3 id="installation" class="position-relative d-flex align-items-center group"> Installation <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="installation" aria-haspopup="dialog" aria-label="Share link: Installation"> Share link </button> </h3>Install the Python client using pip: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Install from source cd geode-client-python pip install . # Or install in editable mode for development pip install -e ".[dev]" # Install with all optional dependencies pip install -e ".[dev,integration,benchmark,property]" </code></pre></div> <h4 id="requirements" class="position-relative d-flex align-items-center group"> Requirements <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="requirements" aria-haspopup="dialog" aria-label="Share link: Requirements"> Share link </button> </h4><ul> <li>Python 3.9 or later</li> <li>aioquic >= 0.9.0</li> <li>Running Geode server with QUIC enabled</li> </ul> <h3 id="quick-start" class="position-relative d-flex align-items-center group"> Quick Start <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="quick-start" aria-haspopup="dialog" aria-label="Share link: Quick Start"> Share link </button> </h3> <h4 id="basic-connection" class="position-relative d-flex align-items-center group"> Basic Connection <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="basic-connection" aria-haspopup="dialog" aria-label="Share link: Basic Connection"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import asyncio from geode_client import Client async def main(): # Create client client = Client(host="127.0.0.1", port=3141, skip_verify=True) # Execute query async with client.connection() as conn: page, _ = await conn.query("RETURN 1 AS x, 'Hello' AS greeting") for row in page.rows: x = row["x"].as_int greeting = row["greeting"].as_string print(f"x={x}, greeting={greeting}") asyncio.run(main()) </code></pre></div> <h4 id="using-url-connection" class="position-relative d-flex align-items-center group"> Using URL Connection <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="using-url-connection" aria-haspopup="dialog" aria-label="Share link: Using URL Connection"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import open_database async def main(): # Open database with URL client = open_database("quic://localhost:3141?insecure_tls_skip_verify=true") async with client.connection() as conn: page, _ = await conn.query("MATCH (n) RETURN n LIMIT 10") print(f"Found {len(page.rows)} nodes") asyncio.run(main()) </code></pre></div> <h4 id="parameterized-queries" class="position-relative d-flex align-items-center group"> Parameterized 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="parameterized-queries" aria-haspopup="dialog" aria-label="Share link: Parameterized Queries"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">async def find_person(client, name: str): async with client.connection() as conn: query = "MATCH (p:Person {name: $name}) RETURN p.age AS age" params = {"name": name} page, _ = await conn.query(query, params) if page.rows: age = page.rows[0]["age"].as_int print(f"{name} is {age} years old") asyncio.run(find_person(client, "Alice")) </code></pre></div> <h3 id="connection-configuration" class="position-relative d-flex align-items-center group"> Connection Configuration <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="connection-configuration" aria-haspopup="dialog" aria-label="Share link: Connection Configuration"> Share link </button> </h3> <h4 id="configuration-options" class="position-relative d-flex align-items-center group"> Configuration Options <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="configuration-options" aria-haspopup="dialog" aria-label="Share link: Configuration Options"> Share link </button> </h4><table> <thead> <tr> <th>Parameter</th> <th>Type</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>host</code></td> <td>str</td> <td><code>"127.0.0.1"</code></td> <td>Server hostname or IP address</td> </tr> <tr> <td><code>port</code></td> <td>int</td> <td><code>3141</code></td> <td>Server port number</td> </tr> <tr> <td><code>page_size</code></td> <td>int</td> <td><code>1000</code></td> <td>Results page size (1-100,000)</td> </tr> <tr> <td><code>hello_name</code></td> <td>str</td> <td><code>"geode-python"</code></td> <td>Client identification name</td> </tr> <tr> <td><code>hello_ver</code></td> <td>str</td> <td><code>"0.1.0"</code></td> <td>Client version string</td> </tr> <tr> <td><code>conformance</code></td> <td>str</td> <td><code>"min"</code></td> <td>GQL conformance level (<code>"min"</code> or <code>"full"</code>)</td> </tr> <tr> <td><code>ca_cert</code></td> <td>str</td> <td><code>None</code></td> <td>Path to CA certificate for server verification</td> </tr> <tr> <td><code>client_cert</code></td> <td>str</td> <td><code>None</code></td> <td>Path to client certificate for mTLS</td> </tr> <tr> <td><code>client_key</code></td> <td>str</td> <td><code>None</code></td> <td>Path to client private key for mTLS</td> </tr> <tr> <td><code>skip_verify</code></td> <td>bool</td> <td><code>False</code></td> <td>Skip TLS certificate verification (insecure)</td> </tr> <tr> <td><code>server_name</code></td> <td>str</td> <td>hostname</td> <td>SNI server name for TLS</td> </tr> </tbody> </table> <h4 id="url-format" class="position-relative d-flex align-items-center group"> URL Format <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="url-format" aria-haspopup="dialog" aria-label="Share link: URL Format"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">quic://host:port?param=value&param2=value2 </code></pre></div> <h4 id="connection-examples" class="position-relative d-flex align-items-center group"> Connection 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="connection-examples" aria-haspopup="dialog" aria-label="Share link: Connection Examples"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Simple connection (development) client = Client(host="localhost", port=3141, skip_verify=True) # Production with TLS client = Client( host="geode.example.com", port=3141, ca_cert="/path/to/ca.crt", server_name="geode.example.com" ) # Mutual TLS (mTLS) client = Client( host="geode.example.com", port=3141, ca_cert="/path/to/ca.crt", client_cert="/path/to/client.crt", client_key="/path/to/client.key", server_name="geode.example.com" ) # URL-based configuration client = open_database("quic://geode.example.com:3141?ca_cert=/path/to/ca.crt") </code></pre></div> <h3 id="transaction-management" class="position-relative d-flex align-items-center group"> Transaction Management <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="transaction-management" aria-haspopup="dialog" aria-label="Share link: Transaction Management"> Share link </button> </h3> <h4 id="basic-transactions" class="position-relative d-flex align-items-center group"> Basic Transactions <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="basic-transactions" aria-haspopup="dialog" aria-label="Share link: Basic Transactions"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">async def transfer_funds(client, from_account: str, to_account: str, amount: float): async with client.connection() as conn: await conn.begin() try: # Debit from source await conn.execute(""" MATCH (a:Account {id: $from_id}) WHERE a.balance >= $amount SET a.balance = a.balance - $amount """, {"from_id": from_account, "amount": amount}) # Credit to destination await conn.execute(""" MATCH (a:Account {id: $to_id}) SET a.balance = a.balance + $amount """, {"to_id": to_account, "amount": amount}) await conn.commit() print("Transaction committed") except Exception as e: await conn.rollback() print(f"Transaction rolled back: {e}") raise </code></pre></div> <h4 id="savepoints-partial-rollback" class="position-relative d-flex align-items-center group"> Savepoints (Partial Rollback) <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="savepoints-partial-rollback" aria-haspopup="dialog" aria-label="Share link: Savepoints (Partial Rollback)"> Share link </button> </h4>Savepoints enable partial rollback within a transaction: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">async def complex_operation(client): async with client.connection() as conn: await conn.begin() # Create initial data await conn.execute("CREATE (p:Person {name: 'Alice', age: 30})") # Create a savepoint sp = await conn.savepoint("before_update") # Make changes await conn.execute("MATCH (p:Person {name: 'Alice'}) SET p.age = 40") # Rollback to savepoint (undoes the age change) await conn.rollback_to(sp) # Alice's age is still 30 await conn.commit() </code></pre></div> <h3 id="query-builders" class="position-relative d-flex align-items-center group"> Query Builders <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-builders" aria-haspopup="dialog" aria-label="Share link: Query Builders"> Share link </button> </h3> <h4 id="querybuilder" class="position-relative d-flex align-items-center group"> QueryBuilder <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="querybuilder" aria-haspopup="dialog" aria-label="Share link: QueryBuilder"> Share link </button> </h4>Build GQL queries programmatically with type safety: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import QueryBuilder query_text, params = ( QueryBuilder() .match("(p:Person {name: $name})-[:KNOWS]->(friend:Person)") .where("friend.age > 25") .return_("friend.name AS name", "friend.age AS age") .order_by("friend.age DESC") .limit(10) .with_param("name", "Alice") .build() ) async with client.connection() as conn: page, _ = await conn.query(query_text, params) for row in page.rows: print(f"{row['name'].as_string}: {row['age'].as_int}") </code></pre></div> <h4 id="patternbuilder" class="position-relative d-flex align-items-center group"> PatternBuilder <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="patternbuilder" aria-haspopup="dialog" aria-label="Share link: PatternBuilder"> Share link </button> </h4>Build graph patterns for MATCH clauses: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import PatternBuilder, EdgeDirection pattern = ( PatternBuilder() .node("a", "Person", {"name": "$person1"}) .edge("knows", "KNOWS", EdgeDirection.UNDIRECTED) .variable_length(1, 6) .node("b", "Person", {"name": "$person2"}) .build() ) # Result: (a:Person {name: $person1})-[knows:KNOWS*1..6]-(b:Person {name: $person2}) query = f"MATCH {pattern} RETURN a, b" </code></pre></div> <h4 id="predicatebuilder" class="position-relative d-flex align-items-center group"> PredicateBuilder <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="predicatebuilder" aria-haspopup="dialog" aria-label="Share link: PredicateBuilder"> Share link </button> </h4>Build WHERE clause conditions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import PredicateBuilder predicate = ( PredicateBuilder() .greater_than("p.age", "25") .is_not_null("p.email") .in_("p.role", ["admin", "user"]) .build_and() ) # Result: p.age > 25 AND p.email IS NOT NULL AND p.role IN ['admin', 'user'] query = f"MATCH (p:Person) WHERE {predicate} RETURN p" </code></pre></div> <h3 id="connection-pooling" class="position-relative d-flex align-items-center group"> Connection Pooling <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="connection-pooling" aria-haspopup="dialog" aria-label="Share link: Connection Pooling"> Share link </button> </h3>Use connection pooling for high-throughput concurrent workloads: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import ConnectionPool async def main(): # Create pool pool = ConnectionPool( host="localhost", port=3141, min_size=2, max_size=10, skip_verify=True ) async with pool: # Acquire connection from pool async with pool.acquire() as conn: page, _ = await conn.query("RETURN 1") # Pool automatically manages connection lifecycle print(f"Pool size: {pool.size}, available: {pool.available}") asyncio.run(main()) </code></pre></div> <h4 id="pool-configuration" class="position-relative d-flex align-items-center group"> Pool Configuration <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="pool-configuration" aria-haspopup="dialog" aria-label="Share link: Pool Configuration"> Share link </button> </h4><table> <thead> <tr> <th>Parameter</th> <th>Type</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>min_size</code></td> <td>int</td> <td><code>1</code></td> <td>Minimum connections to maintain</td> </tr> <tr> <td><code>max_size</code></td> <td>int</td> <td><code>10</code></td> <td>Maximum connections allowed</td> </tr> <tr> <td><code>timeout</code></td> <td>float</td> <td><code>30.0</code></td> <td>Connection acquisition timeout (seconds)</td> </tr> </tbody> </table> <h4 id="concurrent-queries" class="position-relative d-flex align-items-center group"> Concurrent 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="concurrent-queries" aria-haspopup="dialog" aria-label="Share link: Concurrent Queries"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">async def concurrent_queries(pool): """Execute multiple queries concurrently.""" async def fetch_data(i: int): async with pool.acquire() as conn: page, _ = await conn.query( "MATCH (p:Person {id: $id}) RETURN p", {"id": i} ) return page.rows # Execute 100 concurrent queries tasks = [fetch_data(i) for i in range(100)] results = await asyncio.gather(*tasks) print(f"Fetched {len(results)} results concurrently") </code></pre></div> <h3 id="authentication-and-authorization" class="position-relative d-flex align-items-center group"> Authentication and Authorization <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="authentication-and-authorization" aria-haspopup="dialog" aria-label="Share link: Authentication and Authorization"> Share link </button> </h3> <h4 id="basic-authentication" class="position-relative d-flex align-items-center group"> Basic Authentication <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="basic-authentication" aria-haspopup="dialog" aria-label="Share link: Basic Authentication"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import AuthClient async def authenticate(client): async with client.connection() as conn: auth = AuthClient(conn) # Login session = await auth.login("username", "password") print(f"Token: {session.token}") print(f"Roles: {session.roles}") # Create user user = await auth.create_user( username="newuser", email="[email protected]", password="secure123", roles=["user"] ) print(f"Created user: {user.username}") # Check permission has_perm = await auth.check_permission( user_id=user.id, resource="data", action="read" ) print(f"Has read permission: {has_perm}") # Logout await auth.logout(session.token) </code></pre></div> <h4 id="row-level-security-rls" class="position-relative d-flex align-items-center group"> Row-Level Security (RLS) <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="row-level-security-rls" aria-haspopup="dialog" aria-label="Share link: Row-Level Security (RLS)"> Share link </button> </h4>Configure fine-grained access control with RLS policies: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import RLSPolicy async def setup_rls(auth): policy = RLSPolicy( name="user_data_policy", table="user_data", graph="main", operation="SELECT", permissive=True, roles=[1, 2], using_expression="owner_id = current_user_id()", enabled=True, audit_level="READ" ) created = await auth.create_rls_policy(policy) print(f"Created policy: {created.name} (ID: {created.id})") # List policies policies = await auth.list_rls_policies() for p in policies: print(f"Policy: {p.name}, Operation: {p.operation}") </code></pre></div> <h3 id="type-system" class="position-relative d-flex align-items-center group"> Type System <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="type-system" aria-haspopup="dialog" aria-label="Share link: Type System"> Share link </button> </h3>The client supports all GQL types with proper Python mappings: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Access typed values row = page.rows[0] # Basic types int_val = row["count"].as_int str_val = row["name"].as_string bool_val = row["active"].as_bool decimal_val = row["price"].as_decimal # Temporal types date_val = row["birthdate"].as_date timestamp_val = row["created_at"].as_datetime # Complex types array_val = row["tags"].as_array object_val = row["metadata"].as_object bytes_val = row["data"].as_bytes range_val = row["period"].as_range # Raw value access raw = row["field"].raw_value </code></pre></div> <h3 id="pagination" class="position-relative d-flex align-items-center group"> Pagination <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="pagination" aria-haspopup="dialog" aria-label="Share link: Pagination"> Share link </button> </h3>Handle large result sets with pagination: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">async def paginated_query(conn): query = "MATCH (n:Person) RETURN n.name ORDER BY n.name" # Get first page page, pager = await conn.query(query, page_size=100) # Process first page for row in page.rows: process(row) # Get more pages async for next_page in pager(): for row in next_page.rows: process(row) </code></pre></div> <h3 id="error-handling" class="position-relative d-flex align-items-center group"> Error 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="error-handling" aria-haspopup="dialog" aria-label="Share link: Error Handling"> Share link </button> </h3>The client provides specific exceptions for different error types: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import GeodeError, ConnectionError, QueryError, AuthError async def safe_query(conn, query: str): try: page, _ = await conn.query(query) return page except QueryError as e: print(f"Query failed: {e}") except ConnectionError as e: print(f"Connection failed: {e}") except AuthError as e: print(f"Auth failed: {e}") except GeodeError as e: print(f"Geode error: {e}") </code></pre></div> <h4 id="retry-logic" class="position-relative d-flex align-items-center group"> Retry 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="retry-logic" aria-haspopup="dialog" aria-label="Share link: Retry Logic"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import random async def execute_with_retry(conn, query: str, max_attempts: int = 3): for attempt in range(max_attempts): try: page, _ = await conn.query(query) return page except QueryError as e: if "serialization" in str(e).lower() and attempt < max_attempts - 1: delay = random.uniform(0.01, 0.1) * (2 ** attempt) await asyncio.sleep(delay) continue raise </code></pre></div> <h3 id="input-validation" class="position-relative d-flex align-items-center group"> Input Validation <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="input-validation" aria-haspopup="dialog" aria-label="Share link: Input Validation"> Share link </button> </h3>The client includes an input validation module: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import validate, ValidationError try: # Validate query string query = validate.query(user_input) # Validate connection parameters host = validate.hostname(host_input) port = validate.port(port_input) page = validate.page_size(page_input) # Validate identifiers label = validate.label(label_input) prop = validate.property_name(prop_input) except ValidationError as e: print(f"Invalid input: {e}") </code></pre></div> <h4 id="available-validators" class="position-relative d-flex align-items-center group"> Available Validators <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="available-validators" aria-haspopup="dialog" aria-label="Share link: Available Validators"> Share link </button> </h4><table> <thead> <tr> <th>Function</th> <th>Purpose</th> <th>Example Valid Input</th> </tr> </thead> <tbody> <tr> <td><code>validate.query()</code></td> <td>Query strings</td> <td><code>"RETURN 1"</code></td> </tr> <tr> <td><code>validate.param_name()</code></td> <td>Parameter names</td> <td><code>"user_id"</code></td> </tr> <tr> <td><code>validate.hostname()</code></td> <td>Hosts/IPs</td> <td><code>"localhost"</code>, <code>"192.168.1.1"</code></td> </tr> <tr> <td><code>validate.port()</code></td> <td>Port numbers</td> <td><code>3141</code> (1-65535)</td> </tr> <tr> <td><code>validate.page_size()</code></td> <td>Page sizes</td> <td><code>1000</code> (1-100,000)</td> </tr> <tr> <td><code>validate.identifier()</code></td> <td>GQL identifiers</td> <td><code>"node_name"</code></td> </tr> <tr> <td><code>validate.label()</code></td> <td>Node/edge labels</td> <td><code>"Person"</code></td> </tr> <tr> <td><code>validate.timeout()</code></td> <td>Timeout values</td> <td><code>30.0</code> (seconds)</td> </tr> </tbody> </table> <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="connection-reuse" class="position-relative d-flex align-items-center group"> Connection Reuse <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="connection-reuse" aria-haspopup="dialog" aria-label="Share link: Connection Reuse"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Good: Reuse pattern with different parameters pattern = QueryBuilder().match("(n:Person)").where("n.id = $id").return_("n") for i in range(100): query, params = pattern.with_param("id", i).build() # Execute query... </code></pre></div> <h4 id="concurrent-execution" class="position-relative d-flex align-items-center group"> Concurrent Execution <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="concurrent-execution" aria-haspopup="dialog" aria-label="Share link: Concurrent Execution"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Good: Use connection pool for concurrent queries async with ConnectionPool(min_size=5, max_size=20) as pool: tasks = [fetch_data(pool, i) for i in range(100)] await asyncio.gather(*tasks) </code></pre></div> <h4 id="quic-system-optimizations" class="position-relative d-flex align-items-center group"> QUIC System Optimizations <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="quic-system-optimizations" aria-haspopup="dialog" aria-label="Share link: QUIC System Optimizations"> Share link </button> </h4>For optimal QUIC throughput, configure UDP buffer sizes at the OS level. Linux: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">sudo sysctl -w net.core.rmem_max=7340032 sudo sysctl -w net.core.wmem_max=7340032 # Persist across reboots echo "net.core.rmem_max=7340032" | sudo tee -a /etc/sysctl.d/99-geode-quic.conf echo "net.core.wmem_max=7340032" | sudo tee -a /etc/sysctl.d/99-geode-quic.conf </code></pre></div>BSD/macOS: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">sudo sysctl -w kern.ipc.maxsockbuf=8441037 </code></pre></div> <h3 id="testing" class="position-relative d-flex align-items-center group"> Testing <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" aria-haspopup="dialog" aria-label="Share link: Testing"> Share link </button> </h3><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Run all unit tests (377 tests) pytest tests/unit/ # Run with coverage report pytest tests/unit/ --cov=geode_client --cov-report=term-missing # Run specific test module pytest tests/unit/test_types.py -v # Run integration tests (requires Docker, 119 tests) pytest tests/integration/ -m integration # Run property-based tests (50 tests) pytest tests/property/ -v # Run benchmarks (154 benchmarks) pytest benchmarks/ --benchmark-only # Code quality ruff check geode_client/ ruff format geode_client/ mypy geode_client/ </code></pre></div> <h3 id="performance-characteristics" class="position-relative d-flex align-items-center group"> Performance Characteristics <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-characteristics" aria-haspopup="dialog" aria-label="Share link: Performance Characteristics"> Share link </button> </h3><table> <thead> <tr> <th>Metric</th> <th>Value</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td>Connection establishment</td> <td>~50-100ms</td> <td>QUIC handshake + TLS</td> </tr> <tr> <td>Query latency</td> <td>~2-3ms</td> <td>Localhost, simple queries</td> </tr> <tr> <td>Throughput</td> <td>1000+ q/s</td> <td>With connection pooling</td> </tr> <tr> <td>Result parsing</td> <td>~1ms/1000 rows</td> <td>JSON decoding</td> </tr> </tbody> </table> <h3 id="api-reference" class="position-relative d-flex align-items-center group"> API Reference <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="api-reference" aria-haspopup="dialog" aria-label="Share link: API Reference"> Share link </button> </h3> <h4 id="core-classes" class="position-relative d-flex align-items-center group"> Core Classes <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-classes" aria-haspopup="dialog" aria-label="Share link: Core Classes"> Share link </button> </h4><table> <thead> <tr> <th>Class</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>Client</code></td> <td>Factory for creating connections. Use <code>Client.from_url()</code> for URL config.</td> </tr> <tr> <td><code>Connection</code></td> <td>Async context manager for database operations.</td> </tr> <tr> <td><code>Page</code></td> <td>Query result container with columns and rows.</td> </tr> <tr> <td><code>Value</code></td> <td>Typed value container with accessors (<code>as_int</code>, <code>as_string</code>, etc.)</td> </tr> <tr> <td><code>QueryBuilder</code></td> <td>Fluent interface for building GQL queries.</td> </tr> <tr> <td><code>PatternBuilder</code></td> <td>Builder for graph patterns (nodes, edges).</td> </tr> <tr> <td><code>PredicateBuilder</code></td> <td>Builder for WHERE clause predicates.</td> </tr> <tr> <td><code>ConnectionPool</code></td> <td>Connection pool for concurrent workloads.</td> </tr> <tr> <td><code>AuthClient</code></td> <td>Authentication and authorization operations.</td> </tr> </tbody> </table> <h4 id="exceptions" class="position-relative d-flex align-items-center group"> Exceptions <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="exceptions" aria-haspopup="dialog" aria-label="Share link: Exceptions"> Share link </button> </h4><table> <thead> <tr> <th>Exception</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>GeodeError</code></td> <td>Base exception for all Geode errors</td> </tr> <tr> <td><code>GeodeConnectionError</code></td> <td>Connection establishment failures</td> </tr> <tr> <td><code>QueryError</code></td> <td>Query execution failures</td> </tr> <tr> <td><code>AuthError</code></td> <td>Authentication/authorization failures</td> </tr> <tr> <td><code>ValidationError</code></td> <td>Input validation failures</td> </tr> </tbody> </table> <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/python/" >Python</a> </li> <li><a href="/tags/client-libraries/" >Client Libraries</a> </li> <li><a href="/tags/quic/" >QUIC Protocol</a> </li> <li><a href="/tags/connection-pooling/" >Connection Pooling</a> </li> <li><a href="/tags/async/" >Async Patterns</a> </li> <li><a href="/tags/transactions/" >Transactions</a> </li> <li><a href="/tags/tutorials/" >Tutorials</a> </li> </ul> <h3 id="further-reading" class="position-relative d-flex align-items-center group"> Further Reading <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="further-reading" aria-haspopup="dialog" aria-label="Share link: Further Reading"> Share link </button> </h3><ul> <li><a href="https://docs.python.org/3/library/asyncio.html" aria-label="asyncio Documentation – opens in new window" target="_blank" rel="noopener noreferrer" >asyncio Documentation ↗ </a> </li> <li><a href="https://github.com/aiortc/aioquic" aria-label="aioquic Library – opens in new window" target="_blank" rel="noopener noreferrer" >aioquic Library ↗ </a> </li> <li><a href="https://www.iso.org/standard/76120.html" aria-label="ISO/IEC 39075:2024 GQL Standard – opens in new window" target="_blank" rel="noopener noreferrer" >ISO/IEC 39075:2024 GQL Standard ↗ </a> </li> <li><a href="https://gitlab.com/devnw/codepros/geode/geode-client-python" aria-label="Python Client Repository – opens in new window" target="_blank" rel="noopener noreferrer" >Python Client Repository ↗ </a> </li> <li><a href="/docs/" >Geode Documentation</a> </li> </ul>

Popular

Related Articles