Explain hybrid query | TraceDB Documentation

const url = 'http://127.0.0.1:8090/v1/explain';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "access_path_timings": [
    {
      "access_path_id": "ap_12345",
      "build_ms": 12.5,
      "open_ms": 8.3
    }
  ],
  "access_paths": [
    {
      "access_path_id": "ap_12345",
      "candidates": 5,
      "opened": true,
      "visibility_checked_before_open": true
    }
  ],
  "candidate_budget": 100,
  "deduped_candidate_count": 95,
  "dirty_feature_count": 3,
  "early_stop_reason": "Reached candidate budget limit",
  "exact_fallback_triggered": false,
  "failed_feature_count": 2,
  "final_visibility_guard_count": 10,
  "final_visibility_guard_removed": 2,
  "freshness_mode": "latest",
  "fusion_method": "weighted_sum",
  "hot_overlay_searched": true,
  "lexical_cache_hits": 150,
  "lexical_cache_misses": 25,
  "lexical_indexed_documents": 10000,
  "lexical_scored_documents": 850,
  "materialized_count": 900,
  "missing_feature_count": 1,
  "module_versions": [
    "v1.4.2",
    "v2.0.1"
  ],
  "opened_candidate_streams": [
    "stream_01",
    "stream_02"
  ],
  "pending_feature_count": 4,
  "phase_timings": [
    {
      "elapsed_ms": 45.7,
      "phase": "index_scan"
    },
    {
      "elapsed_ms": 30.2,
      "phase": "scoring"
    }
  ],
  "planner_candidates": [
    {
      "freshness": "2024-06-01T12:00:00Z",
      "record_id": "rec_98765",
      "score_components": {
        "final_score": 0.92,
        "freshness_penalty": 0.05,
        "lexical": 0.4,
        "relational": 0.3,
        "vector": 0.27
      },
      "score_upper_bound": 0.95,
      "source": "vector_index",
      "version_id": 3,
      "visibility_checked": true
    }
  ],
  "policy_epoch": 42,
  "read_epoch": 105,
  "returned_count": 50,
  "scalar_filter_applied": true,
  "scalar_filter_predicates": [
    "status = 'active'",
    "region = 'us-west'"
  ],
  "scalar_filter_removed_records": 10,
  "scalar_filter_visible_records": 490,
  "schema_epoch": 7,
  "segments_scanned": 12,
  "selected_strategy": "hybrid_vector_lexical",
  "skipped_access_paths": [
    "ap_54321",
    "ap_67890"
  ],
  "tenant_mask_visible_records": 480,
  "text_candidates": 30,
  "vector_candidates": 20
}

Current TraceDB v1 product route. This OpenAPI artifact is generated from the checked-in route manifest.

Authentication

AuthorizationBearer

Required by gateway-managed routes; direct local engine development can use any token.

Request

This endpoint expects an object.

cursorstring or nullOptional

Opaque cursor returned by the previous query page.

explainbooleanOptional

freshnessstringOptional

graph_seedstring or nullOptional

scalar_eqmap from strings to anyOptional

Scalar equality predicates keyed by schema scalar column.

tablestringOptional

temporal_as_ofinteger or nullOptional

tenant_idstringOptional

textstring or nullOptional

text_fieldstring or nullOptional

Optional schema text-indexed column to search. When omitted, TraceDB searches all text-indexed columns for backwards-compatible fieldless queries.

top_kintegerOptional>=0

vectorlist of doubles or nullOptional

vector_fieldstring or nullOptional

Optional schema vector column to score. When omitted, TraceDB uses the first vector column for backwards-compatible fieldless queries.

Response

Successful TraceDB response.

access_path_timingslist of objectsOptional

access_pathslist of objectsOptional

candidate_budgetintegerOptional

deduped_candidate_countintegerOptional

dirty_feature_countintegerOptional

early_stop_reasonstring or nullOptional

exact_fallback_triggeredbooleanOptional

failed_feature_countintegerOptional

final_visibility_guard_countintegerOptional

final_visibility_guard_removedintegerOptional

freshness_modestringOptional

fusion_methodstringOptional

hot_overlay_searchedbooleanOptional

lexical_cache_hitsintegerOptional

lexical_cache_missesintegerOptional

lexical_indexed_documentsintegerOptional

lexical_scored_documentsintegerOptional

materialized_countintegerOptional

missing_feature_countintegerOptional

module_versionslist of stringsOptional

opened_candidate_streamslist of stringsOptional

pending_feature_countintegerOptional

phase_timingslist of objectsOptional

planner_candidateslist of objectsOptional

policy_epochintegerOptional

read_epochintegerOptional

returned_countintegerOptional

scalar_filter_appliedbooleanOptional

scalar_filter_predicateslist of stringsOptional

scalar_filter_removed_recordsintegerOptional

scalar_filter_visible_recordsintegerOptional

schema_epochintegerOptional

segments_scannedintegerOptional

selected_strategystring or nullOptional

skipped_access_pathslist of stringsOptional

tenant_mask_visible_recordsintegerOptional

text_candidatesintegerOptional

vector_candidatesintegerOptional

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error

502

Bad Gateway Error

503

Service Unavailable Error