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 val caches: List = emptyList(), // Cache 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 val caches: List = emptyList(), // Cache 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) ) ``` ### Cache [Section titled “Cache”](#cache) Cache definition. Precomputes a bounded, sorted projection of edges (e.g., top-N by score) for low-latency reads. ```kotlin data class Cache( val cache: String, // Cache name val fields: List, // Sort keys with order val limit: Int = 100, // Maximum number of pre-sorted entries kept per source key (must be > 0) val comment: String = Constants.DEFAULT_COMMENT,// Cache description ) ``` > **Updating `indexes` / `groups` / `caches` via PUT**: these fields live inside `ModelSchema`, so a `PUT /graph/v3/databases/{database}/tables/{table}` body that omits `schema` does **not** change any of them. To change a cache, send the full `schema` payload with the desired `caches` array. This matches the existing semantics for `indexes` and `groups`. ### 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 } ] } ``` ## 5. Scan-Delete (Immutable Edge Tables) [Section titled “5. Scan-Delete (Immutable Edge Tables)”](#5-scan-delete-immutable-edge-tables) Scan an index range on an [immutable edge table](/design/schema/#immutable-edge-tables-type-immutable_indexed-v3-immutable_edge) 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 [Section titled “Endpoint”](#endpoint-4) ```plaintext DELETE /graph/v3/databases/{database}/tables/{table}/edges/scan/{index} ``` ### Parameters [Section titled “Parameters”](#parameters-4) | 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 [Section titled “Response Type”](#response-type-4) [EdgeScanDeleteResponse](#edgescandeleteresponse) - The count deleted ### Request Example [Section titled “Request Example”](#request-example-4) | Parameter | Value | | ------------- | -------------- | | Authorization | YOUR\_API\_KEY | | database | your\_database | | table | your\_table | | index | seq\_asc | ```bash # 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 [Section titled “Response Example”](#response-example-4) ```json { "database": "your_database", "table": "your_table", "index": "seq_asc", "deleted": 2 } ``` ## 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) | Immutable edge tables accept `INSERT` only; `UPDATE` and `DELETE` are rejected with `400`. Rows are removed via [scan-delete](#5-scan-delete-immutable-edge-tables) instead. ## 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 ) ``` ### EdgeScanDeleteResponse [Section titled “EdgeScanDeleteResponse”](#edgescandeleteresponse) Scan-delete response payload. ```kotlin 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`) ) ``` # 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 ) ``` # Queue API Reference > queue/v1 API reference Caution Authentication is not enforced. See [API References](/api-references/#authentication). queue/v1 API. See [Queue](/design/queue/) for conceptual background. ## 1. Create Queue [Section titled “1. Create Queue”](#1-create-queue) Create a queue, provisioning the backing immutable edge table with the fixed queue schema (`seq`, `value`, and a server-assigned ULID message id). ### Endpoint [Section titled “Endpoint”](#endpoint) ```plaintext POST /queue/v1/namespaces/{namespace}/queues ``` ### Parameters [Section titled “Parameters”](#parameters) | Location | Parameter | Required | Description | | -------- | ------------- | ---------------------- | ----------------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | namespace | Required | Target namespace | | Body | queue | Required | Queue name | | Body | storage | Required | Storage URI (e.g., `datastore:///`) | | Body | partitions | Optional (default: 30) | Partition count, fixed at creation (minimum 1) | ### Response Type [Section titled “Response Type”](#response-type) [QueueDescriptorResponse](#queuedescriptorresponse) - Queue metadata ### Request Example [Section titled “Request Example”](#request-example) | Parameter | Value | | ------------- | --------------- | | Authorization | YOUR\_API\_KEY | | namespace | your\_namespace | ```bash # POST /queue/v1/namespaces/your_namespace/queues curl -X POST \ "http://ab.example.com/queue/v1/namespaces/your_namespace/queues" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "queue": "your_queue", "storage": "datastore://your_namespace/your_queue", "partitions": 30 }' ``` ### Response Example [Section titled “Response Example”](#response-example) ```json { "namespace": "your_namespace", "queue": "your_queue", "partitions": 30, "storage": "datastore://your_namespace/your_queue" } ``` ## 2. Get Queue [Section titled “2. Get Queue”](#2-get-queue) Get a queue’s metadata. ### Endpoint [Section titled “Endpoint”](#endpoint-1) ```plaintext GET /queue/v1/namespaces/{namespace}/queues/{queue} ``` ### Parameters [Section titled “Parameters”](#parameters-1) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | namespace | Required | Target namespace | | Path | queue | Required | Target queue name | ### Response Type [Section titled “Response Type”](#response-type-1) [QueueDescriptorResponse](#queuedescriptorresponse) - Queue metadata ### Request Example [Section titled “Request Example”](#request-example-1) ```bash # GET /queue/v1/namespaces/your_namespace/queues/your_queue curl "http://ab.example.com/queue/v1/namespaces/your_namespace/queues/your_queue" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-1) ```json { "namespace": "your_namespace", "queue": "your_queue", "partitions": 30, "storage": "datastore://your_namespace/your_queue" } ``` ## 3. Enable / Disable Queue [Section titled “3. Enable / Disable Queue”](#3-enable--disable-queue) Activate or deactivate a queue. A queue must be disabled before it can be deleted. ### Endpoint [Section titled “Endpoint”](#endpoint-2) ```plaintext PUT /queue/v1/namespaces/{namespace}/queues/{queue}/enable PUT /queue/v1/namespaces/{namespace}/queues/{queue}/disable ``` ### Parameters [Section titled “Parameters”](#parameters-2) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | namespace | Required | Target namespace | | Path | queue | Required | Target queue name | ### Response Type [Section titled “Response Type”](#response-type-2) [QueueDescriptorResponse](#queuedescriptorresponse) - Queue metadata ### Request Example [Section titled “Request Example”](#request-example-2) ```bash # PUT /queue/v1/namespaces/your_namespace/queues/your_queue/disable curl -X PUT \ "http://ab.example.com/queue/v1/namespaces/your_namespace/queues/your_queue/disable" \ -H "Authorization: YOUR_API_KEY" ``` ## 4. Delete Queue [Section titled “4. Delete Queue”](#4-delete-queue) Delete a queue. The queue must be disabled first; deleting an active queue returns `409 Conflict`. ### Endpoint [Section titled “Endpoint”](#endpoint-3) ```plaintext DELETE /queue/v1/namespaces/{namespace}/queues/{queue} ``` ### Parameters [Section titled “Parameters”](#parameters-3) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | namespace | Required | Target namespace | | Path | queue | Required | Target queue name | ### Request Example [Section titled “Request Example”](#request-example-3) ```bash # DELETE /queue/v1/namespaces/your_namespace/queues/your_queue curl -X DELETE \ "http://ab.example.com/queue/v1/namespaces/your_namespace/queues/your_queue" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-2) `204 No Content` on success; `409 Conflict` if the queue is still enabled. ## 5. Get Partitions [Section titled “5. Get Partitions”](#5-get-partitions) Get a queue’s partition count, for consumers that fan a poll loop across `0 .. partitions-1`. ### Endpoint [Section titled “Endpoint”](#endpoint-4) ```plaintext GET /queue/v1/namespaces/{namespace}/queues/{queue}/partitions ``` ### Parameters [Section titled “Parameters”](#parameters-4) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | namespace | Required | Target namespace | | Path | queue | Required | Target queue name | ### Response Type [Section titled “Response Type”](#response-type-3) [QueuePartitionsResponse](#queuepartitionsresponse) - The partition count ### Request Example [Section titled “Request Example”](#request-example-4) ```bash # GET /queue/v1/namespaces/your_namespace/queues/your_queue/partitions curl "http://ab.example.com/queue/v1/namespaces/your_namespace/queues/your_queue/partitions" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-3) ```json { "namespace": "your_namespace", "queue": "your_queue", "partitions": 30 } ``` ## 6. Enqueue [Section titled “6. Enqueue”](#6-enqueue) Append messages to the queue. Each message is routed to a partition by its `key`; the server assigns a ULID id, and `seq` orders it within the partition. ### Endpoint [Section titled “Endpoint”](#endpoint-5) ```plaintext POST /queue/v1/namespaces/{namespace}/queues/{queue}/messages ``` ### Parameters [Section titled “Parameters”](#parameters-5) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | ----------------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | namespace | Required | Target namespace | | Path | queue | Required | Target queue name | | Body | messages | Required | List of messages, each with `key`, `seq`, and `value` | ### Request Body [Section titled “Request Body”](#request-body) [EnqueueRequest](#enqueuerequest) - Payload containing messages ### Response Type [Section titled “Response Type”](#response-type-4) [EnqueueResponse](#enqueueresponse) - Per-message results ### Request Example [Section titled “Request Example”](#request-example-5) ```bash # POST /queue/v1/namespaces/your_namespace/queues/your_queue/messages curl -X POST \ "http://ab.example.com/queue/v1/namespaces/your_namespace/queues/your_queue/messages" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [ {"key": "user1", "seq": 1000, "value": {"body": "hello"}}, {"key": "user1", "seq": 1001, "value": {"body": "world"}} ] }' ``` ### Response Example [Section titled “Response Example”](#response-example-4) ```json { "accepted": 2, "results": [ { "partition": 7, "id": "01JT7Q0Z8B3N5Y6W9XKQRVMH2D", "status": "CREATED" }, { "partition": 7, "id": "01JT7Q0Z8CM4A1E8ZPXW3G5T7F", "status": "CREATED" } ] } ``` ## 7. Poll [Section titled “7. Poll”](#7-poll) Read one partition forward in `seq` order. The response’s `offset` is the cursor for the next poll, and the value to [commit](#8-commit) once the batch is processed. ### Endpoint [Section titled “Endpoint”](#endpoint-6) ```plaintext GET /queue/v1/namespaces/{namespace}/queues/{queue}/partitions/{partition}/poll ``` ### Parameters [Section titled “Parameters”](#parameters-6) | Location | Parameter | Required | Description | | -------- | ------------- | ----------------------- | --------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | namespace | Required | Target namespace | | Path | queue | Required | Target queue name | | Path | partition | Required | Partition to read (`0 .. partitions-1`) | | Query | limit | Optional (default: 100) | Max messages per page (maximum 1000) | | Query | offset | Optional | Read messages with `seq > offset` (exclusive) | | Query | until | Optional | Read messages with `seq <= until` (inclusive) | ### Response Type [Section titled “Response Type”](#response-type-5) [PollResponse](#pollresponse) - One partition’s page ### Request Example [Section titled “Request Example”](#request-example-6) ```bash # GET /queue/v1/namespaces/your_namespace/queues/your_queue/partitions/7/poll curl "http://ab.example.com/queue/v1/namespaces/your_namespace/queues/your_queue/partitions/7/poll?limit=100&offset=1000" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-5) ```json { "messages": [ { "partition": 7, "id": "01JT7Q0Z8CM4A1E8ZPXW3G5T7F", "seq": 1001, "value": { "body": "world" } } ], "offset": 1001, "hasNext": false } ``` ## 8. Commit [Section titled “8. Commit”](#8-commit) Commit a partition up to an offset: every message with `seq <= offset` is deleted. Assumes one logical consumer per partition; see [Queue](/design/queue/#consumer-lifecycle). ### Endpoint [Section titled “Endpoint”](#endpoint-7) ```plaintext DELETE /queue/v1/namespaces/{namespace}/queues/{queue}/partitions/{partition}/messages ``` ### Parameters [Section titled “Parameters”](#parameters-7) | Location | Parameter | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | Header | Authorization | Optional | Authentication key (reserved for future use) | | Path | namespace | Required | Target namespace | | Path | queue | Required | Target queue name | | Path | partition | Required | Partition to commit (`0 .. partitions-1`) | | Query | offset | Required | Delete every message with `seq <= offset` | ### Response Type [Section titled “Response Type”](#response-type-6) [QueueCommitResponse](#queuecommitresponse) - How many messages were deleted ### Request Example [Section titled “Request Example”](#request-example-7) ```bash # DELETE /queue/v1/namespaces/your_namespace/queues/your_queue/partitions/7/messages curl -X DELETE \ "http://ab.example.com/queue/v1/namespaces/your_namespace/queues/your_queue/partitions/7/messages?offset=1001" \ -H "Authorization: YOUR_API_KEY" ``` ### Response Example [Section titled “Response Example”](#response-example-6) ```json { "namespace": "your_namespace", "queue": "your_queue", "partition": 7, "committed": 2 } ``` ## Data Model [Section titled “Data Model”](#data-model) ### QueueCreateRequest [Section titled “QueueCreateRequest”](#queuecreaterequest) ```kotlin data class QueueCreateRequest( val queue: String, // Queue name val storage: String, // Storage URI val partitions: Int = 30, // Partition count, fixed at creation (minimum 1) ) ``` ### QueueDescriptorResponse [Section titled “QueueDescriptorResponse”](#queuedescriptorresponse) ```kotlin data class QueueDescriptorResponse( val namespace: String, val queue: String, val partitions: Int, val storage: String, ) ``` ### QueuePartitionsResponse [Section titled “QueuePartitionsResponse”](#queuepartitionsresponse) ```kotlin data class QueuePartitionsResponse( val namespace: String, val queue: String, val partitions: Int, ) ``` ### EnqueueRequest [Section titled “EnqueueRequest”](#enqueuerequest) ```kotlin data class EnqueueRequest( val messages: List, ) data class EnqueueMessage( val key: String, // Routes to a partition val seq: Long, // Orders within the partition; may encode a due time val value: Any? = null // Opaque payload (JSON) ) ``` ### EnqueueResponse [Section titled “EnqueueResponse”](#enqueueresponse) ```kotlin data class EnqueueResponse( val accepted: Int, // Count of messages with status CREATED val results: List, ) data class EnqueueResult( val partition: Int, // Partition the message was routed to val id: String, // Server-assigned ULID val status: String, // CREATED on success ) ``` ### PollResponse [Section titled “PollResponse”](#pollresponse) ```kotlin data class PollResponse( val messages: List, // In seq order val offset: Long?, // Cursor for the next poll (highest seq seen) val hasNext: Boolean, // Whether more messages remain in the range ) data class PolledMessage( val partition: Int, val id: String, // ULID message id val seq: Long, val value: Any?, ) ``` ### QueueCommitResponse [Section titled “QueueCommitResponse”](#queuecommitresponse) ```kotlin data class QueueCommitResponse( val namespace: String, val queue: String, val partition: Int, val committed: Int, // Messages deleted by this commit ) ```