---
title: "Read warehouse column metadata for a named relation."
method: POST
path: "/v1/data/describe"
tags: ["data"]
---

# Read warehouse column metadata for a named relation.

`POST /v1/data/describe`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/data/describe`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Returns column-level metadata (COMMENT, data type, nullability) for one named relation,
so a table element can show warehouse-sourced headers and description tooltips (DVT-134).
The relation is given as TYPED PARTS (`database`/`schema`/`table`), each validated against
a strict identifier allowlist — never one dotted string — so a part is never interpolated
into SQL it hasn't been validated for (DVT-7).

Same tenant gate and sole-decryptor path as `POST /v1/data/query`: a cross-tenant
`sourceId` returns 404. The describe runs read-only as the connection's warehouse role
(Postgres `col_description`, Snowflake warehouse-free `SHOW COLUMNS`). A relation the role
cannot see, or that does not exist, returns an empty `columns` list — never an error that
distinguishes "no such table" from "exists but not yours".

Column comments may be sensitive: they are fetched at request time and never persisted
(ADR-0011).

## Request body

- DescribeRequest
  - `sourceId` string, required: Connection name or UUID (resolved per connection-as-code.md).
  - `database` string: Relation database part. Optional for Postgres (the connection is bound to one database); used to fully qualify a Snowflake relation. Identifier allowlist: letters, digits, _ or $, up to 255 chars.
  - `schema` string, required: Relation schema part. Identifier allowlist: letters, digits, _ or $, up to 255 chars.
  - `table` string, required: Relation table part. Identifier allowlist: letters, digits, _ or $, up to 255 chars.

## Response `200`

Column metadata for the relation (empty list when not visible/found).

- DescribeResponseEnvelope
  - `data` object, required
    - `columns` object[], required: One entry per relation column, in catalog order. Empty when the relation is not visible to the connection's role or does not exist.
      - `name` string, required: Source column name.
      - `comment` string, nullable: The column's warehouse COMMENT, or null when none is set.
      - `dataType` string, nullable: Warehouse data type (informational).
      - `nullable` boolean
  - `meta` Meta, required: Response metadata.
    - `requestId` string, required: Correlates with the X-Request-Id header.
    - `total` integer: Item count, present on collection responses.
    - `nextCursor` string, nullable: Opaque keyset-pagination cursor, present on paginated responses (e.g. GET /v1/dashboards) when more rows exist beyond this page. Pass it back as the `cursor` query param to fetch the next page; absent or null on the last page.
    - `roleResolveDegraded` boolean: Snowflake mode only (DVT-2260), on GET /v1/dashboards: present and true when the caller's live Snowflake role resolution failed or was unavailable — role-shared dashboards may be missing from this page. Omitted (not merely false) whenever resolution succeeded or the role-share arm does not apply (off snowflake mode, an org admin/owner, or off the ingress listener).

## Other responses

- `400`: Two shapes, distinguished by the Problem `type`: - `https://docs.dvt.dev/errors/bad-request` (the default) — malformed request or relation name parts. - `https://docs.dvt.dev/errors/caller-session-unconfirmed` (DVT-3780, DVT-4299, DVT-4318) — the caller's-rights (Snowflake `spcs_token`) session's safety parameters could not be confirmed in band, neither as requested on the login nor after the engine re-pinned them with `ALTER SESSION SET` and read them back again. If that re-pin is itself refused but `MULTI_STATEMENT_COUNT` still reads back as 1, the engine accepts the session in client-bound mode instead, enforcing the statement timeout client-side on every statement — the bound is enforced by dvt cancelling the statement from its own process; a statement detached by an engine restart falls back to the account-level `STATEMENT_TIMEOUT_IN_SECONDS`. This error remains for a parameter read that fails outright, a single-statement count that does not confirm, a re-pin that "succeeds" but still disagrees on read-back, or a non-positive configured timeout. Not a grant or name problem and not remediable by the consumer: report it to dvt support.
- `401`: Missing, invalid, or expired session.
- `404`: Resource does not exist.
- `409`: `https://docs.dvt.dev/errors/not-queryable-connection` (DVT-2540) — the resolved connection is configured for writeback only (`kind='writeback'`) and cannot be used to describe warehouse metadata. No self-heal retry; bind a pushdown connection to this `sourceId` instead.
- `429`: Two causes, distinguished by the Problem `type` (DVT-3464 split this from a single shared `errors/rate-limited`, which made an engine-capacity shed indistinguishable from an actual rate limit): - `https://docs.dvt.dev/errors/rate-limited` — a rate or concurrency limiter for this operation rejected the request before it reached the engine. See `components/responses/RateLimited` for the general per-actor SEC-2 tier; some operations stack an additional operation-specific limiter (the query submit rate limit, the per-org running-job cap, or the trial query ceiling). - `https://docs.dvt.dev/errors/engine-at-capacity` — the engine's own admission control (ADR-0053) shed the request before it reached the warehouse — a dvt engine limit, not a warehouse or rate problem (DVT-765). `suggestion` names the actual wait in seconds and, when the engine reports a scope, whether the per-org or global engine concurrency cap was hit. Both carry `Retry-After` (seconds); back off for at least that long before retrying.
- `502`: The analytics engine could not be reached (`https://docs.dvt.dev/errors/engine-unavailable`) or returned an error (`https://docs.dvt.dev/errors/engine-error`). One 502 on this shape is NOT an engine fault and says so: when Snowflake refuses the caller's-rights LOGIN, the Problem type is `https://docs.dvt.dev/errors/caller-connect-refused` — no session was established and the caller's SQL was never reached, so the remediation is a fresh dvt session rather than the engine logs (DVT-4345).

---

[API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)