Skip to main content

Basic Operations

This guide covers the essential CRUD (Create, Read, Update, Delete) operations using ekoDB client libraries.

Complete Examples Available

For complete, runnable examples, visit the ekoDB Examples Repository. It contains 93 examples (56 client library + 37 direct API examples).

Prerequisites​

Before you begin, make sure you have:

  1. ✅ Installed the client library
  2. ✅ Retrieved your API key

Client Initialization​

use ekodb_client::Client;

let client = Client::builder()
    .base_url("https://your-subdomain.production.google.ekodb.net")
    .api_key("your-api-key")
    .build()?;

Insert Records​

Create new records in a collection:

use ekodb_client::Record;

let mut user = Record::new();
user.insert("name", "Alice Smith");
user.insert("email", "alice@example.com");
user.insert("age", 28);

let result = client.insert("users", user).await?;
println!("Created user with ID: {:?}", result.get("id"));

Find Records​

Find by ID​

let user = client.find_by_id("users", "user-id-123").await?;
println!("Found user: {:?}", user);

Find All Records​

let users = client.find_all("users").await?;
println!("Found {} users", users.len());

Update Records​

let mut updates = Record::new();
updates.insert("age", 29);
updates.insert("email", "alice.smith@example.com");

let updated = client.update("users", "user-id-123", updates).await?;
println!("Updated user: {:?}", updated);

Delete Records​

client.delete("users", "user-id-123").await?;
println!("User deleted successfully");

Convenience Methods​

New in v0.8.0

These ergonomic helper methods simplify common patterns and reduce boilerplate code.

Upsert (Insert or Update)​

Atomic insert-or-update operation. Attempts to update the record first; if it doesn't exist, it inserts it instead.

use ekodb_client::Record;

let mut user = Record::new();
user.insert("name", "Alice Smith");
user.insert("email", "alice@example.com");
user.insert("age", 29);

// Will update if exists, insert if not
let result = client.upsert("users", "user-123", user, None).await?;
println!("Upserted user: {:?}", result);

Find One Record by Field​

Find a single record matching a specific field value. Returns null/nil/None if no match found.

// Find user by email
let user = client.find_one("users", "email", "alice@example.com").await?;

match user {
    Some(record) => println!("Found user: {:?}", record),
    None => println!("User not found"),
}

Check Record Existence​

Efficiently check if a record exists without fetching the full document.

if client.exists("users", "user-123").await? {
    println!("User exists");
} else {
    println!("User not found");
}

Paginate Results​

Simplified pagination using page numbers (1-indexed) instead of skip/limit calculations.

// Get page 2 with 10 records per page
let page = 2;
let page_size = 10;

let users = client.paginate("users", page, page_size).await?;
println!("Found {} users on page {}", users.len(), page);
Why Use Convenience Methods?
  • Upsert: Eliminates need for exists-check-then-insert patterns
  • FindOne: Cleaner than building a query with limit(1)
  • Exists: More efficient than fetching the full record
  • Paginate: No need to calculate skip/offset manually

Collection Management​

List Collections​

let collections = client.list_collections().await?;
println!("Collections: {:?}", collections);

Delete Collection​

client.delete_collection("old_data").await?;
println!("Collection deleted");

Check Collection Exists​

let exists = client.collection_exists("users").await?;
if exists {
    println!("Collection exists");
}

Count Documents​

let count = client.count_documents("users").await?;
println!("Total documents: {}", count);

Restore from Trash​

Restore deleted records from trash. Records remain in trash for 30 days before permanent deletion.

// Restore single record
let restored = client.restore_deleted("users", "record_id_123").await?;
if restored {
    println!("Record restored successfully");
}

// Restore all records in collection
let count = client.restore_collection("users").await?;
println!("Restored {} records", count);
Trash Retention

All client libraries support restore operations. Deleted records are kept in trash for 30 days before permanent deletion.

Complete Examples​

For complete, runnable examples with error handling and advanced features, visit:

📚 Example Repository​

ekoDB Client Examples

The repository contains 93 examples total (56 client library + 37 direct API) organized by language:

  • Rust Examples - 15 client examples + 10 direct API examples
  • Python Examples - 16 client examples + 10 direct API examples
  • TypeScript Examples - 16 client examples (Node.js & browsers)
  • Go Examples - 15 client examples + 10 direct API examples
  • Kotlin Examples - 15 client examples with coroutines
  • JavaScript Examples - 12 client examples + 10 direct API examples for Node.js

Core Operations:

  • Simple CRUD - Basic create, read, update, delete operations
  • Query Builder - Complex queries with filters, sorting, pagination
  • Batch Operations - Efficient bulk inserts, updates, deletes
  • Schema Management - Define and enforce data schemas

New in v0.8.0:

  • Convenience Methods - Upsert, findOne, exists, paginate examples (all languages)
  • Bypass Ripple - Control ripple propagation in multi-node deployments (all languages)

Advanced Features:

  • Search - Full-text search with scoring
  • WebSocket - Real-time queries and subscriptions
  • TTL - Automatic document expiration
  • Key-Value - Simple key-value store operations
  • Chat & RAG - Conversational AI with retrieval-augmented generation
  • Functions - Server-side function execution

Running Examples​

Visit the ekoDB Examples Repository for complete, runnable examples in all supported languages. Each example can be copied and adapted to your own project.

  • Rust Examples
  • Python Examples
  • TypeScript/JavaScript Examples
  • Kotlin Examples
  • Go Examples

Next Steps​

  • More Examples - Query builder, search, batch operations, and more
  • API Reference - Direct HTTP API documentation
  • Authentication - Learn about API keys and permissions

Need Help?​