execute_big_query_to_disk
Execute large read-only SQL queries and stream results directly to a CSV file, avoiding token limit issues by saving to disk. Returns execution status and file details.
Instructions
Execute a large read-only SQL query and save results directly to a CSV file.
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 errorInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| file_path | Yes | ||
| database | No | ||
| schema | No | ||
| timeout_seconds | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||