DEV Community

XanderCross2748
XanderCross2748

Posted on

Travel Itinerary Retrieval Architecture: Postgres Document Revisions (and Why IDs Matter)

Short answer: give every itinerary source an immutable version, build retrieval snapshots from one version at a time, and make the version ID visible in every answer and metric. A planner can then refresh safely without mixing yesterday's hotel policy with today's flight data.

That sounds like a data-model detail. It is really a retrieval contract. In a travel system, documents change while a user is comparing routes: a rail timetable is amended, a museum closes on a Monday, or a hotel edits its cancellation window. A vector index that quietly keeps both copies has no reliable way to explain which one grounded the recommendation.

How should a travel itinerary planner handle retrieval, RAG, and document versioning?

Use a four-stage path: source capture, normalization, indexing, and answer assembly. Picture a conveyor belt. The source event puts a versioned box on the belt; chunking labels each piece with that same box ID; retrieval is allowed to pick pieces from one box; generation prints the label on the result.

The source table needs a stable logical key and an immutable revision key. A compact Postgres shape is enough:

type SourceRevision = {
  sourceId: string;       // e.g. "rail-eu-2026-berlin-prague"
  revisionId: string;    // content hash or monotonic revision token
  capturedAt: string;
  effectiveFrom?: string;
  effectiveTo?: string;
  checksum: string;
};

type ChunkRecord = SourceRevision & {
  chunkId: string;
  ordinal: number;
  text: string;
  embedding: number[];
};
Enter fullscreen mode Exit fullscreen mode

revisionId must never be edited in place. If normalization fixes a date format, write a new revision and retain the old one for audit and replay. The vector record can live in a database extension, a dedicated search service, or a self-hosted index; the invariant is the metadata, not the storage brand.

A copyable refresh loop

Ingestion should be idempotent. Compute a checksum of the normalized source, and stop before embedding when that checksum already belongs to a complete revision. Otherwise, create the revision, write chunks, and publish one snapshot marker only after every chunk is searchable.

type IndexWriter = {
  putChunks(rows: ChunkRecord[]): Promise<void>;
  publish(sourceId: string, revisionId: string): Promise<void>;
};

async function refresh(
  source: SourceRevision,
  text: string,
  writer: IndexWriter,
): Promise<string> {
  const chunks = splitForItinerary(text, 700, 80).map((chunk, ordinal) => ({
    ...source,
    chunkId: `${source.revisionId}:${ordinal}`,
    ordinal,
    text: chunk,
    embedding: embed(chunk),
  }));

  await writer.putChunks(chunks);
  await writer.publish(source.sourceId, source.revisionId);
  return source.revisionId;
}
Enter fullscreen mode Exit fullscreen mode

The publish marker is the useful boundary. Queries first resolve the active revision for each source, then filter by that revision before similarity ranking. During a refresh, users continue reading the previous complete snapshot. After publication, new queries see the new one. There is no half-updated itinerary.

I once treated “all chunks written” as publication and then watched a test answer cite chunk 0 from a new train schedule and chunk 7 from the old one. The test did not fail with a dramatic exception; it returned a plausible connection time. That is the dangerous case. A single revisionId assertion in retrieval tests would have caught it.

Chunking is a freshness decision, too

Chunk size is not just a token-budget knob. A long hotel policy chunk preserves context but can hide a changed sentence inside stale neighboring text. Tiny chunks localize updates, yet they can drop the condition that makes a sentence meaningful.

For itinerary documents, split on semantic boundaries first: route, date, cancellation rule, accessibility note. Keep an overlap only where a sentence crosses a boundary. Store ordinal so a reviewer can reconstruct the source order, and store effective dates separately from capture time. A schedule captured at 09:00 may not become valid until next month.

Measure freshness with two clocks: ingestion lag (capturedAt to index publication) and answer age (now minus the newest capturedAt among cited chunks). Alert on the clocks, not on an arbitrary “daily refresh” promise. Your mileage may vary when partners publish irregularly; the right threshold comes from the provider's update contract and the harm of stale advice.

What breaks first, and what should the system say?

Most failures are quiet:

Failure mode Detection User-facing behavior
Duplicate checksum idempotency check Keep the current snapshot
Missing chunk in a revision count and checksum audit Do not publish that revision
Conflicting effective dates validation rule Ask for a date or show both windows
Retrieval spans revisions query invariant Reject the candidate set and retry
Partner feed is late freshness metric Say the schedule was last captured at a timestamp

The answer assembler should return citations containing sourceId, revisionId, and capturedAt. That makes a support ticket reproducible without exposing internal prompts. It also gives observability a useful join key: trace ID plus revision ID links ingestion logs, retrieval scores, and the final response.

Use counters for rejected publications and mixed-revision candidates. Use a histogram for retrieval latency and a gauge for the age of the active snapshot. Log checksums and IDs, not passport numbers or full booking details. Redaction belongs in the ingestion boundary, before text reaches embeddings.

Three-word rule: fail closed.

A transactional database with a vector extension keeps revisions and metadata close together, which is convenient for a small team and makes atomic publication straightforward. An object store plus a separate vector engine can isolate large source files and scale indexing workers independently, but it adds consistency work between the two systems. A hosted search product may reduce operations, while its filtering, snapshot, or retention semantics become constraints you must verify.

Do not choose based on embedding throughput alone. Ask whether the system can express “only revision R,” retain old revisions for a defined period, expose filter latency, and export enough metadata to rebuild an index. A fast similarity result that cannot be audited is not a retrieval architecture; it is a guess generator.

The catch is operational complexity. If your team cannot run checksum audits, publication markers, and freshness alerts, a simpler keyword index over a small, manually curated corpus may be more suitable. Stick with a basic relational search when updates are rare and every document can be reviewed before release. Move to vector retrieval when semantic recall is the actual bottleneck, and carry the same version contract with you.

Further reading

Top comments (0)