Execute a raw SQL query against Dune's data engine.

This is the primary tool for running custom SQL queries on blockchain data. Returns an execution_id that can be used to check status and retrieve results.

Args: sql: The SQL query to execute. Use DuneSQL (Trino) syntax. Read dune://guide/sql-syntax for syntax reference. performance: Performance tier - "medium" (default) or "large" for complex queries.

Returns: Execution details including execution_id and initial state.

Example SQL queries: - SELECT * FROM dex.trades WHERE block_time > now() - interval '1' day LIMIT 10 - SELECT blockchain, SUM(amount_usd) as volume FROM dex.trades GROUP BY 1

Check the status of a query execution.

Use this to poll for completion after executing a query.

Args: execution_id: The execution ID returned from execute_sql or execute_query.

Returns: Execution status including state (QUERY_STATE_EXECUTING, QUERY_STATE_COMPLETED, etc.), queue position, and timing information.

Retrieve the results of a completed query execution.

Args: execution_id: The execution ID from a completed query. limit: Maximum number of rows to return (default 100, max per page). offset: Row offset for pagination (default 0).

Returns: Query results including rows, column metadata, and pagination info.

Retrieve query execution results in CSV format.

Args: execution_id: The execution ID from a completed query. allow_partial_results: Allow truncated results if data exceeds 8GB.

Returns: Query results as CSV string.

Cancel an ongoing query execution.

Args: execution_id: The execution ID of the running query.

Returns: Success status of the cancellation.

Execute a saved query by its ID.

Args: query_id: The unique identifier of the saved query. query_parameters: Optional parameters to pass to the query (key-value pairs). performance: Performance tier - "medium" (default) or "large".

Returns: Execution details including execution_id.

Retrieve details about a saved query.

Args: query_id: The unique identifier of the query.

Returns: Query details including SQL, parameters, name, tags, and state.

Get the latest results of a saved query without re-executing.

This retrieves cached results from the most recent execution. Does not trigger a new execution but consumes credits.

Args: query_id: The unique identifier of the query. limit: Maximum rows to return. offset: Row offset for pagination. allow_partial_results: Allow truncated results if data is too large.

Returns: Latest query results in JSON format.

Get the latest results of a saved query in CSV format.

Args: query_id: The unique identifier of the query. allow_partial_results: Allow truncated results if data exceeds limit. columns: Comma-separated list of column names to return. sort_by: SQL ORDER BY expression (e.g., "volume DESC"). filters: SQL WHERE clause expression for filtering rows. limit: Maximum number of rows to return. offset: Row offset for pagination.

Returns: Query results as CSV string.

Create and save a new query on Dune.

Args: name: Name for the query. query_sql: The SQL query text. Use {{param_name}} for parameters. description: Optional description of what the query does. is_private: Whether the query should be private (default False). parameters: Optional list of parameter definitions, each with: - key: Parameter name - value: Default value - type: "text", "number", or "enum" - enumOptions: List of allowed values (for enum type) tags: Optional list of tags for organization.

Returns: Created query details including query_id.

Example: create_query( name="Top DEX Volume", query_sql="SELECT project, SUM(amount_usd) as volume FROM dex.trades WHERE block_time > now() - interval '{{days}}' day GROUP BY 1 ORDER BY 2 DESC LIMIT 10", parameters=[{"key": "days", "value": "7", "type": "number"}] )

Update an existing saved query.

Only fields provided will be updated.

Args: query_id: The unique identifier of the query to update. query_sql: New SQL query text. name: New name for the query. description: New description. parameters: New parameter definitions. tags: New tags list. is_private: Change privacy setting.

Returns: Update confirmation.

Archive a query, making it uneditable and unexecutable.

Args: query_id: The unique identifier of the query to archive.

Returns: Archive confirmation.

Make a query private, restricting access to the owner.

Args: query_id: The unique identifier of the query.

Returns: Privacy change confirmation.

Make a private query public, allowing broader access.

Args: query_id: The unique identifier of the query.

Returns: Privacy change confirmation.

Upload CSV data to create or overwrite a table in Dune.

Maximum file size is 200MB. Uploading to an existing table overwrites all data.

Args: table_name: Name for the table (will be accessible as dune.your_namespace.table_name). data: CSV data as string, including headers. description: Optional description of the data. is_private: Whether the table should be private.

Returns: Upload confirmation.

Example: upload_csv( table_name="my_token_prices", data="date,token,price\n2024-01-01,ETH,2500\n2024-01-02,ETH,2600" )

Create a new table with a defined schema.

Args: namespace: Namespace for the table (usually your username). table_name: Name for the table. columns: List of column definitions, each with: - name: Column name - type: Data type ("string", "integer", "double", "timestamp", "boolean") - nullable: Whether nulls are allowed (default True) is_public: Whether the table is publicly accessible.

Returns: Table creation confirmation.

Example: create_table( namespace="my_namespace", table_name="token_metrics", columns=[ {"name": "date", "type": "timestamp", "nullable": False}, {"name": "token", "type": "string"}, {"name": "volume", "type": "double"} ] )

Insert rows into an existing table.

Args: namespace: Namespace of the table. table_name: Name of the table. rows: List of row objects where keys match column names.

Returns: Insert confirmation with row count.

Example: insert_table_rows( namespace="my_namespace", table_name="token_metrics", rows=[ {"date": "2024-01-01T00:00:00Z", "token": "ETH", "volume": 1000000}, {"date": "2024-01-02T00:00:00Z", "token": "ETH", "volume": 1200000} ] )

Remove all data from a table while preserving its schema.

Args: namespace: Namespace of the table. table_name: Name of the table to clear.

Returns: Clear confirmation.

Permanently delete a table and all its data.

WARNING: This operation is irreversible!

Args: namespace: Namespace of the table. table_name: Name of the table to delete.

Returns: Deletion confirmation.