# how_to_join

How To Join · v1.3.0 · curated

Return the fail-closed measured way to join two Vlada substrate tables, including an explicit DIRECT_OK, DIRECT_DECLARED_KEY, NEEDS_GRAIN, ROUTE_THROUGH_DIM, ROUTE_MULTIHOP, or DO_NOT_SERVE directive. Direct joins come from (in order) the measured connection registry, the VALIDATED join graph (catalog.json join_edges: uniqueness >= 0.999 and match >= 0.80, measured live), or the semantic layer's declared shared surrogate key (DIRECT_DECLARED_KEY, labelled not-live-measured); a validated or declared direct join is always preferred over a route and never refused. Route coverage (min_coverage) is the weaker side of the weakest hop; a route under 50% is labelled low_coverage_route. Unproved composite, NEEDS_GRAIN, quarantined, impossible, or N:M direct evidence cannot be served. With only table_a, it lists every executable connection from that table.

**Inputs.**
- `table_a` (required): 
- `table_b`: 
- `limit`: 
- `offset`: 

**Known limits.**
- Only joins resolvable to physical columns + measurable live are in the registry; big-fact joins are dimension-routed. Absence of a verified join means 'not proven', not 'impossible'.

**A real answer** (customer seat, 0.24 s, args `{"table_a":"fact_hospital_chargemaster","table_b":"dim_provider_ccn"}`):

```json
{
 "value": {
  "table_a": "fact_hospital_chargemaster",
  "directive": "DIRECT_OK",
  "join": {
   "source": "catalog.json join_edges (validated_sampled)",
   "entity_key": "cms:ccn",
   "verdict": "VALIDATED",
   "match_rate": 0.999409,
   "uniqueness_on_authority": 1.0,
   "left_cov": 0.999409,
   "right_cov": null,
   "cardinality": "N:1",
   "fan_out_ratio": 1.0,
   "sample_size": 5076,
   "notes": "PASSED on a SAMPLE of the fact side -- this shows the join works, not that it holds universally."
  },
  "path": null,
  "grain_qualifier": [],
  "registry": {
   "status": "loaded",
   "measured_edge_count": 3008,
   "join_graph_validated_edge_count": 164,
   "table_count": 305,
   "source_files": []
  }
 },
 "unit": null,
 "vintage": null,
 "methodology": null,
 "caveats": [],
 "response_hash": "dbfeb6f1323d95fe4df912741b146b40305b3b8b2b716d7602516e06b1fa4426",
 "semantic_version": 1,
 "tool_version": "how_to_join@1.3.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "scope": {
   "tool": "how_to_join",
   "filters": {
    "table_a": "fact_hospital_chargemaster",
    "offset": 0
   }
  }
 },
 "method": "Computed over the filters shown in this answer's scope, from the sources listed in its evidence. Nothing outside those filters was included. You did not specify offset; 0 was used.",
 "evidence": {
  "response_hash": "dbfeb6f1323d95fe4df912741b146b40305b3b8b2b716d7602516e06b1fa4426"
 },
 "defaults_applied": [
  {
   "param": "offset",
   "used": 0,
   "reason": "tool default"
  }
 ],
 "as_of": "2026-11-09",
 "as_of_basis": "the catalog of data sources this answer was composed from"
}
```

REST: `POST https://api.vladahealth.com/v1/tools/how_to_join` with the inputs as the JSON body. MCP: the tool by name.