Quick Start

Note

This guide assumes a local, in-memory setup for quick evaluation.

Prerequisites

• Java 17

Start Actionbase

Clone the repository and start the server:

git clone https://github.com/kakao/actionbase.git
cd actionbase
./gradlew :server:bootRun

    _        _   _             _
   / \   ___| |_(_) ___  _ __ | |__   __ _ ___  ___
  / _ \ / __| __| |/ _ \| '_ \| '_ \ / _` / __|/ _ \
 / ___ \ (__| |_| | (_) | | | | |_) | (_| \__ \  __/
/_/   \_\___|\__|_|\___/|_| |_|_.__/ \__,_|___/\___| (0.0.1-SNAPSHOT, ...................)

* Java: 17.0.13
* Tenant: ab-none
* startUp: ...................
* activeProfiles: default
* Datastore: MEMORY {}

✅ The server is now running at http://localhost:8080 and ready to accept requests.

ℹ️ bootRun runs in the foreground. Use another terminal for the next steps.

Define metadata

Note

Metadata management currently uses v2 APIs (service / label), while data read & write operations use v3 APIs (database / table).

Before writing any interaction data, you must define its schema and indexes using metadata APIs. In Actionbase, interactions are stored as edges in a graph model. Create a service and label to define the structure of your edges.

1. Create a service

   Create a namespace for grouping labels. In this guide, we use awesome as an example service name. See Metadata API Reference for details.

   curl -X POST "http://localhost:8080/graph/v2/service/awesome" \
     -H "Content-Type: application/json" \
     -d '{"desc":"Sample"}'

   Expected response:

   {
     "status": "CREATED",
     "result": {
       "active": true,
       "name": "awesome",
       "desc": "Sample"
     }
   }

2. Create a label

   Define the edge schema (source, target, properties) and indexes. See Metadata API Reference for details.

   Key fields:

   • src, tgt: source and target node IDs
   • fields: edge properties
   • indices: used for ordered scans

   curl -X POST "http://localhost:8080/graph/v2/service/awesome/label/likes" \
     -H "Content-Type: application/json" \
     -d '{
       "desc":"Like",
       "type":"INDEXED",
       "schema":{
         "src":{"type":"STRING"},
         "tgt":{"type":"STRING"},
         "fields":[{"name":"created_at","type":"LONG","nullable":false}]
       },
       "dirType":"BOTH",
       "storage":"datastore://awesome/likes",
       "indices":[{"name":"created_at_desc","fields":[{"name":"created_at","order":"DESC"}]}]
     }'

   Expected response:

   {
     "status": "CREATED",
     "result": {
       "active": true,
       "name": "awesome.likes",
       "desc": "Like",
       "type": "INDEXED",
       "schema": {
         "src": {"type": "STRING", "desc": ""},
         "tgt": {"type": "STRING", "desc": ""},
         "fields": [{"name": "created_at", "type": "LONG", "nullable": false, "desc": ""}]
       },
       "dirType": "BOTH",
       "storage": "datastore://awesome/likes",
       "groups": [],
       "indices": [{
         "name": "created_at_desc",
         "fields": [{"name": "created_at", "order": "DESC"}],
         "desc": ""
       }],
       "event": false,
       "readOnly": false,
       "mode": "SYNC"
     }
   }

Write edges

Insert interaction edges to record user actions.

1. Insert edges

   Record user actions as edges. See Mutation API Reference for details.

   Key fields:

   • version: edge version used for concurrency control and out-of-order event handling
   • created_at: application-level timestamp stored as a property

   In this example, we use the same timestamp for both version and created_at for simplicity. Use the timestamp when the user performed the action. See FAQ - How does Actionbase handle out-of-order events? for details.

   graph LR
       Alice((Alice)) -->|likes| Phone((📱 Phone))
       Alice -->|likes| Laptop((💻 Laptop))
       Bob((Bob)) -->|likes| Phone

   curl -X POST "http://localhost:8080/graph/v3/databases/awesome/tables/likes/edges" \
     -H "Content-Type: application/json" \
     -d '{
       "mutations":[
         {"type":"INSERT","edge":{"version":1767571200000,"source":"Alice","target":"Phone","properties":{"created_at":1767571200000}}},
         {"type":"INSERT","edge":{"version":1767571200000,"source":"Alice","target":"Laptop","properties":{"created_at":1767571200000}}},
         {"type":"INSERT","edge":{"version":1767571200000,"source":"Bob","target":"Phone","properties":{"created_at":1767571200000}}}
       ]
     }'

   Expected response:

   {
     "results": [
       {"source": "Alice", "target": "Laptop", "status": "CREATED", "count": 1},
       {"source": "Alice", "target": "Phone", "status": "CREATED", "count": 1},
       {"source": "Bob", "target": "Phone", "status": "CREATED", "count": 1}
     ]
   }

Read edges

Query edges using get, scan, and count operations.

1. Get

   Retrieve a specific edge by source and target. See Query API Reference for details.

   curl -X GET "http://localhost:8080/graph/v3/databases/awesome/tables/likes/edges/get?source=Alice&target=Phone"

   Expected response:

   {
     "edges": [{
       "version": 1767571200000,
       "source": "Alice",
       "target": "Phone",
       "properties": {"created_at": 1767571200000},
       "context": {}
     }],
     "count": 1,
     "total": 1,
     "offset": null,
     "hasNext": false,
     "context": {}
   }

2. Scan (Out)

   List outgoing edges from a source, ordered by index. See Query API Reference for details.

   curl -X GET "http://localhost:8080/graph/v3/databases/awesome/tables/likes/edges/scan/created_at_desc?start=Alice&direction=OUT"

   Expected response:

   {
     "edges": [
       {
         "version": 1767571200000,
         "source": "Alice",
         "target": "Laptop",
         "properties": {"created_at": 1767571200000},
         "context": {}
       },
       {
         "version": 1767571200000,
         "source": "Alice",
         "target": "Phone",
         "properties": {"created_at": 1767571200000},
         "context": {}
       }
     ],
     "count": 2,
     "total": -1,
     "offset": null,
     "hasNext": false,
     "context": {}
   }

3. Scan (In)

   List incoming edges to a target, ordered by index. See Query API Reference for details.

   curl -X GET "http://localhost:8080/graph/v3/databases/awesome/tables/likes/edges/scan/created_at_desc?start=Phone&direction=IN"

   Expected response:

   {
     "edges": [
       {
         "version": 1767571200000,
         "source": "Alice",
         "target": "Phone",
         "properties": {"created_at": 1767571200000},
         "context": {}
       },
       {
         "version": 1767571200000,
         "source": "Bob",
         "target": "Phone",
         "properties": {"created_at": 1767571200000},
         "context": {}
       }
     ],
     "count": 2,
     "total": -1,
     "offset": null,
     "hasNext": false,
     "context": {}
   }

4. Count

   Count edges for a specific direction. See Query API Reference for details.

   curl -X GET "http://localhost:8080/graph/v3/databases/awesome/tables/likes/edges/count?start=Alice&direction=OUT"

   Expected response:

   {
     "start": "Alice",
     "direction": "OUT",
     "count": 2,
     "context": {}
   }

   Count incoming edges:

   curl -X GET "http://localhost:8080/graph/v3/databases/awesome/tables/likes/edges/count?start=Phone&direction=IN"

   Expected response:

   {
     "start": "Phone",
     "direction": "IN",
     "count": 2,
     "context": {}
   }

Stop Actionbase

Terminate the bootRun process (Ctrl+C) to stop the server.