Blobs — SoliDB Docs

Overview

SoliDB Blob Collections provide a native way to store binary large objects (BLOBs). Unlike standard collections which store JSON documents, blob collections are optimized for immutable binary data.

Chunking

Files are automatically split into manageable chunks for efficient storage and streaming.

Replication

Chunks are consistently hashed and replicated across the cluster. SoliDB automates replication factors (min 2, max 10) for high availability.

Metadata

Automatic JSON metadata document generation for querying and management.

Creating a Blob Collection

Create a collection with type: "blob".

POST /_api/database/:db/collection

curl -X POST http://localhost:6745/_api/database/_system/collection \

-H "Authorization: Bearer $TOKEN" \

-H "Content-Type: application/json" \

-d '{ "name": "images", "type": "blob", "replicationFactor": 3 }'

Uploading Files

Use multipart/form-data to upload files. The field name for the file content must be file.

POST /_api/blob/:db/:collection

curl -X POST http://localhost:6745/_api/blob/_system/images \

-H "Authorization: Bearer $TOKEN" \

-F "file=@my-photo.jpg"

Response

{
  "_key": "018e2345-6789-7abc-def0-1234567890ab",
  "name": "my-photo.jpg",
  "type": "image/jpeg",
  "size": 1048576,
  "chunks": 4,
  "created": "2024-03-15T10:00:00Z"
}

Resumable Chunked Uploads

For large files, use the chunked upload API. Files are split into chunks (default 1MB) that can be uploaded in any order and resumed after network interruptions. Sessions expire after 24 hours of inactivity.

Resumable

If a connection drops, check the upload status to see which chunks were received, then resume from where you left off.

Out-of-Order

Chunks can be uploaded in any order and even in parallel from multiple connections.

Workflow

1

Create an upload session

Returns an upload_id, blob_key, and the number of chunks expected.

2

Upload each chunk

POST raw binary data for each chunk index. Each response lists missing chunks.

3

Complete the upload

Promotes temp chunks to permanent storage and creates the metadata document.

Example

# Step 1: Create session
curl -X POST http://localhost:6745/_api/blob/_system/videos/upload \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"total_size": 3145728, "file_name": "clip.mp4", "mime_type": "video/mp4"}'

# Step 2: Upload chunks (0, 1, 2)
curl -X POST http://localhost:6745/_api/blob/_system/videos/upload/$UPLOAD_ID/0 \
-H "Authorization: Bearer $TOKEN" \
--data-binary @chunk_0.bin

# Step 3: Complete
curl -X POST http://localhost:6745/_api/blob/_system/videos/upload/$UPLOAD_ID/complete \
-H "Authorization: Bearer $TOKEN"

# Check status (resume after disconnect)
curl http://localhost:6745/_api/blob/_system/videos/upload/$UPLOAD_ID/status \
-H "Authorization: Bearer $TOKEN"

# Abort if needed
curl -X DELETE http://localhost:6745/_api/blob/_system/videos/upload/$UPLOAD_ID/abort \
-H "Authorization: Bearer $TOKEN"

API Reference

See the full endpoint details in the Blobs API Reference.

Downloading Files

GET /_api/blob/:db/:collection/:key

# Download file with original name

curl -O -J http://localhost:6745/_api/blob/_system/images/<key> \

-H "Authorization: Bearer $TOKEN"

Metadata & Querying

Because metadata is stored as standard JSON documents, you can filter and query your blobs using SDBQL.

SDBQL Query

FOR doc IN images
  FILTER doc.type == "image/jpeg"
  FILTER doc.size > 5000000
  RETURN doc

Important Note

Deleting the metadata document does NOT automatically delete the binary chunks. Use the DELETE /_api/blob endpoint (coming soon) for full cleanup.

Blob Storage