Metadata API Reference

Caution

Authentication is not enforced. See API References.

Metadata management API for databases, tables, and aliases.

1. List Databases

Retrieve all databases.

Endpoint

GET /graph/v3/databases

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)

Response Type

List<DatabaseDescriptor> - List of databases

Request Example

curl -X GET \
    "http://ab.example.com/graph/v3/databases" \
    -H "Authorization: YOUR_API_KEY"

Response Example

[
  {
    "tenant": "default",
    "database": "mydb",
    "active": true,
    "comment": "My database",
    "revision": 1,
    "createdAt": 1700000000000,
    "createdBy": "admin",
    "updatedAt": 1700000000000,
    "updatedBy": "admin"
  }
]

2. Get Database

Retrieve a single database by name.

Endpoint

GET /graph/v3/databases/{database}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name

Response Type

DatabaseDescriptor - Database information

Returns 404 if not found.

Request Example

curl -X GET \
    "http://ab.example.com/graph/v3/databases/mydb" \
    -H "Authorization: YOUR_API_KEY"

Response Example

{
  "tenant": "default",
  "database": "mydb",
  "active": true,
  "comment": "My database",
  "revision": 1,
  "createdAt": 1700000000000,
  "createdBy": "admin",
  "updatedAt": 1700000000000,
  "updatedBy": "admin"
}

3. Create Database

Create a new database.

Endpoint

POST /graph/v3/databases

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Body	database	Required	Database name
Body	comment	Required	Database description

Request Body

DatabaseCreateRequest - Database creation payload

Response Type

DatabaseDescriptor - Created database information

Request Example

curl -X POST \
    "http://ab.example.com/graph/v3/databases" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "database": "mydb",
      "comment": "My database"
    }'

Response Example

{
  "tenant": "default",
  "database": "mydb",
  "active": true,
  "comment": "My database",
  "revision": 1,
  "createdAt": 1700000000000,
  "createdBy": "admin",
  "updatedAt": 1700000000000,
  "updatedBy": "admin"
}

4. Update Database

Update an existing database.

Endpoint

PUT /graph/v3/databases/{database}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name
Body	active	Optional	Whether the database is active
Body	comment	Optional	Database description

Request Body

DatabaseUpdateRequest - Database update payload

Response Type

DatabaseDescriptor - Updated database information

Request Example

curl -X PUT \
    "http://ab.example.com/graph/v3/databases/mydb" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "active": true,
      "comment": "Updated description"
    }'

5. Delete Database

Delete an existing database.

Endpoint

DELETE /graph/v3/databases/{database}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name

Response Type

204 No Content (no response body)

Request Example

curl -X DELETE \
    "http://ab.example.com/graph/v3/databases/mydb" \
    -H "Authorization: YOUR_API_KEY"

6. List Tables

Retrieve all tables in a database.

Endpoint

GET /graph/v3/databases/{database}/tables

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name

Response Type

List<TableDescriptor> - List of tables

Request Example

curl -X GET \
    "http://ab.example.com/graph/v3/databases/mydb/tables" \
    -H "Authorization: YOUR_API_KEY"

7. Get Table

Retrieve a single table by name.

Endpoint

GET /graph/v3/databases/{database}/tables/{table}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name
Path	table	Required	Table name

Response Type

TableDescriptor - Table information

Returns 404 if not found.

Request Example

curl -X GET \
    "http://ab.example.com/graph/v3/databases/mydb/tables/follows" \
    -H "Authorization: YOUR_API_KEY"

Response Example

{
  "type": "edge",
  "tenant": "default",
  "database": "mydb",
  "table": "follows",
  "schema": {
    "type": "edge",
    "source": { "type": "string", "comment": "user id" },
    "target": { "type": "string", "comment": "user id" },
    "properties": [],
    "direction": "OUT",
    "indexes": [],
    "groups": []
  },
  "storage": "datastore://hbase/follows_table",
  "mode": "SYNC",
  "active": true,
  "comment": "User follows relationship",
  "revision": 1,
  "createdAt": 1700000000000,
  "createdBy": "admin",
  "updatedAt": 1700000000000,
  "updatedBy": "admin"
}

8. Create Table

Create a new table.

Endpoint

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

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name
Body	table	Required	Table name
Body	schema	Required	Edge schema definition
Body	storage	Required	Storage URI (datastore://<namespace>/<table>)
Body	mode	Optional	Mutation mode (default: SYNC)
Body	comment	Required	Table description

Request Body

TableCreateRequest - Table creation payload

Response Type

TableDescriptor - Created table information

Request Example

curl -X POST \
    "http://ab.example.com/graph/v3/databases/mydb/tables" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "table": "follows",
      "schema": {
        "type": "EDGE",
        "source": { "type": "string", "comment": "user id" },
        "target": { "type": "string", "comment": "user id" },
        "properties": [],
        "direction": "OUT",
        "indexes": [],
        "groups": []
      },
      "storage": "datastore://hbase/follows_table",
      "mode": "SYNC",
      "comment": "User follows relationship"
    }'

9. Update Table

Update an existing table.

Endpoint

PUT /graph/v3/databases/{database}/tables/{table}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name
Path	table	Required	Table name
Body	active	Optional	Whether the table is active
Body	schema	Optional	Edge schema definition
Body	mode	Optional	Mutation mode
Body	comment	Optional	Table description

Request Body

TableUpdateRequest - Table update payload

Response Type

TableDescriptor - Updated table information

Request Example

curl -X PUT \
    "http://ab.example.com/graph/v3/databases/mydb/tables/follows" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "active": true,
      "comment": "Updated description"
    }'

10. Delete Table

Delete an existing table.

Endpoint

DELETE /graph/v3/databases/{database}/tables/{table}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name
Path	table	Required	Table name

Response Type

204 No Content (no response body)

Request Example

curl -X DELETE \
    "http://ab.example.com/graph/v3/databases/mydb/tables/follows" \
    -H "Authorization: YOUR_API_KEY"

11. List Aliases

Retrieve all aliases in a database.

Endpoint

GET /graph/v3/databases/{database}/aliases

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name

Response Type

List<AliasDescriptor> - List of aliases

Request Example

curl -X GET \
    "http://ab.example.com/graph/v3/databases/mydb/aliases" \
    -H "Authorization: YOUR_API_KEY"

12. Get Alias

Retrieve a single alias by name.

Endpoint

GET /graph/v3/databases/{database}/aliases/{alias}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name
Path	alias	Required	Alias name

Response Type

AliasDescriptor - Alias information

Returns 404 if not found.

Request Example

curl -X GET \
    "http://ab.example.com/graph/v3/databases/mydb/aliases/friends" \
    -H "Authorization: YOUR_API_KEY"

Response Example

{
  "tenant": "default",
  "database": "mydb",
  "alias": "friends",
  "table": "follows",
  "active": true,
  "comment": "Alias for follows",
  "revision": 1,
  "createdAt": 1700000000000,
  "createdBy": "admin",
  "updatedAt": 1700000000000,
  "updatedBy": "admin"
}

13. Create Alias

Create a new alias.

Endpoint

POST /graph/v3/databases/{database}/aliases

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name
Body	alias	Required	Alias name
Body	table	Required	Target table name (same database only)
Body	comment	Required	Alias description

Request Body

AliasCreateRequest - Alias creation payload

Response Type

AliasDescriptor - Created alias information

Request Example

curl -X POST \
    "http://ab.example.com/graph/v3/databases/mydb/aliases" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "alias": "friends",
      "table": "follows",
      "comment": "Alias for follows"
    }'

14. Update Alias

Update an existing alias.

Endpoint

PUT /graph/v3/databases/{database}/aliases/{alias}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name
Path	alias	Required	Alias name
Body	active	Optional	Whether the alias is active
Body	table	Optional	Target table name
Body	comment	Optional	Alias description

Request Body

AliasUpdateRequest - Alias update payload

Response Type

AliasDescriptor - Updated alias information

Request Example

curl -X PUT \
    "http://ab.example.com/graph/v3/databases/mydb/aliases/friends" \
    -H "Authorization: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "active": false,
      "comment": "Deactivated alias"
    }'

15. Delete Alias

Delete an existing alias.

Note

Alias must be deactivated (active: false) before deletion.

Endpoint

DELETE /graph/v3/databases/{database}/aliases/{alias}

Parameters

Location	Parameter	Required	Description
Header	Authorization	Optional	Authentication key (reserved for future use)
Path	database	Required	Database name
Path	alias	Required	Alias name

Response Type

204 No Content (no response body)

Request Example

curl -X DELETE \
    "http://ab.example.com/graph/v3/databases/mydb/aliases/friends" \
    -H "Authorization: YOUR_API_KEY"

Data Model

DatabaseDescriptor

Database information payload.

data class DatabaseDescriptor(
    val tenant: String,       // Tenant name
    val database: String,     // Database name
    val active: Boolean,      // Whether the database is active
    val comment: String,      // Database description
    val revision: Long,       // Revision number
    val createdAt: Long,      // Creation timestamp
    val createdBy: String,    // Creator
    val updatedAt: Long,      // Last update timestamp
    val updatedBy: String,    // Last updater
)

TableDescriptor

Table information payload. Two types are supported: edge and multiEdge.

TableDescriptor.Edge

data class TableDescriptor.Edge(
    val type: String = "edge",     // Table type discriminator
    val tenant: String,            // Tenant name
    val database: String,          // Database name
    val table: String,             // Table name
    val schema: ModelSchema.Edge,  // Edge schema definition
    val storage: String,           // Storage URI (`datastore://<namespace>/<table>`)
    val mode: MutationMode,        // Mutation mode (SYNC, ASYNC, DROP)
    val active: Boolean,           // Whether the table is active
    val comment: String,           // Table description
    val revision: Long,            // Revision number
    val createdAt: Long,           // Creation timestamp
    val createdBy: String,         // Creator
    val updatedAt: Long,           // Last update timestamp
    val updatedBy: String,         // Last updater
)

TableDescriptor.MultiEdge

data class TableDescriptor.MultiEdge(
    val type: String = "multiEdge",     // Table type discriminator
    val tenant: String,                 // Tenant name
    val database: String,               // Database name
    val table: String,                  // Table name
    val schema: ModelSchema.MultiEdge,  // MultiEdge schema definition
    val storage: String,                // Storage URI (`datastore://<namespace>/<table>`)
    val mode: MutationMode,             // Mutation mode (SYNC, ASYNC, DROP)
    val active: Boolean,                // Whether the table is active
    val comment: String,                // Table description
    val revision: Long,                 // Revision number
    val createdAt: Long,                // Creation timestamp
    val createdBy: String,              // Creator
    val updatedAt: Long,                // Last update timestamp
    val updatedBy: String,              // Last updater
)

AliasDescriptor

Alias information payload.

data class AliasDescriptor(
    val tenant: String,       // Tenant name
    val database: String,     // Database name
    val alias: String,        // Alias name
    val table: String,        // Target table name
    val active: Boolean,      // Whether the alias is active
    val comment: String,      // Alias description
    val revision: Long,       // Revision number
    val createdAt: Long,      // Creation timestamp
    val createdBy: String,    // Creator
    val updatedAt: Long,      // Last update timestamp
    val updatedBy: String,    // Last updater
)

ModelSchema.Edge

Edge schema definition. The type discriminator is "EDGE" in requests and "edge" in responses.

data class ModelSchema.Edge(
    val type: String,                               // "EDGE" (request) / "edge" (response)
    val source: Field,                              // Source vertex field
    val target: Field,                              // Target vertex field
    val properties: List<StructField> = emptyList(),// Edge properties
    val direction: DirectionType,                   // Direction type (OUT, IN, BOTH)
    val indexes: List<Index> = emptyList(),          // Index definitions
    val groups: List<Group> = emptyList(),            // Group definitions
)

ModelSchema.MultiEdge

MultiEdge schema definition. Supports multiple edges between the same source-target pair, distinguished by an id field. The type discriminator is "MULTI_EDGE" in requests and "multiEdge" in responses.

data class ModelSchema.MultiEdge(
    val type: String,                               // "MULTI_EDGE" (request) / "multiEdge" (response)
    val id: Field,                                  // Edge identifier field (distinguishes multiple edges)
    val source: Field,                              // Source vertex field
    val target: Field,                              // Target vertex field
    val properties: List<StructField> = emptyList(),// Edge properties
    val direction: DirectionType,                   // Direction type (OUT, IN, BOTH)
    val indexes: List<Index> = emptyList(),          // Index definitions
    val groups: List<Group> = emptyList(),            // Group definitions
)

Field

Vertex field definition. The type value is lowercase in JSON (e.g., "string", "long").

data class Field(
    val type: PrimitiveType,  // Data type (JSON: lowercase, e.g., "string", "long")
    val comment: String,      // Field description
)

StructField

Property field definition. The type value is lowercase in JSON (e.g., "int", "long").

data class StructField(
    val name: String,         // Field name
    val type: PrimitiveType,  // Data type (JSON: lowercase, e.g., "int", "long")
    val comment: String,      // Field description
    val nullable: Boolean,    // Whether the field is nullable
)

Index

Index definition.

data class Index(
    val index: String,                              // Index name
    val fields: List<IndexField>,                   // Indexed fields with sort order
    val comment: String = "",                       // Index description
)

IndexField

Index field definition.

data class IndexField(
    val field: String,  // Field name
    val order: Order,   // Sort order (ASC, DESC)
)

Group

Group definition for aggregation queries.

data class Group(
    val group: String,                              // Group name
    val type: GroupType,                            // Aggregation type (SUM, COUNT)
    val fields: List<GroupField>,                   // Group key fields
    val valueField: String = "-",                   // Value field name
    val comment: String = "",                       // Group description
    val directionType: DirectionType = BOTH,        // Direction type
    val ttl: Long = -1,                             // Time-to-live in milliseconds (-1 = no expiry)
)

DatabaseCreateRequest

Database creation request payload.

data class DatabaseCreateRequest(
    val database: String,     // Database name
    val comment: String,      // Database description
)

DatabaseUpdateRequest

Database update request payload.

data class DatabaseUpdateRequest(
    val active: Boolean?,     // Whether the database is active (optional)
    val comment: String?,     // Database description (optional)
)

TableCreateRequest

Table creation request payload.

data class TableCreateRequest(
    val table: String,             // Table name
    val schema: ModelSchema,       // Schema definition (ModelSchema.Edge or ModelSchema.MultiEdge)
    val storage: String,           // Storage URI (`datastore://<namespace>/<table>`)
    val mode: MutationMode,        // Mutation mode (default: SYNC)
    val comment: String,           // Table description
)

TableUpdateRequest

Table update request payload.

data class TableUpdateRequest(
    val active: Boolean?,          // Whether the table is active (optional)
    val schema: ModelSchema?,      // Schema definition (optional, ModelSchema.Edge or ModelSchema.MultiEdge)
    val mode: MutationMode?,       // Mutation mode (optional)
    val comment: String?,          // Table description (optional)
)

AliasCreateRequest

Alias creation request payload.

data class AliasCreateRequest(
    val alias: String,        // Alias name
    val table: String,        // Target table name (same database only)
    val comment: String,      // Alias description
)

AliasUpdateRequest

Alias update request payload.

data class AliasUpdateRequest(
    val active: Boolean?,     // Whether the alias is active (optional)
    val table: String?,       // Target table name (optional)
    val comment: String?,     // Alias description (optional)
)

Enums

enum class MutationMode { SYNC, ASYNC, DROP, DENY }
enum class DirectionType { BOTH, OUT, IN }
enum class PrimitiveType { BOOLEAN, BYTE, SHORT, INT, LONG, FLOAT, DOUBLE, STRING, OBJECT }
enum class Order { ASC, DESC }
enum class GroupType { SUM, COUNT }

Note

PrimitiveType values are serialized as lowercase in JSON (e.g., "string", "int", "long"). All other enums use uppercase (e.g., "SYNC", "OUT").

Validation Rules

Field	Rule
Database / Table / Alias name	^[a-zA-Z][a-zA-Z0-9_-]{0,63}$ — starts with a letter, max 64 chars
Storage URI	^datastore://[a-z_]+/[a-zA-Z0-9_]+$
Comment	Max 1000 characters

V2 Compatibility

V3 API wraps the existing V2 DDL services with a new interface. The table below shows the mapping between V2 and V3 terminology.

Terminology Mapping

V2 Term	V3 Term	Description
Service	Database	Logical database
Label	Table	Table with edge schema
Alias	Alias	Table alias (unchanged)

Label Type Mapping

V2 LabelType	V3 Table Type	Conversion
INDEXED	edge	Bidirectional
MULTI_EDGE	multiEdge	Bidirectional
HASH	edge	One-way (V2 to V3 only, deprecated)

API Endpoint Mapping

V2 Endpoint	V3 Endpoint
GET /graph/v2/services	GET /graph/v3/databases
GET /graph/v2/services/{service}	GET /graph/v3/databases/{database}
POST /graph/v2/services/{service}	POST /graph/v3/databases
PUT /graph/v2/services/{service}	PUT /graph/v3/databases/{database}
DELETE /graph/v2/services/{service}	DELETE /graph/v3/databases/{database}
GET /graph/v2/services/{service}/labels	GET /graph/v3/databases/{database}/tables
GET /graph/v2/services/{service}/labels/{label}	GET /graph/v3/databases/{database}/tables/{table}
POST /graph/v2/services/{service}/labels/{label}	POST /graph/v3/databases/{database}/tables
PUT /graph/v2/services/{service}/labels/{label}	PUT /graph/v3/databases/{database}/tables/{table}
DELETE /graph/v2/services/{service}/labels/{label}	DELETE /graph/v3/databases/{database}/tables/{table}
GET /graph/v2/services/{service}/aliases	GET /graph/v3/databases/{database}/aliases
GET /graph/v2/services/{service}/aliases/{alias}	GET /graph/v3/databases/{database}/aliases/{alias}
POST /graph/v2/services/{service}/aliases/{alias}	POST /graph/v3/databases/{database}/aliases
PUT /graph/v2/services/{service}/aliases/{alias}	PUT /graph/v3/databases/{database}/aliases/{alias}
DELETE /graph/v2/services/{service}/aliases/{alias}	DELETE /graph/v3/databases/{database}/aliases/{alias}

MutationMode Mapping

V2 Mode	V3 Mode	Description
SYNC	SYNC	Synchronous mutation
ASYNC	ASYNC	Asynchronous mutation
IGNORE	DROP	Drop mutations silently
-	DENY	Deny mutations (V3 only, throws error)

V3 Alias Constraints

V3 aliases can only reference tables within the same database. Cross-database aliases (supported in V2 via database.table format) are not available in V3.