Querying Vectors
Example: Basic Query
res = index.query(
vector=[0.1, 0.2, ...],
top_k=10,
include_metadata=True,
)
for match in res["matches"]:
print(match["id"], match["score"])
2. Querying with Vector Values
| Param | Type | Notes |
|---|
vector | List[float] | Must match index dim |
sparse_vector | {indices, values} | Hybrid only |
id | str | Alternative to vector |
top_k | int | 1–10000 |
3. Querying by ID
Example: Query by ID
res = index.query(id="doc_42", top_k=5)
# Returns vectors similar to the vector stored under id=doc_42
| Behavior | Detail |
|---|
| Looks up | Internal vector for given ID |
| Self-match | The ID itself appears as top result |
| Missing ID | Returns empty matches |
4. Setting Top K Results
| top_k | Use Case |
|---|
| 1 | Best match (recommendation) |
| 5–10 | RAG retrieval |
| 50–100 | Re-ranking pipeline |
| 10000 | Max (paginate beyond) |
res = index.query(
vector=qv,
top_k=5,
include_metadata=True,
)
for m in res["matches"]:
print(m["metadata"]["title"])
| Param | Default |
|---|
include_metadata | False |
include_values | False |
6. Including Values in Results
Warning: include_values=True dramatically increases response size. Only enable when needed.
| Use Case | Recommend |
|---|
| Re-rank locally | Yes |
| Display results | No |
| Pipeline retrieval | Usually no |
7. Querying Specific Namespace
Example: Namespaced Query
res = index.query(
vector=qv,
top_k=5,
namespace="tenant-a",
)
| Behavior | Detail |
|---|
| Default | Empty namespace "" |
| Cross-namespace | Run N queries and merge |
8. Understanding Match Scores
| Metric | Score Field Meaning |
|---|
| cosine | Similarity in [-1, 1]; higher = closer |
| dotproduct | Raw dot; higher = closer |
| euclidean | Distance; lower = closer (API still sorts best-first) |
9. Handling Query Timeouts
Example: Timeout Handling
try:
res = index.query(vector=qv, top_k=10, timeout=5)
except Exception as e:
# fallback / log / retry
pass
| Cause | Fix |
|---|
| Cold start | Pre-warm with a dummy query |
| Large top_k | Reduce top_k |
| Complex filter | Pre-filter / simplify metadata |
| Lever | Effect |
|---|
| Lower top_k | Faster, smaller payload |
| Skip metadata/values | Smaller response |
| Filter on indexed fields | Reduces candidate set |
| Co-locate region | Sub-10ms network RTT |
| Connection reuse | HTTP keep-alive / pool |