Overview
Image Similarity Search allows you to find products based on visual similarity rather than text matching. Select an image by its ID, and the AI analyzes its visual content—including packaging, colors, shapes, and branding—to find similar products in your catalog.
This feature uses multimodal embeddings that combine both visual image data and product metadata (name, description) for more accurate matching.
Prerequisites
Before using image similarity search:
- Enable the Feature: Navigate to Settings → AI Settings and enable “Enable similarity search by images”.
- Image Embeddings: Your product images must have multimodal embeddings generated. This happens automatically in the background after enabling the feature.
**Note:** Generating embeddings for all product images may take some time. The system processes images in the background. New products will automatically get embeddings when their images are added.
Filter Syntax
Image similarity uses the similar to operator with special image/{uuid} or attachment/{uuid} reference syntax.
Basic Syntax
similar to 'image/{uuid}'
Replace {uuid} with the actual UUID of a product image. The system will use that image’s pre-computed embedding to find similar products.
With Threshold
Adjust how strict the similarity matching should be:
similar to 'image/abc123-def456-ghi789' with threshold 0.5
- Lower threshold (e.g., 0.3): More results, looser matches
- Higher threshold (e.g., 0.8): Fewer results, stricter matches
- Default: 0.999 (very strict)
Alternative: Attachment Reference
For attachments with images:
name similar to 'attachment/{uuid}'
Example Use Cases
1. Find Products Similar to a Known Image
If you have a product image UUID and want to find visually similar products:
similar to 'image/abc123-def456-ghi789'
2. Find Products Similar to an Attachment
Use an attachment’s image to find similar products:
name similar to 'attachment/xyz789-abc123-def456'
3. Combine with Text Filters
Narrow results by combining image similarity with other filters:
similar to 'image/abc123-def456' and category.name = 'Supplements'
4. Adjust Similarity Threshold
Find more results with a lower threshold:
similar to 'image/abc123-def456' with threshold 0.4
How Similarity is Calculated
The AI uses Google’s multimodal embedding model (multimodalembedding@001) which creates a combined understanding of:
- Visual Elements: Product packaging, colors, shapes, text on labels, logos
- Product Context: Product name and short description
- Semantic Understanding: Product category, brand identity, and intended use
This combination provides more accurate results than image-only matching. For example, a search using a supplement bottle image will find similar supplement products even if the packaging colors differ, because the AI understands both the visual style and the product category.
Understanding Similarity Scores
Results are ranked by similarity score (0-100%):
| Score Range | Interpretation |
|---|---|
| 75-100% | Same brand/product line, nearly identical packaging |
| 60-75% | Same product type, similar visual style, different brand |
| 40-60% | Related product category, some visual similarity |
| Below 40% | Low similarity, may not be relevant |
Tips for Best Results
card: Use Clear Images
icon: image
Images with good lighting, minimal background clutter, and visible product labels produce the most accurate matches.
card: Consider Product Context
icon: tag
The AI considers product name and description alongside the image. Ensure your product data is accurate for better matching.
card: Try Multiple Images
icon: copy
If results aren't relevant, try searching with a different image of the same product—especially one showing the front label clearly.
card: Combine with Text Filters
icon: filter
Narrow results by combining image similarity with text filters like category or brand.
Troubleshooting
“Image similarity search is not available”
- Verify that Enable similarity search by images is turned on in Settings → AI Settings.
- Check if the embedding worker is running (contact your administrator).
No similar products found
- The image may be too unique or from a category not represented in your catalog.
- Try a different image of the same product.
- Lower the similarity threshold (e.g.,
with threshold 0.4).
Results seem unrelated
- Ensure the referenced image clearly shows a product (not a lifestyle shot or packaging mockup).
- Check if the product has embeddings generated (new images need processing time).
- Try combining with text-based filters to narrow the search scope.
“No embeddings defined for similarity search”
- The entity does not have embeddings configured. Contact your administrator to enable multimodal embeddings for the entity.
Technical Details
**Model:** Google multimodalembedding@001 (1408 dimensions)
**Processing:** Background worker via NATS queue
**Storage:** PostgreSQL with pgvector extension
**Index:** Vector similarity using cosine distance (<=> operator)
[try:/products|Open Products to Try|shopping-cart]