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: Hierarchical tree structure
- database → schema → list of tables (with column counts)

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.
Searches both table names AND table comments.

RETURNS: Flat list of matching tables
- [{database, schema, table, type, full_name, columns, comment}, ...]

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")

This tool validates queries for safety, executes them, and returns all results.
Only SELECT, SHOW, DESCRIBE, and WITH queries are allowed.

IMPORTANT: The schema cache must be populated before executing queries.
Run refresh_catalog first if this is your first query.

Parameters:
- sql: SQL query to execute (SELECT, SHOW, DESCRIBE, or WITH)
- database: Optional database context
- schema: Optional schema context

Returns:
- All query results (respects LIMIT clause if present in SQL)
- Results are cached for CSV export if under 5GB
- Use save_last_query_to_csv to export results

Note:
- If you encounter token limit issues with large result sets, consider using
  execute_big_query_to_disk instead, which streams results directly to a file
  without returning the data in the response, or consider adding a stricter LIMIT clause.

Examples:
- execute_query("SELECT * FROM SALES_DB.PUBLIC.CUSTOMERS LIMIT 10")
- execute_query("SELECT COUNT(*) FROM orders", database="SALES_DB", schema="PUBLIC")
- execute_query("SELECT * FROM large_table LIMIT 1000")

This tool can generate ANY type of SQL query including both read and write operations
(SELECT, INSERT, UPDATE, DELETE, etc.) but does NOT execute them. Useful for generating
queries that users want to review and execute elsewhere after manual verification.

IMPORTANT: Write queries (INSERT, UPDATE, DELETE, etc.) can be generated here but
CANNOT be executed through the execute_query tool for safety reasons. Users must
execute write queries directly in Snowflake after manual review.

Parameters:
- sql: SQL query to generate (read or write operations allowed)
- database: Optional database context
- schema: Optional schema context

The tool will:
- Accept both read and write queries
- Check query type (SELECT, INSERT, UPDATE, DELETE, etc.)
- Extract table references
- Provide hints for improvement
- Return the formatted query ready for manual review
- Indicate whether the query can be executed via execute_query (read-only) or not (write)

Examples:
- validate_query_without_execution("SELECT * FROM customers")
- validate_query_without_execution("INSERT INTO orders (id, amount) VALUES (1, 100.00)")
- validate_query_without_execution("UPDATE customers SET status = 'active' WHERE id = 123")
- validate_query_without_execution("DELETE FROM temp_data WHERE created < '2024-01-01'")

This tool returns a list of previously executed queries with their
status, execution time, and results.

Parameters:
- limit: Maximum number of queries to return (default: 10)
- only_successful: Only show successful queries (default: true)

Examples:
- get_query_history() - Get last 10 successful queries
- get_query_history(limit=50, only_successful=false) - Get last 50 queries including errors

This tool exports the complete results from the most recently executed query
to a CSV file at the specified path. The query must have been executed
successfully and its results must be within the 5GB cache size limit.

Features:
- Exports ALL rows from the last query
- Includes column headers
- Uses comma delimiter
- Handles NULL values as empty strings
- Formats datetime values in ISO format
- Optionally exports the SQL query to a .sql file (enabled by default)

Parameters:
- file_path: Path where the CSV file should be saved (absolute paths recommended)
             Note: Relative paths are resolved from the MCP server's working directory
- export_sql: Whether to also export the SQL query to a .sql file (default: true)

Requirements:
- A query must have been executed successfully using execute_query
- Query results must be under 5GB (cache limit)

Examples:
- save_last_query_to_csv("~/Downloads/customers.csv")
- save_last_query_to_csv("/tmp/query_results.csv")
- save_last_query_to_csv("./data/export.csv", export_sql=false)

Notes:
- When export_sql is true, the SQL file will be saved with the same name as the CSV file
  but with a .sql extension (e.g., customers.csv → customers.sql)
- The SQL file will be formatted for readability with proper indentation

This tool is designed for queries that return large result sets that would exceed
token limits. It streams results directly to disk without returning the data in
the response, avoiding token limit issues.

Features:
- Streams results directly to disk (doesn't return data in response)
- Handles arbitrarily large result sets using streaming
- Returns only execution status, row count, and file size
- Exports SQL query to a .sql file alongside the CSV
- Configurable timeout for long-running queries

Parameters:
- sql: The SQL query to execute (must be read-only)
- file_path: Path where the CSV file should be saved (absolute paths recommended)
             Note: Relative paths are resolved from the MCP server's working directory
- database: Optional database context
- schema: Optional schema context
- timeout_seconds: Query timeout in seconds (default: 300, max: 3600)

Requirements:
- Schema cache must be populated (run refresh_catalog first)
- Query must be read-only (SELECT, SHOW, DESCRIBE, WITH)
- Files must not already exist (will not overwrite)

Examples:
- execute_big_query_to_disk("SELECT * FROM large_table", "~/Downloads/large_data.csv")
- execute_big_query_to_disk("SELECT * FROM sales_data", "/tmp/sales.csv", timeout_seconds=600)

Notes:
- CSV file uses comma delimiter, includes headers, empty string for NULLs
- SQL file is created only after successful CSV export
- Partial files are cleaned up on error