HG Data Warehouse Catalog

hg_catalog — browse / inspect the HG Insights data warehouse schema (table/column names, join keys, sql_qualifier) to plan an hg_data_query. Returns schema metadata, NOT data rows. Required first step before writing SQL. Schema is stable — call once per session.

TWO MODES: (1) ORIENTATION (default, table_names OMITTED): lightweight index of ALL tables as {name, sql_qualifier, description} only — no columns, join keys, or relationships. Cheap first call. (2) DETAIL (table_names SET): full metadata for named tables (columns, order_by, primary_key, join_keys, common_filters, mandatory_predicate, sample_queries) plus relationship edges touching them.

Use this when:

• Discovering which tables and columns exist before writing SQL for hg_data_query.
• Confirming a column's exact name, type, or join key, or a table's sql_qualifier.
• Mapping table relationships to plan a multi-table join.

Do NOT use this when:

• You want to RUN a query and get rows back — call hg_data_query (this tool returns schema only).
• You need product/technology taxonomy VALUES (category, vendor, attribute, or product names/IDs) — call get_product_category, get_vendor_information, or get_product_attribute.

Credits

Free — No credits consumed. See the full credit table for how AI Credits work.

Parameters

Name	Type	Default	Description
table_names	array	-	Exact table names from a prior orientation call (lowercase, underscores; e.g. ["install_global", "company_locations"]). Returns FULL detail for them (columns, join keys, sample queries) plus the relationship edges that touch any of them — an edge is included when EITHER endpoint is in the requested set, not only when both are. Omit for a lightweight ORIENTATION index of all tables ({name, sql_qualifier, description} only, empty relationships[]). An unknown name errors (422) and names the bad entries — call with no table_names first to see valid names.
columns	string	important	Column verbosity. Applies only when table_names is set — an unscoped call always returns the compact orientation index (name/sql_qualifier/description only). none=strips column definitions AND projection/index blocks (projection_details, skip_indexes, indexed_filters); order_by/primary_key/mandatory_predicate kept. important=curated most-important columns with full indexing metadata (default). full=every column live from ClickHouse system.columns (many have no description).
include_sample_queries	boolean	true	Include curated worked SQL examples per table. Applies only when table_names is set. Set false to reduce token usage.

Required Integrations

This tool is only available when your organization has the following integration configured in the HG Insights Integrations settings:

• HG Insights (Data API) (hginsights_v2_data_api)

Use Cases

• List every table in the HG data warehouse before deciding what to query
• Get the exact columns and types on company_spend to build a SQL SELECT for hg_data_query
• Confirm the join keys and grain of install_global before joining it to company_locations
• Look up a cross-db table's sql_qualifier (e.g. products) to write a correct FROM clause
• Discover the relationship edges around a table to plan a multi-table join

Example Usage

Orientation: list all tables (cheap first call)

{
  "tool": "hg_catalog",
  "arguments": {}
}

Full detail for one table with sample queries

{
  "tool": "hg_catalog",
  "arguments": {
    "table_names": [
      "company_spend"
    ]
  }
}

Compact detail for a join: columns only, no sample queries

{
  "tool": "hg_catalog",
  "arguments": {
    "table_names": [
      "install_global",
      "company_locations"
    ],
    "columns": "none",
    "include_sample_queries": false
  }
}

Response Format

Field	Type	Description
tables	array	Available tables in the HG Insights data warehouse. In ORIENTATION mode (no table_names) each entry carries only name, sql_qualifier, and description; pass table_names for the full per-table metadata (columns, join_keys, sample_queries, etc.).
tables[].name	string
tables[].sql_qualifier	any	Database prefix required in FROM, or null for default-database tables. Build the full reference as: sql_qualifier ? ${sql_qualifier}.${name} : name. Example: products → sql_qualifier="hg_statics" → FROM hg_statics.products.
tables[].description	string
tables[].row_count_approx	string	Approximate row count, e.g. "426M".
tables[].engine	string	ClickHouse storage engine.
tables[].order_by	array	ORDER BY sort key columns (primary sort key for ClickHouse MergeTree).
tables[].primary_key	array
tables[].projections	array	Alternate sort-order projection names that can accelerate specific query patterns.
tables[].mandatory_predicate	any	If set, every query touching this table must include a WHERE predicate on this column to avoid a full-table scan.
tables[].columns	array	Column definitions (empty when columns=none).
tables[].columns[].name	string
tables[].columns[].type	string	ClickHouse column type.
tables[].columns[].description	string
tables[].columns[].important	boolean
tables[].join_keys	array	Columns typically used to join this table to other tables.
tables[].common_filters	array	Columns most commonly used in WHERE predicates.
tables[].sample_queries	array	Curated worked SQL examples (empty when include_sample_queries=false).
tables[].sample_queries[].description	string
tables[].sample_queries[].sql	string
relationships	array	Join graph edges. When table_names is set, scoped to edges where from_table OR to_table is in the requested set (an edge touching any requested table is included). When table_names is omitted (orientation mode), this is EMPTY — pass table_names to get the join graph. Use this to discover how tables relate before writing multi-table queries.
relationships[].from_table	string
relationships[].from_column	string
relationships[].to_table	string
relationships[].to_column	string
relationships[].type	string	Cardinality, e.g. "many_to_one".

Related Tools

hg_data_query, get_product_category, get_vendor_information, get_product_attribute