Skip to content

Query API

Query endpoints perform similarity search and metadata filtering entirely in the compressed TT-core domain — no dense materialization required.

Pairwise similarity

Compare two stored keys using core-native inner products.

POST /v1/query/similarity

Request body

Field Type Required Description
key_a string Yes First key
key_b string Yes Second key
namespace string No Namespace (default: default)
metric string No cosine (default), euclidean, or dot

Example

curl -X POST https://gate.holonomx.com/v1/query/similarity \
  -H "X-Api-Key: $HX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_a": "field_t42", "key_b": "field_t43", "metric": "cosine"}'

result = hx.query("field_t42", "field_t43", metric="cosine")
print(result.score)  # 0.9987

Response — 200 OK

{
  "key_a": "field_t42",
  "key_b": "field_t43",
  "metric": "cosine",
  "score": 0.9987
}

CU cost: 1.0

Top-K by stored key

Find the K most similar entries to an existing stored key.

POST /v1/query/topk

Request body

Field Type Required Description
query_key string Yes Reference key to compare against
namespace string No Namespace (default: default)
k int No Number of results (default: 10)
metric string No cosine (default), euclidean, or dot
filters object No Metadata filters to narrow candidates

Example

curl -X POST https://gate.holonomx.com/v1/query/topk \
  -H "X-Api-Key: $HX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query_key": "field_t42", "k": 5, "metric": "cosine"}'

result = hx.query_top_k("field_t42", k=5, metric="cosine")
for key, score in result.results:
    print(f"{key}: {score:.4f}")

Response — 200 OK

{
  "query_key": "field_t42",
  "metric": "cosine",
  "n_candidates": 1200,
  "results": [
    ["field_t43", 0.9987],
    ["field_t41", 0.9954],
    ["field_t44", 0.9921],
    ["field_t40", 0.9888],
    ["field_t45", 0.9812]
  ]
}

CU cost: 1.0

Top-K by external vector

Search for the K most similar entries to a vector you provide. The engine decomposes the incoming vector via TT-SVD on arrival, then performs core-vs-core similarity — no dense comparison needed.

POST /v1/query/vector

Request body

Field Type Required Description
data_b64 string Yes Base64-encoded NumPy array
namespace string No Namespace (default: default)
k int No Number of results (default: 10)
metric string No cosine (default), euclidean, or dot
filters object No Metadata filters to narrow candidates

Example

DATA=$(python3 -c "import numpy as np, base64; print(base64.b64encode(np.random.randn(1024).tobytes()).decode())")
curl -X POST https://gate.holonomx.com/v1/query/vector \
  -H "X-Api-Key: $HX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"data_b64\": \"$DATA\", \"k\": 5}"

import numpy as np

query = np.random.randn(1024)
result = hx.query_vector(query, k=5)
for key, score in result.results:
    print(f"{key}: {score:.4f}")

Response — 200 OK

Same schema as Top-K by stored key.

CU cost: 1.0

Search for keys matching metadata filters. This does not perform similarity — it returns all matching entries.

POST /v1/search

Request body

Field Type Required Description
filters object Yes Metadata key-value filters (exact match)
namespace string No Namespace (default: default)

Example

curl -X POST https://gate.holonomx.com/v1/search \
  -H "X-Api-Key: $HX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"source": "turbine_7"}, "namespace": "telemetry"}'

result = hx.search({"source": "turbine_7"}, namespace="telemetry")
print(f"Found {result.count} entries")

Response — 200 OK

{
  "namespace": "telemetry",
  "count": 3,
  "results": [
    {"key": "sensor_001", "metadata": {"source": "turbine_7", "unit": "Pa"}, "version": 1},
    {"key": "sensor_042", "metadata": {"source": "turbine_7", "unit": "K"}, "version": 2},
    {"key": "sensor_099", "metadata": {"source": "turbine_7", "unit": "m/s"}, "version": 1}
  ]
}

CU cost: 0.5

Metrics reference

Metric Formula Range Best for
cosine $\frac{\mathbf{a} \cdot \mathbf{b}}{|\mathbf{a}||\mathbf{b}|}$ [-1, 1] Directional similarity (default)
euclidean $|\mathbf{a} - \mathbf{b}|_2$ [0, ∞) Absolute distance
dot $\mathbf{a} \cdot \mathbf{b}$ (-∞, ∞) Raw inner product

All metrics are computed in the compressed TT-core domain using core-native contractions. The computation cost is $O(d \cdot r^2)$ where $d$ is the number of TT-cores and $r$ is the maximum bond dimension — independent of the original data size.