Reference

Complete reference for all Couchbase module functions and configuration options.

Complete reference for all Couchbase module functions and configuration options.

📖 Built-In Functions (BIFs)

The Couchbase module provides 13 BIFs for interacting with Couchbase Server:

🔌 Provider & Connection Functions

Functions for accessing Couchbase components:

• couchbaseGetProvider - Get the Couchbase cache provider instance

• couchbaseGetCluster - Get the Couchbase cluster connection

• couchbaseGetBucket - Get a specific Couchbase bucket

• couchbaseGetScope - Get a specific scope within a bucket

• couchbaseGetCollection - Get a specific collection within a scope

🤖 Vector Search Functions

Functions for AI/ML vector operations:

• couchbaseVectorSearch - Search documents by vector similarity

• couchbaseVectorAdd - Store vector documents with embeddings

• couchbaseVectorGet - Retrieve vector document by ID

• couchbaseVectorDelete - Delete vector document by ID

• couchbaseVectorList - List vector documents with filters

📝 Query Functions

Functions for N1QL/SQL++ queries:

• couchbaseQuery - Execute raw N1QL queries with parameters

🔒 Distributed Locking Functions

Functions for coordinating operations across multiple servers:

• couchbaseLock - Acquire distributed lock with optional callback

• couchbaseUnlock - Release distributed lock manually

🧩 Components

The Couchbase module provides components for advanced functionality:

🔒 Distributed Locking Components

• CouchbaseLock - Execute code with automatic distributed lock management

🗄️ Cache Provider Functions

All standard BoxLang cache operations work with Couchbase:

// Set cache value
cache("default").set("key", value, timeoutMinutes);

// Get cache value
data = cache("default").get("key");

// Delete cache value
cache("default").clear("key");

// Check if key exists
exists = cache("default").lookup("key");

// Clear all cache entries
cache("default").clearAll();

// Get cache statistics
stats = cache("default").getStats();

See BoxLang Cache Documentation for complete cache API reference.

⚙️ Configuration Reference

Cache Provider Properties

this.caches["cacheName"] = {
    "provider": "Couchbase",
    "properties": {
        // Required
        "connectionString": "couchbase://localhost",
        "username": "Administrator",
        "password": "password",
        "bucket": "default",

        // Optional
        "scope": "_default",
        "collection": "_default",
        "connectTimeout": "10000",
        "kvTimeout": "2500",
        "maxConnections": 20,

        // TTL settings
        "defaultTimeout": 60,
        "evictionPolicy": "LRU"
    }
};

Property Descriptions

Property	Type	Required	Default	Description
connectionString	String	Yes	-	Couchbase connection string (e.g., couchbase://localhost)
username	String	Yes	-	Couchbase username
password	String	Yes	-	Couchbase password
bucket	String	Yes	-	Bucket name to use
scope	String	No	_default	Scope within the bucket
collection	String	No	_default	Collection within the scope
connectTimeout	Number	No	10000	Connection timeout in milliseconds
kvTimeout	Number	No	2500	Key-value operation timeout in milliseconds
maxConnections	Number	No	20	Maximum number of connections in pool
defaultTimeout	Number	No	60	Default TTL for cache entries (minutes)
evictionPolicy	String	No	LRU	Cache eviction policy (set in Couchbase)

Session Storage Configuration

this.sessionManagement = true;
this.sessionStorage = "couchbase-sessions";
this.sessionTimeout = createTimeSpan(0, 0, 30, 0); // 30 minutes

this.caches["couchbase-sessions"] = {
    "provider": "Couchbase",
    "properties": {
        "connectionString": "couchbase://localhost",
        "username": "Administrator",
        "password": "password",
        "bucket": "sessions",
        "scope": "_default",
        "collection": "boxlang_sessions",
        "defaultTimeout": 30
    }
};

Application Storage Configuration

this.applicationStorage = "couchbase-app";

this.caches["couchbase-app"] = {
    "provider": "Couchbase",
    "properties": {
        "connectionString": "couchbase://localhost",
        "username": "Administrator",
        "password": "password",
        "bucket": "applications",
        "scope": "_default",
        "collection": "boxlang_apps"
    }
};

🔐 Security Configuration

Secure Connections (TLS/SSL)

"connectionString": "couchbases://cluster.example.com" // Note the 's'

Certificate-Based Authentication

"properties": {
    "connectionString": "couchbases://cluster.example.com",
    "certificatePath": "/path/to/cert.pem",
    "keyPath": "/path/to/key.pem"
}

Environment Variables

"properties": {
    "connectionString": env("COUCHBASE_CONNECTION"),
    "username": env("COUCHBASE_USER"),
    "password": env("COUCHBASE_PASS"),
    "bucket": env("COUCHBASE_BUCKET")
}

📊 Vector Search Configuration

Vector Index Creation

// Create vector index for semantic search
couchbaseQuery(
    cacheName = "default",
    query = "CREATE INDEX idx_embedding ON `mybucket`(embedding VECTOR) WHERE type = 'vector_document'"
);

Recommended Vector Settings

// Document structure for vectors
{
    "type": "vector_document",
    "text": "Document content",
    "embedding": [0.1, 0.2, ...], // 1536 dimensions for OpenAI
    "metadata": {
        "category": "docs",
        "importance": "high"
    },
    "userId": "user123",
    "conversationId": "conv456",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
}

🔗 Related Documentation

• Code Usage Guide - Examples and patterns

• Distributed Locking Guide - Lock patterns and best practices

• Scope Storage Guide - Session and application storage

• API Usage - Complete BIF documentation

• AI Memory Guide - Vector search and RAG patterns

• Troubleshooting - Common issues and solutions

📖 External Resources

• Couchbase Server Documentation

• N1QL Language Reference

• Couchbase Java SDK

• BoxLang Documentation