# Couchbase +

Welcome to the BoxLang Couchbase Module! This module provides enterprise-grade caching, session storage, and AI vector memory capabilities powered by Couchbase's distributed NoSQL database.

{% hint style="danger" %}
This module is only available to [+/++ subscribers only](https://ww.boxlang.io/plans) but can be installed in conjunction with the [`bx-plus` Module](https://github.com/ortus-boxlang/boxlang-docs/blob/v1.x/boxlang-framework/boxlang-plus/modules/bx-couchbase/bx-plus/README.md) with a limited trial.
{% endhint %}

## 🎯 What is Couchbase?

Couchbase is a distributed NoSQL document database with built-in caching, full-text search, and vector search capabilities. It combines the best of key-value stores with the flexibility of document databases, making it ideal for:

* High-performance caching
* Session and application state storage
* AI vector embeddings and semantic search
* Real-time applications
* Multi-data center deployments

## 📦 Installation

```bash
# For Operating Systems using our Quick Installer.
install-bx-module bx-couchbase

# Using CommandBox to install for web servers.
box install bx-couchbase
```

## ⚡ Key Features

### Distributed Caching

Store cache data across multiple nodes with automatic failover and replication. Sub-millisecond response times for key-value operations.

### Vector Search

Built-in support for AI vector embeddings with semantic search using KNN (K-Nearest Neighbors). Perfect for RAG (Retrieval Augmented Generation) applications, chatbots, and recommendation systems.

### Session Storage

Use Couchbase as your session or application scope storage backend. Automatic serialization and deserialization of BoxLang data types.

### Distributed Locking

Coordinate operations across multiple servers with true distributed locks. Prevent race conditions in financial transactions, inventory updates, and batch processing.

### N1QL Queries

Execute SQL++ queries (N1QL) directly from BoxLang. Full support for joins, aggregations, and complex filtering.

### Cluster Support

Configure multi-node clusters with automatic discovery and failover. Supports secure connections with TLS.

## 📖 Documentation Structure

* [**Code Usage**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/code-usage) - Working with the cache provider
* [**API Usage**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/api-usage) - Using Built-In Functions (BIFs)
* [**Distributed Locking**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/distributed-locking) - Coordinate operations across servers
* [**Scope Storage**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/scope-storage) - Session and application storage
* [**AI Memory**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/aimemory) - Vector embeddings and semantic search
* [**Troubleshooting**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/troubleshooting) - Common issues and solutions
* [**BIF Reference**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/reference/built-in-functions) - Complete BIF documentation

## 🚀 Quick Example

```js
// In Application.bx
this.caches["default"] = {
    "provider": "Couchbase",
    "properties": {
        "connectionString": "couchbase://localhost",
        "username": "Administrator",
        "password": "password",
        "bucket": "myapp"
    }
};

// In your code
cache("default").set("user:123", {
    name: "John Doe",
    email: "john@example.com",
    role: "admin"
});

user = cache("default").get("user:123");
println("Welcome, #user.name#!");

// Distributed locking
couchbaseLock(
    cacheName = "default",
    name = "payment-#orderId#",
    timeout = 5,
    expires = 30,
    callback = function() {
        // Only one server processes this payment at a time
        processPayment(orderId);
    }
);

// Vector search
embedding = getOpenAIEmbedding("machine learning tutorial");
similar = couchbaseVectorSearch(
    cacheName = "default",
    collection = "myapp._default._default",
    embedding = embedding,
    limit = 5
);
```

## 💡 Use Cases

### 🎯 Application Caching

Cache database query results, API responses, or computed values to reduce latency and database load.

### 👤 Session Management

Store user sessions in a distributed cache that survives application restarts and scales across multiple servers.

### 🤖 AI/ML Applications

Store and search vector embeddings for semantic search, recommendation systems, and RAG chatbots.

### 🔒 Distributed Coordination

Prevent race conditions and double-processing with distributed locks. Perfect for financial transactions, inventory management, and scheduled jobs.

### 📊 Real-Time Analytics

Cache aggregated metrics and dashboards with automatic expiration and refresh.

### 🌐 Multi-Region Deployments

Replicate cache data across geographic regions for low-latency access worldwide.

## 🔧 Requirements

* BoxLang 1.0.0+
* Couchbase Server 7.0+ (7.6+ recommended for vector search)
* Java 21+

## 📦 Installation

```bash
# Install via BoxLang CLI
boxlang install bx-couchbase

# Or add to box.json
{
    "dependencies": {
        "bx-couchbase": "^1.0.0"
    }
}
```

## 🎓 Next Steps

Ready to dive in? Start with:

1. [**Code Usage**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/code-usage) - Learn the basic cache operations
2. [**API Usage**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/api-usage) - Explore the Built-In Functions
3. [**Distributed Locking**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/distributed-locking) - Coordinate operations across servers
4. [**AI Memory**](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/aimemory) - Build AI-powered applications

Need help? Check out [Troubleshooting](https://boxlang.ortusbooks.com/boxlang-framework/boxlang-plus/modules/bx-couchbase/troubleshooting) or visit our [community forums](https://community.ortussolutions.com).