This tool queries INFORMATION_SCHEMA across all databases to build a comprehensive
index of tables, schemas, and columns. The cache has a 5-day TTL.

Use this tool when:
- First connecting to Snowflake
- Schema changes have been made
- Cache has expired (after 5 days)

Parameters:
- force: Force refresh even if cache is not expired (default: false)
- resume: Resume from checkpoints if they exist (default: true)

USE THIS WHEN: You want to explore what databases/schemas exist, or need to filter by exact patterns.
Like SQL's: SHOW TABLES IN database LIKE 'pattern'

RETURNS (small result): hierarchical tree
- database → schema → list of tables

RETURNS (broad result): when the matching tree is too large to return inline
(e.g. show_tables() with no filter, or a broad database_pattern matching tens
of thousands of tables), the COMPLETE tree is written to a temp `.json` file
and the response is instead a compact summary built to help you NARROW:
`total_tables`, `total_schemas`, `results_file`, and a bounded breakdown that
adapts to what's left to narrow -- `top_schemas` (db.schema=count) when the
result is a single database, else `top_databases` (db=count) -- each with a
`(+X more ..., Y tables)` tail marker, plus a `spilled` hint.

To act on a spilled result, prefer RE-CALLING show_tables with a tighter
database_pattern/schema_pattern (served from cache, no Snowflake) until it
fits inline. To read results_file directly instead -- it is compact JSON
nested THREE levels deep, `{"DB": {"SCHEMA": ["TABLE", ...]}}` (so table
names are the innermost array, not a key) -- list its schemas WITHOUT loading
every table name into context:
  jq -r 'to_entries[]|.key as $d|.value|keys[]|"\($d).\(.)"' <results_file>
or, if jq is unavailable:
  python3 -c "import json,sys;d=json.load(open(sys.argv[1]));print(chr(10).join(f'{db}.{s}' for db,sc in d.items() for s in sc))" <results_file>
Mind the nesting depth when counting: `jq '[.[][][]]|length'` counts TABLES
(three flattens to reach the leaf array); `jq '[.[][]]|length'` counts
SCHEMAS. (total_tables/total_schemas in the summary already give both.)

HOW IT WORKS:
- Auto-refreshes cache if expired/empty (requires Snowflake auth on first use)
- Uses cached data if available (no auth needed)
- Pattern matching is case-insensitive substring search

Parameters:
- database_pattern: Filter databases (e.g., "SALES" matches "SALES_DB", "SALES_PROD")
- schema_pattern: Filter schemas (e.g., "PUBLIC")
- table_pattern: Filter tables (e.g., "CUSTOMER" matches "CUSTOMERS", "CUSTOMER_ORDERS")

Examples:
- show_tables() - Browse all databases
- show_tables(database_pattern="SALES") - Only SALES databases
- show_tables(schema_pattern="PUBLIC") - All PUBLIC schemas across databases

USE THIS WHEN: You don't know where a table is, but know part of its name or purpose.
Matches against both table names AND table comments (so a cryptically-named
table is still found when its comment mentions the term).

RETURNS (small result): flat list of matches
- [{database, schema, table, type, full_name}, ...]
  Note: neither the comment nor a column count is returned. The comment is the
  one unbounded field (can be a multi-KB doc-block); a column count does not
  help locate a table. For a table's comment and columns, use describe_table.

RETURNS (broad result): when too many tables match to return inline, the
COMPLETE result is written to a temp `.tsv` file and the response is instead a
compact summary built to help you NARROW: `total_hits`, `results_file`, a
bounded `top_groups` breakdown of the top database.schema clusters (with a
`(+X more groups, Y hits)` tail marker), and a `spilled` hint. To narrow, call
show_tables with database_pattern/schema_pattern from top_groups and/or a more
specific table_pattern -- don't blindly re-search.

HOW IT WORKS:
- Auto-refreshes cache if expired/empty (requires Snowflake auth on first use)
- Uses cached data if available (no auth needed)
- Searches table names and comments for the keyword (case-insensitive)

Parameters:
- search_term: Keyword to search for (case-insensitive)

Examples:
- find_tables("customer") - Find all customer-related tables across all databases
- find_tables("revenue") - Find revenue tables anywhere
- find_tables("staging") - Find tables with "staging" in name or comment

USE THIS WHEN: You need column names, types, and constraints to write a query.
Like SQL's: DESCRIBE TABLE database.schema.table

RETURNS: Detailed column information
- For each column: name, data_type, nullable, position, default, comment, is_primary_key

HOW IT WORKS:
- Looks up table in cache; fetches column details on-demand if not yet loaded
- First call for a table queries Snowflake live (~200ms), subsequent calls use cache
- If table not in cache at all, returns error (use show_tables or find_tables first)

Note: To get sample data rows, use execute_query tool separately.

Parameters:
- database: Database name
- schema: Schema name
- table: Table name

Examples:
- describe_table("SALES_DB", "PUBLIC", "CUSTOMERS")
- describe_table("GDC", "STAGING", "ADMIN__CATEGORIES")

Requires a populated schema cache; auto-refreshes on first use if empty.

Parameters:
- sql: read-only SQL query
- database: optional database context
- schema: optional schema context

Returns a compact TEXT payload (not JSON): a `key: value` header
(status, rows, cols, execution_time, query_id), a `---` separator, then a
positional TSV block. TSV rules: line 1 = tab-separated column names, one row
per line after; NULL = `\N`; tabs/newlines escaped so each row is one line.
Parse with awk/cut, e.g. `awk -F'\t' 'NR>1 && $3=="X"'`.

Large/wide/tall results auto-spill the COMPLETE result to a temp `.tsv` file;
the payload then carries `results_file`, `column_index` (name->position), and a
`spilled` marker in place of inline rows. Read/grep/awk the file; `rows:` is
always the true total.

Example: execute_query("SELECT * FROM SALES_DB.PUBLIC.CUSTOMERS LIMIT 10")

Use when the result needs to land at a specific path -- to share or persist.
Format follows the extension: `.csv` writes CSV (NULL = empty field);
anything else writes TSV (same as execute_query: tab-delimited, NULL = `\N`).

Parameters:
- sql: read-only SQL (SELECT, SHOW, DESCRIBE, WITH)
- file_path: output path (absolute recommended; end with `.csv` for CSV,
  else `.tsv` is used/appended)
- database: optional database context
- schema: optional schema context
- timeout_seconds: query timeout (default 300, max 3600)

Requires a populated schema cache. Will not overwrite an existing file.

Example: execute_query_to_file("SELECT * FROM t", "/tmp/export.csv")