`hg_catalog` next channel

Status: Modified (endpoint migration to GET /v2/data/catalog; new params and richer output) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/hg-catalog.md.

Returns the HG Insights data warehouse SCHEMA (table structure, column definitions, join keys, indexing hints, sample queries, and the full cross-table join graph) for use with hg_data_query. Call once per session before writing SQL; the schema is stable, so cache the result rather than re-calling per query.

Integration required: hginsights_v2 Cache schema version: 3 (differs from base — stale cached payloads from the public channel will not be served)

Parameters

Parameter	Type	Required	Default	Description
`table_names`	`string[]`	Optional	—	Restrict results to these table names (max 20). Both `tables[]` and `relationships[]` are scoped to the requested set server-side. Omit to return all tables and the full join graph.
`columns`	`"none" \| "important" \| "full"`	Optional	`"important"`	Column verbosity. `none` = lightweight orientation pass — strips column definitions AND projection/index blocks (`projection_details`, `skip_indexes`, `indexed_filters`); `order_by`, `primary_key`, `mandatory_predicate`, `join_keys`, and `common_filters` are still returned. `important` = curated most-important columns with full indexing metadata (default). `full` = every column live from ClickHouse `system.columns`.
`include_sample_queries`	`boolean`	Optional	`true`	Include curated worked SQL examples per table. Set `false` to reduce token usage.

Response Format

{
  "tables": [
    {
      "name": "installs",
      "sql_qualifier": null,
      "description": "Monthly technology install signals per company",
      "row_count_approx": "426M",
      "engine": "ReplacingMergeTree",
      "order_by": ["organization_id", "product_id", "country_code"],
      "primary_key": ["organization_id", "product_id"],
      "projections": ["by_product_date"],
      "mandatory_predicate": {
        "column": "organization_id",
        "example": "WHERE organization_id = '3AB6196C…'"
      },
      "columns": [
        { "name": "organization_id", "type": "String", "description": "HG company ID", "important": true }
      ],
      "join_keys": ["organization_id", "product_id"],
      "common_filters": ["organization_id", "product_id", "country_code"],
      "sample_queries": [
        {
          "description": "Get all products installed at a company",
          "sql": "SELECT product_id, product_name FROM installs WHERE organization_id = '…' ORDER BY intensity DESC LIMIT 50"
        }
      ]
    }
  ],
  "relationships": [
    {
      "from_table": "installs",
      "from_column": "product_id",
      "to_table": "products",
      "to_column": "product_id",
      "type": "many_to_one"
    }
  ]
}

New output fields (added in 2026-08-06)

Field	Description
`sql_qualifier`	Database prefix required in `FROM`, or `null` for default-database tables. When non-null, build the full `FROM` reference as `sql_qualifier + "." + name`; when null, use `name` directly. Example: `products` → `sql_qualifier="hg_statics"` → `FROM hg_statics.products`.
`row_count_approx`	Human-readable size estimate (e.g. `"426M"`).
`engine`	ClickHouse storage engine.
`order_by`	ORDER BY sort key columns (primary sort key for ClickHouse MergeTree).
`primary_key`	Primary key columns.
`projections`	Alternate sort-order projection names that can accelerate specific query patterns.
`mandatory_predicate`	If set, every query touching this table must include a WHERE predicate on this column to avoid a full-table scan.
`join_keys`	Columns typically used to join this table to other tables.
`common_filters`	Columns most commonly used in WHERE predicates.
`sample_queries[]`	Curated worked SQL examples (empty when `include_sample_queries=false`).
`relationships[]`	Join graph edges. When `table_names` is set, scoped to edges where `from_table` or `to_table` is in the requested set.

Example Usage

{
  "tool": "hg_catalog",
  "parameters": {
    "table_names": ["installs", "products"],
    "columns": "important",
    "include_sample_queries": true
  }
}

Lightweight orientation pass:

{
  "tool": "hg_catalog",
  "parameters": {
    "columns": "none",
    "include_sample_queries": false
  }
}

hg_data_query — execute ClickHouse SQL against the HG data warehouse; call hg_catalog first to understand the schema.

Changelog

2026-08-06 — Upstream shape changes + description accuracy (audit follow-up)

Upstream: unified API shipped four improvements to GET /v2/data/catalog identified in the hg_catalog audit (#2053).

columns=none now strips projection/index blocks (breaking for cached payloads): Previously none skipped only the per-column columns[] array; projection_details, skip_indexes, and indexed_filters were still returned. The upstream now omits all three in none mode.

relationships[] is now server-side scoped by ?tables= (breaking for cached payloads): When a tables= param is provided, the unified API now returns only relationship edges where from_table or to_table is in the requested set. Previously it returned the full 25-edge graph regardless.

sql_qualifier additive field on TableInfo: New optional field (string | null). Non-null only for tables requiring a database prefix in FROM (currently products → "hg_statics"). When non-null, build the full FROM target as sql_qualifier + "." + name; when null, use name directly.

company_spend table added to the catalog (20 tables total): New table entry in the upstream catalog. No Phoenix-side change required.

Cache schema version bumped to +2 from v1 (was +1).

2026-08-06 — Endpoint migration to `GET /v2/data/catalog`

Availability: live on the private next MCP channel (POST /api/mcp/next) for allow-listed orgs.

Why this changed: the legacy GET /v2/catalog endpoint returned a flat list of table names with minimal metadata. The new GET /v2/data/catalog endpoint is purpose-built for LLM query generation: it surfaces column types, approximate row counts, indexing hints (ORDER BY, projections), mandatory-predicate guards, curated worked SQL examples, and the full cross-table join graph.

Input changes

Parameter	Before	After
`table_name` (single, client-side filter)	optional string	removed
`table_names`	—	new: optional `string[]` (max 20), server-side filter
`columns`	—	new: `'none' \| 'important' \| 'full'` (default `'important'`)
`include_sample_queries`	—	new: optional boolean (default `true`)

Output changes

Before: { tables: Array<{ name, description, columns: [...] }> } (flat shape from /v2/catalog)

After: { tables: TableInfo[], relationships: Relationship[] } with the richer fields listed above.

Auth

Authorization: Bearer <api_key> (previously X-API-Key). Integration key unchanged: hginsights_v2.

Notes

The fetchHgCatalog shared helper (used by hg_data_query) is NOT touched — it stays on /v2/catalog. Migration of that helper and the hg://catalog MCP resource happens in PR 2/2 (#2054).
getCacheSchemaVersion() bumped by +2 (returns super.getCacheSchemaVersion() + 2) to prevent next-channel callers from being served stale v1-auth payloads.

Parameters​

Response Format​

New output fields (added in 2026-08-06)​

Example Usage​

Related Tools​

Changelog​

2026-08-06 — Upstream shape changes + description accuracy (audit follow-up)​

2026-08-06 — Endpoint migration to GET /v2/data/catalog​

Input changes​

Output changes​

Auth​

Notes​