Principle:Langfuse Langfuse Prompt Retrieval and Resolution

Knowledge Sources	Langfuse
Domains	Prompt Management, Caching, API Design
Last Updated	2026-02-14 00:00 GMT

Overview

Prompt Retrieval and Resolution is the read-path strategy that fetches a prompt by name combined with either a numeric version or a symbolic label, resolves its dependency graph into a fully expanded template, and serves the result through a multi-tier cache hierarchy.

Description

When an SDK or application needs a prompt at runtime, it issues a retrieval request specifying the prompt name and either a specific version number or a label (such as "production" or "latest"). The Prompt Retrieval and Resolution system handles this request through a layered approach:

1. Cache check with lock awareness: The system first checks whether the cache is locked (indicating an in-flight mutation). If locked, the cache is bypassed entirely and the database is queried directly. If unlocked, the system attempts to serve from the Redis cache.
2. Cache hit: If a cached entry exists, it is returned immediately. The TTL is refreshed on read (using GETEX with EX) to keep frequently accessed prompts warm.
3. Cache miss with DB fallback: If no cached entry exists, the system queries PostgreSQL. For version-based lookups, it matches on (projectId, name, version). For label-based lookups, it uses an array-contains query on the labels field.
4. Dependency resolution: After fetching the raw prompt from either cache or database, the system resolves any dependency tags by traversing the prompt's dependency graph. The resolved content replaces the original prompt field.
5. Cache population: If the prompt was fetched from the database and caching is enabled (and not locked), the resolved result is written back to Redis for future requests.

The result includes not just the resolved prompt content but also the full resolution graph (an adjacency list of which prompts were inlined) and an isActive flag computed from whether the prompt carries the "production" label.

Usage

Use Prompt Retrieval and Resolution when:

• An SDK client needs to fetch a prompt for LLM invocation at runtime.
• You need to retrieve a specific historical version of a prompt for debugging or audit purposes.
• You want to fetch the prompt labeled "production" for a stable deployment, or "latest" for the most recently created version.
• The retrieved prompt content must have all dependency references pre-resolved into the final expanded text.

Theoretical Basis

Retrieval Addressing

A prompt is addressed by one of two schemes:

VersionAddress = { projectId: string, promptName: string, version: number }
LabelAddress   = { projectId: string, promptName: string, label: string }

These are mutually exclusive: a retrieval request carries either a version or a label, never both. This is enforced at the type level through a discriminated union.

Multi-Tier Read Path

FUNCTION getPrompt(params):
    // Tier 1: Cache (Redis)
    IF shouldUseCache(params):
        cached = getCachedPrompt(params)
        IF cached IS NOT NULL:
            recordMetric(CACHE_HIT)
            RETURN cached
        recordMetric(CACHE_MISS)

    // Tier 2: Database (PostgreSQL)
    dbPrompt = getDbPrompt(params)

    IF dbPrompt IS NULL:
        RETURN NULL

    // Post-processing: resolve dependencies
    resolved = resolvePrompt(dbPrompt)

    // Back-fill cache for future requests
    IF shouldUseCache(params) AND resolved IS NOT NULL:
        cachePrompt(params, resolved)

    RETURN resolved

Prompt Resolution

FUNCTION resolvePrompt(prompt):
    IF prompt IS NULL:
        RETURN NULL

    // Traverse the dependency graph and inline all referenced prompts
    graphResult = buildAndResolvePromptGraph(prompt.projectId, prompt)

    RETURN {
        ...prompt,
        prompt: graphResult.resolvedPrompt,         // Expanded content
        resolutionGraph: graphResult.graph,          // Adjacency list (or NULL if no deps)
        isActive: "production" IN prompt.labels      // Derived from label presence
    }

The isActive Derivation

The isActive field is a computed property, not a stored column. It is derived from the presence of the "production" label in the prompt's labels array. This replaces a legacy isActive boolean that was stored directly in the database. The derivation ensures that isActive is always consistent with the actual label state, even when labels are moved between versions.

Key design decisions:

1. Version vs. label as primary key extension: Using both addressing modes gives consumers flexibility. Version-based retrieval is deterministic and reproducible (ideal for testing and auditing). Label-based retrieval is dynamic and allows zero-downtime prompt updates (ideal for production deployments).
2. TTL refresh on read: Using GETEX with the EX option refreshes the cache TTL every time a prompt is read. This prevents frequently accessed prompts from expiring while allowing cold prompts to naturally age out.
3. Resolved content in cache: The cache stores the fully resolved prompt (with dependencies inlined), not the raw prompt. This means cache hits avoid the cost of dependency graph traversal entirely.
4. Resolution graph transparency: By returning the resolutionGraph alongside the resolved content, consumers can inspect which prompts were composed into the final output, aiding in debugging and provenance tracking.

Related Pages

Implemented By

• Implementation:Langfuse_Langfuse_PromptService_GetPrompt