Core Concepts

Actionbase is a database for serving user interactions—not a general-purpose graph database.

Design Goals

• Write-Time Optimization — Pre-compute read structures at write time. Reads become simple lookups.
• Leverage Proven Storage — Build on HBase for durability and scale. Don’t reinvent storage.

Interaction Axes

Every interaction is expressed in the same model — who did what to which target (source → action → target). The combination of source and target yields three axes:

• User–User (U2U) — follow/unfollow, follower/following counts, timeline scans
• User–Item (U2I) — likes/bookmarks, view history, bidirectional counters
• Item–Item (I2I) — related products, similar-content graphs, and other precomputed item-to-item relations

They look different on the surface, but share the same structure: real-time access with predictable query patterns.

Property Graph Model

Actionbase models interactions as edges:

• Source: who or what acts (e.g., user_id, product_id)
• Target: what is acted on (e.g., product_id, content_id, user_id)
• Properties: schema-defined attributes (e.g., created_at, reaction_type)

User --[likes]--> Product (edge)
  ├─ source: "user123"
  ├─ target: "product456"
  └─ properties: {
      created_at: 1234567890,
      reaction_type: "heart"
    }

User --[follows]--> User (edge)
  ├─ source: "user123"
  ├─ target: "user789"
  └─ properties: {
      created_at: 1234567891
    }

Product --[related]--> Product (edge)
  ├─ source: "product456"
  ├─ target: "product789"
  └─ properties: {
      score: 0.87
    }

See Schema for defining your edges.

State and Event Model

Actionbase uses a state-based mutation model:

• State: current state (e.g., “user liked product”)
• Event: input that transitions state (e.g., “user clicked like”)

When an interaction occurs:

1. Read current state
2. Apply state transition
3. Store new state

Clients attach timestamps to events. Even if events arrive out of order, Actionbase computes the correct final state.

See Mutation for details.

Write-Time Optimization

When an edge is written, Actionbase pre-computes:

1. State — current relationship between source and target
2. Index — ordered structures based on properties (e.g., created_at DESC)
3. Count — counters (e.g., number of likes per item)

Reads use simple GET, COUNT, SCAN operations without query-time computation.

See Mutation for how these are created. See Query for how to access them.

Data Flow

Write Path

Client → Server → Engine → WAL → Storage → CDC

1. Write to WAL for durability
2. Acquire lock
3. Read current state
4. Apply state transition
5. Compute indexes and counters
6. Write to storage
7. Emit CDC for downstream systems

See Mutation.

Read Path

Client → Server → Engine → Storage → Response

• COUNT → EdgeCounter
• GET → EdgeState
• SCAN → EdgeIndex

See Query.

Next Steps

• Schema: Define edge structure
• Guides: Hands-on tutorial