Cloud & Automation

Report Engine Architecture: Request to Result

Trace a report request through gateway, security, validation, cache, Fabric query, result construction and monitoring.

By JaviPublished Updated 7 min readIntermediate

Report request lifecycle from authentication through execution and monitoring

Short answer: a report request passes through six stages: gateway, authorization, validation, cache lookup, query, and result delivery. Each stage should fail with its own explicit response and leave one log record that names the stage. Synchronous responses suit small, fast reports; anything that can outlive an HTTP timeout should become an asynchronous job the client polls.

Request lifecycle

  1. API Management

    Step 1: Receive request

    Assign a request ID, accept a correlation ID

  2. Report Engine

    Step 2: Validate request

    Report, format, date range, row and byte limits

  3. Report Engine

    Step 3: Resolve tenant & security

    Tenant from trusted claims; authorize report and filters

  4. Storage account

    Step 4: Check cache

    Tenant-aware key; fresh output → skip to step 6 or 8

  5. Microsoft Fabric

    Step 5: Query Fabric if needed

    Approved template, bound parameters, timeout

    Only on a cache miss

  6. Report Engine

    Step 6: Build result

    Shape rows into JSON, CSV or Parquet

  7. Storage account

    Step 7: Store output / cache result

    Write to the tenant’s folder with a TTL

  8. Report Engine

    Step 8: Return response

    JSON body or short-lived download link

The lifecycle of one report request. Steps 1–4 always run; step 5 runs only on a cache miss; every request ends with a stored or reused output and a response that carries its request ID.

The client reaches API Management or a gateway, which establishes identity, request size limits, and coarse throttling. The report engine performs report authorization, tenant validation, parameter validation, and finer workload limits before any query work begins.

Cache decision

  1. RequestValidated, tenant resolved
  2. Cache keytenantreportparametersformatversion
  3. Look upIn report-cache, under{tenant}/{report}/…
  4. Cached and fresh?Within the report’s TTL

Yes Cache hit

  1. Authorize again for this caller
  2. Read the stored output
  3. Return result

No Cache miss

  1. Query Fabric (approved template)
  2. Build output: JSON, CSV or Parquet
  3. Store under the tenant’s path, with a TTL
  4. Return result

Tenant-aware: same report, same parameters, different tenants

  • contosocontoso · sales-by-region · 2026-09 · csv · v3report-cache/contoso/sales-by-region/…
  • fabrikamfabrikam · sales-by-region · 2026-09 · csv · v3report-cache/fabrikam/sales-by-region/…

Two keys, two folders: never shared.

Cache hit or miss. The tenant is the first part of the cache key and of the storage path, so two tenants asking for the same report with the same parameters never share an entry. A hit is still authorized; a miss queries Fabric and stores the new output for the next request.

Build a canonical cache key from trusted tenant identity, report type, normalized date range, dimensions, filters, format, and report version. The same safe logical request produces the same key. A hit still requires authorization. A miss proceeds to the controlled query layer and may cache the finished result with TTL and freshness metadata.

Query and result

The query layer selects an approved query template for Fabric Warehouse or Lakehouse SQL endpoint and binds validated values. The result builder enforces row and byte limits, produces JSON, CSV, Parquet or another allowed format, and stores large artifacts privately. Download URLs are short lived and checked against tenant identity.

Observability

Record request_id, correlation_id, tenant_id, client_id, api_key_id, report_name, requested_at, started_at, completed_at, duration_ms, cache_hit, query_duration_ms, rows_returned, output_bytes, status, and error_code. These fields connect directly to the Monitoring pillar and support capacity, reliability, audit, and cost analysis.

Failure handling by stage

A request that fails should tell the caller what to do next and tell the operator where it stopped.

Stage Typical failure Response Record
Gateway Missing or invalid credentials; consumer over its rate limit 401, or 429 with Retry-After Consumer ID, limit that was hit
Authorization Caller not allowed this tenant or report 403 Caller, tenant, report; never the data that would have been returned
Validation Unknown dimension, end before start, range or row limit exceeded 400 with the rule that failed The rule and the offending parameter, with sensitive values redacted
Cache Entry unreadable or partially written Treat as a miss; do not fail the request Cache key, read error
Query Timeout, capacity throttling, transient connection error 503 or 504, with Retry-After when retrying makes sense Query template, duration, error code, rows read if known
Result Output larger than allowed; storage write failed 400 telling the caller to narrow the request or use an export; 500 for a storage failure Rows and bytes produced, storage path

Two rules keep this table honest. Return a validation failure before any query runs, so a bad request costs nothing. And set the query timeout shorter than the gateway’s, so the engine, not the gateway, decides what the caller receives.

When to switch to an asynchronous request

If a report can take longer than the client or gateway will wait, return a job instead of holding the connection. The Asynchronous Request-Reply pattern describes the exchange:

POST /reports/revenue-by-channel/runs
→ 202 Accepted
  Location: /reports/runs/7d1f…
  Retry-After: 10

GET /reports/runs/7d1f…
→ 200 OK   {"status": "running"}

GET /reports/runs/7d1f…
→ 303 See Other
  Location: /reports/runs/7d1f…/result

The job carries the same request ID as the original call, so the log and the job status describe one execution. Cancellation should stop the query, not only the polling: a client that gives up should not leave a query running against your capacity.

One log record per request

{
  "request_id": "7d1f…",
  "correlation_id": "c41a…",
  "tenant_id": "contoso",
  "client_id": "partner-portal",
  "report_name": "revenue-by-channel",
  "report_version": 3,
  "stage_reached": "result",
  "status": "succeeded",
  "cache_hit": false,
  "requested_at": "2026-11-06T08:14:03.120Z",
  "completed_at": "2026-11-06T08:14:05.902Z",
  "duration_ms": 2782,
  "query_duration_ms": 2410,
  "rows_returned": 3120,
  "output_bytes": 188416,
  "error_code": null
}

stage_reached is the field that turns a failure count into a diagnosis: a spike of failures at validation is a client problem, at query a capacity or warehouse problem, at result a size or storage problem. Measuring API and report request volume shows how to aggregate these records.

Sources

Checked November 2026. Status codes follow common HTTP practice; align them with your API’s existing conventions.

Tags

  • Data Architecture
  • API
  • Reporting
  • Microsoft Fabric
  • Caching
  • Multi-Tenancy
  • Observability