René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Migrate client.sql() off deprecated v1 SQL-runner endpoints to the v2 query/sql flow","articleBody":"## Problem\n\n`client.sql()` (the SQL Runner) calls Lightdash API endpoints that have been **deprecated and are past their sunset date** (\"may be removed at any time\"). If Lightdash removes them, `client.sql()` breaks.\n\nThis is independent of query execution (`.execute()`), which already uses the current v2 async flow and is unaffected.\n\n## Deprecated endpoints in use\n\n`lightdash/sql_runner.py` currently calls:\n\n| SDK call | Lightdash status |\n|---|---|\n| `POST /api/v1/projects/{uuid}/sqlRunner/run` | `@deprecated` → `POST /api/v2/projects/{uuid}/query/sql` |\n| `GET /api/v1/projects/{uuid}/sqlRunner/results/{...}` | `@deprecated` → `GET /api/v2/projects/{uuid}/query/{queryUuid}/results` |\n| `GET /api/v1/schedulers/job/{jobId}/status` | (part of the old job-polling flow) |\n\nSource: [`packages/backend/src/controllers/sqlRunnerController.ts`](https://github.com/lightdash/lightdash/blob/main/packages/backend/src/controllers/sqlRunnerController.ts) — the `run` route is annotated `@deprecated Use POST /api/v2/projects/{projectUuid}/query/sql instead`, and the results route `@deprecated Use GET /api/v2/projects/{projectUuid}/query/{queryUuid}/results instead`. These are part of the batch deprecated **2025-02-17** with sunset **2025-05-17**.\n\nThe Lightdash **CLI has already migrated** to v2 (`packages/cli/src/handlers/sql.ts` → `/api/v2/projects/${projectUuid}/query/sql`), so the replacement path is proven.\n\n## Proposed solution\n\nMigrate `client.sql()` to the v2 async query flow:\n\n1. `POST /api/v2/projects/{uuid}/query/sql` with the SQL → returns a `queryUuid`\n2. Poll `GET /api/v2/projects/{uuid}/query/{queryUuid}` until ready, then page results\n\nThis mirrors the flow the SDK **already implements** for metric queries in `_QueryExecutor` (`query.py`) — submit → poll → paginate — so much of that logic can be reused/shared rather than written from scratch.\n\n## Open questions for the team\n\n- **Introspection endpoints:** `sqlRunner/tables` and `sqlRunner/fields` (used by `client.sql_runner.tables()/fields()`) do **not** appear to carry `@deprecated` markers. Leave them on v1, or migrate everything for consistency?\n- **Response shape:** does v2 `/query/sql` + `/query/{queryUuid}/results` return the same row/column shape `SqlResult` expects, or does the result transform need adjusting?\n- **Shared executor:** is it worth refactoring `_QueryExecutor` so both metric-query and SQL-query share the submit/poll/paginate machinery?\n- **Priority:** the sunset date has already passed — how urgent is this relative to other work?\n\n## Scope note\n\n`.execute()` / metric queries, `.compile()` (#5), explores metadata, and `/health` are all on **current, non-deprecated** endpoints — this issue is specifically the SQL Runner.\n","author":{"url":"https://github.com/jpetey75","@type":"Person","name":"jpetey75"},"datePublished":"2026-06-28T18:20:14.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/31/python-sdk/issues/31"}