Skip to main content

​
Description

Complete analysis of a single table including: columns with types, nullability, defaults, and comments; column-level statistics from pg_stats (cardinality classification, null rates, enum-like values with frequencies, value ranges for dates/numbers); primary keys; foreign keys with referenced tables; indexes; check constraints; row estimate; table size; statistics freshness; sample rows (up to 5); and index usage statistics. Use this to understand a table before writing queries. Pay attention to: foreign keys for JOIN paths; cardinality to know what to GROUP BY vs filter; enum-like columns show the allowed values; value ranges show date spans and numeric scales; null rates help you handle NULLs correctly in filters and JOINs; sample rows to see actual data patterns; and index usage to understand query performance.

​
Parameters

ParameterTypeRequiredDescription
table_namestringYesName of the table to describe
schemastringNoSchema name (resolves automatically if omitted)

​
Response schema

FieldTypeDescription
schemastringSchema name
namestringTable name
commentstringTable comment (omitted if empty)
row_estimateintegerEstimated row count
total_bytesintegerTotal disk size in bytes (omitted if zero)
size_humanstringHuman-readable size (omitted if empty)
columnsarrayColumn details (see below)
foreign_keysarrayForeign key constraints (see below)
indexesarrayIndex definitions (see below)
check_constraintsarrayCheck constraints (see below)
stats_agestringTimestamp of last ANALYZE run (omitted if unknown)
stats_age_warningstringWarning if statistics are stale or missing (omitted if fresh)
sample_rowsarrayUp to 5 sample rows as key-value objects (omitted if unavailable)
index_usagearrayPer-index usage statistics (see below)

​
Column object

FieldTypeDescription
namestringColumn name
data_typestringPostgreSQL data type
is_nullablebooleanWhether the column allows NULL
default_valuestringDefault expression (omitted if none)
is_primary_keybooleanWhether this column is part of the primary key
commentstringColumn comment (omitted if empty)
statsobjectColumn statistics from pg_stats (omitted if unavailable)

​
Column stats object

FieldTypeDescription
null_fractionfloatFraction of rows that are NULL (0.0–1.0)
cardinalitystringClassification: unique, near_unique, high_cardinality, low_cardinality, enum_like
distinct_countintegerEstimated number of distinct values
most_common_valsarrayMost frequent values (for enum_like / low_cardinality columns)
most_common_freqsarrayFrequencies of most common values
min_valuestringMinimum value (for date/numeric columns)
max_valuestringMaximum value (for date/numeric columns)

​
Foreign key object

FieldTypeDescription
constraint_namestringConstraint name
column_namestringColumn in this table
referenced_tablestringReferenced table (schema-qualified)
referenced_columnstringReferenced column

​
Index object

FieldTypeDescription
namestringIndex name
definitionstringFull CREATE INDEX statement
is_uniquebooleanWhether the index enforces uniqueness

​
Check constraint object

FieldTypeDescription
namestringConstraint name
expressionstringCheck expression

​
Index usage object

FieldTypeDescription
namestringIndex name
scansintegerNumber of index scans since last stats reset
size_bytesintegerIndex size in bytes
size_humanstringHuman-readable index size

​
Example response

{
  "schema": "public",
  "name": "orders",
  "row_estimate": 248000,
  "total_bytes": 47185920,
  "size_human": "45 MB",
  "columns": [
    {
      "name": "id",
      "data_type": "uuid",
      "is_nullable": false,
      "default_value": "gen_random_uuid()",
      "is_primary_key": true,
      "stats": {
        "null_fraction": 0.0,
        "cardinality": "unique",
        "distinct_count": 248000
      }
    },
    {
      "name": "status",
      "data_type": "text",
      "is_nullable": false,
      "is_primary_key": false,
      "stats": {
        "null_fraction": 0.0,
        "cardinality": "enum_like",
        "distinct_count": 6,
        "most_common_vals": ["paid", "shipped", "delivered", "pending", "draft", "cancelled"],
        "most_common_freqs": [0.35, 0.25, 0.20, 0.10, 0.05, 0.05]
      }
    },
    {
      "name": "created_at",
      "data_type": "timestamp with time zone",
      "is_nullable": false,
      "default_value": "now()",
      "is_primary_key": false,
      "stats": {
        "null_fraction": 0.0,
        "cardinality": "high_cardinality",
        "distinct_count": 185000,
        "min_value": "2022-01-15T08:30:00Z",
        "max_value": "2026-02-25T19:45:00Z"
      }
    }
  ],
  "foreign_keys": [
    {
      "constraint_name": "orders_customer_id_fkey",
      "column_name": "customer_id",
      "referenced_table": "public.customers",
      "referenced_column": "id"
    }
  ],
  "indexes": [
    {
      "name": "orders_pkey",
      "definition": "CREATE UNIQUE INDEX orders_pkey ON public.orders USING btree (id)",
      "is_unique": true
    },
    {
      "name": "orders_customer_id_idx",
      "definition": "CREATE INDEX orders_customer_id_idx ON public.orders USING btree (customer_id)",
      "is_unique": false
    }
  ],
  "stats_age": "2026-02-25T12:00:00Z",
  "sample_rows": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "paid",
      "amount_cents": 4999,
      "created_at": "2026-01-15T14:30:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "status": "shipped",
      "amount_cents": 12500,
      "created_at": "2026-02-01T09:15:00Z"
    }
  ],
  "index_usage": [
    {
      "name": "orders_pkey",
      "scans": 152340,
      "size_bytes": 5242880,
      "size_human": "5120 kB"
    },
    {
      "name": "orders_customer_id_idx",
      "scans": 48210,
      "size_bytes": 3145728,
      "size_human": "3072 kB"
    }
  ]
}

​
Column masking

If a policy file defines column masks, sample rows are automatically masked using the same rules as query results. For example, with email: redact and phone: partial: 
"sample_rows": [
  {"id": 1, "email": "***", "phone": "***********5309", "name": "Alice"}
]
This ensures table analysis never leaks PII. See Column Masking for details.

​
Notes

  • If schema is omitted, Isthmus resolves the table name across all allowed schemas. If the table name is ambiguous (exists in multiple schemas), provide the schema parameter.
  • Column statistics come from pg_stats and require ANALYZE to have run. If stats are unavailable, the stats field is omitted.
  • Cardinality classification thresholds: unique (100% distinct), near_unique (over 90%), high_cardinality (over 200 distinct), low_cardinality (21–200), enum_like (20 or fewer).
  • Sample rows are fetched with LIMIT 5 using a TABLESAMPLE clause when available for performance.
  • Index usage stats come from pg_stat_user_indexes. An index with scans: 0 may be unused and a candidate for removal.
  • The stats_age_warning field appears when the last ANALYZE is older than 7 days or has never been run.