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, None).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", 100).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)​

Insert or update a record by ID. The client first reads the record by ID, then updates it if it exists or inserts it with that ID if it does not. That is two requests, not one atomic operation: another writer can create, change or delete the record between them. See the runnable convenience methods example.

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: Wraps the find-then-insert-or-update pattern in one call (two requests, not atomic)
  • 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​

A delete is permanent for the record's data. Restoring removes the record's tombstone, but its data comes back only if it is still held in memory, which is usually not the case. The single-record methods return true only when the data was recovered; the collection methods return the number of tombstones removed, not the number of records recovered. When you need undo, mark records as deleted with a field (for example deleted_at) and filter on it instead of deleting them. Restore requires admin permissions.

// true only when the record's data was recovered
let restored = client.restore_deleted("users", "record_id_123").await?;

// Number of tombstones removed
let cleared = client.restore_collection("users").await?;

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