Fetch data

Fetches rows from a table or view using structured conditions, optional pagination, sort instructions, and optional post-processing (`group_by`, `time_granularity`, aggregation options). Notes: - Route selection supports `X-Athena-Client` or direct PostgreSQL URI headers (`x-pg-uri` preferred). - Direct URI auth bypass is allowed when URI credentials include both username and password. - Direct URI requests always execute inline (deferred gateway queue is skipped). - Optional `schema_name` targets a non-default schema. When provided, `table_name` must not already be schema-qualified. - PostgreSQL-backed fetch execution accepts canonical nested `select` payloads and compatibility `select` strings. - Schema-qualified base tables such as `public.chat_subscriptions` are supported. - Relation-side schema qualification such as `users:athena.users(id,username,image)` is supported. - Legacy `columns` + `conditions` payloads remain supported and are still the right shape for wildcard/simple fetches and non-PostgreSQL gateway fetch backends. - Structured fetch auth checks apply to every referenced table in the nested tree when API-key enforcement is enabled. - Relation joins resolve from foreign-key metadata first; ambiguous edges should provide `foreign_key`. - Unsupported in this release: top-level AST request bodies (`operation` / `from` / `fields`), relation `on` shapes, and schema-qualified relation selectors combined with `via`. - `X-Strip-Nulls` can be used to remove null-valued fields from response payloads. - Cache behavior may include `X-Athena-Cached`, `X-Athena-Cache-Outcome`, and `X-Athena-Cache-Source` headers.

curl -X POST "https://athena-cluster.com/gateway/fetch" \  -H "Content-Type: application/json" \  -d '{    "table_name": "public.chat_subscriptions",    "select": "users:athena.users(id,username,image),user_id",    "where_filters": [      {        "column": "user_id",        "operator": "eq",        "value": "ef7a4c74-cc35-4d32-945a-a5271279ecdb",        "column_cast": "text"      }    ],    "orderBy": [      {        "column": "user_id",        "direction": "desc"      }    ],    "limit": 1  }'

{
  "status": "success",
  "message": "Fetched 1 rows",
  "data": [
    {
      "user_id": "ef7a4c74-cc35-4d32-945a-a5271279ecdb",
      "users": {
        "id": "ef7a4c74-cc35-4d32-945a-a5271279ecdb",
        "username": "floris",
        "image": "https://cdn.example.com/avatar.png"
      }
    }
  ],
  "cache_key": "chat_subscriptions:compatibility:true:7c9b53f4f1f0b902"
}

{
  "status": "error",
  "message": "Invalid structured select request",
  "error": "table 'athena.user' was not found for structured gateway fetch",
  "code": "VALIDATION_FAILED",
  "data": {
    "operation": "fetch"
  }
}