Image search - AnalyticDB - Alibaba Cloud Documentation Center

The AnalyticDB for MySQL image search service supports search by image, search by text, and tag filtering. Use this service to build visual search applications for e-commerce product retrieval, content recommendation, and security identification.

Important

The image search feature is currently in a private preview. To use this feature, submit a ticket or contact technical support to have it enabled.

Key features

Multi-mode search engine

The image search service offers three working modes to suit different business scenarios. You must specify a working mode when you create an image library. You cannot change the mode after creation.

Mode	Use cases	Core capabilities
Item Search (`item_search`)	E-commerce product retrieval, fashion design	Automatically identifies and extracts the embedding for a specific item for precise item matching.
General Search (`general_search`)	Content recommendation, image library management	Generates a semantic embedding for the entire image, supporting both search by image and search by text.
Adaptive Search (`adaptive_search`)	Security surveillance, identity recognition	Uses a dual-path feature extraction process. It optimizes facial features for face images and switches to full-image semantic features for non-face images.

Note: During import and retrieval, the image search service automatically converts images and text into high-dimensional numerical vectors (embeddings). It then uses vector similarity to perform semantic matching. You do not need to call an embedding model yourself.

Tag filtering

Custom tags: Attach key-value pair tags, such as color, season, or category, when you import an image.
Compound filter syntax: Supports exact match, contains match, multi-value match, and logical combinations (AND/OR).
Filter during retrieval: Combine tag-based conditions with vector similarity search to refine your results.

Manage multiple image libraries

You can create multiple image libraries. Data is isolated between libraries, making the service suitable for multi-tenant SaaS scenarios.

Feature overview

Feature	Description
Image library management	Create, query, and delete image libraries. You must specify a working mode (Item Search, General Search, or Adaptive Search) upon creation. You cannot change this mode later.
Image import	Import images into an image library. Supports single synchronous imports and batch asynchronous imports from an OSS JSONL file. You can include custom tags for subsequent filtering.
Image retrieval	Retrieve similar images from an image library. Search by image: Use an image as a query to find visually similar images in the library. Supports both item-level precision matching and full-image semantic matching. Search by text: Enter a text description, such as "white short-sleeve t-shirt", to retrieve semantically matching images. Supports automatic translation for multiple languages. Tag filtering: During retrieval, supports compound filter conditions based on custom tags, including AND/OR logical combinations.

API overview

All APIs share the same prefix: /api/v1/operators/image-search

Image library management

API	Method	Path
Create image library	POST	`/library/create`
List image libraries	GET	`/library/list`
Delete image library	POST	`/library/delete`

Image import

API	Method	Path
Single import (synchronous)	POST	`/image/add`
Batch import (asynchronous)	POST	`/image/tasks/create`
Query batch import task status	GET	`/image/tasks/results/{task_id}`

Image retrieval

API	Method	Path
Search by image	POST	`/search/by-image`
Search by text	POST	`/search/by-text`

Common response structure

All APIs return a unified JSON structure:

{
  "status": "SUCCESS",
  "message": null,
  "data": { ... }
}

Field	Type	Description
`status`	string	The business status code. `"SUCCESS"` indicates a successful operation. Other values indicate specific error types.
`message`	string / null	A description of the status. This is `null` on success and provides a specific error reason on failure.
`data`	object / null	The business data payload. It is `null` on failure and may also be `null` for some successful API calls.

Standard HTTP status codes, such as 200, 400, 403, 404, 409, and 500, are used for coarse-grained status checks. The status and message fields in the response body provide fine-grained business error information.

Typical application scenarios

E-commerce product retrieval

Build a "find similar by photo" feature. When a user uploads a product photo, the system automatically identifies the main object (such as a dress or a pair of shoes), retrieves visually similar items from the product database, and allows for filtering by tags like color and size.

Intelligent content recommendation

Provide personalized recommendations on a content platform. When a user views an image, the system extracts its semantic features, retrieves content with a similar style or theme, and ranks the results based on the user's profile.

Enterprise image asset management

Manage visual assets for large enterprises. You can batch import historical image resources with categorical tags, allowing you to quickly discover required assets through text descriptions or example images.

Limitations

Item	Description
Working mode	After you create an image library, you cannot change its working mode. To switch modes, you must delete the image library and create a new one.
Number of image libraries	A single AnalyticDB for MySQL instance supports up to 5 image libraries. To request an increase, contact technical support.
Search by text	Only available for image libraries in `general_search` (General Search) mode.