> ## Documentation Index > Fetch the complete documentation index at: https://developers.askparable.com/llms.txt > Use this file to discover all available pages before exploring further. # Describe a Pool table > Describes one table of the catalog. 1. tableRef is the name a FROM clause takes, such as providers.jiracloud.issues. 2. Each field has its Arrow type, its Parable scalar when it has one, and whether it is hidden or a system column. 3. importedForeignKeys are documented relationships, not enforced constraints: a join on one can still multiply rows. 4. A null row count, watermark or validation rate means unknown. ## Access An MCP token or a Parable token can call this operation. See [Authentication](/getting-started/authentication.md) for the kinds of token. Your roles must grant `tenant.data.catalog`. ## Errors * `HTTP 404`: No table of that name is in a Pool the caller may read. The name may be misspelled, or the table may be in a Pool their role does not reach. Copy tableRef from a search result. * `HTTP 403`: The caller cannot read the Workspace data catalog. Use an identity with data catalog permission. ## OpenAPI ````yaml /api-reference/openapi.json post /api/provider-pool/describe-table openapi: 3.0.3 info: description: >- Use the Workspace API to work with artifacts, connectors, Parables, and account resources. title: Workspace API version: v2026.10.22.1 servers: [] security: [] paths: /api/provider-pool/describe-table: post: tags: - Provider pool summary: Describe a Pool table description: >- Describes one table of the catalog. 1. tableRef is the name a FROM clause takes, such as providers.jiracloud.issues. 2. Each field has its Arrow type, its Parable scalar when it has one, and whether it is hidden or a system column. 3. importedForeignKeys are documented relationships, not enforced constraints: a join on one can still multiply rows. 4. A null row count, watermark or validation rate means unknown. operationId: ProviderPoolDescribePoolTableHandler parameters: - description: >- Workspace slug. Overrides subdomain-based workspace resolution when provided. in: header name: X-Tenant required: false schema: example: acme type: string - description: Optional request correlation ID echoed back in the response. in: header name: X-Request-ID required: false schema: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DescribePoolTableInput' required: true responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/PoolTableDescription' links: $ref: '#/components/schemas/ResponseLinks' meta: $ref: '#/components/schemas/ResponseMeta' required: - data - meta type: object description: Successful response headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '400': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: >- The request is not valid. `detail` says why. A value that breaks a field rule gives the code `WA-VL-001` and an `errors` member that names each field. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '401': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: The token is missing, malformed, revoked, or expired. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '403': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: >- The token cannot make this request. For example, the roles of its owner do not allow the operation. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '413': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: The request body is larger than 1 MB. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '429': content: text/plain: schema: example: Too Many Requests type: string description: >- More than 120 requests a minute came from your address. Wait for the number of seconds in `Retry-After`, then try again. headers: Retry-After: description: The number of seconds to wait before you try again. schema: type: integer X-Request-ID: $ref: '#/components/headers/X-Request-ID' '500': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: The request failed on the server. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '504': content: text/plain: schema: example: Gateway Timeout type: string description: The operation did not finish in 30 seconds. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' security: - bearerAuth: [] x-codeSamples: - label: TypeScript SDK lang: typescript source: >- import { WebApiSDK } from "@parable-platform/web-api-sdk"; import type { DescribePoolTableInput } from "@parable-platform/web-api-types"; const sdk = new WebApiSDK({ baseUrl: process.env.PARABLE_API_URL!, auth: { token: process.env.PARABLE_API_TOKEN! }, requestInterceptor: (config) => ({ ...config, headers: { ...config.headers, "X-Tenant": process.env.PARABLE_WORKSPACE! }, }), }); const input: DescribePoolTableInput = JSON.parse(`{ "tableRef": "example" }`); const result = await sdk.providerPool.describePoolTable( input ); - label: Python SDK lang: python source: |- import json import os from parable_types_web_api import DescribePoolTableInput from parable_web_api_sdk import ClientConfig, WebApiSDK sdk = WebApiSDK( ClientConfig( base_url=os.environ["PARABLE_API_URL"], auth_token=os.environ["PARABLE_API_TOKEN"], default_headers={"X-Tenant": os.environ["PARABLE_WORKSPACE"]}, ) ) input_data = DescribePoolTableInput.model_validate( json.loads("{\"tableRef\":\"example\"}"), ) result = sdk.provider_pool.describe_pool_table(input_data) - label: Rust SDK lang: rust source: >- use parable_web_api_sdk::{types, ClientConfig, RequestOptions, WebApiSdk}; let sdk = WebApiSdk::new(ClientConfig::with_base_url( std::env::var("PARABLE_API_URL")?, Some(std::env::var("PARABLE_API_TOKEN")?), None, ))?; let options = RequestOptions::with_header("X-Tenant", std::env::var("PARABLE_WORKSPACE")?, None, None); let input: types::DescribePoolTableInput = serde_json::from_value( serde_json::json!({ "tableRef": "example" }), )?; let result = sdk.provider_pool.describe_pool_table( input, Some(&options) ).await?; - label: Go SDK lang: go source: "sdk, err := webapisdk.New(webapisdk.SDKConfig{\n\tBaseURL: os.Getenv(\"PARABLE_API_URL\"),\n\tAuth: &webapisdk.AuthConfig{Token: os.Getenv(\"PARABLE_API_TOKEN\")},\n\tRequestInterceptor: func(ctx context.Context, req *http.Request) error {\n\t\treq.Header.Set(\"X-Tenant\", os.Getenv(\"PARABLE_WORKSPACE\"))\n\t\treturn nil\n\t},\n})\nif err != nil {\n\treturn err\n}\n\nvar input webapitypes.DescribePoolTableInput\nif err := json.Unmarshal([]byte(`{\"tableRef\":\"example\"}`), &input); err != nil {\n\treturn err\n}\nresult, err := sdk.ProviderPoolNamespace.DescribePoolTable(ctx, input)" components: schemas: DescribePoolTableInput: properties: tableRef: description: >- The table's name as a FROM clause takes it, such as `providers.jiracloud.issues`. Search results return it as `tableRef`. maxLength: 500 minLength: 1 type: string required: - tableRef type: object PoolTableDescription: description: >- One table of the catalog, as Parable describes it: its fields with their Arrow types and Parable scalars, its primary key and relationships, and what is known of its rows and freshness. A value no measurement has produced is null, which means unknown, not healthy. properties: catalogVersion: description: >- The catalog the description was read from. It changes when a table or a column is added, removed or retyped, not when data moves. type: string table: $ref: '#/components/schemas/SemanticCatalogTable' required: - catalogVersion - table type: object ResponseLinks: properties: first: nullable: true type: string last: nullable: true type: string next: nullable: true type: string prev: nullable: true type: string type: object ResponseMeta: properties: requestId: description: Unique identifier for the request type: string totalCount: description: Total count of items for paginated responses nullable: true type: integer required: - requestId type: object ProblemDetails: description: An error response in the Problem Details format (RFC 9457). properties: code: description: The stable error code, when the problem has one. example: WA-VL-001 type: string detail: description: What went wrong with this request. type: string details: description: >- Structured facts about the refusal, such as the entity or the path it concerns. Only some refusals have it. errors: description: >- The fields or filters that failed validation. Only a validation or filter error has it. requestId: description: >- The ID of the request, when the problem has one. The `X-Request-ID` response header always has it. type: string status: description: The HTTP status code. example: 400 type: integer title: description: A short summary, usually the text of the HTTP status. example: Bad Request type: string type: description: >- The problem type. It is `about:blank`: the status and `code` identify the problem. example: about:blank type: string required: - type - title - status - detail type: object SemanticCatalogTable: description: One served base table. properties: catalog: description: >- SQL catalog the table is served under (`providers`, `providers_quarantine`, or `providers_quality`). A quarantine table and a quality history table share the schema name of their Provider table, so the catalog tells them apart. type: string description: description: >- What the table holds, from the Provider's description of the Tap or its documentation. Null when neither describes it. The CatalogSnapshot omits it, for the reason given on SemanticCatalogField.system. nullable: true type: string fields: items: $ref: '#/components/schemas/SemanticCatalogField' type: array importedForeignKeys: description: Foreign keys imported by this table. Empty when none are resolved. items: $ref: '#/components/schemas/SemanticCatalogForeignKey' type: array logicalName: description: Logical table name inside the connector schema. type: string materialized: description: |- Whether the writer has materialized the physical table. Null until an annotation source answers (unknown, never false-by-default). nullable: true type: boolean primaryKey: description: |- Ordered logical columns for the table's primary key. Null when the planner does not expose a complete primary key. oneOf: - $ref: '#/components/schemas/SemanticCatalogPrimaryKey' - enum: - null nullable: true type: object schemaName: description: >- Catalog SCHEMA SEGMENT the table registers under. For the providers catalogs it is a connector slug sanitized for SQL identifiers (`-` becomes `_`, e.g. `google-drive` registers as `google_drive`); for the derived identity-resolution family it is the literal `identity`; for the artifacts it is the publication namespace (`public` for legacy uploads); the workspace catalog keeps the literal `public`. maxLength: 255 minLength: 1 pattern: ^[a-z0-9]+(?:[-_][a-z0-9]+)*$ type: string statsRowCount: description: Row count from the annotation source; null when unknown. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer tableKind: $ref: '#/components/schemas/CatalogTableKindEnum' description: Position in the tap's plan; Flight `parable.annotation.table_kind`. tapKind: $ref: '#/components/schemas/CatalogTapKindEnum' description: >- Catalog tap-kind vocabulary kinds plus `derived` for platform-synthesized families); Flight `parable.annotation.tap_kind`. validationRates: description: |- Per-column validation rates keyed by logical column name. Empty when no annotation source answered. items: $ref: '#/components/schemas/SemanticCatalogValidationRate' type: array watermark: description: Completeness watermark ("complete through T"); null when unknown. format: date-time nullable: true type: string watermarkStale: nullable: true type: boolean required: - catalog - schemaName - logicalName - tableKind - tapKind - validationRates - importedForeignKeys - fields type: object SemanticCatalogField: description: >- One logical column of a served table or view. The semantic catalog is the same catalog that SQL over Flight reports in its metadata, with the Artifact tables you may read. An omitted (null) annotation field means *unknown / not yet computed*. A present value is authoritative. Identity fields (tableKind, tapKind, contractVersion) are always present. properties: arrowType: description: |- Deterministic Arrow DataType rendering (Arrow's canonical Display form). Deliberately a string, not an enum: nested and parameterized types render their full parameters (`List(Field { .. Utf8 .. })`, `Timestamp(Nanosecond, Some("UTC"))`, `Map(...)`), so the value set is open -- it is the exact type served in the Flight IPC schema for the same column, which an enum of type families could not carry. type: string hidden: description: >- True on Parable's operational columns that the logical schema still shows: the `_parable_*` envelope columns of a quarantine table. A main table's envelope columns are left out of the schema, not flagged. type: boolean name: description: |- Logical column name (lowercased source path segments joined with `__`), exactly as served by Flight GetTables. maxLength: 80 minLength: 2 type: string nullable: type: boolean poorPruning: description: >- True on columns whose physical representation defeats data skipping (JSON-encoded, native struct/array, capture buckets). SQL over Flight serves the same value under the `parable.annotation.poor_pruning` field metadata key. type: boolean scalarRef: description: >- Canonical name of the column's semantic scalar (e.g. `Contact.Email`), exactly the Flight `parable.scalar.canonical_name` field metadata value; null when the column carries no semantic scalar. Consumers needing a JSON-Schema pointer can prefix `#/definitions/scalars/`. maxLength: 128 minLength: 3 nullable: true pattern: ^[A-Z][A-Za-z0-9]*\.[A-Z][A-Za-z0-9]*$ type: string system: description: >- True on the row-state columns Parable adds to every Provider table: `dt` and the `_parable_*` load and deletion columns on main and child tables, and the `_parable_*` envelope plus `dt` on quarantine tables. They stay queryable; catalog browsers list them apart from the Provider's own fields. SQL over Flight serves the same value under the `parable.annotation.system` field metadata key. `GET /api/v2/catalog` always sets it. nullable: true type: boolean required: - name - arrowType - nullable - hidden - poorPruning type: object SemanticCatalogForeignKey: description: An imported foreign key from this table to another served table. properties: referencedColumns: items: type: string type: array referencedSchema: description: A URL friendly version of a string maxLength: 255 minLength: 1 pattern: ^[a-z0-9]+(?:[-_][a-z0-9]+)*$ type: string referencedTable: type: string sourceColumns: items: type: string type: array required: - sourceColumns - referencedSchema - referencedTable - referencedColumns type: object SemanticCatalogPrimaryKey: description: Ordered logical columns forming a table's primary key. properties: columns: items: type: string type: array required: - columns type: object CatalogTableKindEnum: description: |- Position of a served table in its Tap's mapping plan. SQL over Flight serves the same values under the `parable.annotation.table_kind` schema metadata key. enum: - main - quarantine - child - child_quarantine type: string CatalogTapKindEnum: description: |- The kind of Tap behind a served table. SQL over Flight serves the same values under the `parable.annotation.tap_kind` schema metadata key. A served table comes from one of the Workspace's Taps (the Tap kinds), or Parable builds it (DERIVED). enum: - override - custom - artifact - derived type: string SemanticCatalogValidationRate: description: |- Per-column validation rate (logical column name -> rate string), from the Flight `parable.annotation.validation_rate.{column}` keys. properties: column: type: string rate: type: string required: - column - rate type: object headers: X-Request-ID: description: >- The ID of the request. It is the `X-Request-ID` value that you sent, or an ID that the server made. Give it when you report a problem. schema: type: string securitySchemes: bearerAuth: description: >- A personal access token, which starts with `pat_`. A Parable token can call each operation that the roles of its owner allow. An MCP token can call only the read operations that are open to agents. A SQL token does not work on this API. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.