Schema

Schema defines the structure of interaction data. Before storing data, define how edges are structured, what properties they have, and how they can be queried.

See Core Concepts for background.

Schema Hierarchy

Note

Actionbase was open-sourced during the v3 transition. Most docs use v3 terms, but this document uses v2 terms (current Schema API). v3 terms are noted in parentheses. See the last section for full mapping.

Service (v3: Database)
├── Label (v3: Table)
│   ├── Schema (src, tgt, fields)
│   └── Indices (v3: Indexes)
└── Alias

• Service groups related Labels and Aliases
• Label defines the schema for edges
• Alias provides an alternative name for a Label

Service (v3: Database)

A namespace that contains labels and aliases.

Property	Description
name	Service identifier (e.g., myservice)
desc	Description (v3: comment)
active	Whether active

Example: an e-commerce service might contain labels for likes, recent_views, and purchases.

Label (v3: Table)

Defines the schema for edges—src, tgt, fields, and indices.

Property	Description
name	Format: service.label
desc	Description (v3: comment)
type	Label type (INDEXED, HASH, MULTI_EDGE, IMMUTABLE_INDEXED)
schema	Edge structure (src, tgt, fields)
dirType	Direction type (v3: direction)
storage	Storage URI (e.g., datastore://<namespace>/<table>)
indices	Indices for querying (v3: indexes)
active	Whether active

Schema Definition

• src (v3: source): source type (STRING, LONG) — who
• tgt (v3: target): target type (STRING, LONG) — what
• fields (v3: properties): each with name, type, nullable

Example: Recent Views

src: user_id (LONG)
tgt: product_id (LONG)
fields:
  - created_at (LONG)
dirType: BOTH

Example: Reactions

src: user_id (LONG)
tgt: product_id (LONG)
fields:
  - created_at (LONG)
  - reaction_type (STRING)
dirType: BOTH

Index Definition

Indices enable efficient querying. Each index has a name and a list of fields with sort order.

indices:
  - name: by_created_at
    fields: [created_at DESC]
  - name: by_type_and_time
    fields: [reaction_type ASC, created_at DESC]

Indices are pre-computed at write time. See Query.

Immutable Edge Tables (type: IMMUTABLE_INDEXED, v3: IMMUTABLE_EDGE)

An append-only variant of the indexed label. A regular edge tracks mutable state (a like can be un-liked); an immutable edge records facts that never change, such as an event log or a message queue. Only index rows are persisted: there is no state row, no count records, and no caches. The index rows are the record.

Property	Constraint
indices	At most one index
dirType	Single direction (OUT or IN) — BOTH is rejected
mutations	INSERT only — UPDATE and DELETE are rejected

These constraints ensure every persisted row is reachable by a single index scan, so deleting the scanned rows is a complete delete. That is what makes eviction (scan-delete) safe.

Behavioral differences from a regular indexed label:

Operation	Behavior
Point get	Rejected; read with an index scan
Count / total	Not supported; no count records are written
CDC	Not emitted; the log itself is the change history
Eviction	Scan-delete removes a scanned index range

Example: Event Log

src: partition (LONG)
tgt: event_id (STRING)
fields:
  - seq (LONG)
  - payload (STRING)
dirType: OUT
indices:
  - name: seq_asc
    fields: [seq ASC]

Immutable edge tables back the queue/v1 API.

Alias

An alternative name for a label.

Property	Description
name	Format: service.alias
desc	Description (v3: comment)
target	The label it points to
active	Whether active

Useful for gradual migrations or domain-specific naming.

Naming Conventions

Type	Format	Example
Service	Simple identifier	myservice
Label	service.label	myservice.likes
Alias	service.alias	myservice.friends

Schema Versions

v2 and v3 map almost 1:1.

v2 (Current)	v3 (Future)
service	database
label	table
src	source
tgt	target
ts	version
fields	properties
dirType	direction
indices	indexes
desc	comment

Next Steps

• Mutation: Write data
• Query: Query data
• Metadata API: API reference