# Table Commands

List, describe, and show table contents.

## Commands


```bash
tdx tables [pattern]              # List tables
tdx table list [pattern]          # Same as tables
tdx table deleted                 # List recoverable deleted tables
tdx table recover <id>            # Recover a deleted table by id
```

## Pattern Syntax

All table commands use dot-separated patterns: `(database).(table)`

- Database wildcard: `"mydb.*"` - all tables from mydb
- Database.table: `mydb.users` - specific table
- Wildcards: `"*.users"`, `"prod_*.user*"` - pattern matching
- Catalog: `"td.mydb.users"` - with catalog prefix


## List Tables


```bash
# List all tables from all databases
tdx tables

# List all tables from specific database
tdx tables "mydb.*"

# Filter tables with pattern
tdx tables "mydb.user_*"

# Database pattern with table
tdx tables "prod_*.access_log"

# Wildcard database and table
tdx tables "*.user*"
```

## Describe Table

Show table schema:


```bash
# Using dot notation
tdx describe mydb.users
tdx desc mydb.users  # alias
```

## Show Table Contents

Display table data (SELECT * with limit):


```bash
# Show first 40 rows (default)
tdx show mydb.users

# With custom limit
tdx show mydb.users --limit 10
```

## Recover Deleted Tables

Tables remain recoverable for **7 days** after deletion. Use the workflow
below to find a deleted table's id, then recover it.


```bash
# List your recoverable deleted tables (paginated)
tdx table deleted
tdx table deleted --page-size 50
tdx table deleted --cursor-id 859018252   # next page

# Recover by id (id comes from `tdx table deleted` or Premium Audit Logs)
tdx table recover 859018252

# If the original name conflicts with an active table or database, rename:
tdx table recover 859018252 --name users_recovered
tdx table recover 859018252 --database analytics_recovered
```

### Required permissions

You need one of the following on the parent database:

- `Database:edit` (Full Access in the UI)
- `Database:owner_manage` (you created the database)
- `Database:manage` (administrator with explicit grant)


If the parent database itself was also deleted, only users with
`Database:manage` can recover it — otherwise contact an administrator.

### Limitations

- Schema annotations are not recoverable (hard-deleted on table delete).
- Preview data is not recoverable; it repopulates on the next import.
- Recovery is only available within the 7-day retention window.


## Using Session Context

Set a default database to avoid repeating it in every command:


```bash
# Set session database
tdx use database mydb

# Now these commands use mydb automatically
tdx tables        # Lists tables in mydb
tdx describe users
tdx show users --limit 10
```

## Examples


```bash
# List tables in production databases
tdx tables "prod_*.*"

# Describe user tables across all databases
tdx tables "*.user*"

# Show sample data from specific table
tdx show mydb.users --limit 5 --json

# Export table schema
tdx describe mydb.users --json --output schema.json
```