SearchResults

Retrieval result object

Returned by Table.search, retrieval db.sql(...), and pages from sql_stream.

Methods

to_pandas() -> DataFrame

Convert to a pandas-compatible dict structure (requires pandas for convenient use).

frame = results.to_pandas()
# columns typically include id, score

to_polars() -> DataFrame

Convert to Polars (requires polars installed).

explain() -> str

Human-readable metrics string (tier candidate counts, decompressions).

results = table.search("Tesla", explain=True)
print(results.explain())
# "tier1=84 tier2=20 tier3=5 decompressions=5"

Properties

provenance -> str | None

Structured JSON provenance trace. Only populated when explain=True was passed to Table.search. Returns None otherwise.

The JSON string contains a ProvenanceRecord with per-tier candidate lists, drop reasons, and latency:

import json

results = table.search("financial crisis 2008", top_k=5, explain=True)
prov = json.loads(results.provenance)

Schema:

{
  "query": "financial crisis 2008",
  "strategy": null,
  "tier1": {
    "bm25_candidates": [{"id": 42, "score": 0.91}, ...],
    "hnsw_candidates": [{"id": 42, "score": 0.87}, ...],
    "rrf_merged": [],
    "drops": [],
    "latency_us": 0
  },
  "tier2": {
    "bm25_candidates": [],
    "hnsw_candidates": [],
    "rrf_merged": [{"id": 42, "score": 0.94}, ...],
    "drops": [{"id": 77, "stage": "crag_filter", "reason": "crag median filter"}],
    "latency_us": 0
  },
  "tier3": {
    "bm25_candidates": [],
    "hnsw_candidates": [],
    "rrf_merged": [],
    "drops": [],
    "latency_us": 0
  },
  "final_ids": [42, 11, 55],
  "total_latency_ms": 3.4
}

Drop stages:

Stage	Meaning
metadata_filter	Excluded by a WHERE clause
tier1_budget_cut	Fell below Tier 1 candidate budget
tier2_budget_cut	Fell below Tier 2 candidate budget
crag_filter	Removed by CRAG median filter
tier3_budget_cut	Fell below final top-k budget

The same record is appended to <db>/<table>/_search_log.ndjson on disk for offline analysis.

See Retrieval provenance for query patterns and use cases.

Analytics results

GROUP BY queries return an analytics wrapper with the same to_pandas() / to_polars() methods and columns named after the group key and aggregate (for example tag, count).