{
  "docVersion": 1,
  "id": "blog-gis-2",
  "name": "\"Drivers within 3 km\" — how the query stays fast",
  "purpose": "A radius query: GiST bounding boxes cheaply eliminate everyone outside a box, exact distance filters the rest, and <-> orders the survivors by true distance.",
  "nodes": {
    "rider": {
      "type": "user",
      "label": "Rider pin",
      "x": 40,
      "y": 260,
      "w": 140,
      "h": 86,
      "runtime": "28.61, 77.20"
    },
    "q": {
      "type": "search",
      "label": "ST_DWithin(loc, pin, 3000)",
      "x": 320,
      "y": 260,
      "w": 210,
      "h": 86,
      "color": "blue",
      "runtime": "radius = 3 km"
    },
    "idx": {
      "type": "search",
      "label": "GiST bounding-box scan",
      "x": 640,
      "y": 120,
      "w": 200,
      "h": 86,
      "color": "amber",
      "notes": "Step 1: the index compares BOUNDING BOXES, not exact geometry — it throws away the 99% of drivers whose box can't be within 3 km. Cheap, integer-ish math."
    },
    "exact": {
      "type": "k8s",
      "label": "exact distance check",
      "x": 640,
      "y": 320,
      "w": 200,
      "h": 86,
      "color": "green",
      "notes": "Step 2: on the tiny surviving candidate set, PostGIS computes true distance and keeps only those genuinely within 3 km."
    },
    "knn": {
      "type": "worker",
      "label": "ORDER BY loc <-> pin",
      "x": 640,
      "y": 520,
      "w": 200,
      "h": 86,
      "color": "purple",
      "runtime": "LIMIT 10"
    },
    "out": {
      "type": "mobile",
      "label": "10 nearest drivers",
      "x": 960,
      "y": 320,
      "w": 140,
      "h": 86,
      "color": "green",
      "runtime": "~milliseconds"
    }
  },
  "edges": {
    "e1": {
      "from": "rider",
      "to": "q",
      "fromSide": "right",
      "toSide": "left",
      "animated": true
    },
    "e2": {
      "from": "q",
      "to": "idx",
      "fromSide": "right",
      "toSide": "left",
      "label": "1 · prune by box"
    },
    "e3": {
      "from": "idx",
      "to": "exact",
      "fromSide": "bottom",
      "toSide": "top",
      "label": "2 · refine survivors",
      "color": "amber",
      "style": "dashed"
    },
    "e4": {
      "from": "exact",
      "to": "knn",
      "fromSide": "bottom",
      "toSide": "top",
      "label": "3 · sort by <->",
      "color": "green"
    },
    "e5": {
      "from": "knn",
      "to": "out",
      "fromSide": "right",
      "toSide": "top",
      "label": "top 10",
      "color": "purple",
      "animated": true
    }
  },
  "boxes": {},
  "texts": {
    "t1": {
      "x": 40,
      "y": 430,
      "text": "the #1 PostGIS mistake:  WHERE ST_Distance(loc, pin) < 3000\n→ that computes distance for EVERY row — no index, full scan, slow.\nST_DWithin(...) is the index-friendly twin. always use it for radius.",
      "color": "red",
      "size": 12
    }
  },
  "meta": {
    "createdAt": "2026-07-21T09:00:00.000Z",
    "modifiedAt": "2026-07-21T09:00:00.000Z"
  }
}