Crate spatio 

Spatio - A simple embedded spatio-temporal database

Spatio is a fast, embedded spatio-temporal database designed for applications that need to store and query location-based data efficiently.

Core Features

• Fast key-value storage with optional persistence
• Automatic spatial indexing for geographic points
• Trajectory tracking for moving objects over time
• TTL support for automatic data expiration
• Atomic operations for data consistency
• Thread-safe concurrent access

Quick Start

use spatio::{Point, SetOptions, Spatio};
use std::time::Duration;

// Create an in-memory database
let db = Spatio::memory()?;

// Store a simple key-value pair
db.insert("user:123", b"John Doe", None)?;

// Store a geographic point (automatically indexed)
let nyc = Point::new(40.7128, -74.0060);
db.insert_point("cities", &nyc, b"New York City", None)?;

// Find nearby points within 100km
let nearby = db.find_nearby("cities", &nyc, 100_000.0, 10)?;
println!("Found {} cities nearby", nearby.len());

// Atomic batch operations
db.atomic(|batch| {
    batch.insert("sensor:temp", b"22.5C", None)?;
    batch.insert("sensor:humidity", b"65%", None)?;
    Ok(())
})?;

// Data with TTL (expires in 5 minutes)
let opts = SetOptions::with_ttl(Duration::from_secs(300));
db.insert("session:abc", b"user_data", Some(opts))?;

Custom Geohash Configuration

Configure geohash precision for different spatial requirements:

use spatio::{Spatio, Config};

// Default configuration (precision 8, ~39m accuracy)
let db = Spatio::memory()?;

// Custom precision (10 = ~61cm accuracy)
let precise_db = Spatio::memory_with_config(
    Config::with_geohash_precision(10)
)?;

// Manual configuration
let config = Config::with_geohash_precision(6); // ~610m accuracy
let custom_db = Spatio::memory_with_config(config)?;

Trajectory Tracking

use spatio::{Point, Spatio};

let db = Spatio::memory()?;

// Track a vehicle's movement over time
let trajectory = vec![
    (Point::new(40.7128, -74.0060), 1640995200), // Start
    (Point::new(40.7150, -74.0040), 1640995260), // 1 min later
    (Point::new(40.7172, -74.0020), 1640995320), // 2 min later
];

db.insert_trajectory("vehicle:truck001", &trajectory, None)?;

// Query trajectory for a time range
let path = db.query_trajectory("vehicle:truck001", 1640995200, 1640995320)?;
println!("Retrieved {} waypoints", path.len());

Spatial Queries

use spatio::{Point, Spatio};

let db = Spatio::memory()?;

// Insert some cities
let nyc = Point::new(40.7128, -74.0060);
let brooklyn = Point::new(40.6782, -73.9442);
db.insert_point("cities", &nyc, b"New York", None)?;
db.insert_point("cities", &brooklyn, b"Brooklyn", None)?;

// Check if any points exist within a circular region
let has_nearby = db.contains_point("cities", &nyc, 50_000.0)?; // 50km radius
assert!(has_nearby);

// Count points within distance
let count = db.count_within_distance("cities", &nyc, 50_000.0)?;
println!("Found {} cities within 50km", count);

// Check if any points exist within a bounding box
let has_points = db.intersects_bounds("cities", 40.6, -74.1, 40.8, -73.9)?;
assert!(has_points);

// Find all points within a bounding box
let points = db.find_within_bounds("cities", 40.6, -74.1, 40.8, -73.9, 100)?;
println!("Found {} cities in the area", points.len());

Re-exports

pub use builder::DBBuilder;

pub use db::DB;

pub use error::Result;

pub use error::SpatioError;

pub use spatial::BoundingBox;

pub use spatial::Point;

pub use types::Config;

pub use types::DbStats;

pub use types::SetOptions;

pub use types::SyncMode;

pub use types::SyncPolicy;

pub use types::HistoryEntry;

pub use types::HistoryEventKind;

pub use namespace::Namespace;

pub use namespace::NamespaceManager;

pub use storage::MemoryBackend;

pub use storage::StorageBackend;

pub use storage::StorageOp;

pub use storage::StorageStats;

pub use storage::AOFBackend;

pub use batch::AtomicBatch;

pub use persistence::AOFConfig;

pub use persistence::AOFFile;

pub use index::DEFAULT_GEOHASH_PRECISION;

pub use index::DEFAULT_SEARCH_PRECISIONS;

Modules

batch

Atomic batch operations for Spatio database transactions.

builder

Database builder for flexible configuration

db

Core database implementation for Spatio.

error

Error types and result aliases for Spatio operations.

ffi

C-compatible FFI for the Spatio database.

index

Spatial index manager powering geospatial queries.

namespace

Namespace support for Spatio

persistence

Append-only persistence layer for Spatio (feature aof).

prelude

Prelude module for common imports

spatial

Spatial utilities for Spatio

storage

Storage backend abstraction for Spatio

types

Simplified types and configuration for Spatio

Constants

VERSION

Version information

Type Aliases

Spatio