Mutation API Reference

Caution

Authentication is not enforced. See API References.

Edge mutation API. See Mutation for conceptual background.

1. Edge Mutation

Mutate edges between source nodes and target nodes.

Endpoint

POST /graph/v3/databases/{database}/tables/{table}/edges

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Target database name
Path	table	Required	Target table name
Query	lock	Optional (default: true)	Whether to acquire lock during mutation
Body	mutations	Required	List of mutation items

Request Body

EdgeBulkMutationRequest - Payload containing mutation items

Response Type

EdgeMutationResponse - Payload containing mutation results

Request Example

Parameter	Value
Authorization	YOUR_API_KEY
database	your_database
table	your_table
lock	true

# POST /graph/v3/databases/your_database/tables/your_table/edges
curl -X POST \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges?lock=true" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mutations": [
        {
          "type": "INSERT",
          "edge": {
            "version": 1,
            "source": "source1",
            "target": "target1",
            "properties": {
              "weight": 0.8,
              "type": "FOLLOWS"
            }
          }
        }
      ]
    }'

Response Example

{
  "results": [
    {
      "source": "source1",
      "target": "target1",
      "status": "CREATED",
      "count": 1
    }
  ]
}

2. Edge Mutation (Sync)

Mutate edges synchronously. This endpoint waits for the mutation to complete before returning a response.

Endpoint

POST /graph/v3/databases/{database}/tables/{table}/edges/sync

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Target database name
Path	table	Required	Target table name
Query	lock	Optional (default: true)	Whether to acquire lock during mutation
Body	mutations	Required	List of mutation items

Request Body

EdgeBulkMutationRequest - Payload containing mutation items

Response Type

EdgeMutationResponse - Payload containing mutation results

Request Example

Parameter	Value
Authorization	YOUR_API_KEY
database	your_database
table	your_table
lock	true

# POST /graph/v3/databases/your_database/tables/your_table/edges/sync
curl -X POST \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/sync?lock=true" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mutations": [
        {
          "type": "UPDATE",
          "edge": {
            "version": 2,
            "source": "source1",
            "target": "target1",
            "properties": {
              "weight": 0.9,
              "type": "FOLLOWS"
            }
          }
        }
      ]
    }'

Response Example

{
  "results": [
    {
      "source": "source1",
      "target": "target1",
      "status": "UPDATED",
      "count": 1
    }
  ]
}

3. Multi-Edge Mutation

Mutate multi-edges identified by edge IDs.

Endpoint

POST /graph/v3/databases/{database}/tables/{table}/multi-edges

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Target database name
Path	table	Required	Target table name
Query	lock	Optional (default: true)	Whether to acquire lock during mutation
Body	mutations	Required	List of mutation items

Request Body

MultiEdgeBulkMutationRequest - Payload containing mutation items

Response Type

MultiEdgeMutationResponse - Payload containing mutation results

Request Example

Parameter	Value
Authorization	YOUR_API_KEY
database	your_database
table	your_table
lock	true

# POST /graph/v3/databases/your_database/tables/your_table/multi-edges
curl -X POST \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/multi-edges?lock=true" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mutations": [
        {
          "type": "INSERT",
          "edge": {
            "version": 1,
            "id": "edge1",
            "source": "source1",
            "target": "target1",
            "properties": {
              "weight": 0.8,
              "type": "FOLLOWS"
            }
          }
        }
      ]
    }'

Response Example

{
  "results": [
    {
      "id": "edge1",
      "status": "CREATED",
      "count": 1
    }
  ]
}

4. Multi-Edge Mutation (Sync)

Mutate multi-edges synchronously. This endpoint waits for the mutation to complete before returning a response.

Endpoint

POST /graph/v3/databases/{database}/tables/{table}/multi-edges/sync

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Target database name
Path	table	Required	Target table name
Query	lock	Optional (default: true)	Whether to acquire lock during mutation
Body	mutations	Required	List of mutation items

Request Body

MultiEdgeBulkMutationRequest - Payload containing mutation items

Response Type

MultiEdgeMutationResponse - Payload containing mutation results

Request Example

Parameter	Value
Authorization	YOUR_API_KEY
database	your_database
table	your_table
lock	true

# POST /graph/v3/databases/your_database/tables/your_table/multi-edges/sync
curl -X POST \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/multi-edges/sync?lock=true" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mutations": [
        {
          "type": "DELETE",
          "edge": {
            "version": 3,
            "id": "edge1",
            "source": "source1",
            "target": "target1",
            "properties": {}
          }
        }
      ]
    }'

Response Example

{
  "results": [
    {
      "id": "edge1",
      "status": "DELETED",
      "count": 1
    }
  ]
}

5. Scan-Delete (Immutable Edge Tables)

Scan an index range on an immutable edge table and delete the matched rows, returning the count deleted. Used for eviction and retention.

Rejected with 400 on non-immutable tables. limit is required and capped at 1000; one call deletes at most one page, so loop until the returned count is below limit to drain a larger range.

Endpoint

DELETE /graph/v3/databases/{database}/tables/{table}/edges/scan/{index}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Target database name
Path	table	Required	Target table name (must be an immutable edge table)
Path	index	Required	Index to scan
Query	start	Required	Source node to scan from
Query	direction	Required	Scan direction (OUT, IN)
Query	limit	Required	Max rows to delete in this call (maximum 1000)
Query	ranges	Optional	Index range predicate (e.g., seq:lte:1001)

Response Type

EdgeScanDeleteResponse - The count deleted

Request Example

Parameter	Value
Authorization	YOUR_API_KEY
database	your_database
table	your_table
index	seq_asc

# DELETE /graph/v3/databases/your_database/tables/your_table/edges/scan/seq_asc
curl -X DELETE \
    "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/scan/seq_asc?start=1&direction=OUT&limit=100&ranges=seq:lte:1001" \
    -H "Authorization: YOUR_API_KEY"

Response Example

{
  "database": "your_database",
  "table": "your_table",
  "index": "seq_asc",
  "deleted": 2
}

Event Types

The type field in mutation items specifies the operation to perform:

Type	Description
INSERT	Create a new edge or update an existing edge with a new version
UPDATE	Update properties of an existing edge
DELETE	Delete an edge (marks it as deleted)

Immutable edge tables accept INSERT only; UPDATE and DELETE are rejected with 400. Rows are removed via scan-delete instead.

Lock Parameter

The lock parameter controls whether to acquire a lock during mutation:

• true (default): Acquires a lock to prevent concurrent modifications. Ensures data consistency but may have higher latency.
• false: Skips locking. Faster but may lead to race conditions if multiple mutations target the same edge simultaneously.

Note: It is recommended to use lock=true in production environments to ensure data consistency.

Data Model

EdgeBulkMutationRequest

Edge mutation request payload.

data class EdgeBulkMutationRequest(
  val mutations: List<MutationItem>, // List of mutation items
) {
  data class MutationItem(
    val type: EventType,        // Event type (INSERT, UPDATE, DELETE)
    val edge: Edge,             // Edge data
  )
}

MultiEdgeBulkMutationRequest

Multi-edge mutation request payload.

data class MultiEdgeBulkMutationRequest(
  val mutations: List<MutationItem>, // List of mutation items
) {
  data class MutationItem(
    val type: EventType,        // Event type (INSERT, UPDATE, DELETE)
    val edge: MultiEdge,        // Multi-edge data
  )
}

EdgeMutationResponse

Edge mutation response payload.

data class EdgeMutationResponse(
  val results: List<Item>,      // List of mutation results
) {
  data class Item(
    val source: Any,            // Source node ID
    val target: Any,            // Target node ID
    val status: String,         // Mutation status (e.g., CREATED, UPDATED, DELETED)
    val count: Int,             // Number of edges affected
  )
}

MultiEdgeMutationResponse

Multi-edge mutation response payload.

data class MultiEdgeMutationResponse(
  val results: List<Item>,      // List of mutation results
) {
  data class Item(
    val id: Any,               // Edge ID
    val status: String,         // Mutation status (e.g., CREATED, UPDATED, DELETED)
    val count: Int,             // Number of edges affected
  )
}

Edge

Individual edge information for mutation.

data class Edge(
  val version: Long,                 // Edge version
  val source: Any,                   // Source node ID
  val target: Any,                   // Target node ID
  val properties: Map<String, Any?>, // Edge properties
)

MultiEdge

Individual multi-edge information for mutation.

data class MultiEdge(
  val version: Long,                 // Edge version
  val id: Any,                       // Edge ID
  val source: Any? = null,           // Source node ID (optional)
  val target: Any? = null,           // Target node ID (optional)
  val properties: Map<String, Any?>,  // Edge properties
)

EdgeScanDeleteResponse

Scan-delete response payload.

data class EdgeScanDeleteResponse(
  val database: String,  // Target database name
  val table: String,     // Target table name
  val index: String,     // Index that was scanned
  val deleted: Int,      // Rows deleted by this call (at most `limit`)
)