Skip to content

PATTERN Cited by 1 source

Upload-then-poll indexing

Intent

Collapse the write → indexed → searchable latency path into a single awaitable API call that returns once the document is fully indexed and ready to query — so application code can treat "document is written" and "document is searchable" as the same event.

Problem

Traditional managed search separates storage from indexing, which turns every write into a three-step workflow the application has to orchestrate:

  1. Write the document to the source of truth (object store, DB).
  2. Wait for an indexing pipeline (CDC stream, batch ETL, scheduled sync) to pick it up.
  3. Poll / retry the search until the document shows up.

This creates a window where the document exists but is invisible to search. For agent workflows — "save this resolution, then next turn search for it" — the window is unacceptable: if the next turn happens before the sync catches up, the agent doesn't see its own write.

Solution

Expose a single API that writes the document, performs indexing synchronously (or within a bounded poll loop the platform runs on behalf of the caller), and returns once indexing is complete:

const item = await instance.items.uploadAndPoll("faq.md", content, {
  metadata: { category: "onboarding" }
});
console.log(item.status);  // "completed"

// immediately search after indexing is completed
const results = await instance.search({
  messages: [{ role: "user", content: "onboarding guide" }]
});

Cloudflare's 2026-04-16 framing:

"You can upload a file, the file is sent to index immediately, and you can poll for indexing status all with one uploadAndPoll() API. Once completed, you can search the instance immediately, and there are no external dependencies to wire together."

— (Cloudflare, 2026-04-16)

The caller awaits one Promise; the platform owns the polling loop, retries, error surfacing.

Why it matters for agents

The AI Search support-agent worked example depends on this shape. When the agent resolves a ticket and calls save_resolution:

const item = await instance.items.uploadAndPoll(filename, content);
return { saved: true, filename, status: item.status };

"uploadAndPoll waits until indexing is complete, so the resolution is searchable before the next query." Without this semantic, the agent would have to manage a "write-then-hope" workflow: either accept a silent indexing-lag window (the next turn might miss the write) or implement its own polling loop over a separate indexing-status API.

Structural requirements

  • Unified storage and index — storage and index live in the same platform-managed unit, so "the write is durable" and "the index is consistent with the write" can be combined in one operation.
  • Bounded indexing latency. The Poll half is bounded; runaway indexing would hang the caller. AI Search doesn't publish a p99 indexing-latency number in the 2026-04-16 post; this is a caveat.
  • Status surface. The returned item includes status so the caller can distinguish completed from failed.

Consequences

Pros

  • Write-read consistency at the app boundary. "Document is written" and "document is searchable" converge to one event.
  • No external pipeline to operationalise. No Kafka, no CDC, no batch ETL, no sync-worker on-call rotation.
  • Trivial correctness for write-then-read workflows — which covers most agent-memory (concepts/agent-memory) writes.
  • Applies per-tenant. Combines naturally with runtime-provisioned per-tenant indexes where each tenant's writes must be immediately queryable within their own instance.

Cons / tradeoffs

  • Longer wall-clock for the caller. Fire-and-forget writes are impossible; every write waits for indexing.
  • Hides the indexing tail. If p99 indexing latency is seconds-to-tens-of-seconds, the caller sees that as request latency — potentially breaking SLOs for high-throughput ingest paths.
  • Doesn't fit bulk ingest. Batch uploading a million documents with per-document polling is not the intended path; bulk ingestion needs async with status checks.
  • Caller must handle partial failure. If indexing fails after storage succeeds, the API must surface that cleanly and the caller must decide: retry, compensate, alert.

Contrast

Shape Write semantics Window
Source DB + CDC-fed search index Write returns on DB commit; index catches up async Seconds to minutes
Managed external-source crawl Write to external source; index crawls on schedule Minutes to hours
Two-call API (upload() + getStatus()) Write returns; caller polls separately App-owned loop
uploadAndPoll() Write returns once indexed One awaitable

Seen in

Last updated · 200 distilled / 1,178 read