Query Similar Content

Once you’ve uploaded reference data, you can query a Search function and get back the items most similar in meaning to your query. Queries can be text or images — and depending on how compatible the model is across modalities, you can sometimes query a text collection with an image or vice versa.

Query from the console

Open your function and go to the Search tab. Type or paste a text query, or upload an image, and run it.

You’ll see a ranked list of items from your Gallery, each with a similarity score, ordered from most to least similar. The Search tab queries the same set of samples you uploaded via the Import tab and can review in the Gallery tab.

Query from the API

The Search endpoints are separate from the classification invoke endpoint. There’s one for text queries and one for image queries.

Query by text:

POST https://www.nyckel.com/v1/functions/{functionId}/search
Authorization: Bearer {your_access_token}
Content-Type: application/json

{
  "data": "your text query here"
}

Query by image:

POST https://www.nyckel.com/v1/functions/{functionId}/search
Authorization: Bearer {your_access_token}
Content-Type: application/json

{
  "data": "https://example.com/query-image.jpg"
}

The response is a ranked list of reference samples — the items you uploaded earlier — each with a similarity score.

{
  "searchSamples": [
    { "sampleId": "sample_abc123", "distance": 0.18 },
    { "sampleId": "sampleId_def456", "distance": 0.27 },
    { "sampleId": "sample_ghi789", "distance": 0.41 }
  ]
}

Refer to the API Reference for the canonical request and response shape, including how to fetch the full content of a returned sample by its ID.

Reading similarity scores

Search functions return a similarity (or distance) score for each result. Unlike classification confidence, these scores are relative, not probabilities:

Ranking matters more than the absolute number. The top result being 0.78 vs. 0.92 matters less than which item is first.
Look at the score gap. A long flat run of similar scores often means none of the results are a strong match. A clear gap between the top item and the rest is a good sign that the top item really is the best answer.
Set thresholds per application. Run a representative batch of real queries against your own data and pick a cutoff that produces useful results in your interface. The right number is data-dependent — there’s no universal threshold.

Next Steps — where to go from here.