MDDB Usage Examples

Basic Operations

Adding Documents

curl -X POST http://localhost:11023/v1/add \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "key": "hello", "lang": "en_US", "meta": {"category": ["blog"]}, "contentMd": "# Hello World" }' curl -X POST http://localhost:11023/v1/add \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "key": "tutorial", "lang": "en_US", "meta": { "category": ["tutorial", "beginner"], "tags": ["golang", "database", "markdown"], "author": ["John Doe"] }, "contentMd": "# Tutorial Content" }'

Retrieving Documents

curl -X POST http://localhost:11023/v1/get \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "key": "hello", "lang": "en_US" }' curl -X POST http://localhost:11023/v1/get \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "key": "hello", "lang": "en_US", "env": { "year": "2024", "siteName": "My Blog" } }'

Search Examples

Basic Search

curl -X POST http://localhost:11023/v1/search \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "limit": 50 }' curl -X POST http://localhost:11023/v1/search \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "filterMeta": {"category": ["tutorial"]}, "sort": "addedAt", "asc": false }'

Advanced Filtering

curl -X POST http://localhost:11023/v1/search \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "filterMeta": { "category": ["tutorial", "guide", "howto"] } }' curl -X POST http://localhost:11023/v1/search \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "filterMeta": { "category": ["tutorial"], "author": ["John Doe"], "status": ["published"] } }'

Pagination

curl -X POST http://localhost:11023/v1/search \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "limit": 10, "offset": 0 }' curl -X POST http://localhost:11023/v1/search \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "limit": 10, "offset": 10 }'

Vector Search (Semantic Search)

Setup

First, configure an embedding provider:

export MDDB_EMBEDDING_PROVIDER=openai
export MDDB_EMBEDDING_API_KEY=sk-your-key-here export MDDB_EMBEDDING_PROVIDER=voyage
export MDDB_EMBEDDING_API_KEY=pa-your-key-here export MDDB_EMBEDDING_PROVIDER=ollama

Adding Documents (auto-embedding)

When an embedding provider is configured, documents are automatically embedded when added:

curl -X POST http://localhost:11023/v1/add \ -H 'Content-Type: application/json' \ -d '{ "collection": "docs", "key": "auth-guide", "lang": "en_US", "meta": {"category": ["security"], "type": ["guide"]}, "contentMd": "# Authentication Guide\n\nThis guide covers user authentication using JWT tokens. Learn how to implement login, registration, and session management." }' curl -X POST http://localhost:11023/v1/add \ -H 'Content-Type: application/json' \ -d '{ "collection": "docs", "key": "api-reference", "lang": "en_US", "meta": {"category": ["api"], "type": ["reference"]}, "contentMd": "# API Reference\n\nComplete REST API reference with endpoints, parameters, and response formats." }' curl -X POST http://localhost:11023/v1/add \ -H 'Content-Type: application/json' \ -d '{ "collection": "docs", "key": "deployment", "lang": "en_US", "meta": {"category": ["devops"], "type": ["guide"]}, "contentMd": "# Deployment Guide\n\nHow to deploy the application to production using Docker, Kubernetes, and CI/CD pipelines." }'

Semantic Search (finding documents by meaning)

curl -X POST http://localhost:11023/v1/vector-search \ -H 'Content-Type: application/json' \ -d '{ "collection": "docs", "query": "how to login users", "topK": 3, "includeContent": true }'

Response shows which documents are most relevant and their similarity scores:

{ "results": [ { "document": { "id": "docs|auth-guide|en_us", "key": "auth-guide", "meta": {"category": ["security"], "type": ["guide"]}, "contentMd": "# Authentication Guide\n..." }, "score": 0.85, "rank": 1 }, { "document": { "id": "docs|api-reference|en_us", "key": "api-reference", "meta": {"category": ["api"], "type": ["reference"]} }, "score": 0.42, "rank": 2 } ], "total": 2, "model": "text-embedding-3-small", "dimensions": 1536
}

Hybrid Search (vector + metadata filter)

Combine semantic search with metadata pre-filtering:

curl -X POST http://localhost:11023/v1/vector-search \ -H 'Content-Type: application/json' \ -d '{ "collection": "docs", "query": "password reset flow", "topK": 5, "filterMeta": {"category": ["security"]}, "includeContent": false }'

Search with Similarity Threshold

curl -X POST http://localhost:11023/v1/vector-search \ -H 'Content-Type: application/json' \ -d '{ "collection": "docs", "query": "kubernetes deployment", "topK": 10, "threshold": 0.7 }'

Reindex Existing Documents

If you added documents before configuring embeddings, or changed the model:

curl -X POST http://localhost:11023/v1/vector-reindex \ -H 'Content-Type: application/json' \ -d '{"collection": "docs", "force": false}' curl -X POST http://localhost:11023/v1/vector-reindex \ -H 'Content-Type: application/json' \ -d '{"collection": "docs", "force": true}'

Check Embedding Status

curl http://localhost:11023/v1/vector-stats | jq

Response:

{ "enabled": true, "provider": "text-embedding-3-small", "model": "text-embedding-3-small", "dimensions": 1536, "index_ready": true, "collections": { "docs": { "total_documents": 3, "embedded_documents": 3 } }
}

Export Examples

NDJSON Export

curl -X POST http://localhost:11023/v1/export \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "format": "ndjson" }' > export.ndjson curl -X POST http://localhost:11023/v1/export \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "filterMeta": {"status": ["published"]}, "format": "ndjson" }' > published.ndjson

ZIP Export

curl -X POST http://localhost:11023/v1/export \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "format": "zip" }' > export.zip

Backup & Restore

Creating Backups

curl "http://localhost:11023/v1/backup?to=backup-$(date +%s).db" curl "http://localhost:11023/v1/backup?to=my-backup.db" #!/bin/bash
DATE=$(date +%Y-%m-%d)
curl "http://localhost:11023/v1/backup?to=backup-${DATE}.db"

Restoring from Backup

curl -X POST http://localhost:11023/v1/restore \ -H 'Content-Type: application/json' \ -d '{"from": "backup-1699296000.db"}'

Maintenance

Truncating Revisions

curl -X POST http://localhost:11023/v1/truncate \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "keepRevs": 5, "dropCache": true }' curl -X POST http://localhost:11023/v1/truncate \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "keepRevs": 0, "dropCache": true }'

Shell Scripts

Bulk Import

#!/bin/bash for file in posts/*.md; do key=$(basename "$file" .md) content=$(cat "$file") curl -X POST http://localhost:11023/v1/add \ -H 'Content-Type: application/json' \ -d "{ \"collection\": \"blog\", \"key\": \"$key\", \"lang\": \"en_US\", \"meta\": {\"category\": [\"blog\"]}, \"contentMd\": $(echo "$content" | jq -Rs .) }"
done

Export and Process

#!/bin/bash curl -X POST http://localhost:11023/v1/export \ -H 'Content-Type: application/json' \ -d '{"collection": "blog", "format": "ndjson"}' | \ jq -r '.key + ": " + .meta.category[0]'

Automated Backup

#!/bin/bash BACKUP_DIR="/backups/mddb"
DATE=$(date +%Y-%m-%d-%H%M%S)
KEEP_DAYS=7 curl "http://localhost:11023/v1/backup?to=${BACKUP_DIR}/backup-${DATE}.db" find ${BACKUP_DIR} -name "backup-*.db" -mtime +${KEEP_DAYS} -delete

Integration Examples

Node.js Client

// mddb-client.js
const axios = require('axios'); class MDDBClient { constructor(baseURL = 'http://localhost:11023') { this.client = axios.create({ baseURL }); } async add(collection, key, lang, meta, contentMd) { const response = await this.client.post('/v1/add', { collection, key, lang, meta, contentMd }); return response.data; } async get(collection, key, lang, env = {}) { const response = await this.client.post('/v1/get', { collection, key, lang, env }); return response.data; } async search(collection, filterMeta = {}, options = {}) { const response = await this.client.post('/v1/search', { collection, filterMeta, ...options }); return response.data; }
} // Usage
const mddb = new MDDBClient(); await mddb.add('blog', 'hello', 'en_US', { category: ['blog'] }, '# Hello World'
); const doc = await mddb.get('blog', 'hello', 'en_US');
console.log(doc);

Python Client

import requests class MDDBClient: def __init__(self, base_url='http://localhost:11023'): self.base_url = base_url def add(self, collection, key, lang, meta, content_md): response = requests.post(f'{self.base_url}/v1/add', json={ 'collection': collection, 'key': key, 'lang': lang, 'meta': meta, 'contentMd': content_md }) return response.json() def get(self, collection, key, lang, env=None): response = requests.post(f'{self.base_url}/v1/get', json={ 'collection': collection, 'key': key, 'lang': lang, 'env': env or {} }) return response.json() def search(self, collection, filter_meta=None, **options): response = requests.post(f'{self.base_url}/v1/search', json={ 'collection': collection, 'filterMeta': filter_meta or {}, **options }) return response.json() mddb = MDDBClient() mddb.add('blog', 'hello', 'en_US', {'category': ['blog']}, '# Hello World') doc = mddb.get('blog', 'hello', 'en_US')
print(doc)

Go Client

// mddb_client.go
package main import ( "bytes" "encoding/json" "net/http"
) type MDDBClient struct { BaseURL string
} func (c *MDDBClient) Add(collection, key, lang string, meta map[string][]string, contentMd string) (map[string]interface{}, error) { data := map[string]interface{}{ "collection": collection, "key": key, "lang": lang, "meta": meta, "contentMd": contentMd, } body, _ := json.Marshal(data) resp, err := http.Post(c.BaseURL+"/v1/add", "application/json", bytes.NewBuffer(body)) if err != nil { return nil, err } defer resp.Body.Close() var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) return result, nil
} // Usage
func main() { client := &MDDBClient{BaseURL: "http://localhost:11023"} doc, _ := client.Add("blog", "hello", "en_US", map[string][]string{"category": {"blog"}}, "# Hello World") fmt.Println(doc)
}

Schema Validation

Schema validation enforces structure on document metadata per collection. It is opt-in -- collections without a schema accept any metadata.

Setting Up a Schema

curl -X POST http://localhost:11023/v1/schema/set \ -H 'Content-Type: application/json' \ -d '{ "collection": "products", "schema": { "required": ["sku", "price", "category"], "properties": { "sku": { "type": "string", "pattern": "^SKU-[0-9]+$" }, "price": { "type": "number" }, "category": { "type": "string", "enum": ["electronics", "clothing", "books"] }, "tags": { "type": "string", "minItems": 1, "maxItems": 10 } } } }'

Adding Documents with Validation

curl -X POST http://localhost:11023/v1/add \ -H 'Content-Type: application/json' \ -d '{ "collection": "products", "key": "laptop-1", "lang": "en_US", "meta": { "sku": ["SKU-10042"], "price": ["999.99"], "category": ["electronics"], "tags": ["laptop", "computer", "portable"] }, "contentMd": "# Laptop Pro 15\n\nHigh-performance laptop." }' curl -X POST http://localhost:11023/v1/add \ -H 'Content-Type: application/json' \ -d '{ "collection": "products", "key": "bad-product", "lang": "en_US", "meta": { "sku": ["INVALID"], "category": ["furniture"] }, "contentMd": "# Bad Product" }'

Dry-Run Validation

curl -X POST http://localhost:11023/v1/validate \ -H 'Content-Type: application/json' \ -d '{ "collection": "products", "meta": { "sku": ["SKU-20001"], "price": ["49.99"], "category": ["books"] } }'

Listing and Managing Schemas

curl -X POST http://localhost:11023/v1/schema/list \ -H 'Content-Type: application/json' \ -d '{}' curl -X POST http://localhost:11023/v1/schema/get \ -H 'Content-Type: application/json' \ -d '{"collection": "products"}' curl -X POST http://localhost:11023/v1/schema/delete \ -H 'Content-Type: application/json' \ -d '{"collection": "products"}'

Blog Schema Example

curl -X POST http://localhost:11023/v1/schema/set \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "schema": { "required": ["category", "author", "status"], "properties": { "category": { "type": "string", "enum": ["blog", "tutorial", "news", "changelog"] }, "author": { "type": "string" }, "status": { "type": "string", "enum": ["draft", "published", "archived"] }, "tags": { "type": "string", "maxItems": 5 }, "featured": { "type": "boolean", "maxItems": 1 } } } }' curl -X POST http://localhost:11023/v1/add \ -H 'Content-Type: application/json' \ -d '{ "collection": "blog", "key": "schema-validation-guide", "lang": "en_US", "meta": { "category": ["tutorial"], "author": ["Jane Doe"], "status": ["published"], "tags": ["mddb", "validation", "schema"], "featured": ["true"] }, "contentMd": "# Schema Validation Guide\n\nLearn how to validate document metadata." }'