ReferenceAPI ReferenceTables

Tables

Table endpoints let you browse, inspect, and document the Iceberg tables in your data lake. Tables are automatically created when pipelines write data — you do not create tables manually. These endpoints proxy to ratq (the DuckDB query sidecar) for schema introspection and data preview.

Endpoints

MethodEndpointDescription
GET/api/v1/tablesList all tables
GET/api/v1/tables/{ns}/{layer}/{name}Get table details and schema
GET/api/v1/tables/{ns}/{layer}/{name}/previewPreview table data
PUT/api/v1/tables/{ns}/{layer}/{name}/metadataUpdate table metadata

List Tables

GET /api/v1/tables

Returns a list of all tables in the data lake, enriched with metadata descriptions when a TableMetadataStore is configured.

Query Parameters

ParameterTypeDefaultDescription
namespacestring—Filter by namespace
layerstring—Filter by layer (bronze, silver, gold)

Request

curl "http://localhost:8080/api/v1/tables?namespace=default&layer=silver"

Response — 200 OK

{
  "tables": [
    {
      "namespace": "default",
      "layer": "silver",
      "name": "orders",
      "row_count": 12340,
      "size_bytes": 524288,
      "description": "Cleaned orders table"
    },
    {
      "namespace": "default",
      "layer": "silver",
      "name": "customers",
      "row_count": 5600,
      "size_bytes": 210000,
      "description": null
    }
  ],
  "total": 2
}

Response Fields

FieldTypeDescription
tablesarrayList of table objects
tables[].namespacestringNamespace the table belongs to
tables[].layerstringData layer
tables[].namestringTable name
tables[].row_countintegerNumber of rows in the table
tables[].size_bytesintegerTable size in bytes
tables[].descriptionstring|nullTable description from metadata (if set)
totalintegerTotal number of matching tables

Error Responses

StatusCodeDescription
500INTERNALratq sidecar not configured
503UNAVAILABLEratq sidecar is unreachable

Get Table

GET /api/v1/tables/{ns}/{layer}/{name}

Returns detailed information about a single table, including its full column schema and metadata.

Path Parameters

ParameterTypeDescription
nsstringNamespace
layerstringData layer
namestringTable name

Request

curl http://localhost:8080/api/v1/tables/default/silver/orders

Response — 200 OK

{
  "namespace": "default",
  "layer": "silver",
  "name": "orders",
  "row_count": 12340,
  "size_bytes": 524288,
  "description": "Cleaned orders table",
  "owner": "user-id",
  "columns": [
    { "name": "id", "type": "VARCHAR", "description": "Primary key" },
    { "name": "customer_id", "type": "INTEGER", "description": "FK to customers table" },
    { "name": "amount", "type": "DECIMAL(14,2)", "description": "Order total" },
    { "name": "status", "type": "VARCHAR", "description": "Order status" },
    { "name": "created_at", "type": "TIMESTAMP", "description": null }
  ]
}

Response Fields

FieldTypeDescription
namespacestringNamespace
layerstringData layer
namestringTable name
row_countintegerNumber of rows
size_bytesintegerTable size in bytes
descriptionstring|nullTable description
ownerstring|nullOwner user ID
columnsarrayColumn definitions
columns[].namestringColumn name
columns[].typestringDuckDB column type
columns[].descriptionstring|nullColumn description (from metadata)

Error Responses

StatusCodeDescription
404NOT_FOUNDTable not found
500INTERNALratq sidecar not configured
503UNAVAILABLEratq sidecar is unreachable

Preview Table Data

GET /api/v1/tables/{ns}/{layer}/{name}/preview

Returns the first N rows of a table for quick inspection. Uses DuckDB to scan the Iceberg table directly.

Path Parameters

ParameterTypeDescription
nsstringNamespace
layerstringData layer
namestringTable name

Query Parameters

ParameterTypeDefaultDescription
limitinteger50Number of rows to return (max 1000)

Request

curl "http://localhost:8080/api/v1/tables/default/silver/orders/preview?limit=10"

Response — 200 OK

{
  "columns": [
    { "name": "id", "type": "VARCHAR" },
    { "name": "amount", "type": "DECIMAL(14,2)" },
    { "name": "status", "type": "VARCHAR" }
  ],
  "rows": [
    ["ORD-001", 129.99, "completed"],
    ["ORD-002", 45.50, "pending"],
    ["ORD-003", 89.00, "completed"]
  ],
  "total_rows": 3,
  "duration_ms": 12
}

Response Fields

FieldTypeDescription
columnsarrayColumn definitions
columns[].namestringColumn name
columns[].typestringDuckDB column type
rowsarrayResult rows as arrays of values
total_rowsintegerNumber of rows returned
duration_msintegerQuery execution time in milliseconds

Error Responses

StatusCodeDescription
404NOT_FOUNDTable not found
500INTERNALratq sidecar not configured
503UNAVAILABLEratq sidecar is unreachable

Update Table Metadata

PUT /api/v1/tables/{ns}/{layer}/{name}/metadata

Updates the metadata for a table — description, owner, and column descriptions. This is a partial update; only provided fields are changed. Only available when a TableMetadataStore is configured.

Path Parameters

ParameterTypeDescription
nsstringNamespace
layerstringData layer
namestringTable name

Request Body

FieldTypeRequiredDescription
descriptionstringNoTable description
ownerstringNoOwner user ID
column_descriptionsobjectNoMap of column name to description

Request

curl -X PUT http://localhost:8080/api/v1/tables/default/silver/orders/metadata \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Cleaned orders from raw data",
    "owner": "user-id",
    "column_descriptions": {
      "id": "Primary key",
      "amount": "Order total in USD",
      "status": "Order lifecycle status"
    }
  }'

Response — 200 OK

{
  "namespace": "default",
  "layer": "silver",
  "name": "orders",
  "description": "Cleaned orders from raw data",
  "owner": "user-id",
  "column_descriptions": {
    "id": "Primary key",
    "amount": "Order total in USD",
    "status": "Order lifecycle status"
  }
}

Response Fields

FieldTypeDescription
namespacestringNamespace
layerstringData layer
namestringTable name
descriptionstringTable description
ownerstringOwner user ID
column_descriptionsobjectMap of column names to descriptions

Error Responses

StatusCodeDescription
400INVALID_ARGUMENTInvalid request body
404NOT_FOUNDTable not found
503UNAVAILABLETableMetadataStore not configured

Table metadata is stored separately from the Iceberg table itself. The metadata is managed by ratd in Postgres and enriched onto table responses when available. Column descriptions appear in the portal’s table detail view and schema browser.

QueryStorage