Find similar objects

How do you find similar objects in Tallyfy Answers?

Section titled “How do you find similar objects in Tallyfy Answers?”

The recommendation endpoint lets you find objects similar to a specified reference object.

This similarity search uses vector embeddings¹ to find objects with related characteristics. It’s useful for recommendation systems, content discovery, and finding related items.

How does similarity search work in Tallyfy Answers?

Section titled “How does similarity search work in Tallyfy Answers?”

Here’s how Tallyfy Answers uses semantic similarity to find related objects:

1. Tallyfy converts each whole object, as JSON text, into a vector embedding (a numerical representation)
2. When searching for similar objects, Tallyfy compares vector distances
3. Objects with closer vector distances are more similar
4. Only objects with the same source as the reference object are compared, and the closest come back first

API endpoint

Section titled “API endpoint”

GET /collections/{collection_name}/recommend/{object_id}

This endpoint needs the API key.

Path parameters

Section titled “Path parameters”

Parameter	Type	Required	Description
collection_name	string	Yes	Name of the collection to search in
object_id	string	Yes	The uid of the reference object to find similar objects to

Query parameters

Section titled “Query parameters”

Parameter	Type	Required	Default	Description
limit	integer	No	4	Maximum number of similar objects to return (1-20)

Response

Section titled “Response”

A successful request returns a 200 OK status code and a JSON response like this one, for the reference object article-123:

{
  "message": [
    {
      "title": "Advanced Features",
      "url": "https://example.com/advanced",
      "hierarchy": {"lvl0": "Documentation", "lvl1": "Advanced features"},
      "snippet": "Deep dive into advanced capabilities",
      "source": "Documentation",
      "uid": "article456"
    }
  ],
  "status": 200
}

Response fields

Section titled “Response fields”

Field	Type	Description
message	array	Similar objects, closest first. The closest match, normally the reference object itself, is left out.
message[].title	string	The object’s title
message[].url	string	The object’s url. A root-relative path gets a trailing slash, and a full URL comes back unchanged.
message[].hierarchy	object	The object’s hierarchy, as stored
message[].snippet	string	The object’s snippet
message[].source	string	The object’s source, the same as the reference object’s
message[].uid	string	The object’s uid with any hyphens removed, so article-456 comes back as article456
status	integer	200

Because hyphens are removed, a returned uid may not match the stored one. Use the uid you imported when you pass an object to this endpoint.

There’s no similarity score in the response.

Error scenarios

Section titled “Error scenarios”

Status	Description
404	Collection or reference object not found
400	Invalid collection name format
403	The Authorization header is missing or doesn’t match the API key
422	limit is outside 1 to 20

Example request

Section titled “Example request”

# Find objects similar to article-123, limit to 5 results
curl -X GET "https://answers.tallyfy.com/collections/docs/recommend/article-123?limit=5" \
  -H "Authorization: Bearer your_api_key"

What are common use cases for similarity search?

Section titled “What are common use cases for similarity search?”

• Product recommendations: “Customers who viewed this also viewed…”
• Content discovery: Finding related articles or documentation
• Similarity matching: Identifying near-duplicate content
• Alternative suggestions: Offering similar options when an item is unavailable

What are best practices for similarity search?

Section titled “What are best practices for similarity search?”

• Results always come from objects with the same source as the reference object, so give related objects the same source
• You’ll get better recommendations if your objects contain rich, descriptive text
• Include diverse object attributes to improve similarity matching accuracy

Related articles

Section titled “Related articles”

Answers > Search

Tallyfy Answers search combines AI semantic understanding with traditional keyword matching, so…

Answers > Objects

Objects are the JSON records you store in a Tallyfy Answers collection. They’re indexed in…

Overview

Tallyfy Answers is a hosted search service that matches the JSON objects you send it by meaning…

Answers > Collections

Collections in Tallyfy Answers group similar objects together, like database tables. You can…

Footnotes

Section titled “Footnotes”

1. Lists of numbers that represent what a text means. Tallyfy Answers makes them with Voyage AI’s voyage-3 model. ↩