Tutorials & Guides

Tutorials & Guides Share link

Welcome to Geode’s comprehensive tutorial collection. Whether you’re new to graph databases or transitioning from other systems, these tutorials provide structured, hands-on learning paths to master Geode and the ISO/IEC 39075:2024 GQL standard.

Learning Geode Through Tutorials Share link

Tutorials are your fastest path to productive graph database development. Unlike reference documentation that explains what features exist, tutorials show how to use them through practical, goal-oriented examples that build your skills incrementally.

Why Tutorial-Based Learning Works Share link

Structured Progression: Tutorials guide you from basic concepts to advanced techniques in a logical sequence. You start with simple node creation, progress to complex pattern matching, and eventually master transactions, security policies, and performance optimization.

Hands-On Practice: Every tutorial includes executable code examples. You learn by doing, not just reading. Whether you’re using Python’s async client, Go’s database/sql driver, or Rust’s high-performance tokio integration, you’ll write real code that runs against a real database.

Context and Purpose: Tutorials explain not just the syntax but the reasoning behind design decisions. You’ll understand why GQL uses declarative pattern matching instead of imperative traversals, and when to use subqueries versus OPTIONAL MATCH clauses.

Error Prevention: Good tutorials anticipate common mistakes and show you how to avoid them. You’ll learn why relationship direction matters in pattern matching, how to prevent injection vulnerabilities in dynamic queries, and when to use transactions versus individual statements.

Tutorial Categories in Geode Share link

Getting Started Tutorials Share link

Begin your journey with installation, basic configuration, and your first GQL queries. These tutorials assume no prior graph database experience and introduce fundamental concepts like nodes, relationships, properties, and pattern matching.

First Steps: Install Geode, start the server, connect with a client, and execute your first CREATE, MATCH, and RETURN statements. Within 15 minutes, you’ll have a working graph database storing and querying connected data.

Data Modeling: Learn how to represent real-world entities and relationships as graph structures. Unlike relational databases where you normalize data into tables, graph modeling focuses on connections. A social network tutorial might show how users, posts, comments, and likes form a natural graph structure that’s easier to query than SQL joins.

Basic Queries: Master the core GQL operations—CREATE for inserting data, MATCH for finding patterns, SET for updates, and DELETE for removal. Each tutorial provides multiple examples with increasing complexity, from single-node queries to multi-hop relationship traversals.

Client Integration Tutorials Share link

Geode provides production-ready clients in Python, Go, Rust, and Zig. Each language has its own idioms and patterns for database interaction.

Python Async Client: Build asynchronous applications using Python’s async/await syntax. Learn connection pooling for high-throughput scenarios (workload dependent), context managers for transaction handling, and type-safe parameter binding. Example applications include web API backends using FastAPI and data processing pipelines.

Go database/sql Driver: Integrate Geode into Go applications using the standard database/sql interface. This tutorial covers prepared statements, connection lifecycle management, error handling with GQL status codes, and concurrent query execution. You’ll build a REST API that exposes graph data through HTTP endpoints.

Rust High-Performance Client: Leverage Rust’s zero-cost abstractions and tokio runtime for maximum throughput (workload dependent). Learn about the query builder API, connection pooling, async streams for result iteration, and integration with web frameworks like Axum and Actix.

Zig Native Client: For systems programming and embedded scenarios, the Zig client provides direct control over memory allocation and error handling. This tutorial shows how to integrate Geode into low-level applications requiring predictable performance and minimal overhead.

Query Pattern Tutorials Share link

GQL’s declarative pattern matching is fundamentally different from SQL’s procedural joins. These tutorials build your intuition for expressing complex graph traversals concisely.

Pattern Matching Fundamentals: Learn how MATCH (a:Person)-[:KNOWS]->(b:Person) declares a relationship pattern that Geode resolves efficiently. Understand node variables, relationship types, property filters, and direction constraints.

Multi-Hop Traversals: Find paths through your graph using variable-length relationships. MATCH (a)-[:FOLLOWS*1..3]->(b) finds users within three degrees of separation. Learn when to use bounded versus unbounded traversals and how Geode optimizes path finding.

Subqueries and Composition: Break complex queries into manageable pieces using subqueries. Calculate aggregations, filter based on connected subgraphs, or return transformed results. Understand how subqueries enable reusable query components.

OPTIONAL MATCH: Handle missing data gracefully using OPTIONAL patterns. Unlike SQL’s LEFT JOIN, OPTIONAL MATCH preserves graph structure while allowing null values for absent relationships. Learn when to use OPTIONAL versus multiple queries.

Transaction and Concurrency Tutorials Share link

Production applications require transactional consistency and concurrent access patterns.

ACID Transactions: Every Geode operation supports full ACID semantics—atomicity, consistency, isolation, and durability. Learn how to group multiple queries into transactions, handle rollback scenarios, and use savepoints for partial rollback.

Isolation Levels: Understand how Geode’s SERIALIZABLE isolation prevents anomalies like dirty reads, non-repeatable reads, and phantom reads. Learn the performance implications and when snapshot isolation is sufficient.

Concurrent Patterns: Build applications that handle multiple simultaneous clients safely. Learn optimistic locking strategies, retry logic for transaction conflicts, and connection pool configuration for maximum throughput.

Distributed Transactions: For applications spanning multiple data stores, learn integration patterns with external systems while maintaining consistency guarantees.

Security and Access Control Tutorials Share link

Geode’s Row-Level Security (RLS) provides fine-grained access control at the data level, not just the table level.

Authentication Setup: Configure TLS certificates, set up user credentials, and integrate with external authentication providers. Geode requires TLS 1.3 for all connections, ensuring data is encrypted in transit.

Role-Based Access: Define roles with specific capabilities—read-only users, editors who can modify data, and administrators with schema privileges. Learn policy composition for complex authorization rules.

Row-Level Security Policies: Restrict query results based on user identity and data properties. A multi-tenant application might use RLS to ensure users only see their organization’s data, even when querying shared tables. The database enforces policies automatically without application-level filtering.

Audit Logging: Track who accessed what data and when. Implement comprehensive audit trails for compliance requirements in regulated industries.

Performance and Optimization Tutorials Share link

Scalable applications require understanding query performance characteristics and optimization techniques.

Query Profiling: Use Geode’s PROFILE command to understand query execution plans. Identify bottlenecks like full table scans, unindexed property lookups, or inefficient join strategies.

Index Design: Learn which queries benefit from indexes and how to create them. Property indexes accelerate equality and range lookups. Relationship indexes speed up traversals from specific node types.

Caching Strategies: Implement application-level caching for frequently accessed data. Understand cache invalidation patterns and when to use client-side versus server-side caching.

Bulk Operations: Load large datasets efficiently using batch inserts and COPY commands. Learn partitioning strategies for parallel data loading and how to maintain index consistency during bulk operations.

Code Examples Across Languages Share link

Every tutorial provides working code in multiple languages, demonstrating idiomatic patterns for each ecosystem.

Python Example: Creating and Querying a Social Graph Share link

import asyncio
from geode_client import Client

async def social_graph_example():
    client = Client(host="localhost", port=3141)
    async with client.connection() as conn:
        # Create users with a transaction
        async with client.connection() as tx:
            await tx.begin()
            await tx.execute("""
                CREATE (alice:Person {name: 'Alice', age: 30})
                CREATE (bob:Person {name: 'Bob', age: 25})
                CREATE (alice)-[:KNOWS {since: 2020}]->(bob)
            """)

        # Query friends of friends
        result, _ = await conn.query("""
            MATCH (a:Person {name: 'Alice'})-[:KNOWS*1..2]->(friend)
            RETURN DISTINCT friend.name, friend.age
            ORDER BY friend.name
        """)

        for row in result.rows:
            print(f"Friend: {row['friend.name']}, Age: {row['friend.age']}")

asyncio.run(social_graph_example())

Go Example: Product Recommendations Share link

package main

import (
    "context"
    "database/sql"
    "fmt"
    _ "geodedb.com/geode"
)

func main() {
    db, err := sql.Open("geode", "quic://localhost:3141")
    if err != nil {
        panic(err)
    }
    defer db.Close()

    // Find products similar to what user purchased
    rows, err := db.QueryContext(context.Background(), `
        MATCH (u:User {id: $userId})-[:PURCHASED]->(p:Product)
              -[:SIMILAR_TO]->(rec:Product)
        WHERE NOT EXISTS {
            MATCH (u)-[:PURCHASED]->(rec)
        }
        RETURN rec.name, rec.price
        ORDER BY rec.price
        LIMIT 5
    `, sql.Named("userId", "user123"))

    if err != nil {
        panic(err)
    }
    defer rows.Close()

    for rows.Next() {
        var name string
        var price float64
        rows.Scan(&name, &price)
        fmt.Printf("Recommendation: %s ($%.2f)\n", name, price)
    }
}

Rust Example: High-Throughput Event Processing Share link

use geode_client::{Client, QueryBuilder};
use tokio;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect("localhost:3141").await?;

    // Stream events and create graph relationships in real-time
    let query = QueryBuilder::new()
        .match_pattern("(e:Event)")
        .where_clause("e.timestamp > $cutoff")
        .return_clause("e.id, e.type, e.user_id")
        .build();

    let mut results = client.execute(&query)
        .bind("cutoff", "2025-01-01T00:00:00Z")
        .stream()
        .await?;

    while let Some(row) = results.next().await {
        let event_id: String = row.get("e.id")?;
        let event_type: String = row.get("e.type")?;

        // Process events at 10,000+ per second
        println!("Processing event: {} ({})", event_id, event_type);
    }

    Ok(())
}

Best Practices from Tutorials Share link

Through hands-on examples, you’ll internalize these production-ready practices:

Parameterized Queries: Always use parameter binding instead of string concatenation to prevent GQL injection attacks. Every client library provides safe parameter mechanisms.

Connection Pooling: Don’t create a new connection for every query. Use connection pools to amortize TLS handshake costs and maintain persistent connections to the server.

Transaction Boundaries: Keep transactions short and focused. Long-running transactions hold locks and can impact concurrency. Commit or rollback promptly.

Error Handling: Implement retry logic for transient failures like network timeouts or transaction conflicts. Distinguish between retryable errors and permanent failures.

Resource Cleanup: Use language-specific resource management patterns—Python’s async with, Go’s defer, Rust’s Drop trait—to ensure connections and transactions are properly closed even during errors.

Common Tutorial Pitfalls and Solutions Share link

Pitfall: Cartesian Product Queries Forgetting relationship constraints causes queries to return every possible node combination. Always connect patterns with relationships or WHERE clauses.

Pitfall: Unbounded Traversals MATCH (a)-[:CONNECTED*]->(b) without a maximum hop count can traverse the entire graph. Use bounded ranges like [:CONNECTED*1..5] unless you specifically need unlimited depth.

Pitfall: Property Access Without Checks Accessing properties that might not exist causes runtime errors. Use OPTIONAL MATCH or COALESCE() for nullable properties.

Pitfall: Ignoring Transaction Boundaries Relying on auto-commit for multi-step operations leads to inconsistent state if intermediate steps fail. Explicitly manage transactions for related operations.

Interactive Learning Resources Share link

Geode Shell: The interactive REPL lets you experiment with queries immediately. Type geode shell to start exploring your data interactively with syntax highlighting and auto-completion.

Test Harness: Run the cross-client test harness to see working examples in all languages executing the same queries. Learn how different clients handle parameters, results, and errors.

Sample Datasets: Load pre-built datasets representing common domains—social networks, product catalogs, knowledge graphs, security policies. Learn through realistic scenarios rather than toy examples.

Progressive Tutorial Paths Share link

Beginner Path (Week 1): Installation, basic CRUD, simple pattern matching, single-client integration.

Intermediate Path (Week 2-3): Complex queries, transactions, security policies, connection pooling, error handling.

Advanced Path (Week 4+): Performance optimization, distributed systems integration, custom client implementation, production deployment.

Community Tutorials Share link

Beyond official documentation, the Geode community creates tutorials for specific use cases:

• E-commerce recommendation systems
• Fraud detection in financial networks
• Social network analysis and influence graphs
• Knowledge graph construction from text
• Real-time event correlation
• Multi-tenant SaaS architectures

Next Steps Share link

Start with the Getting Started tutorial to install Geode and execute your first queries. Then explore client-specific tutorials for your programming language. As you build proficiency, tackle performance optimization and security hardening tutorials to prepare for production deployment.

Every tutorial builds on previous knowledge while standing alone as a reference for specific techniques. Learn at your own pace, experiment freely in development environments, and apply lessons to your production use cases.

Related Topics Share link

• Examples: Working code snippets demonstrating specific features
• Guides: In-depth explanations of concepts and architectures
• Quick Start: Condensed tutorials for rapid initial setup
• Hands-On Learning: Interactive exercises and challenges
• Developer Guide: Comprehensive reference for building on Geode