# 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}")
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://databridge.gitbook.io/databridge-docs/api-reference/endpoints/cache.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.