Execution & Results

In this quickstart, we will walk through how to fetch Dune data in Python.

• 📓 You also can choose to use this Google Colab Notebook or this Hex Notebook to get started fast.
• ⌨️ For a quickstart on TypeScript, please download Dune TypeScript SDK and follow this demo project.

Prerequisites

• Python environment set up (check out Anaconda Navigator if you want somewhere to start.)
• Have a Dune API key (to obtain one follow the steps here)

Step 1: Prepare your Dune query

Have a Dune query you’d like to pull data from. Here, we’ll use this query to get the DAI token balance for vitalik.eth.

Step 2: Install Dune Python SDK

Ensure the Dune Python SDK is installed in your environment. You can install it using pip:

pip install dune-client

Step 3: Get data from Dune query

Import packages

from dune_client.types import QueryParameter
from dune_client.client import DuneClient
from dune_client.query import QueryBase
# import other needed packages
import pandas as pd

Set up a Dune Python client

inline

dune = DuneClient(
    api_key='<paste your api key here>',
    base_url="https://api.dune.com",
    request_timeout=300 # request will time out after 300 seconds
)

dune = DuneClient(
    api_key='<paste your api key here>',
    base_url="https://api.dune.com",
    request_timeout=300 # request will time out after 300 seconds
)

import dotenv, os

# change the current working directory where .env file lives
os.chdir("/Users/abc/project")
# load .env file
dotenv.load_dotenv(".env")
# setup Dune Python client
dune = DuneClient.from_env()

To avoid request timeout, you can increase the request timeout setting to be higher than the default 10 seconds in the same .env file we saved the API key information. Here is a sample .env file.

DUNE_API_KEY=<paste your API key here>
DUNE_API_REQUEST_TIMEOUT=120

import config

dune = DuneClient(
    api_key=config.dune_api_key,
    base_url="https://api.dune.com",
    request_timeout=(config.request_timeout)
)

To avoid request timeout, you can increase the request timeout setting to be higher than the default 10 seconds in the same config.py file we saved the API key information. Here is a sample config.py file.

dune_api_key='<paste your API key here>'
request_timeout=300

Get query result

You can choose to either get the latest query result without triggering an execution or to trigger an execution and get the result to ensure freshest data.

Get latest result without execution

  query_result = dune.get_latest_result(3373921) # get latest result in json format
  # query_result = dune.get_latest_result_dataframe(3373921) # get latest result in Pandas dataframe format

  query_result = dune.get_latest_result(3373921) # get latest result in json format
  # query_result = dune.get_latest_result_dataframe(3373921) # get latest result in Pandas dataframe format

query = QueryBase(
    query_id=3373921,

    # uncomment and change the parameter values if needed
    # params=[
    #     QueryParameter.text_type(name="contract", value="0x6B175474E89094C44Da98b954EedeAC495271d0F"), # default is DAI
    #     QueryParameter.text_type(name="owner", value="owner"), # default using vitalik.eth's wallet 
    # ],
)

query_result = dune.run_query_dataframe(
  query=query
  # , ping_frequency = 10 # uncomment to change the seconds between checking execution status, default is 1 second
  # , performance="large" # uncomment to run query on large engine, default is medium
  # , batch_size = 5_000 # uncomment to change the maximum number of rows to retrieve per batch of results, default is 32_000
) 

# Note: to get the result in csv format, call run_query_csv(); for json format, call run_query().

• To paginate query results, please visit the pagination page to get more info.
• If you are using the Python SDK:
  • For higher level functions like run_query(), pagination is handled for you automatically behind the scene, so you will get the entire dataset as the returned result. You can pass in parameter batch_size to define the maximum number of rows per batch or pagination call.
  • For lower level functions like get_execution_results(), you can pass in pagination parameters limit and offset directly, as instructed here.

Putting it all together

import dotenv, os
from dune_client.types import QueryParameter
from dune_client.client import DuneClient
from dune_client.query import QueryBase

# change the current working directory where .env file lives
os.chdir("/Users/abc/project")
# load .env file
dotenv.load_dotenv(".env")
# setup Dune Python client
dune = DuneClient.from_env()

""" get the latest executed result without triggering a new execution """
query_result = dune.get_latest_result(3373921) # get latest result in json format
# query_result = dune.get_latest_result_dataframe(3373921) # get latest result in Pandas dataframe format


"""  query the query (execute and get latest result) """
query = QueryBase(
    query_id=3373921,

    # uncomment and change the parameter values if needed
    # params=[
    #     QueryParameter.text_type(name="contract", value="0x6B175474E89094C44Da98b954EedeAC495271d0F"), # default is DAI
    #     QueryParameter.text_type(name="owner", value="owner"), # default using vitalik.eth's wallet 
    # ],
)

query_result = dune.run_query_dataframe(
  query=query
  # , ping_frequency = 10 # uncomment to change the seconds between checking execution status, default is 1 second
  # , performance="large" # uncomment to run query on large engine, default is medium
  # , batch_size = 5_000 # uncomment to change the maximum number of rows to retrieve per batch of results, default is 32_000
) 

# Note: to get the result in csv format, call run_query_csv(); for json format, call run_query().