CLI Data Types

CLI Data Types

OstrichDB CLI uses a strongly-typed system where every record must have an explicit data type specified at creation. This guide covers all supported data types, their formats, validation rules, and best practices.

Type System Overview

Strong Typing

OstrichDB enforces strict type validation:

• Explicit Declaration: All records must specify a type with OF_TYPE
• Format Validation: Values must match the specified type format
• Type Consistency: Record types cannot be changed accidentally
• Validation at Creation: Invalid types or values are rejected immediately

Type Specification

# General syntax
NEW <location> OF_TYPE <type> [WITH <value>]

# Examples
NEW users.staff.name OF_TYPE STRING WITH "Alice Johnson"
NEW inventory.count OF_TYPE INTEGER WITH 150
NEW settings.enabled OF_TYPE BOOLEAN WITH true

Primary Data Types

STRING (Shorthand: STR)

Text data of any length, including letters, numbers, symbols, and spaces.

Format:

• Any sequence of characters
• Enclosed in quotes when containing spaces
• UTF-8 encoded

Examples:

# Simple string
NEW users.staff.name OF_TYPE STRING WITH "John Doe"

# String with special characters
NEW products.description OF_TYPE STR WITH "High-quality laptop (2024 model) - $1,299"

# Empty string
NEW temp.empty OF_TYPE STRING WITH ""

# String with numbers
NEW codes.product_id OF_TYPE STRING WITH "PROD-2024-001"

Use Cases:

• Names and descriptions
• Product codes and IDs
• Text content
• Mixed alphanumeric data

INTEGER (Shorthand: INT)

Whole numbers without decimal points, positive or negative.

Format:

• No decimal point
• Can be negative (prefix with -)
• Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

Examples:

# Positive integer
NEW inventory.electronics.count OF_TYPE INTEGER WITH 25

# Negative integer
NEW accounts.balance OF_TYPE INT WITH -150

# Zero
NEW counters.reset_value OF_TYPE INTEGER WITH 0

# Large number
NEW statistics.total_users OF_TYPE INT WITH 1000000

Use Cases:

• Counts and quantities
• IDs and indices
• Ages and years
• Inventory levels

FLOAT (Shorthand: FLT)

Floating-point numbers with decimal points.

Format:

• Must include decimal point
• Can be negative
• Scientific notation supported
• 64-bit precision

Examples:

# Price with decimals
NEW products.laptop.price OF_TYPE FLOAT WITH 1299.99

# Percentage
NEW statistics.growth_rate OF_TYPE FLT WITH 15.7

# Scientific notation
NEW measurements.distance OF_TYPE FLOAT WITH 1.5e6

# Negative float
NEW accounts.debt OF_TYPE FLOAT WITH -250.50

Use Cases:

• Prices and costs
• Measurements
• Percentages and rates
• Scientific data

BOOLEAN (Shorthand: BOOL)

True or false values only.

Format:

• Exactly true or false (case-sensitive)
• No other variations accepted

Examples:

# Enable feature
NEW settings.dark_mode OF_TYPE BOOLEAN WITH true

# Disable option
NEW users.alice.verified OF_TYPE BOOL WITH false

# Status flag
NEW system.maintenance_mode OF_TYPE BOOLEAN WITH true

Use Cases:

• Feature flags
• Status indicators
• Configuration options
• Yes/No questions

CHAR

Single character values.

Format:

• Exactly one character
• Letters, numbers, or symbols
• No shorthand available

Examples:

# Letter grade
NEW students.alice.grade OF_TYPE CHAR WITH A

# Status code
NEW orders.status OF_TYPE CHAR WITH P

# Symbol
NEW math.operator OF_TYPE CHAR WITH +

Use Cases:

• Single letter codes
• Status indicators
• Mathematical operators
• Grade systems

Date and Time Types

DATE

Calendar dates in YYYY-MM-DD format.

Format:

• Must be YYYY-MM-DD
• Zero-padded months and days
• Valid calendar dates only

Examples:

# Birth date
NEW users.john.birth_date OF_TYPE DATE WITH 1990-05-15

# Project deadline
NEW projects.website.deadline OF_TYPE DATE WITH 2024-12-31

# Historical date
NEW events.founding OF_TYPE DATE WITH 1776-07-04

Use Cases:

• Birth dates
• Deadlines and milestones
• Historical events
• Scheduling

TIME

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

Format:

• 24-hour format: HH:MM:SS
• Zero-padded hours, minutes, seconds
• Valid time values only

Examples:

# Meeting time
NEW calendar.meeting_start OF_TYPE TIME WITH 14:30:00

# Business hours
NEW store.opening_time OF_TYPE TIME WITH 09:00:00
NEW store.closing_time OF_TYPE TIME WITH 21:30:00

# Midnight
NEW system.backup_time OF_TYPE TIME WITH 00:00:00

Use Cases:

• Meeting times
• Business hours
• Schedules
• Time-based events

DATETIME

Combined date and time in ISO 8601 format.

Format:

• YYYY-MM-DDTHH:MM:SS
• ‘T’ separator between date and time
• Optional timezone (Z for UTC)

Examples:

# Event timestamp
NEW events.user_login OF_TYPE DATETIME WITH 2024-01-15T10:30:00

# UTC timestamp
NEW logs.error_occurred OF_TYPE DATETIME WITH 2024-01-15T10:30:00Z

# System event
NEW system.last_restart OF_TYPE DATETIME WITH 2024-01-14T23:45:30

Use Cases:

• Log timestamps
• Event recording
• System events
• Precise timing

Special Types

UUID

Universally Unique Identifiers in standard UUID format.

Format:

• 8-4-4-4-12 hexadecimal digits
• Lowercase letters a-f and numbers 0-9
• Hyphens in specific positions

Examples:

# User ID
NEW users.alice.user_id OF_TYPE UUID WITH 550e8400-e29b-41d4-a716-446655440000

# Session token
NEW sessions.current OF_TYPE UUID WITH 6ba7b810-9dad-11d1-80b4-00c04fd430c8

# Transaction ID
NEW transactions.payment OF_TYPE UUID WITH 12345678-1234-5678-9abc-123456789012

Use Cases:

• Unique identifiers
• Session tokens
• Database keys
• Transaction IDs

NULL

Represents null or empty values.

Format:

• Exactly null (lowercase)
• Represents absence of value

Examples:

# Optional field not set
NEW users.john.middle_name OF_TYPE NULL WITH null

# Placeholder value
NEW temp.placeholder OF_TYPE NULL WITH null

# Reset value
NEW counters.temp_value OF_TYPE NULL WITH null

Use Cases:

• Optional fields
• Placeholder values
• Reset operations
• Empty states

Array Types

All primary types can be stored as arrays by prefixing the type with [].

Array Format Rules

• JSON-like syntax: [element1,element2,element3]
• No spaces: Elements separated by commas without spaces
• Type consistency: All elements must match the base type
• Empty arrays: [] for empty arrays

[]STRING (Shorthand: []STR)

Arrays of strings.

Examples:

# Team members
NEW teams.engineering.members OF_TYPE []STRING WITH "Alice,Bob,Carol,Dave"

# Tags
NEW products.laptop.tags OF_TYPE []STR WITH "electronics,computer,portable"

# Skills
NEW users.alice.skills OF_TYPE []STRING WITH "Python,JavaScript,SQL"

# Empty array
NEW temp.empty_list OF_TYPE []STRING WITH ""

[]INTEGER (Shorthand: []INT)

Arrays of integers.

Examples:

# Test scores
NEW students.alice.scores OF_TYPE []INTEGER WITH 85,92,78,96

# Monthly sales
NEW reports.q1_sales OF_TYPE []INT WITH 15000,18000,22000

# Years of experience
NEW team.experience_years OF_TYPE []INTEGER WITH 5,3,8,2,10

[]FLOAT (Shorthand: []FLT)

Arrays of floating-point numbers.

Examples:

# Product prices
NEW catalog.electronics.prices OF_TYPE []FLOAT WITH 299.99,1299.99,89.99

# Monthly averages
NEW analytics.monthly_avg OF_TYPE []FLT WITH 15.7,18.2,22.1,19.8

# Measurements
NEW lab.temperature_readings OF_TYPE []FLOAT WITH 23.5,24.1,23.8,24.3

[]BOOLEAN (Shorthand: []BOOL)

Arrays of boolean values.

Examples:

# Feature flags
NEW settings.features_enabled OF_TYPE []BOOLEAN WITH true,false,true,true

# Permission matrix
NEW users.alice.permissions OF_TYPE []BOOL WITH true,false,false,true

# Status checks
NEW system.health_checks OF_TYPE []BOOLEAN WITH true,true,false,true

[]CHAR

Arrays of single characters.

Examples:

# Grade sequence
NEW students.alice.semester_grades OF_TYPE []CHAR WITH A,B,A,B

# Status codes
NEW orders.status_history OF_TYPE []CHAR WITH P,S,D

# Operators
NEW math.equation_operators OF_TYPE []CHAR WITH +,-,*,/

Date/Time Arrays

[]DATE, []TIME, []DATETIME

Arrays of date, time, or datetime values.

Examples:

# Important dates
NEW project.milestones OF_TYPE []DATE WITH 2024-03-15,2024-06-30,2024-12-31

# Daily schedule
NEW calendar.meeting_times OF_TYPE []TIME WITH 09:00:00,13:00:00,15:30:00

# Event log
NEW system.events OF_TYPE []DATETIME WITH 2024-01-15T09:00:00,2024-01-15T10:30:00,2024-01-15T14:15:00

[]UUID

Arrays of UUID values.

Examples:

# Related user IDs
NEW groups.admins.member_ids OF_TYPE []UUID WITH 550e8400-e29b-41d4-a716-446655440000,6ba7b810-9dad-11d1-80b4-00c04fd430c8

# Transaction chain
NEW payments.related_transactions OF_TYPE []UUID WITH 12345678-1234-5678-9abc-123456789012,87654321-4321-8765-cba9-210987654321

Type Validation

Validation Rules

OstrichDB performs strict validation at record creation:

Format Validation:

# ✅ Valid
NEW users.age OF_TYPE INTEGER WITH 25

# ❌ Invalid - string value for integer type
NEW users.age OF_TYPE INTEGER WITH "twenty-five"
Error: Value "twenty-five" is not a valid INTEGER

Array Validation:

# ✅ Valid array
NEW tags OF_TYPE []STRING WITH "red,green,blue"

# ❌ Invalid - spaces in array
NEW tags OF_TYPE []STRING WITH "red, green, blue"
Error: Array elements cannot contain spaces between commas

# ❌ Invalid - mixed types in array
NEW mixed OF_TYPE []INTEGER WITH 1,2,"three"
Error: All array elements must be of type INTEGER

Date/Time Validation:

# ✅ Valid date
NEW deadline OF_TYPE DATE WITH 2024-12-31

# ❌ Invalid date format
NEW deadline OF_TYPE DATE WITH 12/31/2024
Error: Date must be in YYYY-MM-DD format

# ❌ Invalid date
NEW deadline OF_TYPE DATE WITH 2024-02-30
Error: Invalid date - February 30th does not exist

Common Validation Errors

Type Mismatch:

NEW count OF_TYPE INTEGER WITH 25.5
Error: Value "25.5" is not a valid INTEGER (contains decimal)

Invalid Boolean:

NEW flag OF_TYPE BOOLEAN WITH yes
Error: Boolean values must be exactly "true" or "false"

Invalid UUID:

NEW id OF_TYPE UUID WITH 123-456-789
Error: UUID must be in format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Array Format Error:

NEW list OF_TYPE []STRING WITH Alice,Bob,Carol
Error: Array values must be properly formatted: "Alice,Bob,Carol"

Type Conversion

Automatic Conversion

OstrichDB does not perform automatic type conversion. Values must match the specified type exactly.

No Auto-Conversion:

# This will NOT convert string to integer
NEW count OF_TYPE INTEGER WITH "42"
Error: Value "42" is not a valid INTEGER (quotes indicate string)

# Correct way
NEW count OF_TYPE INTEGER WITH 42

Manual Type Changes

Use CHANGE_TYPE to convert existing records:

# Change string to integer (if value is convertible)
CHANGE_TYPE products.count TO INTEGER
Warning: Current value "25" will be converted to INTEGER.
Proceed? (y/N): y

# Change single value to array
CHANGE_TYPE users.skill TO []STRING
Warning: Current value "Python" will become ["Python"]
Proceed? (y/N): y

Best Practices

Type Selection Guidelines

Use STRING for:

• Names and descriptions
• Codes and identifiers
• Mixed alphanumeric data
• Text content

Use INTEGER for:

• Counts and quantities
• Ages and indices
• Years
• Whole number measurements

Use FLOAT for:

• Prices and currency
• Percentages and ratios
• Measurements with precision
• Scientific data

Use BOOLEAN for:

• Feature flags
• Status indicators
• Yes/No questions
• Configuration options

Array Usage

When to Use Arrays:

• Multiple related values of the same type
• Lists that grow dynamically
• Categorical data
• Tag systems

Array Alternatives:

# Instead of arrays, consider separate records for complex data
# Array approach
NEW user.skills OF_TYPE []STRING WITH "Python,JavaScript,SQL"

# Separate records approach (more queryable)
NEW user.skills.python OF_TYPE BOOLEAN WITH true
NEW user.skills.javascript OF_TYPE BOOLEAN WITH true
NEW user.skills.sql OF_TYPE BOOLEAN WITH true

Naming Conventions

Include Type Hints in Names:

# Good - type is clear from name
NEW user.age OF_TYPE INTEGER WITH 30
NEW user.salary OF_TYPE FLOAT WITH 75000.50
NEW user.active OF_TYPE BOOLEAN WITH true
NEW user.skills OF_TYPE []STRING WITH "Python,Java"

# Better - explicit type indication
NEW user.age_years OF_TYPE INTEGER WITH 30
NEW user.salary_usd OF_TYPE FLOAT WITH 75000.50
NEW user.is_active OF_TYPE BOOLEAN WITH true
NEW user.skill_list OF_TYPE []STRING WITH "Python,Java"

Data Consistency

Maintain Type Consistency:

# Good - consistent types for similar data
NEW users.alice.age OF_TYPE INTEGER WITH 30
NEW users.bob.age OF_TYPE INTEGER WITH 25
NEW users.carol.age OF_TYPE INTEGER WITH 35

# Bad - inconsistent types
NEW users.alice.age OF_TYPE INTEGER WITH 30
NEW users.bob.age OF_TYPE STRING WITH "twenty-five"
NEW users.carol.age OF_TYPE FLOAT WITH 35.0

Validation Practices

Always Validate Types:

# Check type before operations
TYPE_OF users.alice.age
# Output: users.alice.age: INTEGER

# Verify array types
TYPE_OF teams.skills
# Output: teams.skills: []STRING

Test with Sample Data:

# Test type creation with sample data first
NEW test.sample OF_TYPE []DATETIME WITH 2024-01-15T10:00:00,2024-01-15T11:00:00

# Verify it works
FETCH test.sample
TYPE_OF test.sample

# Then use for real data
NEW calendar.meetings OF_TYPE []DATETIME WITH 2024-01-15T10:00:00,2024-01-15T14:00:00

Troubleshooting Types

Common Issues

Array Formatting:

# Problem: Spaces in array
NEW tags OF_TYPE []STRING WITH "red, green, blue"

# Solution: Remove spaces
NEW tags OF_TYPE []STRING WITH "red,green,blue"

Date Formats:

# Problem: Wrong date format
NEW date OF_TYPE DATE WITH 01/15/2024

# Solution: Use YYYY-MM-DD
NEW date OF_TYPE DATE WITH 2024-01-15

Boolean Values:

# Problem: Non-standard boolean
NEW flag OF_TYPE BOOLEAN WITH TRUE

# Solution: Use lowercase
NEW flag OF_TYPE BOOLEAN WITH true

Debug Type Issues

Check Current Type:

TYPE_OF problematic.record

Validate Record:

FETCH problematic.record

Test Type Creation:

# Create test record with problematic type/value
NEW test.debug OF_TYPE PROBLEMATIC_TYPE WITH problematic_value

Next Steps

Now that you understand data types:

1. Configure OstrichDB - Set up your environment
2. Practice with Commands - Apply type knowledge to operations
3. Experiment: Create records with different types
4. Build Schemas: Design your data structure with appropriate types

Understanding the type system is crucial for effective OstrichDB usage. Choose types carefully and maintain consistency for the best database experience.