> For the complete documentation index, see [llms.txt](https://databridge.gitbook.io/databridge-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://databridge.gitbook.io/databridge-docs/api-reference/endpoints/cache.md).

# Cache

The cache functionality in DataBridge allows you to create and manage specialized caches for efficient querying of your documents.

## `POST` Create Cache

Create a new cache with specified configuration. The cache can be created using metadata filters, specific document IDs, or both.

**Parameters:**

* `name`: Name of the cache to create
* `model`: Name of the model to use (e.g. "llama2")
* `gguf_file`: Name of the GGUF file to use for the model
* `filters`: Optional metadata filters to determine which documents to include
* `docs`: Optional list of specific document IDs to include

**Returns:** Cache configuration object with success status.

{% tabs %}
{% tab title="Python SDK" %}

```python
from databridge import DataBridge

# Create client instance
db = DataBridge(uri="your-databridge-uri")

# Create cache using filters
cache = db.create_cache(
    name="tech_docs",
    model="llama2",
    gguf_file="llama-2-7b-chat.Q4_K_M.gguf",
    filters={"category": "tech", "topic": "ml"}
)

# Create cache using specific documents
cache = db.create_cache(
    name="research_docs",
    model="llama2",
    gguf_file="llama-2-7b-chat.Q4_K_M.gguf",
    docs=["doc_123", "doc_456"]
)

# Create cache using both filters and specific documents
cache = db.create_cache(
    name="combined_cache",
    model="llama2",
    gguf_file="llama-2-7b-chat.Q4_K_M.gguf",
    filters={"category": "tech"},
    docs=["doc_789"]
)
```

{% endtab %}

{% tab title="REST API" %}

```bash
# Create cache with filters
curl -X POST "http://localhost:8000/cache/create" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tech_docs",
    "model": "llama2",
    "gguf_file": "llama-2-7b-chat.Q4_K_M.gguf",
    "filters": {
        "category": "tech",
        "topic": "ml"
    }
  }'

# Create cache with specific documents
curl -X POST "http://localhost:8000/cache/create" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research_docs",
    "model": "llama2",
    "gguf_file": "llama-2-7b-chat.Q4_K_M.gguf",
    "docs": ["doc_123", "doc_456"]
  }'
```

{% endtab %}
{% endtabs %}

**Response:**

{% tabs %}
{% tab title="200 Success" %}

```json
{
    "name": "tech_docs",
    "model": "llama2",
    "gguf_file": "llama-2-7b-chat.Q4_K_M.gguf",
    "filters": {
        "category": "tech",
        "topic": "ml"
    },
    "doc_count": 5,
    "success": true
}
```

{% endtab %}

{% tab title="400 Bad Request" %}

```json
{
    "detail": "No documents to add to cache"
}
```

{% endtab %}

{% tab title="401 Unauthorized" %}

```json
{
    "detail": "Invalid authentication credentials"
}
```

{% endtab %}
{% endtabs %}

## `GET` Get Cache

Get cache configuration by name.

**Parameters:**

* `name`: Name of the cache to retrieve

**Returns:** Cache existence status.

{% tabs %}
{% tab title="Python SDK" %}

```python
from databridge import DataBridge

# Create client instance
db = DataBridge(uri="your-databridge-uri")

# Get cache
cache = db.get_cache("tech_docs")
```

{% endtab %}

{% tab title="REST API" %}

```bash
curl -X GET "http://localhost:8000/cache/tech_docs" \
  -H "Authorization: Bearer your_token"
```

{% endtab %}
{% endtabs %}

**Response:**

{% tabs %}
{% tab title="200 Success" %}

```json
{
    "exists": true
}
```

{% endtab %}

{% tab title="401 Unauthorized" %}

```json
{
    "detail": "Invalid authentication credentials"
}
```

{% endtab %}
{% endtabs %}

## `POST` Update Cache

Update cache with new documents matching its filter.

**Parameters:**

* `name`: Name of the cache to update

**Returns:** Success status of the update operation.

{% tabs %}
{% tab title="Python SDK" %}

```python
from databridge import DataBridge

# Create client instance
db = DataBridge(uri="your-databridge-uri")

# Get and update cache
cache = db.get_cache("tech_docs")
success = cache.update()
```

{% endtab %}

{% tab title="REST API" %}

```bash
curl -X POST "http://localhost:8000/cache/tech_docs/update" \
  -H "Authorization: Bearer your_token"
```

{% endtab %}
{% endtabs %}

**Response:**

{% tabs %}
{% tab title="200 Success" %}

```json
{
    "success": true
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "detail": "Cache 'tech_docs' not found"
}
```

{% endtab %}
{% endtabs %}

## `POST` Add Documents to Cache

Add specific documents to an existing cache.

**Parameters:**

* `name`: Name of the cache
* `docs`: List of document IDs to add

**Returns:** Success status of the add operation.

{% tabs %}
{% tab title="Python SDK" %}

```python
from databridge import DataBridge

# Create client instance
db = DataBridge(uri="your-databridge-uri")

# Get cache and add documents
cache = db.get_cache("tech_docs")
success = cache.add_docs(["doc_123", "doc_456"])
```

{% endtab %}

{% tab title="REST API" %}

```bash
curl -X POST "http://localhost:8000/cache/tech_docs/add_docs" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "docs": ["doc_123", "doc_456"]
  }'
```

{% endtab %}
{% endtabs %}

**Response:**

{% tabs %}
{% tab title="200 Success" %}

```json
{
    "success": true
}
```

{% endtab %}

{% tab title="401 Unauthorized" %}

```json
{
    "detail": "Invalid authentication credentials"
}
```

{% endtab %}
{% endtabs %}

## `POST` Query Cache

Query the cache with a prompt to generate a completion.

**Parameters:**

* `name`: Name of the cache
* `query`: Query text
* `max_tokens`: Optional maximum number of tokens to generate
* `temperature`: Optional temperature parameter for controlling randomness

**Returns:** Completion response with generated text.

{% tabs %}
{% tab title="Python SDK" %}

```python
from databridge import DataBridge

# Create client instance
db = DataBridge(uri="your-databridge-uri")

# Get cache and query
cache = db.get_cache("tech_docs")

# Basic query
response = cache.query("What are the key concepts in machine learning?")
print(response.completion)

# Query with parameters
response = cache.query(
    "Explain machine learning concepts",
    max_tokens=500,
    temperature=0.7
)
```

{% endtab %}

{% tab title="REST API" %}

```bash
curl -X POST "http://localhost:8000/cache/tech_docs/query" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key concepts in machine learning?",
    "max_tokens": 500,
    "temperature": 0.7
  }'
```

{% endtab %}
{% endtabs %}

**Response:**

{% tabs %}
{% tab title="200 Success" %}

```json
{
    "completion": "Machine learning is a field that focuses on...",
    "tokens_used": 150,
    "finish_reason": "length"
}
```

{% endtab %}

{% tab title="401 Unauthorized" %}

```json
{
    "detail": "Invalid authentication credentials"
}
```

{% endtab %}
{% endtabs %}

## Best Practices

1. **Cache Naming**: Use descriptive names for your caches that reflect their content or purpose
2. **Document Organization**: Use consistent metadata when ingesting documents to make filtering easier
3. **Cache Updates**: Regularly update your caches if you frequently add new documents
4. **Query Parameters**:
   * Use lower temperature (0.0-0.3) for more focused, deterministic responses
   * Use higher temperature (0.7-1.0) for more creative responses
   * Adjust max\_tokens based on your needed response length

## Error Handling

Always wrap cache operations in try-except blocks in production code:

```python
try:
    cache = db.get_cache("ml_cache")
    response = cache.query("What is machine learning?")
except ValueError as e:
    print(f"Cache error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```