---
sidebar_position: 4
title: list_columns
description: List columns of a table or view with types and comments
---

# list_columns

List all columns of a table or view with their types and comments.

## Description

The `list_columns` tool returns detailed column information for a specified table or view, including data types, nullability, and any comments. This is useful for understanding table structure before writing queries.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `table` | string | Yes | Table or view name |
| `database` | string | Yes | Database name |
| `schema` | string | No | Schema name (defaults to `main`) |

## Output Schema

```json
{
  "success": boolean,
  "database": string,            // Database name
  "schema": string,              // Schema name
  "table": string,               // Table or view name
  "objectType": "table" | "view", // Whether it's a table or view
  "columns": [                   // List of columns (on success)
    {
      "name": string,            // Column name
      "type": string,            // Data type
      "nullable": boolean,       // Whether nulls are allowed
      "comment": string | null   // Column comment if set
    }
  ],
  "columnCount": number,         // Number of columns
  "error": string                // Error message (on failure)
}
```

## Example Usage

**Get columns for a table:**

```text
What columns does the customers table have in my_database?
```

The AI assistant will call the tool with:

```json
{
  "table": "customers",
  "database": "my_database"
}
```

**Get columns in a specific schema:**

```text
Show me the schema of staging.raw_events in analytics_db
```

```json
{
  "table": "raw_events",
  "database": "analytics_db",
  "schema": "staging"
}
```

## Success Response Example

```json
{
  "success": true,
  "database": "my_database",
  "schema": "main",
  "table": "customers",
  "objectType": "table",
  "columns": [
    {
      "name": "id",
      "type": "INTEGER",
      "nullable": false,
      "comment": "Primary key"
    },
    {
      "name": "email",
      "type": "VARCHAR",
      "nullable": false,
      "comment": "Customer email address"
    },
    {
      "name": "name",
      "type": "VARCHAR",
      "nullable": true,
      "comment": "Full name"
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP",
      "nullable": false,
      "comment": null
    },
    {
      "name": "metadata",
      "type": "JSON",
      "nullable": true,
      "comment": "Additional customer attributes"
    }
  ],
  "columnCount": 5
}
```

## Error Response Example

```json
{
  "success": false,
  "error": "Catalog Error: Table \"nonexistent_table\" does not exist"
}
```