{namespace}`¶

Performs analogical search using the parallelogram rule in hypervector space: A : B :: C : ? — given three known values, find the fourth that completes the analogy.

Request¶

Content-Type: application/json

URL Parameters:

Parameter	Description
`db_name`	Name of the database
`namespace`	Namespace within the database

Body:

Parameter	Type	Required	Default	Description
`a`	string	✅	—	First anchor value
`b`	string	✅	—	Second anchor value (relation source)
`c`	string	✅	—	Query value to apply the relation to
`field_name`	string	❌	`"value"`	Field to search across
`encoding`	string	❌	`"semantic"`	Encoding type (`"semantic"` recommended)
`top_k`	int	❌	`10`	Number of results to return

Behavior¶

Parallelogram rule — The relation vector is computed as B - A in hypervector space. This relation is then applied to C to compute the expected answer: D = C + (B - A). All stored rows are ranked by similarity to the resulting vector.

Anchor resolution — Rows containing A, B, and C in field_name are located in the namespace. If any anchor value is not found, the endpoint returns an empty result with strategy: "anchor_not_found".

Deduplication — Results are deduplicated by field value, and the input values A, B, C are excluded from results.

Confidence — A confidence score is computed from the margin between the top-ranked result and the second-best match. Higher margin = higher confidence.

Responses¶

200 OK¶

{
  "status": "success",
  "query_type": "analogy",
  "analogy": "Einstein:Relativity :: Darwin:?",
  "field": "value",
  "strategy": "hypervector",
  "confidence": 0.842,
  "count": 3,
  "results": [
    {
      "id": 77,
      "score": 0.913,
      "matched_value": "Evolution",
      "data": {
        "value": "Evolution",
        "author": "Darwin"
      }
    }
  ]
}

Field	Description
`analogy`	String representation of the analogy query
`field`	The field searched
`strategy`	`"hypervector"` on success, `"anchor_not_found"` if any anchor is missing, `"no_data"` if namespace is empty
`confidence`	Score confidence based on margin between top-1 and top-2 results (0.0–1.0)
`count`	Number of results returned
`results`	Array of matches with `id`, `score`, `matched_value`, and full `data`

Error Responses¶

Status	Condition
`404`	Collection not found
`500`	Unexpected internal error

Notes¶

All three anchor values (A, B, C) must exist as stored field values in the namespace. If any are missing, strategy will be "anchor_not_found" and results will be empty.
"semantic" encoding is strongly recommended — the parallelogram rule relies on meaningful geometric relationships in the embedding space.
Low confidence scores suggest the analogy is ambiguous or the relation does not generalise well to C.

Example¶

import requests

SERVER_URL = "http://18.220.128.24:8000"
API_KEY    = "yourapitoken"

def analogy_search(db_name: str, namespace: str, a: str, b: str, c: str, field_name: str = "value") -> dict:
    response = requests.post(
        f"{SERVER_URL}/compose/analogy/{db_name}/{namespace}",
        headers={"X-API-Key": API_KEY},
        json={
            "a":          a,
            "b":          b,
            "c":          c,
            "field_name": field_name,
            "encoding":   "semantic",
            "top_k":      5,
        },
    )
    response.raise_for_status()
    return response.json()


result = analogy_search(
    db_name="my_db",
    namespace="knowledge_base",
    a="Einstein",
    b="Relativity",
    c="Darwin",
)
print(result)

Expected output:

{
  "status": "success",
  "query_type": "analogy",
  "analogy": "Einstein:Relativity :: Darwin:?",
  "field": "value",
  "strategy": "hypervector",
  "confidence": 0.842,
  "count": 1,
  "results": [
    {
      "id": 77,
      "score": 0.913,
      "matched_value": "Evolution",
      "data": { "value": "Evolution", "author": "Darwin" }
    }
  ]
}

POST /compose/analogy/{db_name}/{namespace}¶