The same rating key can mean a marketplace average or someone's bad afternoon. Your ingestion job accepts the number, and your app summary suddenly sounds like an angry review.
Lab note 111: we wanted to pin down where a retrieval pipeline should separate app-level evidence from individual testimony.
The catch comes early: the example below is synthetic. It demonstrates an ingestion boundary, not measured answer quality. Separating evidence also won't make a capped collection of reviews representative.
The collision fits in valid JSON
Our app-market Actor can attach reviews to app records and also emit standalone review records.
The Actor's recordType determines whether rating means an app average from 0 to 5 or an individual review score from 1 to 5.
Example: these synthetic records deliberately share an appId while making different claims.
rows = [ { "recordType": "app", "appId": "example-app", "name": "Example app", "rating": 4.5, "reviewCount": 10, "description": "Example inventory synchronization app.", }, { "recordType": "review", "appId": "example-app", "appName": "Example app", "reviewId": "example-review", "rating": 1, "text": "Example review: synchronization stopped during setup.", }, ] A generic numeric filter accepts both ratings. That's the trap: validating the value doesn't validate the claim.
If you serialize both as “app name, rating, text,” the distinction becomes something the model must reconstruct from surrounding prose. Chunking can remove that surrounding prose. A tidy schema union has quietly become an evidence blender.
The boundary belongs before indexing:
dataset records | recordType + rating validation | +-- app ----> aggregate collection ----> overall-rating answers | +-- review -> testimony collection ---> customer-experience answers The collections can be physical indexes or enforced metadata partitions. What matters is that the retrieval request carries the distinction.
Filter by meaning before filtering by score
Sorting mixed records by rating doesn't rank apps. It ranks app averages alongside individual opinions.
That can place an enthusiastic testimonial ahead of an app summary, or let a complaint supply the score for an overall-rating answer. Neither requires malformed data.
Use the discriminator before interpreting the number, and preserve unrated apps without inventing a score.
def typed_score(row): kind = row.get("recordType") if kind not in ("app", "review"): raise ValueError("unknown recordType") if kind == "app" and "rating" not in row: return kind, None value = row.get("rating") minimum = 0 if kind == "app" else 1 if type(value) not in (int, float) or not minimum <= value <= 5: raise ValueError("invalid rating for recordType") return kind, value def eligible_for_rating_rank(row): kind, score = typed_score(row) return kind == "app" and score is not None The type check deliberately rejects booleans. The range comparison also rejects non-finite floating-point values.
Missing app ratings deserve their own boundary. The Actor omits rating when an app has no rating; replacing that omission with zero manufactures a negative signal.
Keep the app available for descriptive retrieval, but use eligible_for_rating_rank before numeric ranking. “Unrated” is useful evidence about what you don't know.
| Evidence | Supports | Does not establish |
|---|---|---|
| App average | The marketplace's aggregate rating | What a particular customer experienced |
| Individual review | That reviewer's published experience | The app's overall rating |
| App review count | Context for the aggregate | Representativeness of the collected review text |
An app-level review count doesn't promote a nearby review into consensus. Adjacency isn't a statistical method, even inside a vector database.
Deduplication needs the evidence type
Deduplicating everything by appId can overwrite an app summary with a review. It can also collapse distinct reviews about the same app.
The reverse mistake is keeping every serialized appearance of a review. With includeReviews and emitReviewRecords enabled, review content can appear inside its parent app and as a standalone record.
Embedding both appearances spends context on repeated testimony. Retrieval may then surface the same complaint through different chunks, making repetition look like corroboration.
Build identities around the claim being stored.
def source_key(row, kind): app_id = row.get("appId") if not isinstance(app_id, str) or not app_id.strip(): raise ValueError("missing appId") if kind == "app": return kind, app_id review_id = row.get("reviewId") if not isinstance(review_id, str) or not review_id.strip(): raise ValueError("missing reviewId") return kind, app_id, review_id This key is for a current-record collection. If you retain historical snapshots, add a deliberate versioning policy rather than assuming dataset order means capture order.
Text similarity alone isn't a replacement for review identity. Similar complaints can come from different reviewers; the same review can also arrive through different ingestion paths.
Keep reviews out of app-summary chunks
A separate review collection won't help if the app document still embeds its attached reviews.
For this pipeline, standalone review records are the indexing source for testimony. The app projection omits reviews; keep the original records separately for inspection and reprocessing.
Give every chunk its own evidence label so a split can't strand the rating beside unlabeled prose.
def prompt_chunks(row, kind, score, chunk_chars=1200): label = "app_average_rating" if kind == "app" else "review_stars" score_text = "unavailable" if score is None else str(score) header = [ f"recordType={kind}", f"appId={row['appId']}", f"{label}={score_text}", ] if kind == "app": count = row.get("reviewCount") if type(count) is int and count >= 0: header.append(f"reviewCount={count}") fields = ("name", "tagline", "description") else: header.append(f"reviewId={row['reviewId']}") fields = ("appName", "author", "date", "text") parts = [] for field in fields: value = row.get(field) if isinstance(value, str) and value.strip(): parts.append(f"{field}: {value}") body = "\n".join(parts) pieces = [ body[start:start + chunk_chars] for start in range(0, len(body), chunk_chars) ] or [""] prefix = "\n".join(header) return [f"{prefix}\n\n{piece}" for piece in pieces] The renamed labels belong to our projection, not the Actor's output schema. The source records retain their original rating fields.
This is deliberately simple character slicing. It preserves the evidence boundary, but it isn't a tokenizer-aware splitter or a token ceiling. Your production chunker should budget the repeated header and body together using the target model's tokenizer.
The useful trade-off is a little repeated metadata in exchange for chunks that can explain what their number means.
Put the filters in front of both collections
Combine validation, identity handling, projection, and routing at ingestion.
Exact duplicate records collapse. Conflicting records with the same identity are withheld for resolution, rather than letting arrival order choose an authoritative version.
def build_collections(records): pending = {} conflicts = set() rejected = [] for row in records: try: kind, score = typed_score(row) key = source_key(row, kind) except ValueError as exc: rejected.append((row, str(exc))) continue if key in pending: if pending[key][0] != row: conflicts.add(key) else: pending[key] = (row, kind, score) collections = {"app": [], "review": []} for key, (row, kind, score) in pending.items(): if key in conflicts: rejected.append((row, "conflicting records for identity")) continue collections[kind].extend(prompt_chunks(row, kind, score)) return collections, rejected def collection_for(intent, collections): routes = { "overall_rating": "app", "customer_experience": "review", } if intent not in routes: raise ValueError("choose an explicit evidence intent") return collections[routes[intent]] collections, rejected_rows = build_collections(rows) aggregate_candidates = collection_for("overall_rating", collections) experience_candidates = collection_for("customer_experience", collections) These candidate lists stand in for the corresponding search collections. The dispatcher selects where retrieval happens; it doesn't implement semantic search.
The conflict policy is conservative: even a changed capture timestamp makes otherwise matching records unequal. For scheduled ingestion, resolve versions explicitly before this boundary or expect those records to be withheld.
We'd make the caller supply the intent explicitly. A keyword heuristic around “rating” won't reliably distinguish “what's the overall rating?” from “why did reviewers give low ratings?”
For a request needing both kinds of evidence, retrieve both routes deliberately and keep their answer sections labeled.
A clean split doesn't make a representative sample
The plain verdict: separate the evidence before retrieval, then carry its meaning through every chunk.
In the synthetic example, the complaint remains available to experience retrieval. Its score can't enter the aggregate candidate pool through the review record.
The worked example uses Ecwid App Market Pricing & Category Scraper, but the ingestion pattern applies whenever a shared field name hides different units of evidence.
There's still a sampling catch. Review collection is capped by maxReviewsPerApp, so averaging the collected review stars creates a statistic about that selection. It doesn't reconstruct the marketplace average.
Likewise, minReviewCount filters apps by published review count. It doesn't make the attached text representative.
Routing constrains what evidence reaches an answer. The answer template must still attribute testimony to a reviewer and aggregate ratings to the app record. A clean index can't preserve that distinction after the application discards it.
Reproduce the evidence boundary
Start with the synthetic cells above to inspect the split without depending on marketplace content.
Then collect app records with attached and standalone reviews. Example: this input chooses an app namespace and enables both review representations.
import os from apify_client import ApifyClient run_input = { "mode": "byApp", "appIds": ["the-printful"], "includeReviews": True, "emitReviewRecords": True, "maxReviewsPerApp": 10, "maxItems": 1, } client = ApifyClient(os.environ["APIFY_TOKEN"]) run = client.actor( "vexaloom-labs/ecwid-app-market-pricing-and-category-scraper" ).call(run_input=run_input) if run["status"] != "SUCCEEDED": raise RuntimeError(f"Actor ended with status {run['status']}") items = client.dataset(run["defaultDatasetId"]).list_items().items live_collections, live_rejected_rows = build_collections(items) For your check:
- Inspect rejected rows before indexing.
- Confirm app chunks exclude attached review text.
- Route an overall-rating request to app records and an experience request to review records.
- Check that answers preserve those evidence labels. If the source provides no reviews, leave testimony unavailable.
Example: use this exact input JSON for the collection step.
{ "mode": "byApp", "appIds": ["the-printful"], "includeReviews": true, "emitReviewRecords": true, "maxReviewsPerApp": 10, "maxItems": 1 } Drafted with AI assistance and reviewed for accuracy.




