Run hybrid query | TraceDB Documentation

const url = 'http://127.0.0.1:8090/v1/query';
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);
}

{
  "explain": {
    "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": "max_candidates_reached",
    "exact_fallback_triggered": false,
    "failed_feature_count": 0,
    "final_visibility_guard_count": 2,
    "final_visibility_guard_removed": 1,
    "freshness_mode": "strict",
    "fusion_method": "weighted_sum",
    "hot_overlay_searched": true,
    "lexical_cache_hits": 150,
    "lexical_cache_misses": 25,
    "lexical_indexed_documents": 5000,
    "lexical_scored_documents": 4500,
    "materialized_count": 4800,
    "missing_feature_count": 0,
    "module_versions": [
      "v1.2.3",
      "v1.2.4"
    ],
    "opened_candidate_streams": [
      "stream_01",
      "stream_02"
    ],
    "pending_feature_count": 4,
    "phase_timings": [
      {
        "elapsed_ms": 30.7,
        "phase": "index_lookup"
      },
      {
        "elapsed_ms": 45.2,
        "phase": "scoring"
      }
    ],
    "planner_candidates": [
      {
        "freshness": "2024-06-01T12:00:00Z",
        "record_id": "rec_98765",
        "score_components": {
          "final_score": 0.95,
          "freshness_penalty": 0.05,
          "lexical": 0.4,
          "relational": 0.3,
          "vector": 0.2
        },
        "score_upper_bound": 1,
        "source": "primary_index",
        "version_id": 42,
        "visibility_checked": true
      }
    ],
    "policy_epoch": 202406,
    "read_epoch": 202406,
    "returned_count": 10,
    "scalar_filter_applied": true,
    "scalar_filter_predicates": [
      "status = 'active'",
      "region = 'us-west'"
    ],
    "scalar_filter_removed_records": 15,
    "scalar_filter_visible_records": 985,
    "schema_epoch": 202405,
    "segments_scanned": 12,
    "selected_strategy": "hybrid_search",
    "skipped_access_paths": [
      "ap_54321"
    ],
    "tenant_mask_visible_records": 1000,
    "text_candidates": 7,
    "vector_candidates": 3
  },
  "next_cursor": "eyJwYWdlIjoxMiwib3ZlcmZsb3ciOnRydWV9",
  "results": [
    {
      "fields": {},
      "record_id": "rec_98765",
      "score": {
        "final_score": 0.95,
        "freshness_penalty": 0.05,
        "lexical": 0.4,
        "relational": 0.3,
        "vector": 0.2
      },
      "tenant_id": "tenant_123",
      "version_id": 42
    }
  ]
}

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.

explainobjectOptional

Explain response.

next_cursorstring or nullOptional

resultslist of objectsOptional

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