Basic Operations

Configuration

You can configure your ekoDB instance via the /api/config endpoint. This endpoint supports PUT requests and allows you to update the configuration of use_typed_values and soon more configurations.

HTTP
JavaScript
Python

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

{
  "use_typed_values": true, // true by default
}

const response = await fetch(
  'https://{EKODB_API_URL}/api/config', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {YOUR_TOKEN}'
  },
  body: JSON.stringify({
    use_typed_values: true, // true by default
  })
});

import requests

response = requests.put(
    'https://{EKODB_API_URL}/api/config',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer {YOUR_TOKEN}'
    },
    json={
        'use_typed_values': True  # true by default
    }
)

Typed Values

By default, ekoDB returns values as typed values: {"value_name": {"type": "string", "value": "value"}}.

Example of typed values:

{
  "name": {"type": "String", "value": "John Doe"},
  "age": {"type": "Integer", "value": 30},
  "email": {"type": "String", "value": "john@example.com"},
  "phone": {"type": "String", "value": "012-123-4567"},
  "address": {
    "street_number": {"type": "Integer", "value": 123},
    "street": {"type": "String", "value": "Main St"},
    "city": {"type": "String", "value": "City"},
    "state": {"type": "String", "value": "State"},
    "zip": {"type": "Integer", "value": 12345},
    "longitude": {"type": "Float", "value": -122.4194},
    "latitude": {"type": "Float", "value": 47.6062}
  },
  "is_active": {"type": "Boolean", "value": true},
  "keywords": {"type": "Array", "value": ["keyword1", "keyword2"]},
  "created_at": {"type": "DateTime", "value": "2023-01-01T00:00:00Z"}
}

You can disable typed values in the configuration to have ekoDB return values as the key-value pairing.

Note: Typed values are enabled by default but the rest of this documentation will assume that you are using non-typed values for simplicity sake.

Example of non-typed values:

{
  "name": "John Doe",
  "age": 30,
  "email": "john@example.com",
  "phone": "012-123-4567",
  "address": {
    "street_number": 123,
    "street": "Main St",
    "city": "City",
    "state": "State",
    "zip": 12345,
    "longitude": -122.4194,
    "latitude": 47.6062
  },
  "is_active": true,
  "keywords": ["keyword1", "keyword2"],
  "created_at": "2023-01-01T00:00:00Z"
}

Available Typed Values:

"String"
"Integer"
"Float"
"Number" (alias for Integer and Float, use Integer or Float for better performance)
"Boolean"
"Object"
"Array"
"Binary"
"Bytes"
"DateTime" (RFC3339 string)
"Null"

Records or key-value pairs

Storing data using as records or key-value pairs is similar to using any NoSQL database or key-value store. Collections of records or documents are similar to tables with rows like a SQL database. Every insert returns a generated id that you can use to fetch, update, or delete the record or document. If you would rather use in-memory key-value pairs, you can use the key-value pairs endpoint instead, where you can leverage your own keys to store and retrieve data. You can also link records or documents to each other using relationships via storing the id of the other record or document in the current record or document. You can also link records or documents to key-value pairs and commit the changes to the database.

Insert Record

Insert a single record into a collection:

HTTP
JavaScript
Python

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

{
  "name": "John Doe", // String
  "age": 30, // Integer
  "email": "john@example.com", // String
  "phone": "012-123-4567", // String
  "address": {
    "street_number": 123, // Integer
    "street": "Main St", // String
    "city": "City", // String
    "state": "State", // String
    "zip": 12345, // Integer
    "longitude": -122.4194, // Float
    "latitude": 47.6062 // Float
  }, // Object
  "is_active": true, // Boolean
  "keywords": ["keyword1", "keyword2"], // Array
  "created_at": "2023-01-01T00:00:00Z" // DateTime RFC3339
}

# Response
{
  "id": "{ID}"
}

const response = await fetch(
'https://{EKODB_API_URL}/api/insert/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {YOUR_TOKEN}'
  },
  body: JSON.stringify({
    name: 'John Doe',
    age: 30,
    email: 'john@example.com',
    phone: '012-123-4567',
    address: {
      street_number: 123,
      street: 'Main St',
      city: 'City',
      state: 'State',
      zip: 12345,
      longitude: -122.4194,
      latitude: 47.6062
    },
    is_active: true,
    keywords: ['keyword1', 'keyword2'],
    created_at: '2023-01-01T00:00:00Z'
  })
});

const data = await response.json();
const id = data.id;

import requests

response = requests.post(
    'https://{EKODB_API_URL}/api/insert/users',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer {YOUR_TOKEN}'
    },
    json={
        'name': 'John Doe',
        'age': 30,
        'email': 'john@example.com',
        'phone': '012-123-4567',
        'address': {
            'street_number': 123,
            'street': 'Main St',
            'city': 'City',
            'state': 'State',
            'zip': 12345,
            'longitude': -122.4194,
            'latitude': 47.6062
        },
        'is_active': True,
        'keywords': ['keyword1', 'keyword2'],
        'created_at': '2023-01-01T00:00:00Z'
    }
)

id = response.json()['id']

Read Record

Retrieve a record by its ID:

HTTP
JavaScript
Python

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

# Response
{
  "id": "{ID}",
  "name": "John Doe",
  "age": 30,
  "email": "john@example.com",
  "phone": "012-123-4567",
  "address": {
    "street_number": 123,
    "street": "Main St",
    "city": "City",
    "state": "State",
    "zip": 12345,
    "longitude": -122.4194,
    "latitude": 47.6062
  },
  "is_active": true,
  "keywords": ["keyword1", "keyword2"],
  "created_at": "2023-01-01T00:00:00Z"
}

const response = await fetch(
  'https://{EKODB_API_URL}/api/find/users/123', {
  headers: { 'Authorization': 'Bearer {YOUR_TOKEN}' }
});

const data = await response.json();
const id = data.id;
const name = data.name;
const age = data.age;
const email = data.email;
const address = data.address;
const is_active = data.is_active;
const keywords = data.keywords;
const created_at = data.created_at;

import requests

response = requests.get(
    'https://{EKODB_API_URL}/api/find/users/123',
    headers={'Authorization': 'Bearer {YOUR_TOKEN}'}
)

data = response.json()
id = data['id']
name = data['name']
age = data['age']
email = data['email']
address = data['address']
is_active = data['is_active']
keywords = data['keywords']
created_at = data['created_at']

Query Records

Retrieve multiple records by query:

HTTP
JavaScript
Python

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

{
  "filter": {
    // Condition
    "type": "Condition",
    "content": {
      "field":    "phone",
      "operator": "Eq",
      "value":    "012-123-4567"
    }

    // Logical Or
    "type": "Logical",
    "content": {
      "operator": "Or",
      "expressions": [
        {
          "type": "Condition",
          "content": {
            "field":    "phone",
            "operator": "Eq",
            "value":    "012-123-4567"
          }
        },
        {
          "type": "Condition",
          "content": {
            "field":    "email",
            "operator": "Eq",
            "value":    "john@example.com"
          }
        }
      ]
    }
    
    // Logical And
    "type": "Logical",
    "content": {
      "operator": "And",
      "expressions": [
        {
          "type": "Condition",
          "content": {
            "field":    "phone.value",
            "operator": "Eq",
            "value":    "012-123-4567"
          }
        },
        {
          "type": "Condition",
          "content": {
            "field":    "email",
            "operator": "Eq",
            "value":    "john@example.com"
          }
        }
      ]
    }

    // List of operators
    // Eq, Ne, Gt, Lt, Gte, Lte, In, NotIn, Contains, StartsWith, EndsWith
  }
  sort: { createdAt: "desc" || "asc" }, // Sort by createdAt in descending or ascending order
  limit: 10, // Number of records to return
  skip: 0 // Number of records to skip
}

# Response
[
  {
    "id": "xyz123abc",
    "name": "John Doe",
    "age": 30,
    "email": "john@example.com",
    "phone": "012-123-4567",
    "address": {
      "street_number": 123,
      "street": "Main St",
      "city": "City",
      "state": "State",
      "zip": 12345,
      "longitude": -122.4194,
      "latitude": 47.6062
    },
    "is_active": true,
    "keywords": ["keyword1", "keyword2"],
    "created_at": "2023-01-01T00:00:00Z"
  },
  // ...more
]

const response = await fetch('https://{EKODB_API_URL}/api/find/users', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer {YOUR_TOKEN}' },
  body: JSON.stringify({
    "filter": {
        // Condition
        "type": "Condition",
        "content": {
            "field":    "phone.value",
            "operator": "Eq",
            "value":    "012-123-4567"
        }
    },
    // Logical Or
    "type": "Logical",
    "content": {
        "operator": "Or",
        "expressions": [
                {
                    "type": "Condition",
                    "content": {
                        "field":    "phone.value",
                        "operator": "Eq",
                        "value":    "012-123-4567"
                    }
                }
            ]
        }
    },
    // Logical And
    "type": "Logical",
    "content": {
        "operator": "And",
        "expressions": [
                {
                    "type": "Condition",
                    "content": {
                        "field":    "phone.value",
                        "operator": "Eq",
                        "value":    "012-123-4567"
                    }
                }
            ]
        }

        // List of operators
        // Eq, Ne, Gt, Lt, Gte, Lte, In, NotIn, Contains, StartsWith, EndsWith
    },
    "sort": { "createdAt": "desc" || "asc" }, // Sort by createdAt in descending or ascending order
    "limit": 10, // Number of records to return
    "skip": 0 // Number of records to skip
  })
});

const records = await response.json();
// Access individual records like this:
const firstRecord = records[0];
const id = firstRecord.id;
const name = firstRecord.name;
const age = firstRecord.age;
// ... and so on for other properties

import requests

response = requests.post(
    'https://{EKODB_API_URL}/api/find/users/123',
    headers={
        'Authorization': 'Bearer {YOUR_TOKEN}'
    },
    json={
        'filter': {
            # Condition
            'type': 'Condition',
            'content': {
                'field': 'id',
                'operator': 'Eq',
                'value': '123'
            },

            # Logical Or
            'type': 'Logical',
            'content': {
                'operator': 'Or',
                'expressions': [
                    {
                        'type': 'Condition',
                        'content': {
                            'field': 'id',
                            'operator': 'Eq',
                            'value': '123'
                        }
                    }
                ]
            },
            # List of operators
            # Eq, Ne, Gt, Lt, Gte, Lte, In, NotIn, Contains, StartsWith, EndsWith
        },
        'sort': { 'createdAt': 'desc' || 'asc' },
        'limit': 10,
        'skip': 0
    }
)

# Response array of objects
[
  {
    id,
    name,
    age,
    email,
    phone,
    address,
    is_active,
    keywords,
    created_at
  },
  # ...more
] = response.json()

Update Record

Update an existing record by its ID:

HTTP
JavaScript
Python

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

{
  "name": "Jane Doe",
  "age": 31
}

# Response
{
  "id": "{ID}"
}

const response = await fetch('https://{EKODB_API_URL}/api/update/users/123', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {YOUR_TOKEN}'
  },
  body: JSON.stringify({
    name: 'Jane Doe',
    age: 31
  })
});

const {
  id
} = await response.json();

import requests

response = requests.put(
    'https://{EKODB_API_URL}/api/update/users/123',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer {YOUR_TOKEN}'
    },
    json={
        'name': 'Jane Doe',
        'age': 31
    }
)

id = response.json()['id']

Search Records

Search for records by search query options:

HTTP
JavaScript
Python

# Search supports both POST and GET
# - GET calls should be on the query parameters with the same data as POST
# - POST calls should be on the body with the same data as GET

# GET - Note: see body below for an explanation of each parameter
GET https://{EKODB_API_URL}/api/search/{collection}?query=search&language=english&case_sensitive=false&fuzzy=true&min_score=0.5&fields=source&weights=field_name:0-1&stemming=true&boost_exact=true&max_edit_distance=0&bypass_ripple=true
Authorization: Bearer {YOUR_TOKEN}

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

{
    "query": "your desired query",
    "language": "english || arabic || danish || dutch || finnish || french || german || greek || hungarian || italian || norwegian || portuguese || romanian || russian || spanish || swedish || tamil || turkish",
    "case_sensitive": false,
    "fuzzy": true,
    "min_score": 0.5,
    "fields": "field1,field2,field3",
    "weights": "field1:0-1,field2:0-1,field3:0-1", // as a float between 0 and 1
    "stemming": true, // enable stemming - stemming is the process of reducing words to their base form (e.g. "running" -> "run")
    "boost_exact": true, // boost exact matches
    "max_edit_distance": 0, // maximum edit distance - maximum edit distance is the maximum number of edits (insertions, deletions, or substitutions) allowed between the query and the document
    "bypass_ripple": true // bypass ripple - ripple is how you can pass data between nodes (e.g. from one node to another or to bypass nodes)
}

# Response
{
    "results": [
        {
            "id": "123",
            "name": "John Doe",
            "age": 30
        }
    ],
    "total": 1,
    "execution_time_ms": 0
}

const response = await fetch('https://{EKODB_API_URL}/api/search/{collection}', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {YOUR_TOKEN}'
  },
  body: JSON.stringify({
    query: 'search query', // your desired query
    language: 'english', // language of the query
    case_sensitive: false, // case sensitive
    fuzzy: true, // fuzzy matching
    min_score: 0.5, // minimum score 0-1 (0 is the lowest score and 1 is the highest as a float)
    fields: 'field1,field2,field3', // fields to search
    weights: 'field1:0-1,field2:0-1,field3:0-1', // weights for each field
    stemming: true, // enable stemming - stemming is the process of reducing words to their base form (e.g. "running" -> "run")
    boost_exact: true, // boost exact matches
    max_edit_distance: 0, // maximum edit distance 0-1 (0 is the lowest edit distance and 1 is the highest as a float) - maximum edit distance is the maximum number of edits (insertions, deletions, or substitutions) allowed between the query and the document
    bypass_ripple: true // bypass ripple - ripple is how you can pass data between nodes (e.g. from one node to another or to bypass nodes)
  })
});

const {
  results: [
    {
      id: '123',
      name: 'John Doe',
      age: 30
    }
  ],
  total: 1,
  execution_time_ms: 0
} = await response.json();

import requests

response = requests.post(
    'https://{EKODB_API_URL}/api/search/{collection}',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer {YOUR_TOKEN}'
    },
    json={
        'query': 'search query',  # your desired query
        'language': 'english',  # language of the query
        'case_sensitive': False,  # case sensitive
        'fuzzy': True,  # fuzzy matching
        'min_score': 0.5,  # minimum score 0-1
        'fields': 'field1,field2,field3',  # fields to search
        'weights': 'field1:0-1,field2:0-1,field3:0-1',  # weights for each field
        'stemming': True,  # enable stemming
        'boost_exact': True,  # boost exact matches
        'max_edit_distance': 0,  # maximum edit distance
        'bypass_ripple': True  # bypass ripple
    }
)

data = response.json()
results = data['results']
first_result = results[0]  # {'id': '123', 'name': 'John Doe', 'age': 30}
total = data['total']  # 1
execution_time = data['execution_time_ms']  # 0

Delete Record

Delete a record by its ID:

HTTP
JavaScript
Python

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

const response = await fetch('https://{EKODB_API_URL}/api/delete/users/123', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer {YOUR_TOKEN}' }
});

const {
  id,
} = await response.json();

import requests

response = requests.delete(
    'https://{EKODB_API_URL}/api/delete/users/123',
    headers={'Authorization': 'Bearer {YOUR_TOKEN}'}
)

id = response.json()['id']

Configuration​

Typed Values​

Records or key-value pairs​

Insert Record​

Read Record​

Query Records​

Update Record​

Search Records​

Delete Record​