Caching

Learn how Query-2jz's intelligent caching system improves performance and reduces database load.

What is Caching?

Query-2jz's caching system automatically stores frequently accessed data in memory or Redis, dramatically improving response times and reducing database queries.

Caching Features

Automatic query caching

Multi-level caching

Smart TTL management

Automatic invalidation

Cache security

HTTP caching

Cache Levels

Query-2jz implements a multi-level caching strategy for optimal performance.

L1: Memory Cache

Fastest access, limited capacity

• In-process memory storage
• Sub-millisecond access time
• Limited by available RAM
• Perfect for hot data
• Automatic LRU eviction

L2: Redis Cache

Shared cache, persistent storage

• Distributed across instances
• Persistent across restarts
• Larger capacity than memory
• Network latency overhead
• Advanced data structures

L3: HTTP Cache

Browser and CDN caching

• Browser cache headers
• CDN edge caching
• ETag support
• Conditional requests
• Global distribution

Automatic Query Caching

Query-2jz automatically caches query results based on intelligent heuristics.

Cache Strategy

How Query-2jz decides what to cache

Cacheable Queries

• Read-only operations (GET requests)
• Queries without user-specific data
• Frequently accessed data
• Expensive database operations
• Static or slowly changing data

Cache Keys

// Cache key generation
const cacheKey = `query-2jz:${model}:${JSON.stringify(query)}:${JSON.stringify(options)}`;

// Examples:
// query-2jz:User:{"where":{"status":"active"}}:{"limit":10}
// query-2jz:Post:{"where":{"published":true},"include":"author"}:{"orderBy":"createdAt:desc"}

TTL (Time To Live)

Default TTL

• Simple queries: 5 minutes
• Complex queries: 15 minutes
• Aggregations: 30 minutes
• Static data: 1 hour

Custom TTL

// Custom TTL in query
GET /api/query-2jz/User?ttl=3600  // 1 hour
GET /api/query-2jz/Post?ttl=1800  // 30 minutes

Cache Invalidation

Query-2jz automatically invalidates cache when data changes.

Invalidation Strategy

How cache is automatically cleared

Automatic Invalidation

• Model-level invalidation on mutations
• Record-specific invalidation
• Relationship-based invalidation
• Pattern-based invalidation

Invalidation Examples

// When a user is updated
PUT /api/query-2jz/User/1
{
  "name": "John Updated"
}

// Automatically invalidates:
// - query-2jz:User:{"id":"1"}
// - query-2jz:User:{"where":{"status":"active"}}
// - query-2jz:User:{"where":{"name":"John*"}}
// - Any queries including this user

Manual Invalidation

// Clear specific cache
DELETE /api/query-2jz/cache/User/1

// Clear model cache
DELETE /api/query-2jz/cache/User

// Clear pattern cache
DELETE /api/query-2jz/cache/User?pattern=*active*

// Clear all cache
DELETE /api/query-2jz/cache

HTTP Caching

Query-2jz provides HTTP caching headers for browser and CDN caching.

HTTP Cache Headers

Browser and CDN-friendly caching

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=300
ETag: "abc123def456"
Last-Modified: Wed, 01 Jan 2024 00:00:00 GMT
Vary: Accept-Encoding

Conditional Requests

// Client request with ETag
GET /api/query-2jz/User/1
If-None-Match: "abc123def456"

// Server response (304 Not Modified)
HTTP/1.1 304 Not Modified
ETag: "abc123def456"
Cache-Control: public, max-age=300

Cache Control Directives

Public Caching

Cache-Control: public, max-age=300

Private Caching

Cache-Control: private, max-age=60

Cache Configuration

Configure caching behavior in your Query-2jz configuration.

Memory Cache Configuration

{
  "cache": {
    "type": "memory",
    "ttl": 300,           // Default TTL in seconds
    "maxSize": 1000,      // Maximum number of items
    "checkPeriod": 120,   // Cleanup interval
    "useClones": false    // Use object references
  }
}

Redis Cache Configuration

{
  "cache": {
    "type": "redis",
    "connection": "redis://localhost:6379",
    "ttl": 300,
    "keyPrefix": "query-2jz:",
    "compression": true,
    "retryDelayOnFailover": 100,
    "maxRetriesPerRequest": 3
  }
}

HTTP Cache Configuration

{
  "cache": {
    "http": {
      "enabled": true,
      "defaultMaxAge": 300,
      "etag": true,
      "lastModified": true,
      "vary": ["Accept-Encoding"],
      "public": true
    }
  }
}

Cache Monitoring

Monitor cache performance and statistics.

Cache Statistics

Monitor cache hit rates and performance

Cache Stats Endpoint

GET /api/query-2jz/cache/stats

Response Example

{
  "memory": {
    "hits": 1250,
    "misses": 150,
    "hitRate": 0.893,
    "size": 850,
    "maxSize": 1000,
    "ttl": 300
  },
  "redis": {
    "hits": 3200,
    "misses": 400,
    "hitRate": 0.889,
    "connected": true,
    "memory": "2.5MB"
  },
  "http": {
    "requests": 5000,
    "cacheHits": 3500,
    "hitRate": 0.7,
    "bandwidthSaved": "15.2MB"
  }
}

Best Practices

Do

• Use appropriate TTL values
• Monitor cache hit rates
• Configure Redis for production
• Use HTTP caching for static data
• Implement cache warming
• Set up cache monitoring
• Use cache keys consistently

Don't

• Cache user-specific data globally
• Use extremely long TTL values
• Ignore cache invalidation
• Cache sensitive information
• Over-cache small datasets
• Forget to monitor performance
• Use inconsistent cache keys