Globe KV

Globe KV is a key-value store designed for fast reads and low-latency data access. It is ideal for caching, user settings, session storage, and feature flags in Dart applications.

Unlike traditional databases, Globe KV does not guarantee immediate consistency. Updates can take up to 60 seconds to propagate globally. This makes it great for temporary or frequently accessed data but unsuitable for operations requiring absolute consistency (e.g., payments, counters).

This page covers setup, storing and retrieving data, data expiration, performance characteristics, and eventual consistency

Setting Up Globe KV

1. Adding Globe KV to your Project

Add globe_kv to your pubspec.yaml:

dependencies:
  globe_kv: latest

Then install it:

dart pub get

Or run this command in your terminal:

With Dart:

dart pub add globe_kv

With Flutter:

flutter pub add globe_kv

2. Creating a Namespace

To use Globe KV, you need a KV namespace.

1. From your Globe dashboard, go to the KV section
2. Select Create Namespace
3. Enter your Namespace name (e.g. users)
4. Select Create

3. Creating an Instance

Create a new Globe KV instance, passing in your KV namespace.

import 'package:globe_kv/globe_kv.dart';

// Replace 'namespace-id' with your actual KV namespace
final kv = Globe KV('namespace-id');

4. Persist Data to Your Local Filesystem

In development, Globe KV will use in-memory storage so your data will be lost when the Dart app is restarted. To persist data to your local filesystem, use the GlobeFileStore instance:

final kv = Globe KV('namespace-id', store: GlobeFileStore());

Using Globe KV

Storing, Retrieving, and Deleting Data

Globe KV is a key-value store, meaning you store and retrieve data using keys.

Writing Data

await kv.set('user:123', 'John Doe');

Reading Data

final userData = await kv.getString('user:123');
debugPrint(userData); // Output: John Doe

Deleting Data

await kv.delete('user:123');

Retrieving Data

Globe KV supports typed retrieval, so you can fetch data in a specific format:

await kv.getString('key');  // String?
await kv.getInt('key');     // int?
await kv.getBool('key');    // bool?
await kv.getBinary('key');  // List<int>?

Listing and Filtering Data

When storing multiple related keys (e.g., user data), use prefixes to group and filter keys.

Listing All Keys with a Prefix

final result = await kv.list(prefix: 'user:');
print(result.results.map((e) => e.key)); // ['user:123', 'user:456']

Paginating Large Datasets

By default, list() returns up to 1000 keys per page. If you have more, paginate:

final result = await kv.list(prefix: 'user:', limit: 10);
if (!result.complete) {
  final nextResult = await kv.list(prefix: 'user:', limit: 10, cursor: result.cursor!);
}

Expiring Data (TTL & Absolute Expiration)

Globe KV supports automatic data deletion, which is useful for managing temporary session data or cached API responses. You can configure expiration when you write data, and it will be automatically removed from the store after the specified time.

Setting a Time-to-Live (TTL) on Write

You can set a duration in seconds for how long a key should exist before it is automatically deleted.

// The key 'user:123' will be automatically deleted in 60 seconds.
await kv.set('user:123', 'John Doe', ttl: 60);

Setting an Absolute Expiration Time on Write

Alternatively, you can provide a specific DateTime for when the key should expire.

// The key will be deleted at the specified time.
await kv.set(
  'user:123',
  'John Doe',
  expires: DateTime.now().add(Duration(minutes: 5))
);

When to Use TTL vs. Absolute Expiration

• TTL (time-to-live) is best for short-lived cache data where the lifetime starts from the moment of creation (e.g., "keep this for 5 minutes").
• Absolute expiration is best when data must expire at a fixed point in time, regardless of when it was created (e.g., "delete this at midnight").

Performance: Hot vs Cold Reads

Understanding Edge Caching

Globe KV uses edge locations (Points of Presence, POPs) to cache data closer to users, reducing latency. When you request data:

• If the data is already cached at a nearby edge location, it's a Hot Read (very fast).
• If the data is not cached, it must be fetched from the central store, resulting in a Cold Read (slower).

By default, the cache for a hot read lasts 60 seconds.

Controlling Edge Cache with ttl on Reads

You can control how long a value is cached at the edge by providing a ttl parameter to the get method. This ttl specifies a cache time-to-live for the read result and does not affect the original key's expiration that was set using kv.set().

To cache a read result for longer than the 60-second default, provide a custom ttl (in seconds):

// Read the key and cache the result at the edge for 24 hours.
// This does NOT change the underlying expiration of 'user:123'.
await kv.get('user:123', ttl: 60 * 60 * 24);

Use this for data that rarely changes, like feature flags or app settings, to ensure most reads are hot and fast for your users.

Eventual Consistency

Globe KV is not fully consistent—updates may take up to 60 seconds to reflect globally.

Good for:

• User preferences
• Feature flags
• Non-critical cached data

Not suitable for:

• Financial transactions
• Real-time counters

For Less Frequent Updates, Use a Longer Cache

If your data doesn't change often, increasing the TTL on reads can improve performance:

await kv.get('user:123', ttl: 60 * 60 * 24); // Cache for 24 hours

This reduces cold reads and improves performance for users.