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

How a Field Gets Its Type​

  • The first write pins the type. When a collection's schema has no type for a field yet, the first value written to it sets one, inferred from that value (or taken from the schema you created the collection with). From then on a value of another type is refused, for example Type mismatch for field 'qty': expected Integer, got Float.
  • Accepted conversions. An Integer is accepted into a Float field, and an Integer or Float into a Decimal or Number field. A field declared DateTime, UUID or Decimal also accepts a string in that format. Every other mismatch is refused, including a Float into an Integer field.
  • null is accepted for a field of any type. A field whose first value is null is typed Null, and a Null field accepts values of any type afterwards. To keep a field's type enforced, declare it when you create the collection, or leave the field out of a record until it has a value.
  • Object takes any JSON object, with any nesting, including arrays and arrays of objects inside it. Array takes any JSON array, including an array of objects. A top-level array written to an Object field is refused, because it is an Array: give a list its own Array field, or put it under a key of the object.
  • An object shaped like a typed value is read as one. An object whose keys are type and value (optionally with schema keys such as required or unique) and whose type is an ekoDB type name ("String", "Integer", "DateTime", ...) is taken as that typed value, not stored as an object. If your own data has that shape, name the keys differently (kind and amount, for example).

Runnable examples: client_schema.ts (declaring field types) and client_simple_crud.ts (insert, read, update and delete).

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


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

Precision Limitation

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


Producing a non-inferable type on write

ekoDB infers a field's type from the raw JSON you send: true/false → Boolean, a JSON string → String, a whole number → Integer, a fractional number → Float, an array → Array, an object → Object. The types below in Advanced Numeric, Temporal, and (for Set/Vector) Collection are not inferred from a raw value — a raw RFC 3339 string is stored as a String, a raw array as an Array, and so on. To store one of these, send the typed wrapper { "type": "<TypeName>", "value": <value> }.

One exception, via schema coercion: if the collection's schema declares a field as Number or Decimal, a raw numeric value is upgraded to that type. There is no string→DateTime/UUID/Decimal or array→Set/Vector coercion.

Advanced Numeric Types​

Number​

Flexible numeric type that holds either an integer or a float. A raw number is inferred as Integer or Float, so request Number explicitly with the { "type": "Number", "value": … } wrapper (or declare the field as Number in the schema, which coerces a raw number to Number):

{
"metric": { "type": "Number", "value": 42 }, // Number holding an integer
"average": { "type": "Number", "value": 42.5 } // Number holding a 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. The wrapper's value is a string (to preserve precision); a raw string is stored as String, so use the wrapper (or declare the field as Decimal in the schema, which coerces a raw numeric value to Decimal):

{
"balance": { "type": "Decimal", "value": "1234.56" },
"price": { "type": "Decimal", "value": "0.10" },
"total": { "type": "Decimal", "value": "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
  • Precision-preserving internal storage
Totals in functions

A function's Group step returns exact Min and Max for Decimal fields. To total or average money in a Group step (Sum, Average), store the amount as an Integer number of minor units (cents, for example) and divide for display.


Temporal Types​

DateTime​

RFC 3339 formatted date-time values with timezone support. A raw RFC 3339 string is stored as a String; to store a true DateTime (which enables date math and range semantics), use the wrapper with an RFC 3339 string value:

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

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

Store dates as DateTime and read them, and any string field that may hold a timestamp, through your client library's value helpers (for example getValue and extractRecord in TypeScript), which return the value itself. Do not branch on a response's type tag to tell a date-like string from a date.

Use Cases: Timestamps, scheduling, time-series data


Duration​

Time-span values. The Duration wrapper's value is an integer number of milliseconds (a raw string like "30s" is stored as a String, not a Duration):

{
"timeout": { "type": "Duration", "value": 30000 }, // 30 seconds
"interval": { "type": "Duration", "value": 300000 }, // 5 minutes
"ttl": { "type": "Duration", "value": 7200000 } // 2 hours
}
Human-readable durations are a separate feature

The shorthand forms "30s", "5m", "1h", "7d" are accepted by the key-value store's ttl field, which has its own duration parser — they are not the Duration field type, whose wrapper takes milliseconds.

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. A raw array is stored as an Array, so use the wrapper to get a Set:

{
"uniqueTags": { "type": "Set", "value": ["rust", "database", "nosql"] },
"permissions": { "type": "Set", "value": ["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. A raw array is stored as an Array, so use the wrapper to get a Vector:

{
"embedding": { "type": "Vector", "value": [0.1, 0.2, 0.3, 0.4] },
"features": { "type": "Vector", "value": [1.5, 2.3, 0.8, 4.1] }
}

Features:

  • Optimized for similarity search
  • High-performance indexing for fast similarity search
  • Cosine, Euclidean, Dot Product metrics
  • Fixed dimension per field when the field has a vector index (see Vector Search)

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. A raw string is stored as a String, so use the wrapper to get a UUID:

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

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

Use Cases: Unique identifiers, correlation IDs, distributed systems


Binary​

Binary data for images, files, and other binary content. A raw string is stored as a String; use the wrapper with a base64-encoded string value to get Binary:

{
"image": { "type": "Binary", "value": "iVBORw0KGgoAAAANSUhEUgAAAAUA..." },
"file": { "type": "Binary", "value": "SGVsbG8gV29ybGQh" }
}

Encoding: base64 string on write (the wrapper also accepts a [0-255] byte array); reads return a byte array
Storage: Efficient binary storage

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


Bytes​

Raw byte arrays for unencoded binary data storage. A raw array is stored as an Array, so use the wrapper with a [0-255] byte-value array to get Bytes:

{
"rawData": { "type": "Bytes", "value": [72, 101, 108, 108, 111] } // "Hello"
}

Format: Array of decimal 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


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​

  • Integer to Float (always safe, within f64's exact-integer range)
  • Integer to Decimal (lossless)
  • Float to Decimal (within Decimal's range)
  • Integer or Float to Number (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": { "field_type": "String", "required": true },
"age": { "field_type": "Number", "min": 0, "max": 150 },
"email": { "field_type": "String", "unique": true },
"balance": { "field_type": "Decimal" },
"tags": { "field_type": "Array" },
"metadata": { "field_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, or Integer minor units when a function totals the amounts)
  • Store dates as strings (use DateTime)
  • Use Array when you need uniqueness (use Set)
  • Mix types inconsistently
  • Put ., , or : in field names (see Field Paths)

Next Steps​


Questions? Contact support@ekodb.io