Skip to main content

Basic Operations

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

tip

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");

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:

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​

# Clone the repository
git clone https://github.com/ekoDB/ekodb-client.git
cd ekodb-client/examples

# Set up environment
cp .env.example .env
# Edit .env with your API URL and key

# Run all examples
make test-examples

# Run specific language examples
make test-examples-rust
make test-examples-python
make test-examples-typescript
make test-examples-kotlin
make test-examples-javascript

# To run this directly without package installation, 
# go to https://github.com/ekoDB/ekodb-client-go 
# and use the file path to run the example
make test-examples-go

Next Steps​

Need Help?​