API: API reference documentation # REST API > Actionbase REST API reference Actionbase provides REST APIs for metadata management, mutations, and queries. ## Base URL [Section titled “Base URL”](#base-url) * Local: `http://localhost:8080` * Deployed: your server URL (e.g., `http://ab.example.com`) ## Authentication [Section titled “Authentication”](#authentication) Internally, Actionbase uses a custom authentication system. We abstracted it via `CustomTokenFilter` interface, but weren’t confident the implementation was ready for public release due to security considerations. Given the time available, we focused on documentation and developer experience, leaving the interface without a default implementation. The `Authorization` header is accepted but not validated—any value works, or omit it entirely. As we continue documenting production operations, we plan to provide authentication support as well. ## APIs [Section titled “APIs”](#apis) * [Metadata API](/api-references/metadata/) — Manage databases, tables, and aliases (v3) * [Mutation API](/api-references/mutation/) — Create, update, and delete edges (v3) * [Query API](/api-references/query/) — Query edges by count, scan, or get (v3) # Metadata API Reference > Metadata management API reference Caution Authentication is not enforced. See [API References](/api-references/#authentication). Metadata management API for databases, tables, and aliases. ## 1. List Databases [Section titled “1. List Databases”](#1-list-databases) Retrieve all databases. ### Endpoint [Section titled “Endpoint”](#endpoint) ```plaintext GET /graph/v3/databases ``` ### Parameters [Section titled “Parameters”](#parameters) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | ### Response Type [Section titled “Response Type”](#response-type) `List<`[DatabaseDescriptor](#databasedescriptor)`>` - List of databases ### Request Example [Section titled “Request Example”](#request-example) ```bash curl -X GET \ "http://ab.example.com/graph/v3/databases" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example) ```json [ { "tenant": "default", "database": "mydb", "active": true, "comment": "My database", "revision": 1, "createdAt": 1700000000000, "createdBy": "admin", "updatedAt": 1700000000000, "updatedBy": "admin" } ] ``` ## 2. Get Database [Section titled “2. Get Database”](#2-get-database) Retrieve a single database by name. ### Endpoint [Section titled “Endpoint”](#endpoint-1) ```plaintext GET /graph/v3/databases/{database} ``` ### Parameters [Section titled “Parameters”](#parameters-1) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | database | Required | Database name | ### Response Type [Section titled “Response Type”](#response-type-1) [DatabaseDescriptor](#databasedescriptor) - Database information Returns 404 if not found. ### Request Example [Section titled “Request Example”](#request-example-1) ```bash curl -X GET \ "http://ab.example.com/graph/v3/databases/mydb" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-1) ```json { "tenant": "default", "database": "mydb", "active": true, "comment": "My database", "revision": 1, "createdAt": 1700000000000, "createdBy": "admin", "updatedAt": 1700000000000, "updatedBy": "admin" } ``` ## 3. Create Database [Section titled “3. Create Database”](#3-create-database) Create a new database. ### Endpoint [Section titled “Endpoint”](#endpoint-2) ```plaintext POST /graph/v3/databases ``` ### Parameters [Section titled “Parameters”](#parameters-2) | 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 [Section titled “Request Body”](#request-body) [DatabaseCreateRequest](#databasecreaterequest) - Database creation payload ### Response Type [Section titled “Response Type”](#response-type-2) [DatabaseDescriptor](#databasedescriptor) - Created database information ### Request Example [Section titled “Request Example”](#request-example-2) ```bash 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 [Section titled “Response Example”](#response-example-2) ```json { "tenant": "default", "database": "mydb", "active": true, "comment": "My database", "revision": 1, "createdAt": 1700000000000, "createdBy": "admin", "updatedAt": 1700000000000, "updatedBy": "admin" } ``` ## 4. Update Database [Section titled “4. Update Database”](#4-update-database) Update an existing database. ### Endpoint [Section titled “Endpoint”](#endpoint-3) ```plaintext PUT /graph/v3/databases/{database} ``` ### Parameters [Section titled “Parameters”](#parameters-3) | 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 [Section titled “Request Body”](#request-body-1) [DatabaseUpdateRequest](#databaseupdaterequest) - Database update payload ### Response Type [Section titled “Response Type”](#response-type-3) [DatabaseDescriptor](#databasedescriptor) - Updated database information ### Request Example [Section titled “Request Example”](#request-example-3) ```bash 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 [Section titled “5. Delete Database”](#5-delete-database) Delete an existing database. ### Endpoint [Section titled “Endpoint”](#endpoint-4) ```plaintext DELETE /graph/v3/databases/{database} ``` ### Parameters [Section titled “Parameters”](#parameters-4) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | database | Required | Database name | ### Response Type [Section titled “Response Type”](#response-type-4) 204 No Content (no response body) ### Request Example [Section titled “Request Example”](#request-example-4) ```bash curl -X DELETE \ "http://ab.example.com/graph/v3/databases/mydb" \ -H "Authorization: YOUR_API_KEY" ``` ## 6. List Tables [Section titled “6. List Tables”](#6-list-tables) Retrieve all tables in a database. ### Endpoint [Section titled “Endpoint”](#endpoint-5) ```plaintext GET /graph/v3/databases/{database}/tables ``` ### Parameters [Section titled “Parameters”](#parameters-5) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | database | Required | Database name | ### Response Type [Section titled “Response Type”](#response-type-5) `List<`[TableDescriptor](#tabledescriptor)`>` - List of tables ### Request Example [Section titled “Request Example”](#request-example-5) ```bash curl -X GET \ "http://ab.example.com/graph/v3/databases/mydb/tables" \ -H "Authorization: YOUR_API_KEY" ``` ## 7. Get Table [Section titled “7. Get Table”](#7-get-table) Retrieve a single table by name. ### Endpoint [Section titled “Endpoint”](#endpoint-6) ```plaintext GET /graph/v3/databases/{database}/tables/{table} ``` ### Parameters [Section titled “Parameters”](#parameters-6) | 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 [Section titled “Response Type”](#response-type-6) [TableDescriptor](#tabledescriptor) - Table information Returns 404 if not found. ### Request Example [Section titled “Request Example”](#request-example-6) ```bash curl -X GET \ "http://ab.example.com/graph/v3/databases/mydb/tables/follows" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-3) ```json { "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 [Section titled “8. Create Table”](#8-create-table) Create a new table. ### Endpoint [Section titled “Endpoint”](#endpoint-7) ```plaintext POST /graph/v3/databases/{database}/tables ``` ### Parameters [Section titled “Parameters”](#parameters-7) | 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:///`) | | Body | mode | Optional | Mutation mode (default: SYNC) | | Body | comment | Required | Table description | ### Request Body [Section titled “Request Body”](#request-body-2) [TableCreateRequest](#tablecreaterequest) - Table creation payload ### Response Type [Section titled “Response Type”](#response-type-7) [TableDescriptor](#tabledescriptor) - Created table information ### Request Example [Section titled “Request Example”](#request-example-7) ```bash 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 [Section titled “9. Update Table”](#9-update-table) Update an existing table. ### Endpoint [Section titled “Endpoint”](#endpoint-8) ```plaintext PUT /graph/v3/databases/{database}/tables/{table} ``` ### Parameters [Section titled “Parameters”](#parameters-8) | 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 [Section titled “Request Body”](#request-body-3) [TableUpdateRequest](#tableupdaterequest) - Table update payload ### Response Type [Section titled “Response Type”](#response-type-8) [TableDescriptor](#tabledescriptor) - Updated table information ### Request Example [Section titled “Request Example”](#request-example-8) ```bash 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 [Section titled “10. Delete Table”](#10-delete-table) Delete an existing table. ### Endpoint [Section titled “Endpoint”](#endpoint-9) ```plaintext DELETE /graph/v3/databases/{database}/tables/{table} ``` ### Parameters [Section titled “Parameters”](#parameters-9) | 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 [Section titled “Response Type”](#response-type-9) 204 No Content (no response body) ### Request Example [Section titled “Request Example”](#request-example-9) ```bash curl -X DELETE \ "http://ab.example.com/graph/v3/databases/mydb/tables/follows" \ -H "Authorization: YOUR_API_KEY" ``` ## 11. List Aliases [Section titled “11. List Aliases”](#11-list-aliases) Retrieve all aliases in a database. ### Endpoint [Section titled “Endpoint”](#endpoint-10) ```plaintext GET /graph/v3/databases/{database}/aliases ``` ### Parameters [Section titled “Parameters”](#parameters-10) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | database | Required | Database name | ### Response Type [Section titled “Response Type”](#response-type-10) `List<`[AliasDescriptor](#aliasdescriptor)`>` - List of aliases ### Request Example [Section titled “Request Example”](#request-example-10) ```bash curl -X GET \ "http://ab.example.com/graph/v3/databases/mydb/aliases" \ -H "Authorization: YOUR_API_KEY" ``` ## 12. Get Alias [Section titled “12. Get Alias”](#12-get-alias) Retrieve a single alias by name. ### Endpoint [Section titled “Endpoint”](#endpoint-11) ```plaintext GET /graph/v3/databases/{database}/aliases/{alias} ``` ### Parameters [Section titled “Parameters”](#parameters-11) | 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 [Section titled “Response Type”](#response-type-11) [AliasDescriptor](#aliasdescriptor) - Alias information Returns 404 if not found. ### Request Example [Section titled “Request Example”](#request-example-11) ```bash curl -X GET \ "http://ab.example.com/graph/v3/databases/mydb/aliases/friends" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-4) ```json { "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 [Section titled “13. Create Alias”](#13-create-alias) Create a new alias. ### Endpoint [Section titled “Endpoint”](#endpoint-12) ```plaintext POST /graph/v3/databases/{database}/aliases ``` ### Parameters [Section titled “Parameters”](#parameters-12) | 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 [Section titled “Request Body”](#request-body-4) [AliasCreateRequest](#aliascreaterequest) - Alias creation payload ### Response Type [Section titled “Response Type”](#response-type-12) [AliasDescriptor](#aliasdescriptor) - Created alias information ### Request Example [Section titled “Request Example”](#request-example-12) ```bash 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 [Section titled “14. Update Alias”](#14-update-alias) Update an existing alias. ### Endpoint [Section titled “Endpoint”](#endpoint-13) ```plaintext PUT /graph/v3/databases/{database}/aliases/{alias} ``` ### Parameters [Section titled “Parameters”](#parameters-13) | 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 [Section titled “Request Body”](#request-body-5) [AliasUpdateRequest](#aliasupdaterequest) - Alias update payload ### Response Type [Section titled “Response Type”](#response-type-13) [AliasDescriptor](#aliasdescriptor) - Updated alias information ### Request Example [Section titled “Request Example”](#request-example-13) ```bash 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 [Section titled “15. Delete Alias”](#15-delete-alias) Delete an existing alias. ### Endpoint [Section titled “Endpoint”](#endpoint-14) ```plaintext DELETE /graph/v3/databases/{database}/aliases/{alias} ``` ### Parameters [Section titled “Parameters”](#parameters-14) | 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 [Section titled “Response Type”](#response-type-14) 204 No Content (no response body) ### Request Example [Section titled “Request Example”](#request-example-14) ```bash curl -X DELETE \ "http://ab.example.com/graph/v3/databases/mydb/aliases/friends" \ -H "Authorization: YOUR_API_KEY" ``` ## Data Model [Section titled “Data Model”](#data-model) ### DatabaseDescriptor [Section titled “DatabaseDescriptor”](#databasedescriptor) Database information payload. ```kotlin 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 [Section titled “TableDescriptor”](#tabledescriptor) Table information payload. Two types are supported: `edge` and `multiEdge`. #### TableDescriptor.Edge [Section titled “TableDescriptor.Edge”](#tabledescriptoredge) ```kotlin 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:///`) 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 [Section titled “TableDescriptor.MultiEdge”](#tabledescriptormultiedge) ```kotlin 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:///`) 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 [Section titled “AliasDescriptor”](#aliasdescriptor) Alias information payload. ```kotlin 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 [Section titled “ModelSchema.Edge”](#modelschemaedge) Edge schema definition. The `type` discriminator is `"EDGE"` in requests and `"edge"` in responses. ```kotlin 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 = emptyList(),// Edge properties val direction: DirectionType, // Direction type (OUT, IN, BOTH) val indexes: List = emptyList(), // Index definitions val groups: List = emptyList(), // Group definitions ) ``` ### ModelSchema.MultiEdge [Section titled “ModelSchema.MultiEdge”](#modelschemamultiedge) 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. ```kotlin 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 = emptyList(),// Edge properties val direction: DirectionType, // Direction type (OUT, IN, BOTH) val indexes: List = emptyList(), // Index definitions val groups: List = emptyList(), // Group definitions ) ``` ### Field [Section titled “Field”](#field) Vertex field definition. The `type` value is lowercase in JSON (e.g., `"string"`, `"long"`). ```kotlin data class Field( val type: PrimitiveType, // Data type (JSON: lowercase, e.g., "string", "long") val comment: String, // Field description ) ``` ### StructField [Section titled “StructField”](#structfield) Property field definition. The `type` value is lowercase in JSON (e.g., `"int"`, `"long"`). ```kotlin 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 [Section titled “Index”](#index) Index definition. ```kotlin data class Index( val index: String, // Index name val fields: List, // Indexed fields with sort order val comment: String = "", // Index description ) ``` ### IndexField [Section titled “IndexField”](#indexfield) Index field definition. ```kotlin data class IndexField( val field: String, // Field name val order: Order, // Sort order (ASC, DESC) ) ``` ### Group [Section titled “Group”](#group) Group definition for aggregation queries. ```kotlin data class Group( val group: String, // Group name val type: GroupType, // Aggregation type (SUM, COUNT) val fields: List, // 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 [Section titled “DatabaseCreateRequest”](#databasecreaterequest) Database creation request payload. ```kotlin data class DatabaseCreateRequest( val database: String, // Database name val comment: String, // Database description ) ``` ### DatabaseUpdateRequest [Section titled “DatabaseUpdateRequest”](#databaseupdaterequest) Database update request payload. ```kotlin data class DatabaseUpdateRequest( val active: Boolean?, // Whether the database is active (optional) val comment: String?, // Database description (optional) ) ``` ### TableCreateRequest [Section titled “TableCreateRequest”](#tablecreaterequest) Table creation request payload. ```kotlin data class TableCreateRequest( val table: String, // Table name val schema: ModelSchema, // Schema definition (ModelSchema.Edge or ModelSchema.MultiEdge) val storage: String, // Storage URI (`datastore:///`) val mode: MutationMode, // Mutation mode (default: SYNC) val comment: String, // Table description ) ``` ### TableUpdateRequest [Section titled “TableUpdateRequest”](#tableupdaterequest) Table update request payload. ```kotlin 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 [Section titled “AliasCreateRequest”](#aliascreaterequest) Alias creation request payload. ```kotlin data class AliasCreateRequest( val alias: String, // Alias name val table: String, // Target table name (same database only) val comment: String, // Alias description ) ``` ### AliasUpdateRequest [Section titled “AliasUpdateRequest”](#aliasupdaterequest) Alias update request payload. ```kotlin 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 [Section titled “Enums”](#enums) ```kotlin 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 } ``` ### Validation Rules [Section titled “Validation Rules”](#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 [Section titled “V2 Compatibility”](#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 [Section titled “Terminology Mapping”](#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 [Section titled “Label Type Mapping”](#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 [Section titled “API Endpoint Mapping”](#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 [Section titled “MutationMode Mapping”](#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 [Section titled “V3 Alias Constraints”](#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. # Mutation API Reference > Edge mutation API reference Caution Authentication is not enforced. See [API References](/api-references/#authentication). Edge mutation API. See [Mutation](/design/mutation/) for conceptual background. ## 1. Edge Mutation [Section titled “1. Edge Mutation”](#1-edge-mutation) Mutate edges between source nodes and target nodes. ### Endpoint [Section titled “Endpoint”](#endpoint) ```plaintext POST /graph/v3/databases/{database}/tables/{table}/edges ``` ### Parameters [Section titled “Parameters”](#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 [Section titled “Request Body”](#request-body) [EdgeBulkMutationRequest](#edgebulkmutationrequest) - Payload containing mutation items ### Response Type [Section titled “Response Type”](#response-type) [EdgeMutationResponse](#edgemutationresponse) - Payload containing mutation results ### Request Example [Section titled “Request Example”](#request-example) | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | lock | true | ```bash # 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 [Section titled “Response Example”](#response-example) ```json { "results": [ { "source": "source1", "target": "target1", "status": "CREATED", "count": 1 } ] } ``` ## 2. Edge Mutation (Sync) [Section titled “2. Edge Mutation (Sync)”](#2-edge-mutation-sync) Mutate edges synchronously. This endpoint waits for the mutation to complete before returning a response. ### Endpoint [Section titled “Endpoint”](#endpoint-1) ```plaintext POST /graph/v3/databases/{database}/tables/{table}/edges/sync ``` ### Parameters [Section titled “Parameters”](#parameters-1) | 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 [Section titled “Request Body”](#request-body-1) [EdgeBulkMutationRequest](#edgebulkmutationrequest) - Payload containing mutation items ### Response Type [Section titled “Response Type”](#response-type-1) [EdgeMutationResponse](#edgemutationresponse) - Payload containing mutation results ### Request Example [Section titled “Request Example”](#request-example-1) | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | lock | true | ```bash # 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 [Section titled “Response Example”](#response-example-1) ```json { "results": [ { "source": "source1", "target": "target1", "status": "UPDATED", "count": 1 } ] } ``` ## 3. Multi-Edge Mutation [Section titled “3. Multi-Edge Mutation”](#3-multi-edge-mutation) Mutate multi-edges identified by edge IDs. ### Endpoint [Section titled “Endpoint”](#endpoint-2) ```plaintext POST /graph/v3/databases/{database}/tables/{table}/multi-edges ``` ### Parameters [Section titled “Parameters”](#parameters-2) | 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 [Section titled “Request Body”](#request-body-2) [MultiEdgeBulkMutationRequest](#multiedgebulkmutationrequest) - Payload containing mutation items ### Response Type [Section titled “Response Type”](#response-type-2) [MultiEdgeMutationResponse](#multiedgemutationresponse) - Payload containing mutation results ### Request Example [Section titled “Request Example”](#request-example-2) | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | lock | true | ```bash # 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 [Section titled “Response Example”](#response-example-2) ```json { "results": [ { "id": "edge1", "status": "CREATED", "count": 1 } ] } ``` ## 4. Multi-Edge Mutation (Sync) [Section titled “4. Multi-Edge Mutation (Sync)”](#4-multi-edge-mutation-sync) Mutate multi-edges synchronously. This endpoint waits for the mutation to complete before returning a response. ### Endpoint [Section titled “Endpoint”](#endpoint-3) ```plaintext POST /graph/v3/databases/{database}/tables/{table}/multi-edges/sync ``` ### Parameters [Section titled “Parameters”](#parameters-3) | 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 [Section titled “Request Body”](#request-body-3) [MultiEdgeBulkMutationRequest](#multiedgebulkmutationrequest) - Payload containing mutation items ### Response Type [Section titled “Response Type”](#response-type-3) [MultiEdgeMutationResponse](#multiedgemutationresponse) - Payload containing mutation results ### Request Example [Section titled “Request Example”](#request-example-3) | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | lock | true | ```bash # 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 [Section titled “Response Example”](#response-example-3) ```json { "results": [ { "id": "edge1", "status": "DELETED", "count": 1 } ] } ``` ## Event Types [Section titled “Event Types”](#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) | ## Lock Parameter [Section titled “Lock Parameter”](#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 [Section titled “Data Model”](#data-model) ### EdgeBulkMutationRequest [Section titled “EdgeBulkMutationRequest”](#edgebulkmutationrequest) Edge mutation request payload. ```kotlin data class EdgeBulkMutationRequest( val mutations: List, // List of mutation items ) { data class MutationItem( val type: EventType, // Event type (INSERT, UPDATE, DELETE) val edge: Edge, // Edge data ) } ``` ### MultiEdgeBulkMutationRequest [Section titled “MultiEdgeBulkMutationRequest”](#multiedgebulkmutationrequest) Multi-edge mutation request payload. ```kotlin data class MultiEdgeBulkMutationRequest( val mutations: List, // List of mutation items ) { data class MutationItem( val type: EventType, // Event type (INSERT, UPDATE, DELETE) val edge: MultiEdge, // Multi-edge data ) } ``` ### EdgeMutationResponse [Section titled “EdgeMutationResponse”](#edgemutationresponse) Edge mutation response payload. ```kotlin data class EdgeMutationResponse( val results: List, // 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 [Section titled “MultiEdgeMutationResponse”](#multiedgemutationresponse) Multi-edge mutation response payload. ```kotlin data class MultiEdgeMutationResponse( val results: List, // 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 [Section titled “Edge”](#edge) Individual edge information for mutation. ```kotlin data class Edge( val version: Long, // Edge version val source: Any, // Source node ID val target: Any, // Target node ID val properties: Map, // Edge properties ) ``` ### MultiEdge [Section titled “MultiEdge”](#multiedge) Individual multi-edge information for mutation. ```kotlin 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, // Edge properties ) ``` # Query API Reference > Edge query API reference Caution Authentication is not enforced. See [API References](/api-references/#authentication). Edge query API (unique-edge). For unique-edge vs multi-edge, see [FAQ](/faq/#what-is-the-difference-between-unique-edge-and-multi-edge). For conceptual background, see [Query](/design/query/). ## 1. Count [Section titled “1. Count”](#1-count) Retrieve the number of edges starting from a specific node. ### Endpoint [Section titled “Endpoint”](#endpoint) ```plaintext GET /graph/v3/databases/{database}/tables/{table}/edges/count ``` ### Parameters [Section titled “Parameters”](#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 | start | Required | Starting node ID | | Query | direction | Required | [Query direction](#query-direction) (OUT or IN) | | Query | ranges | Optional (default: null) | [Scan range](#index-ranges) | ### Response Type [Section titled “Response Type”](#response-type) [Count](#count-response) - Payload containing edge count information ### Request Example [Section titled “Request Example”](#request-example) | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | start | source1 | | direction | OUT | ```bash # count?start=source1&direction=OUT curl -X GET \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/count?start=source1&direction=OUT" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example) ```json { "start": "source1", "direction": "OUT", "count": 10, "context": {} } ``` ## 2. Get [Section titled “2. Get”](#2-get) Retrieve an edge between a source node and a target node. ### Endpoint [Section titled “Endpoint”](#endpoint-1) ```plaintext GET /graph/v3/databases/{database}/tables/{table}/edges/get ``` ### Parameters [Section titled “Parameters”](#parameters-1) | 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 | source | Required | Source node ID list (comma-separated) | | Query | target | Required | Target node ID list (comma-separated) | | Query | filters | Optional (default: null) | [Filtering conditions](#filters) | When multiple source or target IDs are specified, the operation behaves as **mget** to retrieve multiple edges. In this case, a maximum of **25 edges** can be retrieved per API request. To retrieve more edges, make multiple API requests. ### Response Type [Section titled “Response Type”](#response-type-1) [EdgeFrame](#edgeframe-response) - Payload containing edge data ### Request Example (Get) - 1 source, 1 target [Section titled “Request Example (Get) - 1 source, 1 target”](#request-example-get---1-source-1-target) Retrieves edge data for (source, target). (Maximum 1 result) | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | source | source1 | | target | target1 | ```bash # get?source=source1&target=target1 curl -X GET \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/get?source=source1&target=target1" \ -H "Authorization: YOUR_API_KEY" ``` **Response:** ```json { "edges": [ { "version": 1, "source": "source1", "target": "target1", "properties": { "weight": 0.8, "type": "FOLLOWS" }, "context": {} } ], "count": 1, "total": 1, "offset": null, "hasNext": false, "context": {} } ``` ### Request Example (MGet) - 1 source, N targets [Section titled “Request Example (MGet) - 1 source, N targets”](#request-example-mget---1-source-n-targets) Retrieves edge data for (source, target1) \~ (source, targetN). (Maximum N results) | Parameter | Value | | ------------- | ----------------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | source | source1 | | target | target1,target2,target3 | ```bash # get?source=source1&target=target1,target2,target3 curl -X GET \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/get?source=source1&target=target1,target2,target3" \ -H "Authorization: YOUR_API_KEY" ``` **Response:** ```json { "edges": [ { "version": 3, "source": "source1", "target": "target3", "properties": { "weight": 0.75, "type": "FOLLOWS" }, "context": {} }, { "version": 1, "source": "source1", "target": "target1", "properties": { "weight": 0.8, "type": "FOLLOWS" }, "context": {} } ], "count": 2, "total": 2, "offset": null, "hasNext": false, "context": {} } ``` ### Request Example (MGet) - M sources, 1 target [Section titled “Request Example (MGet) - M sources, 1 target”](#request-example-mget---m-sources-1-target) Retrieves edge data for (source1, target) \~ (sourceM, target). (Maximum M results) | Parameter | Value | | ------------- | ----------------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | source | source1,source2,source3 | | target | target1 | ```bash # get?source=source1,source2,source3&target=target1 curl -X GET \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/get?source=source1,source2,source3&target=target1" \ -H "Authorization: YOUR_API_KEY" ``` **Response:** ```json { "edges": [ { "version": 3, "source": "source3", "target": "target1", "properties": { "weight": 0.75, "type": "FOLLOWS" }, "context": {} }, { "version": 1, "source": "source1", "target": "target1", "properties": { "weight": 0.8, "type": "FOLLOWS" }, "context": {} } ], "count": 2, "total": 2, "offset": null, "hasNext": false, "context": {} } ``` ### Request Example (MGet) - M sources, N targets (Not Recommended) [Section titled “Request Example (MGet) - M sources, N targets (Not Recommended)”](#request-example-mget---m-sources-n-targets-not-recommended) Retrieves edge data for (source1, target1) \~ (sourceM, targetN). (Maximum M × N results) **Note:** This format should not be used in production as it can retrieve up to M × N edges. | Parameter | Value | | ------------- | ----------------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | source | source1,source2,source3 | | target | target1,target2,target3 | ```bash # get?source=source1,source2,source3&target=target1,target2,target3 curl -X GET \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/get?source=source1,source2,source3&target=target1,target2,target3" \ -H "Authorization: YOUR_API_KEY" ``` **Response:** ```json { "edges": [ { "version": 3, "source": "source1", "target": "target3", "properties": { "weight": 0.75, "type": "FOLLOWS" }, "context": {} }, { "version": 3, "source": "source3", "target": "target1", "properties": { "weight": 0.75, "type": "FOLLOWS" }, "context": {} }, { "version": 1, "source": "source1", "target": "target1", "properties": { "weight": 0.8, "type": "FOLLOWS" }, "context": {} } ], "count": 3, "total": 3, "offset": null, "hasNext": false, "context": {} } ``` ## 3. Get (Multi-Edge) [Section titled “3. Get (Multi-Edge)”](#3-get-multi-edge) Retrieve multiple multi-edges by their IDs. For unique-edge vs multi-edge, see [FAQ](/faq/#what-is-the-difference-between-unique-edge-and-multi-edge). ### Endpoint [Section titled “Endpoint”](#endpoint-2) ```plaintext GET /graph/v3/databases/{database}/tables/{table}/multi-edges/ids ``` ### Parameters [Section titled “Parameters”](#parameters-2) | 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 a multi-edge table) | | Query | ids | Required | Edge ID list (comma-separated) | | Query | filters | Optional (default: null) | [Filtering conditions](#filters) | | Query | features | Optional (default: empty list) | List of features to include | A maximum of **25 edges** can be retrieved per API request. To retrieve more edges, make multiple API requests. ### Response Type [Section titled “Response Type”](#response-type-2) [EdgeFrame](#edgeframe-response) - Payload containing edge data ### Request Example (GET) [Section titled “Request Example (GET)”](#request-example-get) | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | ids | id1,id2,id3 | ```bash # multi-edges/ids?ids=id1,id2,id3 curl -X GET \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/multi-edges/ids?ids=id1,id2,id3" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-1) ```json { "edges": [ { "version": 1, "source": "id1", "target": "id1", "properties": { "amount": 1000, "paidAt": 1609459200000 }, "context": {} }, { "version": 1, "source": "id3", "target": "id3", "properties": { "amount": 3000, "paidAt": 1609545600000 }, "context": {} } ], "count": 2, "total": 2, "offset": null, "hasNext": false, "context": {} } ``` ### Request Example (POST) [Section titled “Request Example (POST)”](#request-example-post) For requests with many IDs, use the POST endpoint with a JSON body. ```plaintext POST /graph/v3/databases/{database}/tables/{table}/multi-edges/ids ``` | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | **Request Body:** ```json { "ids": ["id1", "id2", "id3"], "filters": "amount:gte:1000", "features": [] } ``` ```bash curl -X POST \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/multi-edges/ids" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ids": ["id1", "id2", "id3"], "filters": "amount:gte:1000"}' ``` ## 4. Scan [Section titled “4. Scan”](#4-scan) Scan edges using an index. ### Endpoint [Section titled “Endpoint”](#endpoint-3) ```plaintext GET /graph/v3/databases/{database}/tables/{table}/edges/scan/{index} ``` ### Parameters [Section titled “Parameters”](#parameters-3) | 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 | | Path | index | Required | Index name to use | | Query | start | Required | Starting node ID | | Query | direction | Required | [Query direction](#query-direction) (OUT or IN) | | Query | limit | Optional | Maximum number of results to return; 25 is recommended for production | | Query | offset | Optional (default: null) | [Pagination](#pagination) offset | | Query | ranges | Optional (default: null) | [Scan range](#index-ranges) | | Query | filters | Optional (default: null) | [Filtering conditions](#filters) | | Query | features | Optional (default: empty list) | List of features to include (e.g., `total` to calculate the total value) | ### Response Type [Section titled “Response Type”](#response-type-3) [EdgeFrame](#edgeframe-response) - Payload containing edge data ### Request Example [Section titled “Request Example”](#request-example-1) | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | index | your\_index | | start | source1 | | direction | OUT | ```bash # scan/your_index?start=source1&direction=OUT curl -X GET \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/scan/your_index?start=source1&direction=OUT" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-2) ```json { "edges": [ { "version": 1, "source": "source1", "target": "target1", "properties": { "weight": 0.8, "type": "FOLLOWS" }, "context": {} } ], "count": 1, "total": -1, "offset": null, "hasNext": false, "context": {} } ``` **Note:** When `total` is -1, the total count is not calculated. If `features=total` is provided, the total is actually calculated. ## Pagination [Section titled “Pagination”](#pagination) The `offset` parameter indicates the starting position of the next page, and `hasNext` indicates whether there is a next page. If there is no offset, the first page is returned. ### 1. First Page Request [Section titled “1. First Page Request”](#1-first-page-request) Request the first page without an offset. **Request Example** | Parameter | Value | Description | | ------------- | -------------- | -------------- | | Authorization | YOUR\_API\_KEY | | | database | your\_database | | | table | your\_table | | | index | your\_index | | | start | source1 | | | direction | OUT | | | limit | | 25 recommended | ```bash # scan/your_index?start=source1&direction=OUT curl -X GET \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/scan/your_index?start=source1&direction=OUT" \ -H "Authorization: YOUR_API_KEY" ``` **Response:** ```json { "edges": [ { "version": 1, "source": "source1", "target": "target1", "properties": { "weight": 0.8, "type": "FOLLOWS" }, "context": {} }, ... ], "count": 10, "total": -1, "offset": "string_encoded", "hasNext": true, "context": {} } ``` ### 2. Next Page Request [Section titled “2. Next Page Request”](#2-next-page-request) Use the `offset` value from the previous response to retrieve the next page. **Request Example** | Parameter | Value | Description | | ------------- | --------------- | ------------------------------------- | | Authorization | YOUR\_API\_KEY | | | database | your\_database | | | table | your\_table | | | index | your\_index | | | start | source1 | | | direction | OUT | | | offset | string\_encoded | Value received from previous response | | limit | | 25 recommended | ```bash # scan/your_index?start=source1&direction=OUT&offset=string_encoded curl -X GET \ "http://ab.example.com/graph/v3/databases/your_database/tables/your_table/edges/scan/your_index?start=source1&direction=OUT&offset=string_encoded" \ -H "Authorization: YOUR_API_KEY" ``` **Response:** ```json { "edges": [ { "version": 1, "source": "source1", "target": "target1", "properties": { "weight": 0.8, "type": "FOLLOWS" }, "context": {} }, ... ], "count": 10, "total": -1, "offset": null, "hasNext": false, "context": {} } ``` ## Index Ranges [Section titled “Index Ranges”](#index-ranges) The `ranges` parameter allows you to specify the data scan range in count/scan queries. ### Relationship between Ranges and Indexes [Section titled “Relationship between Ranges and Indexes”](#relationship-between-ranges-and-indexes) > **Important:** Ranges can only use fields that are included in the index. 1. **Index Dependency:** Fields used in `ranges` must have an index. Attempting to specify a range on a field without an index will return unexpected results. 2. **Operator Meaning:** The `eq`, `gt(e)`, `lt(e)`, and `between` operators determine the start and end points of the actual storage scan. They must be used appropriately according to index properties. * When an index is set to `DESC` (descending): `lt` becomes the start point and `gt` becomes the end point. * When an index is set to `ASC` (ascending): `gt` becomes the start point and `lt` becomes the end point. 3. **Composite Ranges:** Ranges can be used in the order of the field combination that the index is defined on. Ranges must be applied in the order of fields defined in the index. ### Range Syntax [Section titled “Range Syntax”](#range-syntax) Ranges are written in the following format: ```plaintext ranges=range1[;range2;range3;...] ``` Each range follows this format: ```plaintext field:operator:value ``` To apply multiple ranges, separate them with semicolons (`;`): ```plaintext field1:operator1:value1;field2:operator2:value2 ``` When using the `in` or `bt` (between) operator, multiple values are separated by commas (`,`): ```plaintext field:in:value1,value2,value3 field:bt:minValue,maxValue ``` ### Operators [Section titled “Operators”](#operators) | Operator | Description | Example | | -------- | --------------------- | ------------------------------ | | `eq` | Equal | `type:eq:0` | | `gt` | Greater than | `createdAt:gt:1000000` | | `gte` | Greater than or equal | `createdAt:gte:1000000` | | `lt` | Less than | `createdAt:lt:2000000` | | `lte` | Less than or equal | `createdAt:lte:2000000` | | `bt` | Between two values | `createdAt:bt:1000000,2000000` | ### Examples [Section titled “Examples”](#examples) **Simple range:** ```plaintext GET .../scan/your_index?start=10&direction=OUT&ranges=type:eq:0 ``` This example specifies a range to retrieve only edges where the `type` property is 0. Note that `type` refers to `properties.type`, and `properties.type` must be included in `your_index`. **Composite range:** ```plaintext GET .../scan/your_index?start=10&direction=OUT&ranges=type:eq:0;createdAt:gt:1000000 ``` This example specifies a range to retrieve only edges where `type` is 0 and `createdAt` is greater than 1000000. **Between operator:** ```plaintext GET .../scan/your_index?start=10&direction=OUT&ranges=createdAt:bt:1000000,2000000 ``` This example specifies a range to retrieve only edges where `createdAt` is between 1000000 and 2000000. ## Filters [Section titled “Filters”](#filters) The `filters` parameter allows you to filter data (edges) in get/scan queries. It uses the same format as [ranges](#index-ranges). **Difference from ranges:** While [ranges](#index-ranges) pre-specifies the query range and can only use fields set as indexes, `filters` filters the query results and can use fields that are not set as indexes. ### Filter Examples [Section titled “Filter Examples”](#filter-examples) ```plaintext GET .../get?source=1,2,3&target=10&filters=type:eq:0 GET .../scan/your_index?start=1&direction=OUT&ranges=createdAt:gte:1000000&filters=type:eq:0 ``` ## Data Model [Section titled “Data Model”](#data-model) ### Query Direction [Section titled “Query Direction”](#query-direction) * **OUT:** Outgoing direction (e.g., retrieving products that a user liked in a user \[likes]→ product relationship) * **IN:** Incoming direction (e.g., retrieving users who liked a product in the above relationship) ### Count Response [Section titled “Count Response”](#count-response) Count query response. Payload containing edge count information. ```kotlin data class Count( val start: Any, // Starting node ID val direction: Direction, // Direction (IN, OUT) val count: Long, // Edge count val context: Map, // Context information ) ``` ### EdgeFrame Response [Section titled “EdgeFrame Response”](#edgeframe-response) Get and scan query response. Payload containing edge data. ```kotlin data class EdgeFrame( val edges: List, // Edge list val count: Int, // Number of edges currently returned val total: Long, // Total edge count (-1 means not calculated) val offset: String?, // Pagination offset val hasNext: Boolean, // Whether next page exists val context: Map, // Context information ) ``` ### Edge [Section titled “Edge”](#edge) Individual edge information payload. ```kotlin data class Edge( val version: Long, // Edge version val source: Any, // Source node ID val target: Any, // Target node ID val properties: Map, // Edge properties val context: Map, // Context information ) ```