Basic Operations

Manage individual records using ekoDB's REST API. All operations support JSON payloads and return structured responses.

Configuration

Update ekoDB instance configuration via the REST API.

PUT https://{EKODB_API_URL}/api/config
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "use_typed_values": true
}

# Response
{
  "status": "success",
  "use_typed_values": true
}

Configuration Options:

use_typed_values (boolean) - Enable typed field values (default: true)

Insert Record

Create a new record in a collection.

POST https://{EKODB_API_URL}/api/insert/{collection}
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

# Response
{
  "id": "record_id_123"
}

Get Full Record After Insert

The insert operation returns only the record ID. To retrieve the full record with all fields, use a GET request with the returned ID.

Disable Real-Time Sync:

Use bypass_ripple=true to skip real-time synchronization for bulk imports or background jobs:

POST https://{EKODB_API_URL}/api/insert/{collection}?bypass_ripple=true
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "name": "Bulk Import User",
  "email": "bulk@example.com"
}

Get Record by ID

Retrieve a specific record by its ID.

GET https://{EKODB_API_URL}/api/find/{collection}/{record_id}
Authorization: Bearer {YOUR_TOKEN}

# Response
{
  "id": "record_id_123",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "created_at": "2024-01-15T10:30:00Z"
}

Alternative POST Method:

POST https://{EKODB_API_URL}/api/find/{collection}/{record_id}
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

# Same response as GET

Query Records

Query records with filters, sorting, and pagination.

POST https://{EKODB_API_URL}/api/find/{collection}
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "filter": {
    "type": "expression",
    "content": {
      "field": "age",
      "operator": "GreaterThan",
      "value": 25
    }
  },
  "sort": {
    "field": "created_at",
    "order": "desc"
  },
  "limit": 10,
  "offset": 0
}

# Response
{
  "records": [
    {
      "id": "record_1",
      "name": "John Doe",
      "age": 30
    },
    {
      "id": "record_2",
      "name": "Jane Smith",
      "age": 28
    }
  ],
  "total": 2
}

Query Operators:

Equals - Exact match
NotEquals - Not equal to
GreaterThan - Greater than
LessThan - Less than
GreaterThanOrEqual - Greater than or equal
LessThanOrEqual - Less than or equal
Contains - String contains (case-insensitive)
StartsWith - String starts with
EndsWith - String ends with

Combine Filters with AND:

{
  "filter": {
    "type": "and",
    "content": [
      {
        "type": "expression",
        "content": {
          "field": "age",
          "operator": "GreaterThan",
          "value": 25
        }
      },
      {
        "type": "expression",
        "content": {
          "field": "status",
          "operator": "Equals",
          "value": "active"
        }
      }
    ]
  }
}

Combine Filters with OR:

{
  "filter": {
    "type": "or",
    "content": [
      {
        "type": "expression",
        "content": {
          "field": "role",
          "operator": "Equals",
          "value": "admin"
        }
      },
      {
        "type": "expression",
        "content": {
          "field": "role",
          "operator": "Equals",
          "value": "moderator"
        }
      }
    ]
  }
}

Complex Nested Filters:

Find active users who are either admins OR (have age > 25 AND verified):

{
  "filter": {
    "type": "and",
    "content": [
      {
        "type": "expression",
        "content": {
          "field": "status",
          "operator": "Equals",
          "value": "active"
        }
      },
      {
        "type": "or",
        "content": [
          {
            "type": "expression",
            "content": {
              "field": "role",
              "operator": "Equals",
              "value": "admin"
            }
          },
          {
            "type": "and",
            "content": [
              {
                "type": "expression",
                "content": {
                  "field": "age",
                  "operator": "GreaterThan",
                  "value": 25
                }
              },
              {
                "type": "expression",
                "content": {
                  "field": "verified",
                  "operator": "Equals",
                  "value": true
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Advanced Queries

For complex queries with nested filters and advanced operations, see the Advanced Operations documentation.

Update Record

Update an existing record by ID.

PUT https://{EKODB_API_URL}/api/update/{collection}/{record_id}
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "status": "active",
  "updated_at": "2024-01-15T11:00:00Z"
}

# Response
{
  "id": "record_id_123",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "status": "active",
  "updated_at": "2024-01-15T11:00:00Z"
}

Partial Updates:

Only the fields provided in the request body are updated. Existing fields remain unchanged.

Disable Real-Time Sync:

PUT https://{EKODB_API_URL}/api/update/{collection}/{record_id}?bypass_ripple=true
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "status": "processed"
}

Search Records

Full-text and semantic search across records.

POST https://{EKODB_API_URL}/api/search/{collection}
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "query": "software engineer",
  "limit": 10,
  "offset": 0
}

# Response
{
  "results": [
    {
      "record": {
        "id": "record_1",
        "name": "John Doe",
        "title": "Senior Software Engineer"
      },
      "score": 0.95
    }
  ],
  "total": 1
}

Search with Vector Similarity:

POST https://{EKODB_API_URL}/api/search/{collection}
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "query": "machine learning",
  "vector_field": "embedding",
  "limit": 5,
  "similarity_threshold": 0.8
}

GET Alternative:

GET https://{EKODB_API_URL}/api/search/{collection}?query=software%20engineer&limit=10
Authorization: Bearer {YOUR_TOKEN}

Delete Record

Delete a record by ID (moves to trash for 30 days before permanent deletion).

DELETE https://{EKODB_API_URL}/api/delete/{collection}/{record_id}
Authorization: Bearer {YOUR_TOKEN}

# Response
{
  "id": "record_id_123",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

Deleted Record Returned

The delete operation returns the full deleted record, useful for undo operations or audit logs.

Disable Real-Time Sync:

DELETE https://{EKODB_API_URL}/api/delete/{collection}/{record_id}?bypass_ripple=true
Authorization: Bearer {YOUR_TOKEN}

Collection-Level Operations

Delete Entire Collection

Delete all records in a collection permanently.

Admin Permission Required

Collection-level operations require admin permissions and cannot be undone.

DELETE https://{EKODB_API_URL}/api/collections/{collection}
Authorization: Bearer {ADMIN_TOKEN}

# Response
{
  "status": "deleted",
  "collection": "users",
  "records_deleted": 1234
}

Restore Record from Trash

Restore a previously deleted record from trash.

POST https://{EKODB_API_URL}/api/trash/{collection}/{record_id}
Authorization: Bearer {ADMIN_TOKEN}

# Response
{
  "status": "restored",
  "id": "record_id_123",
  "collection": "users"
}

Restore Collection from Trash

Restore all deleted records in a collection from trash.

POST https://{EKODB_API_URL}/api/trash/{collection}
Authorization: Bearer {ADMIN_TOKEN}

# Response
{
  "status": "restored",
  "collection": "users",
  "records_restored": 42
}

Using Operations Within Transactions

All write operations (insert, update, delete) can be performed within a transaction by adding the transaction_id query parameter. Operations are tracked and can be committed or rolled back together.

Insert Within Transaction:

POST https://{EKODB_API_URL}/api/insert/users?transaction_id=tx-001
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "name": "John Doe",
  "email": "john@example.com"
}

Update Within Transaction:

PUT https://{EKODB_API_URL}/api/update/users/user_123?transaction_id=tx-001
Content-Type: application/json
Authorization: Bearer {YOUR_TOKEN}

{
  "status": "active"
}

Delete Within Transaction:

DELETE https://{EKODB_API_URL}/api/delete/users/user_123?transaction_id=tx-001
Authorization: Bearer {YOUR_TOKEN}

Complete Transaction Example:

# 1. Begin transaction
tx_id=$(curl -s -X POST https://{EKODB_API_URL}/api/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -d '{"isolation_level": "Serializable"}' | jq -r '.transaction_id')

# 2. Insert record in transaction
curl -X POST https://{EKODB_API_URL}/api/insert/users?transaction_id=$tx_id \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -d '{"name": "Jane Doe", "email": "jane@example.com"}'

# 3. Update record in transaction
curl -X PUT https://{EKODB_API_URL}/api/update/users/user_456?transaction_id=$tx_id \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -d '{"status": "verified"}'

# 4. Commit transaction (or rollback if needed)
curl -X POST https://{EKODB_API_URL}/api/transactions/$tx_id/commit \
  -H "Authorization: Bearer {YOUR_TOKEN}"

Transaction Support

For full transaction management including savepoints and rollback capabilities, see the Transactions documentation.

Complete Example

Here's a complete workflow for creating and managing a user:

# 1. Insert user
curl -X POST https://{EKODB_API_URL}/api/insert/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30,
    "status": "pending"
  }'
# Response: {"id": "user_123", ...}

# 2. Get user by ID
curl -X GET https://{EKODB_API_URL}/api/find/users/user_123 \
  -H "Authorization: Bearer {YOUR_TOKEN}"

# 3. Update user status
curl -X PUT https://{EKODB_API_URL}/api/update/users/user_123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -d '{
    "status": "active",
    "activated_at": "2024-01-15T11:00:00Z"
  }'

# 4. Query active users
curl -X POST https://{EKODB_API_URL}/api/find/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -d '{
    "filter": {
      "type": "expression",
      "content": {
        "field": "status",
        "operator": "Equals",
        "value": "active"
      }
    },
    "limit": 10
  }'

# 5. Search users
curl -X POST https://{EKODB_API_URL}/api/search/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -d '{
    "query": "john",
    "limit": 5
  }'

# 6. Delete user
curl -X DELETE https://{EKODB_API_URL}/api/delete/users/user_123 \
  -H "Authorization: Bearer {YOUR_TOKEN}"

Best Practices

Use Appropriate HTTP Methods

# Create - POST
POST /api/insert/{collection}

# Read - GET
GET /api/find/{collection}/{id}

# Update - PUT
PUT /api/update/{collection}/{id}

# Delete - DELETE
DELETE /api/delete/{collection}/{id}

Handle Errors Gracefully

# Check status code
response=$(curl -s -w "\n%{http_code}" -X GET .../api/find/users/user_123)
status_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

if [ "$status_code" != "200" ]; then
  echo "Error: $body"
fi

Use Filters for Efficient Queries

# Good: Filter on indexed fields
POST /api/find/users
{"filter": {"field": "status", "operator": "Equals", "value": "active"}}

# Good: Limit results
POST /api/find/users
{"filter": {...}, "limit": 100}

# Avoid: Fetching all records without filter
POST /api/find/users
{"limit": 10000}  # Use pagination instead

Pagination for Large Result Sets

# Page 1
POST /api/find/users
{"limit": 100, "offset": 0}

# Page 2
POST /api/find/users
{"limit": 100, "offset": 100}

# Page 3
POST /api/find/users
{"limit": 100, "offset": 200}

Batch Operations - Bulk operations for multiple records
Transactions - ACID transactions for atomicity
Client Libraries - Language-specific client libraries
Authentication - API key and JWT authentication

Configuration​

Insert Record​

Get Record by ID​

Query Records​

Update Record​

Search Records​

Delete Record​

Collection-Level Operations​

Delete Entire Collection​

Restore Record from Trash​

Restore Collection from Trash​

Using Operations Within Transactions​

Complete Example​

Best Practices​

Use Appropriate HTTP Methods​

Handle Errors Gracefully​

Use Filters for Efficient Queries​

Pagination for Large Result Sets​

Related Documentation​

Configuration

Insert Record

Get Record by ID

Query Records

Update Record

Search Records

Delete Record

Collection-Level Operations

Delete Entire Collection

Restore Record from Trash

Restore Collection from Trash

Using Operations Within Transactions

Complete Example

Best Practices

Use Appropriate HTTP Methods

Handle Errors Gracefully

Use Filters for Efficient Queries

Pagination for Large Result Sets

Related Documentation