query_dataset
Download blockchain data and return the file paths where the data is stored.
IMPORTANT WORKFLOW NOTE: When running SQL queries, use this function first to download
data, then use the returned file paths with query_sql() to execute SQL on those files.
Example workflow for SQL:
1. First download data: result = query_dataset('transactions', blocks='1000:1010', output_format='parquet')
2. Get file paths: files = result.get('files', [])
3. Run SQL query: query_sql("SELECT * FROM read_parquet('/path/to/file.parquet')", files=files)
DATASET-SPECIFIC PARAMETERS:
For datasets that require specific address parameters (like 'balances', 'erc20_transfers', etc.),
ALWAYS use the 'contract' parameter to pass ANY Ethereum address. For example:
- For 'balances' dataset: Use contract parameter for the address you want balances for
query_dataset('balances', blocks='1000:1010', contract='0x123...')
- For 'logs' or 'erc20_transfers': Use contract parameter for contract address
query_dataset('logs', blocks='1000:1010', contract='0x123...')
To check what parameters a dataset requires, always use lookup_dataset() first:
lookup_dataset('balances') # Will show required parameters
Args:
dataset: The name of the dataset to query (e.g., 'logs', 'transactions', 'balances')
blocks: Block range specification as a string (e.g., '1000:1010')
start_block: Start block number as integer (alternative to blocks)
end_block: End block number as integer (alternative to blocks)
use_latest: If True, query the latest block
blocks_from_latest: Number of blocks before the latest to include (e.g., 10 = latest-10 to latest)
contract: Contract address to filter by - IMPORTANT: Use this parameter for ALL address-based filtering
regardless of the parameter name in the native cryo command (address, contract, etc.)
output_format: Output format (json, csv, parquet) - use 'parquet' for SQL queries
include_columns: Columns to include alongside the defaults
exclude_columns: Columns to exclude from the defaults
Returns:
Dictionary containing file paths where the downloaded data is stored
