columnHistogram

Return the whole value distribution of one column: the most common values with their frequencies, and the full histogram of everything else.

read-onlyany connectionsweeps instancesweeps groupcan return data values

Synopsis

columnHistogram(column, schema, table)

Description

Return the whole value distribution of one column: the most common values with their frequencies, and the full histogram of everything else. tableStats carries three points off that histogram -- low, mid and high -- which is enough to pick parameters to re-plan with; this is the tool for when the shape of the distribution itself is the question. The two are complements rather than alternatives: ANALYZE puts the most frequent values in most_common_vals and builds the histogram only from what is LEFT, so a value in the MCV list never appears in the bounds however common it is, and reading either alone misdescribes the column.

The bounds are equal-frequency, so consecutive entries delimit buckets holding roughly the same number of rows -- bounds bunched together are a dense region and a wide gap is a sparse one, which is what makes them usable as sample points across the distribution rather than one corner of it. statistics_target says why the histogram is the width it is and is the knob that changes it. COSTS NOTHING TO READ but RETURNS LITERAL COLUMN VALUES, more of them than any other operation here: the bounds and the MCVs are rows sampled out of the table. pg_stats filters on has_column_privilege, so a role without SELECT on the column gets nulls rather than data -- and it also drops the row entirely when row-level security is active on the table for this role, which is the same nulls for a completely different reason. stats_hidden_by_rls distinguishes them; the owner is exempt from RLS unless FORCE ROW LEVEL SECURITY is set, so asking as the owner is usually how to see the distribution.

This operation can return values that came from your data. It never changes anything and never returns rows, but read what reaches the caller before connecting it to a database whose contents are sensitive.

Parameters

column requiredstring
schema requiredstring
table requiredstring

Also accepts connection, instance, group, described once under arguments every tool takes.

Output

The full value distribution of one column: the most common values and the histogram of what is left. An absent extension or a missing grant is reported as {error, hint} instead.

Field	Type
avg_width	integer \| null
column	string \| null
histogram_bounds	array \| null
histogram_buckets	integer \| null
inherited	boolean \| null
most_common_freqs	array \| null
most_common_vals	array \| null
n_distinct	number \| null
note	string \| null
null_frac	number \| null
physical_order_correlation	number \| null
schema	string \| null
statistics_target	object \| null
table	string \| null

Scope

A physical replica is byte-identical here, so asking each member of a replication group adds nothing.

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "columnHistogram",
    "arguments": {
      "schema": "shop",
      "table": "orders",
      "column": "created_at"
    }
  }
}

Result

{
  "schema": "shop",
  "table": "orders",
  "column": "created_at",
  "inherited": false,
  "null_frac": 0.0,
  "avg_width": 8,
  "n_distinct": -0.98,
  "physical_order_correlation": 0.997,
  "most_common_vals": null,
  "most_common_freqs": null,
  "histogram_bounds": [
    "2025-09-15 00:02:11+00",
    "2026-01-04 11:40:09+00",
    "2026-05-20 08:12:55+00",
    "2026-09-14 23:58:40+00"
  ],
  "histogram_buckets": 3,
  "statistics_target": {
    "default": 100,
    "effective": 100
  },
  "note": null
}

Invented values on a fictional shop database, shaped by and checked against this tool's output schema. Real output is returned as structuredContent to clients that negotiate MCP 2025-06-18 or later.