Skip to main content

Data Types

ekoDB supports 16 comprehensive data types with flexible type enforcement per collection and per field.

Type Enforcement​

  • Write-time validation: Types are checked when data is inserted or updated
  • Optional at key-value level: Key-value operations can be schema-less
  • Required at document level: Collections can enforce schemas
  • Dynamic inference: Types are automatically detected if not specified
  • Explicit specification: Define schemas via /api/collections/{collection} endpoint

Basic Types​

String​

UTF-8 encoded text data for names, descriptions, and general content.

{
  "name": "Alice",
  "email": "alice@example.com",
  "description": "Software engineer"
}

Use Cases: Names, emails, descriptions, URLs, JSON strings

Integer​

64-bit signed integers for whole numbers.

Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

{
  "age": 30,
  "count": 1000,
  "year": 2024
}

Use Cases: Counters, ages, quantities, IDs

Float​

64-bit IEEE 754 floating-point numbers for decimal values.

{
  "price": 29.99,
  "temperature": 98.6,
  "percentage": 0.85
}

Use Cases: Prices, measurements, percentages, scientific data

⚠️ Note: Floats have precision limitations. For financial calculations, use Decimal instead.

Boolean​

Binary true/false values for logical operations.

{
  "isActive": true,
  "hasAccess": false,
  "verified": true
}

Use Cases: Flags, toggles, status indicators

Advanced Numeric Types​

Number​

Flexible numeric type that automatically handles both integers and floats.

{
  "value": 42,        // Stored as integer
  "value": 42.5       // Stored as float
}

Use Cases: When you don't know if a value will be an integer or float

Benefits:

  • Automatic type detection
  • Seamless conversion
  • Flexible queries

Decimal​

Arbitrary-precision decimal numbers that avoid floating-point rounding errors.

{
  "balance": "1234.56",
  "price": "0.10",
  "total": "999999.99"
}

Use Cases:

  • Financial calculations (currency, accounting)
  • Scientific computations requiring exact precision
  • Any scenario where 0.1 + 0.2 must equal exactly 0.3

Why Decimal?

  • No binary floating-point approximation
  • Exact decimal representation
  • Stores as mantissa + scale

Temporal Types​

DateTime​

RFC 3339 formatted date-time values with timezone support.

{
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-12-31T23:59:59+00:00",
  "scheduledFor": "2025-06-15T14:30:00-05:00"
}

Format: ISO 8601 / RFC 3339
Timezone: Always include timezone (Z for UTC or offset)

Use Cases: Timestamps, scheduling, time-series data

Duration​

Time duration values for representing time spans.

{
  "timeout": "30s",
  "interval": "5m",
  "ttl": "2h",
  "expiry": "7d"
}

Supported Units:

  • s - seconds
  • m - minutes
  • h - hours
  • d - days

Use Cases: TTL, timeouts, intervals, expiration

Collection Types​

Array​

Ordered lists of heterogeneous elements, preserving insertion order.

{
  "tags": ["rust", "database", "nosql"],
  "scores": [95, 87, 92, 88],
  "mixed": ["text", 42, true, null]
}

Features:

  • Maintains order
  • Allows duplicates
  • Can contain different types
  • Supports nested arrays

Use Cases: Tags, lists, ordered data, multi-value fields

Set​

Unordered collections of unique values with automatic deduplication.

{
  "uniqueTags": ["rust", "database", "nosql"],
  "permissions": ["read", "write", "delete"]
}

Features:

  • Automatic deduplication
  • No guaranteed order
  • Fast membership testing
  • Unique values only

Use Cases: Unique tags, permissions, categories

Vector​

Fixed-dimension numeric arrays optimized for embeddings and vector similarity search.

{
  "embedding": [0.1, 0.2, 0.3, 0.4, ...],  // 384-dimensional
  "features": [1.5, 2.3, 0.8, 4.1]
}

Features:

  • Optimized for similarity search
  • HNSW indexing support
  • Cosine, Euclidean, Dot Product metrics
  • Fixed dimensions per field

Use Cases:

  • AI/ML embeddings
  • Semantic search
  • Recommendation systems
  • Image/text similarity

Object​

Nested documents/maps with key-value pairs for complex structured data.

{
  "address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102"
  },
  "metadata": {
    "source": "api",
    "version": "1.0"
  }
}

Features:

  • Nested structure
  • Flexible schema
  • Supports all types as values
  • Can be deeply nested

Use Cases: Nested data, complex structures, JSON documents

Specialized Types​

UUID​

Universally unique identifiers (RFC 4122) for globally unique record identification.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

Format: 8-4-4-4-12 hexadecimal digits

Use Cases: Unique identifiers, correlation IDs, distributed systems

Binary​

Base64-encoded binary data for images, files, and other binary content.

{
  "image": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
  "file": "SGVsbG8gV29ybGQh"
}

Encoding: Base64
Storage: Efficient binary storage

Use Cases: Images, files, encrypted data, binary blobs

Bytes​

Raw byte arrays (Vec<u8>) for unencoded binary data storage.

{
  "rawData": [0x48, 0x65, 0x6c, 0x6c, 0x6f]
}

Format: Array of byte values (0-255)

Use Cases: Raw binary data, protocol buffers, custom encodings

Null​

Explicit null/empty values for optional fields.

{
  "middleName": null,
  "deletedAt": null,
  "optionalField": null
}

Use Cases: Optional fields, missing data, explicit absence

Response Formats​

ekoDB supports two response formats:

Typed Responses (Default)​

Includes type metadata for strong typing:

{
  "name": {
    "type": "String",
    "value": "Alice"
  },
  "age": {
    "type": "Integer",
    "value": 30
  }
}

Benefits:

  • Type safety
  • Explicit type information
  • Better for strongly-typed languages

Non-Typed Responses​

Traditional NoSQL format:

{
  "name": "Alice",
  "age": 30
}

Benefits:

  • Simpler JSON
  • Smaller payload size
  • Familiar format

Configuration: Set via /api/config endpoint or ekoDB App

Type Conversion​

ekoDB automatically handles type conversions where safe:

Number Type Flexibility​

// Number can match Integer or Float
{ "value": 42 }      // Integer
{ "value": 42.5 }    // Float

Automatic Coercion​

  • String to Number (if valid)
  • Integer to Float (always safe)
  • Number to Integer/Float (automatic)

Schema Definition​

Define schemas to enforce types when creating a collection:

POST /api/collections/users
Content-Type: application/json
Authorization: Bearer {ADMIN_TOKEN}

{
  "fields": {
    "name": { "type": "String", "required": true },
    "age": { "type": "Number", "min": 0, "max": 150 },
    "email": { "type": "String", "unique": true },
    "balance": { "type": "Decimal" },
    "tags": { "type": "Array" },
    "metadata": { "type": "Object" }
  }
}

Note: See Collections & Schemas for complete schema management documentation.

Best Practices​

✅ Do​

  • Use Decimal for financial data
  • Use DateTime with timezones
  • Use Vector for embeddings
  • Use Set for unique collections
  • Define schemas for production collections

❌ Don't​

  • Use Float for money (use Decimal)
  • Store dates as strings (use DateTime)
  • Use Array when you need uniqueness (use Set)
  • Mix types inconsistently

Next Steps​

Questions? Contact support@ekodb.io