examples · sql · 12 / 13 · limited

12. DELETE via /sql (returns translation)

caveat

Same caveat as UPDATE: DELETE through /sql translates but doesn't execute. The response tells you which row would be deleted. To actually delete it, send DELETE /v1/tenants/:t/rows/:schema/:pk.

the /sql path

POST /v1/tenants/:t/sql (translation only)

# /sql DELETE: translates only, doesn't execute.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/sql" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "DELETE FROM shop.orders WHERE id = '\''o_003'\''"
  }'

response (the translation)

{
  "kind":   "delete",
  "schema": "shop.orders",
  "pk":     "o_003"
}

the recommended path

DELETE /v1/tenants/:t/rows/:schema/:pk

# Recommended: DELETE on the row endpoint.
curl -X DELETE "https://$OC_HOST/v1/tenants/$OC_TENANT/rows/shop.orders/o_003" \
  -H "Authorization: Bearer $OC_TOKEN"

# Python SDK doesn't have an explicit delete helper for rows yet -
# use fetch / requests via the SDK's _request or raw HTTP.
import requests, os

requests.delete(
    f"https://{os.environ['OC_HOST']}/v1/tenants/{os.environ['OC_TENANT']}/rows/shop.orders/o_003",
    headers={"Authorization": f"Bearer {os.environ['OC_TOKEN']}"},
)

what gets cleaned up

Deleting a row tears down its secondary index entries, graph edges declared on it, and FTS / vector index entries (if any) - all in the same WAL frame. No follow-up cleanup required from your side.

irreversible

Deletes are not soft. Once the WAL frame is committed, the row is gone. If you need recovery, use point-in-time recovery from Restore.