Go Examples

Complete examples for the OxiDB Go client. Install with go get github.com/parisxmas/oxiwire-go

Connect

import "github.com/parisxmas/OxiDB/go/oxidb"

// Connect to localhost:4444 (default)
client, err := oxidb.ConnectDefault()
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Enable OxiWire binary protocol (fastest)
client.UseOxiWire()

// Or connect with custom host/port/timeout
client, err = oxidb.Connect("192.168.1.10", 4444, 10*time.Second)

Insert Documents

// Insert a single document
result, err := client.Insert("users", map[string]any{
    "name":  "Alice",
    "email": "[email protected]",
    "age":   30,
})

// Insert many documents
docs := []map[string]any{
    {"name": "Bob", "age": 25},
    {"name": "Charlie", "age": 35},
    {"name": "Diana", "age": 28},
}
result, err := client.InsertMany("users", docs)

Find Documents

// Find all users over 25
users, err := client.Find("users", map[string]any{
    "age": map[string]any{"$gt": 25},
}, nil)

// Find with sort, skip, limit
limit := 10
skip := 0
users, err := client.Find("users", map[string]any{}, &oxidb.FindOptions{
    Sort:  map[string]any{"age": -1},
    Skip:  &skip,
    Limit: &limit,
})

// Find one document
user, err := client.FindOne("users", map[string]any{
    "name": "Alice",
})

// Count documents
count, err := client.Count("users", map[string]any{
    "age": map[string]any{"$gte": 18},
})

Query Operators

// Comparison: $eq, $ne, $gt, $gte, $lt, $lte
query := map[string]any{"age": map[string]any{"$gte": 18, "$lt": 65}}

// $in — match any value in list
query = map[string]any{"status": map[string]any{"$in": []any{"active", "pending"}}}

// $exists — check field presence
query = map[string]any{"email": map[string]any{"$exists": true}}

// $regex — pattern matching
query = map[string]any{"name": map[string]any{"$regex": "^A"}}

// $and / $or — logical operators
query = map[string]any{
    "$or": []any{
        map[string]any{"age": map[string]any{"$lt": 18}},
        map[string]any{"age": map[string]any{"$gte": 65}},
    },
}

// Nested fields with dot notation
query = map[string]any{"address.city": "Berlin"}

Update Documents

// Update all matching documents
result, err := client.Update("users",
    map[string]any{"name": "Alice"},
    map[string]any{"$set": map[string]any{"age": 31}},
)

// Update one document
result, err = client.UpdateOne("users",
    map[string]any{"name": "Bob"},
    map[string]any{
        "$inc": map[string]any{"login_count": 1},
        "$set": map[string]any{"last_login": time.Now().Format(time.RFC3339)},
    },
)

// Update operators: $set, $unset, $inc, $mul, $min, $max,
// $rename, $currentDate, $push, $pull, $addToSet, $pop

Delete Documents

// Delete all matching documents
result, err := client.Delete("users", map[string]any{
    "age": map[string]any{"$lt": 18},
})

// Delete one document
result, err = client.DeleteOne("users", map[string]any{
    "name": "Charlie",
})

Indexes

// Create a regular index
err := client.CreateIndex("users", "age")

// Create a unique index
err = client.CreateUniqueIndex("users", "email")

// Create a composite index
err = client.CreateCompositeIndex("orders", []string{"customer_id", "date"})

// List indexes on a collection
indexes, err := client.ListIndexes("users")

// Drop an index
err = client.DropIndex("users", "idx_age")

Aggregation Pipeline

// Group users by city, count and average age
results, err := client.Aggregate("users", []map[string]any{
    {"$match": map[string]any{"age": map[string]any{"$gte": 18}}},
    {"$group": map[string]any{
        "_id":       "$city",
        "count":    map[string]any{"$sum": 1},
        "avg_age":  map[string]any{"$avg": "$age"},
    }},
    {"$sort": map[string]any{"count": -1}},
    {"$limit": 10},
})

// Pipeline stages: $match, $group, $sort, $project,
// $limit, $skip, $unwind, $addFields, $lookup, $count

Transactions

// Simple transaction helper
err := client.WithTransaction(func() error {
    _, err := client.Insert("accounts", map[string]any{
        "owner": "Alice", "balance": 1000,
    })
    if err != nil {
        return err
    }
    _, err = client.UpdateOne("accounts",
        map[string]any{"owner": "Bob"},
        map[string]any{"$inc": map[string]any{"balance": -500}},
    )
    return err
})

// Manual transaction control
client.BeginTx()
// ... operations ...
client.CommitTx()   // or client.RollbackTx()

SQL Queries

// Execute SQL queries
result, err := client.SQL("SELECT * FROM users WHERE age > 25 ORDER BY name")

result, err = client.SQL("INSERT INTO users (name, age) VALUES ('Eve', 22)")

result, err = client.SQL("UPDATE users SET age = 31 WHERE name = 'Alice'")

result, err = client.SQL("DELETE FROM users WHERE age < 18")

result, err = client.SQL("CREATE INDEX idx_age ON users (age)")

// JOINs and GROUP BY
result, err = client.SQL(`
    SELECT u.name, COUNT(o._id) as order_count
    FROM users u
    JOIN orders o ON u._id = o.user_id
    GROUP BY u.name
    ORDER BY order_count DESC
`)

Full-Text Search

// Create a text index on fields
err := client.CreateTextIndex("articles", []string{"title", "body"})

// Search within a collection's text index
results, err := client.TextSearch("articles", "rust database", 20)

// Search across blobs (PDF, DOCX, etc.)
results, err = client.Search("quarterly report", nil, 10)

Vector Search

// Create a vector index
err := client.CreateVectorIndex("products", "embedding", 384, "cosine")

// Insert documents with vector embeddings
client.Insert("products", map[string]any{
    "name":      "Wireless Mouse",
    "embedding": queryVector, // []float64 of dimension 384
})

// Find 5 nearest neighbors
results, err := client.VectorSearch("products", "embedding", queryVector, 5)
// Each result has _similarity and _distance fields

Blob Storage

// Create a bucket
err := client.CreateBucket("documents")

// Upload a file
data, _ := os.ReadFile("report.pdf")
meta, err := client.PutObject("documents", "report.pdf", data,
    "application/pdf", map[string]string{"author": "Alice"})

// Download a file
content, metadata, err := client.GetObject("documents", "report.pdf")

// List objects
prefix := "reports/"
objects, err := client.ListObjects("documents", &prefix, nil)

// Delete
err = client.DeleteObject("documents", "report.pdf")

Pipeline (Batch Commands)

// Send multiple commands in a single roundtrip
results, err := client.Pipeline([]map[string]any{
    {"cmd": "find", "collection": "users", "query": map[string]any{}},
    {"cmd": "count", "collection": "orders", "query": map[string]any{}},
    {"cmd": "list_collections"},
})

// Bulk insert with pipeline (multiple batches in one roundtrip)
total, err := client.PipelineInsertMany("logs", batches)

Collections & Databases

// Collection management
err := client.CreateCollection("users")
collections, err := client.ListCollections()
err = client.DropCollection("temp")

// Multi-database support
err = client.CreateDatabase("analytics")
err = client.UseDatabase("analytics")
databases, err := client.ListDatabases()
err = client.DropDatabase("analytics")

// Compaction (reclaim disk space)
stats, err := client.Compact("users")

Authentication & Users

// Authenticate
role, err := client.AuthSimple("admin", "secretpassword")

// User management (requires Admin role)
err = client.CreateUser("alice", "password123", "ReadWrite")
users, err := client.ListUsers()

// Per-database roles
err = client.GrantDbRole("alice", "analytics", "Admin")
err = client.RevokeDbRole("alice", "analytics")

Installation

# OxiDB Go client
go get github.com/parisxmas/OxiDB/go/oxidb

# OxiWire protocol library (standalone)
go get github.com/parisxmas/[email protected]