Data Types

OstrichDB supports a rich set of data types for storing various kinds of information. Each record must specify a type when created, and the database enforces type consistency.

Basic Types

STRING / STR / CHAR

Text data stored as UTF-8 encoded strings.

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/name?type=STRING&value=John Doe"

JSON representation:

{
  "name": "name",
  "type": "STRING",
  "value": "John Doe"
}

INTEGER / INT

64-bit signed integers from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/age?type=INTEGER&value=42"

JSON representation:

{
  "name": "age",
  "type": "INTEGER",
  "value": 42
}

FLOAT / FLT

64-bit floating-point numbers (IEEE 754 double precision).

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/price?type=FLOAT&value=19.99"

JSON representation:

{
  "name": "price",
  "type": "FLOAT",
  "value": 19.99
}

BOOLEAN / BOOL

True or false values.

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/active?type=BOOLEAN&value=true"

JSON representation:

{
  "name": "active",
  "type": "BOOLEAN",
  "value": true
}

Temporal Types

DATE

Date values in YYYY-MM-DD format.

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/birth_date?type=DATE&value=1990-05-15"

JSON representation:

{
  "name": "birth_date",
  "type": "DATE",
  "value": "1990-05-15"
}

TIME

Time values in HH:MM:SS format (24-hour).

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/meeting_time?type=TIME&value=14:30:00"

JSON representation:

{
  "name": "meeting_time",
  "type": "TIME",
  "value": "14:30:00"
}

DATETIME

Combined date and time in ISO 8601 format.

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/created_at?type=DATETIME&value=2024-01-15T10:30:00Z"

JSON representation:

{
  "name": "created_at",
  "type": "DATETIME",
  "value": "2024-01-15T10:30:00Z"
}

Special Types

UUID

Universally Unique Identifiers in standard UUID format.

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/session_id?type=UUID&value=550e8400-e29b-41d4-a716-446655440000"

JSON representation:

{
  "name": "session_id",
  "type": "UUID",
  "value": "550e8400-e29b-41d4-a716-446655440000"
}

NULL

Represents null or empty values.

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/optional_field?type=NULL&value=null"

JSON representation:

{
  "name": "optional_field",
  "type": "NULL",
  "value": null
}

CREDENTIAL

Encrypted credential storage for sensitive data like passwords or API keys.

Usage:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/api_key?type=CREDENTIAL&value=secret-api-key"

JSON representation:

{
  "name": "api_key",
  "type": "CREDENTIAL",
  "value": "[ENCRYPTED]"
}

Array Types

All basic types can be stored as arrays by prefixing with [].

String Arrays

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/tags?type=[]STRING&value=[\"admin\",\"user\",\"active\"]"

Integer Arrays

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/scores?type=[]INTEGER&value=[85,92,78,96]"

Float Arrays

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/prices?type=[]FLOAT&value=[19.99,24.50,12.75]"

Boolean Arrays

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/permissions?type=[]BOOLEAN&value=[true,false,true]"

Date Arrays

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/important_dates?type=[]DATE&value=[\"2024-01-01\",\"2024-06-15\",\"2024-12-31\"]"

Time Arrays

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/schedule?type=[]TIME&value=[\"09:00:00\",\"13:00:00\",\"17:00:00\"]"

DateTime Arrays

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/events?type=[]DATETIME&value=[\"2024-01-15T10:00:00Z\",\"2024-01-15T14:00:00Z\"]"

UUID Arrays

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/session_ids?type=[]UUID&value=[\"550e8400-e29b-41d4-a716-446655440000\",\"6ba7b810-9dad-11d1-80b4-00c04fd430c8\"]"

Type Validation

Automatic Validation

OstrichDB automatically validates data types when creating or updating records:

Format validation: Ensures data matches expected format
Range validation: Checks numeric values are within valid ranges
Structure validation: Validates array structures and nested data

Validation Examples

Valid date:

# ✅ Correct format
curl -X POST "...?type=DATE&value=2024-01-15"

Invalid date:

# ❌ Invalid format
curl -X POST "...?type=DATE&value=01/15/2024"
# Returns validation error

Valid array:

# ✅ Proper JSON array
curl -X POST "...?type=[]STRING&value=[\"item1\",\"item2\"]"

Invalid array:

# ❌ Not a JSON array
curl -X POST "...?type=[]STRING&value=item1,item2"
# Returns validation error

Type Conversion

Automatic Conversions

Some types allow automatic conversion:

String to Number: “42” → 42 (for INTEGER/FLOAT types)
Number to String: 42 → “42” (for STRING type)
Boolean conversion: “true”/“false” → true/false

Explicit Type Specification

Always specify the intended type explicitly to avoid ambiguity:

# Store as string
curl -X POST "...?type=STRING&value=42"

# Store as integer
curl -X POST "...?type=INTEGER&value=42"

Working with Arrays

Array Creation

Create arrays using JSON array syntax:

curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/items?type=[]STRING&value=[\"apple\",\"banana\",\"orange\"]"

Array Modification

Update arrays by replacing the entire array:

curl -X PUT "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/items?value=[\"apple\",\"banana\",\"grape\"]"

Array Queries

Search for records containing specific array elements:

curl "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records?valueContains=apple"

Best Practices

Type Selection

Use STRING for text data and identifiers
Use INTEGER for whole numbers and counts
Use FLOAT for decimal numbers and measurements
Use BOOLEAN for true/false flags
Use DATE/TIME/DATETIME for temporal data
Use UUID for unique identifiers
Use CREDENTIAL for sensitive data
Use arrays for lists of homogeneous data

Consistency

Be consistent with type usage across similar records
Use the same type for the same kind of data
Document your type choices for team members

Performance

Choose the most specific type possible
Use INTEGER instead of STRING for numeric data
Use DATE instead of STRING for date data
Consider array types for related list data

Security

Use CREDENTIAL type for sensitive data
Ensure encrypted collections for confidential information
Validate data types to prevent injection attacks

Type Reference Summary

Type	Description	Example Value
STRING	Text data	”Hello World”
INTEGER	Whole numbers	42
FLOAT	Decimal numbers	3.14159
BOOLEAN	True/false	true
DATE	Date only	”2024-01-15”
TIME	Time only	”14:30:00”
DATETIME	Date and time	”2024-01-15T14:30:00Z”
UUID	Unique identifier	”550e8400-e29b-41d4-a716-446655440000”
NULL	Null value	null
CREDENTIAL	Encrypted data	”[ENCRYPTED]”
[]TYPE	Array of type	[“item1”, “item2”]