Collections
POST
/_api/database/:db/collection
Create a new collection.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | The name of the collection. | Yes |
| type | string | Collection type: document (default), edge, or blob. |
No |
| numShards | integer | Number of shards. Default: 1. | No |
| shardKey | string | Field to shard by. Default: _key. |
No |
| replicationFactor | integer | Number of replicas. Default: 1. | No |
{"name": "users", "type": "document", "numShards": 3}
Response
200 OK
application/json
{
"name": "users",
"status": "created",
"numShards": 3,
"shardKey": "_key",
"replicationFactor": 1
}
GET
/_api/database/:db/collection
List all collections in a database.
Response
200 OK
application/json
{
"collections": [
{
"name": "users",
"count": 0,
"type": "document",
"shardConfig": { "num_shards": 3, ... },
"stats": { ... }
}
]
}
GET
/_api/database/:db/collection/:name/sharding
Get sharding details (nodes, shards, status).
Response
200 OK
application/json
{
"shards": [...],
"nodes": [...]
}
GET
/_api/database/:db/collection/:name/stats
Get collection statistics (count, size).
Response
200 OK
application/json
{
"database": "my_db",
"collection": "users",
"document_count": 1250,
"disk_usage": {
"total_size": 40960,
...
}
}
PUT
/_api/database/:db/collection/:name/properties
Update collection properties (e.g. sharding).
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| numShards | integer | New number of shards (triggers rebalance). | No |
| replicationFactor | integer | New replication factor. | No |
PUT
/_api/database/:db/collection/:name/truncate
Remove all documents from a collection.
Response
200 OK
application/json
{
"database": "my_db",
"collection": "users",
"deleted": 1250,
"status": "truncated"
}
PUT
/_api/database/:db/collection/:name/compact
Trigger compaction for a collection to reclaim space.
Response
200 OK
application/json
{
"database": "my_db",
"collection": "users",
"status": "compacted"
}
PUT
/_api/database/:db/collection/:name/recount
Recalculate collection document count.
Response
200 OK
application/json
{
"count": 1250,
"status": "recounted"
}
POST
/_api/database/:db/collection/:name/repair
Repair collection shards (fix metadata inconsistencies).
Response
200 OK
application/json
{
"status": "repaired",
"details": "..."
}
GET
/_api/database/:db/collection/:name/count
Get document count for a collection.
Response
{ "count": 12345 }
POST
/_api/database/:db/collection/:name/prune
Delete old document revisions to free up space.
Response
{ "pruned": 500 }
DELETE
/_api/database/:db/collection/:name
Drop a collection.
Response
204 No Content
GET
/_api/database/:db/collection/:name/export
Export collection data.
Response
200 OK
application/x-ndjson
// Stream of JSON objects (new-line delimited). For blob collections, includes binary chunks.
{"_key": "123", "name": "Alice", "_collectionType": "document"}
{"_key": "456", "name": "Bob", "_collectionType": "document"}
...
POST
/_api/database/:db/collection/:name/import
Import data into collection.
Supported Formats
Send raw data in the request body. Format is auto-detected:
- JSON Array:
[{"name": "a"}, {"name": "b"}] - JSONL: Newline-delimited JSON objects.
- Mixed JSONL/Binary: For blob collections, streams JSON metadata followed immediately by raw binary data chunks.
- CSV: Comma-separated values (first row as headers).
Schema Management
POST
/_api/database/:db/collection/:name/schema
Set or update the JSON schema for a collection.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | Schema name (e.g. "users_v1"). | Yes |
| validation_mode | string | One of: off, lenient, strict. |
Yes |
| schema | object | The JSON Schema object (Draft 7+). | Yes |
{
"name": "users_v1",
"validation_mode": "strict",
"schema": {
"type": "object",
"required": ["email"],
"properties": { "email": { "type": "string" } }
}
}
Response
200 OK
application/json
{
"status": "schema_updated",
"collection": "users"
}
GET
/_api/database/:db/collection/:name/schema
Get the current schema for a collection.
Response
200 OK
application/json
{
"name": "users_v1",
"validation_mode": "strict",
"schema": { ... }
}
DELETE
/_api/database/:db/collection/:name/schema
Remove the schema (disables validation).
Response
200 OK
application/json
{
"status": "schema_removed",
"collection": "users"
}
Columnar Collections
POST
/_api/database/:db/columnar
Create a new columnar collection.
Request Body
{
"name": "metrics",
"columns": [
{"name": "timestamp", "type": "TIMESTAMP"},
{"name": "value", "type": "FLOAT64"},
{"name": "host", "type": "STRING"}
],
"compression": "lz4"
}
Response
200 OK
{ "name": "metrics", "status": "created" }
POST
/_api/database/:db/columnar/:name/insert
Insert rows into a columnar collection.
Request Body
{
"rows": [
{"timestamp": "2024-01-15T10:00:00Z", "value": 42.5, "host": "server1"},
{"timestamp": "2024-01-15T10:01:00Z", "value": 43.2, "host": "server1"}
]
}
POST
/_api/database/:db/columnar/:name/query
Query rows with filters (optimized scan).
Request Body
{
"columns": ["timestamp", "value"],
"filter": {"column": "host", "op": "EQ", "value": "server1"},
"limit": 100
}
POST
/_api/database/:db/columnar/:name/aggregate
Run aggregation functionality.
Request Body
{
"column": "value",
"operation": "AVG",
"group_by": ["host"]
}
POST
/_api/database/:db/columnar/:name/index
Create an index on a columnar collection column.
Request Body
{
"column": "host",
"index_type": "sorted"
}
Response
200 OK
{ "status": "created", "column": "host", "index_type": "sorted" }
GET
/_api/database/:db/columnar/:name/indexes
List indexes on a columnar collection.
Response
200 OK
{
"indexes": [
{"column": "host", "index_type": "sorted", "created_at": 1704067200}
],
"count": 1
}
DELETE
/_api/database/:db/columnar/:name/index/:column
Drop an index from a columnar collection.
Response
200 OK
{ "status": "deleted", "column": "host" }
ESC