> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/workflows/blocks/blocks/run-a-model/roboflow-visual-search-classifier.md).

# Roboflow Visual Search Classifier

Classify an image by finding the most visually similar annotated image.

Search a Roboflow classification project for the visually closest image and return the matched image's classification annotation as a standard classification prediction. Single-label annotations are returned in single-label classification shape, and multi-label annotations are returned in multi-label classification shape. Classification confidence is derived from the best candidate's public Roboflow project search `score` field when present.

This block performs an external visual search API call and is not intended for real-time or high-throughput workloads. To bound latency, query images are downscaled with aspect ratio preserved to a maximum side length of 224 pixels by default. Increase `max_image_size` when finer visual matching is more important than lower latency.

## How This Block Works

This block uses Roboflow project image search:

1. Receives an input image from the workflow
2. Downscales the query image if its larger side exceeds `max_image_size`
3. Sends the query image to Roboflow project search as `image_base64`
4. Requests candidate image fields and classification labels or annotations
5. Uses the best candidate's annotation as the predicted class
6. Maps the API `score` field to classification confidence when present
7. Returns the result through the standard `predictions` classification output

The target project must expose classification annotation data in visual search results. This block does not train a model, create annotations, consume raw search backend relevance scores, or manage the visual search index.

### Type identifier

Use the following identifier in step `"type"` field: `roboflow_core/visual_search_classifier@v1` to add the block as a step in your workflow.

### Properties

| **Name**         | **Type** | **Description**                                                                                                                                                                                                 | Refs |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `name`           | `str`    | Enter a unique identifier for this step..                                                                                                                                                                       | ❌    |
| `target_project` | `str`    | Roboflow classification project URL slug to search..                                                                                                                                                            | ✅    |
| `workspace`      | `str`    | Optional Roboflow workspace URL slug that owns the target project. If not provided, the workspace is resolved from the request API key..                                                                        | ✅    |
| `top_k`          | `int`    | Number of visually similar image candidates to request. The nearest candidate is used for classification..                                                                                                      | ✅    |
| `max_image_size` | `int`    | Maximum side length, in pixels, for the visual search query image. Images larger than this are downscaled with aspect ratio preserved before search. Increase this value for finer matching at higher latency.. | ✅    |

The **Refs** column marks possibility to parametrise the property with dynamic values available in `workflow` runtime. See *Bindings* for more info.

### Runtime compatibility

`requires_internet` - air-gapped / offline deployments : This block depends on a service that is not reachable from fully offline / air-gapped deployments.

### Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds `Roboflow Visual Search Classifier` in version `v1` has.

<details>

<summary>Input and output bindings</summary>

* input
  * `image` ([*`image`*](/workflows/developer-guide/developer-guide/kinds/image.md)): Image to classify using visual search..
  * `target_project` ([*`roboflow_project`*](/workflows/developer-guide/developer-guide/kinds/roboflow-project.md)): Roboflow classification project URL slug to search..
  * `workspace` ([*`string`*](/workflows/developer-guide/developer-guide/kinds/string.md)): Optional Roboflow workspace URL slug that owns the target project. If not provided, the workspace is resolved from the request API key..
  * `top_k` ([*`integer`*](/workflows/developer-guide/developer-guide/kinds/integer.md)): Number of visually similar image candidates to request. The nearest candidate is used for classification..
  * `max_image_size` ([*`integer`*](/workflows/developer-guide/developer-guide/kinds/integer.md)): Maximum side length, in pixels, for the visual search query image. Images larger than this are downscaled with aspect ratio preserved before search. Increase this value for finer matching at higher latency..
* output
  * `predictions` ([`classification_prediction`](/workflows/developer-guide/developer-guide/kinds/classification-prediction.md)): Predictions from classifier.
  * `inference_id` ([`inference_id`](/workflows/developer-guide/developer-guide/kinds/inference-id.md)): Inference identifier.
  * `candidate_found` ([`boolean`](/workflows/developer-guide/developer-guide/kinds/boolean.md)): Boolean flag.
  * `class_found` ([`boolean`](/workflows/developer-guide/developer-guide/kinds/boolean.md)): Boolean flag.
  * `best_candidate` ([`dictionary`](/workflows/developer-guide/developer-guide/kinds/dictionary.md)): Dictionary.
  * `candidates` ([`list_of_values`](/workflows/developer-guide/developer-guide/kinds/list-of-values.md)): List of values of any type.
  * `best_candidate_image` ([`image`](/workflows/developer-guide/developer-guide/kinds/image.md)): Image in workflows.
  * `visual_search_score` ([`float`](/workflows/developer-guide/developer-guide/kinds/float.md)): Float value.
  * `error_status` ([`boolean`](/workflows/developer-guide/developer-guide/kinds/boolean.md)): Boolean flag.
  * `message` ([`string`](/workflows/developer-guide/developer-guide/kinds/string.md)): String value.

</details>

<details>

<summary>Example JSON definition</summary>

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/visual_search_classifier@v1",
	    "image": "$inputs.image",
	    "target_project": "reference-images",
	    "workspace": "my-workspace",
	    "top_k": 1,
	    "max_image_size": 224
	}
```

</details>