An Introduction to SpacetimeDB: A Tutorial

Table of Contents

1. Introduction
2. What Sets SpaceTimeDB Apart: Key Features and Use Cases
3. Core Concepts of SpaceTimeDB
4. Installation & Setup of SpaceTimeDB
5. Using SpaceTimeDB in Code/Programming
6. Conclusion

Introduction

Computing is rapidly changing. Managing real-time, time-sensitive, and geospatial data has become very important. In order to maintain such data, we cannot rely on traditional databases. Enter SpaceTimeDB, a cutting-edge, next-generation database solution engineered to efficiently handle large-scale, time-series, and geospatial data.

SpaceTimeDB was launched in March 2025 by Clockwork Labs, and it is quickly gaining traction. Its official release is mature, stable, and production-ready. Its developers, Clockwork Labs, have attracted reputable investors such as Andreessen Horowitz, Supercell, and Skycatcher. Although the database is in its early stages, it has already been used in the BitCraft Online game. The game uses SpaceTimeDB to manage real-time data, enabling a seamless multiplayer experience.

This tutorial gives a comprehensive understanding of SpaceTimeDB, its features, its impact on the industry, and how you can leverage it to enhance your projects.

What Sets SpaceTimeDB Apart: Key Features and Use Cases

What Makes SpaceTimeDB Different?

Traditional databases are unable to handle the unique demands of time-series and geospatial data fully. Time-series data is rapidly changing, and traditional databases aren’t meant to efficiently handle such rapidly changing data. At the same time, geospatial data requires specialized indexing and querying techniques to be useful, which traditional databases cannot achieve.

SpaceTimeDB was designed to address these problems. It is built for real-time, high-volume data workloads, providing optimized performance for both time-series and geospatial data.

Key Features of SpaceTimeDB

• Time-Series Support: SpaceTimeDB is natively built to support time-series data at scale. It supports real-time analytics and historical data analysis, so it can handle large datasets that change over time.
• Geospatial Data Handling: SpaceTimeDB also excels at handling geospatial data. It can track movement on a map, analyze spatial relationships, and perform other geospatial-related tasks with ease.
• Real-Time Data Processing: Real-time performance is a hallmark of SpaceTimeDB. It's optimized for low-latency queries.
• Scalability and Data Compression: SpaceTimeDB is designed to scale as your data grows. It uses data compression to reduce storage costs without sacrificing performance.
• Advanced Querying: SpaceTimeDB supports powerful querying. Its engine is optimized for complex queries that would be slow in other databases.

Use Cases of SpaceTimeDB

• IoT (Internet of Things): It can manage the large volume of data that comes from sensors and devices.
• Financial Services: Real-time tracking of stock prices, financial transactions, or market analytics.
• Gaming: Used in real-time multiplayer games like BitCraft Online, where seamless data management is critical for gameplay.
• Geospatial Applications: Location-based data like GPS, maps, and spatial relationships in applications such as autonomous vehicles or mapping services.
• Smart Cities: Real-time data from urban infrastructure for managing traffic, utilities, and environmental monitoring.

Core Concepts of SpaceTimeDB

Data Model of SpaceTimeDB

SpaceTimeDB's data model is focused on time series and geospatial data.

• Time-Series Data: Data is organized chronologically, enabling precise data retrieval over specific time intervals.
• Geospatial Data: SpaceTimeDB supports spatial indexing. This ensures that location-based data is efficiently stored and queried.

Time-Sensitive Data:

SpaceTimeDB can efficiently handle time-sensitive data.

• Real-Time Data Handling: SpaceTimeDB provides low latency, which is required for real-time apps.
• Efficient Time-Series Storage: SpaceTimeDB's architecture can scale effortlessly. It supports data compression to optimize storage. This makes it economical to store large datasets.

Queries in SpaceTimeDB:

SpaceTimeDB offers powerful querying capabilities.

• Spatial Queries: SpaceTimeDB can perform spatial queries to retrieve data based on location. For example, the query to retrieve the nearest neighbor in searches.
• Temporal Queries: SpaceTimeDB supports queries to retrieve data based on time ranges.
• Geospatial Queries: SpaceTimeDB supports location-based searches and spatial data analysis.
• Complex Querying: SpaceTimeDB's query engine is optimized to handle both time-series and spatial queries simultaneously.

Architectural Concepts in SpaceTimeDB

• Host: Refers to the server that runs the SpaceTimeDB databases.
• Database: An application operation on a SpaceTimeDB host; it exposes tables for data storage and reducers that allow client interactions. The database schema and business logic are defined by a module, commonly written in C# or Rust.
• Module: A collection of stored procedures and schema definitions that dictate the database's structure and behavior. They are written in Rust and C# and assembled using the SpaceTimeCLI tool. These are compiled into WebAssembly for efficiency.
• Table: A table within SpaceTimeDB.
• Reducer: A function that the database exports, enabling connected clients to interact with the database. They perform the CRUD operations.
• Clients: Applications or services that connect to a SpaceTimeDB database instance to interact with its data and logic. They communicate with the DB via WebSockets and invoke reducers.

Typical Client Responsibilities:

• Authenticating and connecting to the DB.
• Subscribing to relevant tables.
• Displaying or reacting to real-time data.
• Sending actions (via reducers).
• Handling disconnections and reconnections gracefully.

Installation & Setup of SpaceTimeDB

The easiest way to install spaceTimeDB is via docker

Docker Setup

Install Docker if it is not already installed and run the following command:

docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start

The above command pulls and runs Docker. It opens port 3000 for access.

Using SpaceTimeDB in Code/Programming

Creating a Table in C# in SpaceTimeDB

To create a table in SpaceTimeDB, we define a struct and annotate it with SpacetimeDB. Table:

[SpacetimeDB.Table(Name = "users", Public = true)]
public partial struct User
{
    [SpacetimeDB.PrimaryKey]
    uint userId;
    string name;
    string email;
    string role;
}

Creating a Reducer in C# in SpaceTimeDB

Reducers are functions that manipulate data in SpaceTimeDB. Here's an example of a simple reducer that logs when a user connects:

[Reducer(ReducerKind.ClientConnected)]
public static void Connect(ReducerContext ctx)
{
    Log.Info($"{ctx.Sender} just connected to reducer.");
}

Basic Database Operations in SpaceTimeDB

In this section, we will cover basic CRUD operations using C# in SpaceTimeDB.

Create

To insert/create a new entry in SpaceTimeDB, we can use the Insert function:

// Create User
[SpacetimeDB.Reducer]
public static void CreateUser(ReducerContext ctx) {
    var newUser = new User { Id = 0, Username = "JohnDoe", DogCount = 3 };
    var insertedUser = ctx.Db.user.Insert(newUser);
    Console.WriteLine($"User created with ID: {insertedUser.Id}");
}

Explantion

• The Insert function adds a new user to the user table.
• The insertedUser object is returned, which includes the Id generated by SpaceTimeDB.

Read

To read data from the database, we use the find method. Here, we query a user by their unique ID:

// Read User by ID
[SpacetimeDB.Reducer]
public static void GetUserById(ReducerContext ctx) {
    var userId = 1;
    var user = ctx.Db.user.Id.find(userId).unwrap();  // Corrected: 'find' instead of 'Find'
    Console.WriteLine($"Found user: {user.Username}, Dog Count: {user.DogCount}");
}

Explanation:

• The find method retrieves a user based on their ID.
• The unwrap method is used to ensure that the user is found, or an error is thrown if not.

Update

To update an existing entry, we first use find to locate the record, modify it, and then call Update to persist the changes:

// Update User
[SpacetimeDB.Reducer]
public static void UpdateUser(ReducerContext ctx) {
    var userId = 1;
    var user = ctx.Db.user.Id.find(userId).unwrap();  // Corrected: 'find' instead of 'Find'
    user.DogCount += 1;
    ctx.Db.user.Id.Update(user);
    Console.WriteLine($"User {user.Username} updated. New Dog Count: {user.DogCount}");
}

Explanation:

We fetch a user by Id, increment their dog count by 1, and then use the Update method to save the changes.

Delete:

To delete a user, we use the Delete function:

// Delete User
[SpacetimeDB.Reducer]
public static void DeleteUser(ReducerContext ctx) {
    var usernameToDelete = "JohnDoe";
    var usernameIndex = ctx.Db.user.Username;
    var userToDelete = usernameIndex.find(usernameToDelete).unwrap();  // Corrected: 'find' instead of 'Find'
    usernameIndex.Delete(userToDelete.Username);
    Console.WriteLine($"User {usernameToDelete} deleted.");
}

Explanation:

We use the find method to retrieve the user based on their Username and then call delete to remove them from the database.

Conclusion

In conclusion, SpaceTimeDB is a cutting-edge database solution designed to handle time-series and geospatial data. It offers high performance for high-volume, real-time workloads. Its unique features make it a database that's hard to ignore, providing optimized performance for both time-sensitive and location-based data. Whether you're building applications for IoT, gaming, or real-time analytics, SpaceTimeDB equips you with the tools to efficiently manage complex data at scale.

Frequently Asked Questions