Matches & Match Review
What is product matching?
Section titled “What is product matching?”When Aperture observes a product listing at a retailer, it must decide whether that listing refers to a product already in the master catalog. This process is exact matching: it confirms identity, not similarity. A match links the observation to a shared master-catalog id. This is what lets Aperture group the same product across retailers. For example, the Market Presence filter below counts how many distinct retailers are linked to a matched product.
The matching pipeline runs automatically and handles most decisions without human input. The Matches section is where you see those outcomes, act on the cases the pipeline held for review, and monitor overall coverage.
The Match Queue
Section titled “The Match Queue”Navigate to Matches to reach the Match Queue. It is a browseable table of every product observation the system has processed, grouped by master-catalog product.
Filtering and sorting
Section titled “Filtering and sorting”The queue can be filtered to five states using the Status filter in the toolbar:
| Status | Meaning |
|---|---|
| All Matches | Every observation, regardless of state. |
| Verified / Exact | The pipeline matched this listing to a master-catalog product with high confidence, or a reviewer approved the match. |
| Pending Review | The pipeline found a probable match but confidence fell below the automatic approval threshold, and the decision is waiting on a reviewer. |
| Unmatched | The listing has not been linked to any master-catalog product. |
| Rejected | A reviewer rejected this candidate as a match. |
The rest of the toolbar lets you narrow the queue further:
- Confidence. High (90 % and above), Medium (70–89 %), or Low (below 70 %).
- Market Presence. Shows only products observed at 2 or more retailers, 3+, 4+, 5+, up to 10+ retailers, counted across all of that product’s observations in the catalog. Useful for focusing on high-coverage items.
- Click the Product or Confidence column headers to sort ascending or descending.
Grouped view
Section titled “Grouped view”Rows are grouped by master-catalog product. Each group header shows the canonical product image and title, brand, and the number of observations for that product on the current page of results. Rows are only grouped within the page you’re viewing, so this count does not reflect a product’s full retailer coverage. To see how many distinct retailers a product is observed at across the whole catalog, use the Market Presence filter above. Click a group header to expand it and inspect each individual observation: its retailer, confidence score, match method, and a reason snippet. Hovering the matched-product cell opens a side-by-side image preview of the observed listing and the master-catalog product. Listings the pipeline could not link to any master-catalog product are listed separately at the bottom of the table under a “No Match Found” heading.
From the Match Queue toolbar you can jump directly to Review Matches or Match Stats.
Match Review
Section titled “Match Review”The Match Review page is a focused, one-at-a-time workflow for clearing the pending queue. Open it from the Review Matches button on the Match Queue, or navigate to Matches › Review.
The header shows the total number of pending matches awaiting review. When the queue is empty, the page shows an “All caught up” screen. If you skipped groups during the session, that screen reports how many matches you skipped and tells you to reload the page to review them again. If the pending matches cannot be loaded, the page shows “Could not load matches” with a Retry button. Your earlier decisions are already saved.
Three-panel layout
Section titled “Three-panel layout”The review screen arranges information across three equal panels:
| Panel | Contents |
|---|---|
| Master Catalog (left) | The canonical product the pipeline proposed as the match: image, title, brand, GTIN, MPN, bundle quantity, weight, net content, and dimensions, plus the price, category, mapped category, and description of the group’s reference observation. See the note below. |
| Actions & Trace (centre) | Match decision summary, Confirm / Reject buttons, candidate navigation, group progress, and the optional full match trace. |
| Match Candidate (right) | The retailer listing being evaluated: the same attributes as the master panel plus SKU, retailer name, sub-retailer, and a link to the live product page. Sub-retailer appears next to the retailer name when the listing carries one. |
Most fields on the Match Candidate panel that differ from the Master Catalog panel are highlighted in amber for quick comparison. Title and image are compared against whatever the Master Catalog panel shows: the canonical master value when the master record already exists in the global catalog, and the reference observation’s own scraped title or image when it does not, the same fallback used below for bundle quantity, weight, net content, and dimensions. Brand works differently. When the product is already in the global catalog, the Match Candidate panel shows the master catalog brand rather than the retailer’s own brand, so brand is never highlighted. Check the listing’s title, image, or live product page to confirm the brand. GTIN and MPN have no such fallback: they are blank when the master record isn’t yet in the global catalog, so a candidate’s identifier is then highlighted as differing from an empty master value. Price, category, mapped category, and description are not canonical in this view, so an amber highlight on these fields compares the candidate listing against the group’s reference observation, not against the master record. That reference observation may be a different retailer’s listing. Bundle quantity, weight, net content, and dimensions are compared against the values shown on the Master Catalog panel: the canonical master figures when the master record carries them, and the reference observation’s scraped figures when it does not.
Reviewing a match
Section titled “Reviewing a match”- Read the match decision summary in the centre panel. It shows the pipeline’s final status, confidence percentage, and match method.
- Compare the two panels. Check title, image, physical attributes, such as size, pack quantity, and weight, and any identifiers present on both sides. Also confirm the brand shown makes sense for the listing.
- Click Confirm Match or Reject, or use the keyboard shortcuts below.
- The next pending candidate appears automatically. When all candidates for a master-catalog product have been reviewed, the queue advances to the next group.
If a match trace is available, a View Full Trace button appears. The trace opens in a dialog and shows how every layer of the pipeline contributed to the decision. See The match trace below.
Keyboard shortcuts
Section titled “Keyboard shortcuts”| Key | Action |
|---|---|
Space | Confirm Match (approve) |
X | Reject |
← / → | Navigate to previous / next candidate within the current group |
N | Skip to the next product group |
Shortcuts do not fire while you type in a text field or select, or while a dialog is open. With focus on a button or link, Space activates that control instead of confirming the match.
Groups and progress
Section titled “Groups and progress”Observations are grouped by master-catalog product. The centre panel shows Candidate X of Y for multi-candidate groups, with ← → arrows to switch between them. Below the action buttons, Group X of Y and a progress bar track your progress through the current batch of up to 250 pending candidates, not the whole pending queue. The total shown in the page header covers the whole queue.
The Skip group button (or N) moves past the current group without deciding on it. A skipped group stays pending. It may reappear in a later batch, but if only skipped matches remain, the page shows “All caught up” and you must reload the page to review them again.
Up to six additional pending candidates in the same group are listed in a card below the progress bar. Click any of them to jump directly to that candidate.
When you finish a batch, the page shows a “Batch complete” screen reporting how many pending matches still remain, with a Load next batch button that shows the remaining count. When none remain, the button reads Check for new matches. The next batch is never loaded automatically. You choose when to continue.
The match trace
Section titled “The match trace”The match trace is the full audit log of how the pipeline decided on a particular listing. It records every stage the engine ran, what each stage found, and the final verdict.
Final decision card
Section titled “Final decision card”At the top of the trace, and in the centre panel before you open the full trace, you see the Final Decision card:
- Status badge. Matched, Pending Review, Unmatched, or Failed.
- Confidence. A percentage from 0–100 %. A high score with method “Barcode (GTIN)” means the match was determined by a unique product identifier. A lower score with a method like “Title Similarity” or “Semantic Search” means the syntactic or semantic layers found a probable but not certain match. Check the AI Verification stage further down the trace to see whether the AI weighed in on an ambiguous pair, and how. The percentage is hidden when it rounds to 0 %.
- Method. The strategy that produced the final result. See the table below.
- Reason. A short plain-language explanation of why the pipeline reached its conclusion.
- Requires manual review label. Shown in amber when the pipeline explicitly held the decision for a human.
Pipeline stages
Section titled “Pipeline stages”The trace lists each stage the engine ran in order, with duration in milliseconds and an outcome icon:
| Stage | What it does |
|---|---|
| Category Mapping | Normalises the listing’s raw category string into the global taxonomy before matching begins. |
| Historical Match | Checks whether this listing was previously matched. If a prior decision exists and is still current, the engine reuses it without re-evaluating. |
| Identifier Match | Matches on GTIN, meaning barcode, or MPN, meaning manufacturer part number. Exact identifier matches produce the highest confidence scores. |
| Title Fuzzy Match | Compares normalised product titles with string-similarity scoring, which combines token overlap and character-level similarity, using Postgres trigram search to pull candidates. Brand, category, and net-content agreement can promote near-identical titles. |
| Description Match | Compares product descriptions for meaningful multi-token overlap. |
| Semantic Search | Resolves the listing’s category to a node in the global taxonomy so later stages can use category agreement as a matching signal. It does not itself propose candidates. |
| Vector Similarity | Embeds titles as vectors and finds semantically close master-catalog products via pgvector search. |
| Abstain Guard | A safety check that evaluates whether the best candidate has sufficient corroborating evidence. If the only evidence is a single low-confidence vector match, or if two candidates are too close to separate, the guard flags the decision for manual review instead of auto-approving. |
| AI Verification | An AI model evaluates the top candidates, up to 10, against the listing. For each candidate, it returns a verdict, either match, mismatch, or unsure, together with a numeric confidence score. Used when the syntactic and semantic layers leave ambiguity. Confirming a candidate here keeps the final method of whichever earlier stage proposed it. |
| Retailer Collision | Shown when a candidate was rejected because a different product from the same retailer is already linked to that master-catalog entry. This is a strong signal that the listing is a size or packaging variant rather than the same product. |
| Final Decision | Appears when the pipeline reaches a decision through the confidence cascade or the abstain check: either an auto-approved match, or a match held for manual review. A high-confidence match found directly by an earlier stage is instead marked “Auto-matched” on that stage, and no Final Decision stage is written when the pipeline creates a new master-catalog entry instead of linking the listing to an existing one. |
A skipped stage means it was unnecessary, because a prior stage already found a definitive answer, because the required service was unavailable, or because none of the candidates could be resolved to master-catalog records to compare against. The skip reason is always printed under the stage, so you can see which case applied. Each stage also shows the strategy that ran, per-candidate scores, any rejection reason, and signal pills. Signal pills are small tags showing the individual signals that fed into the composite score, for example: brand match: ✓, title similarity: 87 %, category node match: ✓, bundle qty match: ✓. A rejected candidate is struck through and labelled with the reason, such as “Retailer already has this product”, “Brand mismatch”, or “Promotion guard”. Hovering a candidate’s internal ID shows a preview card with its image, title, brand, category, and identifiers, or a note that the product is no longer in the global catalog when the ID can’t be resolved.
Match methods
Section titled “Match methods”| Method shown | What produced it |
|---|---|
| Barcode (GTIN) | A deterministic identifier match. It is a GTIN hit found by the identifier layer against the in-memory catalog, including a GTIN recovered from the listing’s title or SKU field when the barcode field itself was missing. A GTIN hit found directly in the global catalog does not carry this label. It shows as its raw value in the Match Queue and trace, and as “Global Barcode (GTIN)” in Match Stats. Manufacturer part-number hits do not carry this label. The label also appears on lower-confidence identifier hits that the pipeline deliberately sent on for further verification rather than auto-approving. An example is a barcode hit whose brand, pack quantity, or model number disagrees with the master record. |
| Identifier Match | A deterministic match on a product identifier. |
| Title Similarity | Fuzzy title comparison |
| Description Match | Description similarity |
| Semantic Search | Vector / embedding similarity |
| AI Verification | A label for an AI-semantic method value, mainly seen on older data. A match the AI verification stage confirms shows the method of the earlier stage that proposed it, not this label. |
| Historical Match | Replay of a prior matching decision |
| Manual | Approved or rejected by a reviewer through this workflow |
| Global Catalog | Matched via an existing global-catalog entry |
| Barcode Variant | The same barcode already present in the global catalog under an equivalent encoding. Examples include a 12-digit UPC matched against its 13-digit EAN, or a value stored without its check digit |
| Batch Dedup | Reused a decision already made earlier in the same import batch |
consensus | A matching decision propagated from an automated consensus pass. Shown as its raw internal value because no friendly label is defined. |
Match Stats
Section titled “Match Stats”Navigate to Matches › Match Stats, or click Match Stats on the Match Queue toolbar, for an aggregate view of matching quality and coverage.
KPI cards
Section titled “KPI cards”Six headline numbers appear at the top:
- Catalog Size. The number of unique products in the master catalog.
- Observations. The total number of retailer listings the pipeline has processed, with the average number of retailers observed per product shown alongside.
- Exact Matches. How many observations are in the Verified / Exact state, that is, resolved to a master-catalog product, whether by the pipeline or by a reviewer’s approval, with a breakdown of how many were matched automatically and how many manually.
- Pending Review. Observations still in the pending state, with the share of all observations. This is a broader number than the Match Review queue: it also includes observations with no proposed master-catalog product, shown as Unmatched in the Match Queue, and pending observations the pipeline did not flag for human review.
- Rejected. Observations a reviewer rejected as a match, with the share of all observations.
- Avg Confidence. The average match confidence across observations that carry a confidence score. Observations with no score are excluded from the average, not counted as zero. Colour-coded green (85 % and above), amber (60–84 %), or red (below 60 %).
Confidence distribution and match methods
Section titled “Confidence distribution and match methods”Two charts sit side by side:
- Confidence Distribution. A bar chart bucketing matched observations by confidence band: 100 %, 90–99 %, 70–89 %, 40–69 %, and below 40 %.
- Match Method Breakdown. A donut chart with a count-and-percentage legend showing how many matches each method produced. Most labels match the Match methods table above, plus “Global Barcode (GTIN)”, “New Product Generated”, and an “Unmatched” slice for observations with no method.
Matching activity
Section titled “Matching activity”A Matching Activity chart tracks the last 35 days of pipeline output as a daily trend: total observations seen that day (“Products Discovered”), observations linked to a master-catalog product (“Matched”, including those still pending review), and observations still in the pending state (“Pending”), which includes unmatched ones that are not in the review queue.
Category and retailer coverage
Section titled “Category and retailer coverage”Two tables round out the page, both showing average confidence computed only across observations that carry a confidence score:
- Category Coverage lists each product category with its total observation count, how many are verified versus pending, and its average confidence, sorted to surface the lowest-confidence categories first.
- Retailer Match Coverage lists each retailer with the same total / verified / pending / average-confidence breakdown, plus its most common match method, sorted by total observations.
The end-to-end review flow
Section titled “The end-to-end review flow”For a step-by-step walkthrough, from spotting pending candidates on the Matches page, through the Match Review queue, to seeing your decisions reflected in Match Stats and in downstream surfaces like Prices and common products, see Reviewing Product Matches: from Pending Queue to Confident Coverage.