Skip to main content

Basic Operations

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

:::tip 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​

:::tip 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);

:::tip 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);

:::tip 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?​