When to use Replace vs Append

While there may be other considerations to take into account for your particular setup and use case, which method to use comes down to:

1. How you're extracting the data

If you’re always getting data for “right now” from your data source and want to build up a historical record in your dataset, you need to use Append. This will let you plot trends over time and also let you display comparisons such as today vs yesterday, this month vs previous month, and so on.


  1. The Twitter API lets you fetch only the current number of followers. So, you can fetch followers each day and Append it to your Dataset. This will let you plot a line chart of your number of followers over time.
  2. You can also create a Number widget displaying your followers say today vs yesterday, this month vs previous month, etc. (Note: While creating the Datasets Number widget on your dashboard, you’ll need to use the Aggregate = Latest option for achieving such a comparison visualization).

If you’re not interested in maintaining historical data or displaying a comparison, OR you’re able to pull the complete data for the entire time period you’re interested in, you can consider using Replace.


  1. You want to display the names of the customer support agents currently online on your phone help desk system.
  2. You want to display your total sales this month which is available via a single API query to your billing system.

2. How frequently you want to push data

Replace first deletes all the existing records within the dataset and then writes the new data. This is a slower and costlier operation to perform as compared to Append.

If you’re planning to push data more than once every few minutes, we would recommend using Append as it’ll be faster and give you better performance. Even if say you’re updating a dataset that contains only a single record (i.e. something you might consider using Replace for), if you’re planning to push frequently, we would recommend using Append in combination with unique_by instead.


You’re tracking the price of Bitcoin on your dashboard and want to update the price every 10 seconds. We would recommend using Append in combination with unique_by.

3. Number of records pushed by request

A single Replace or Append request will accept a maximum of 500 records. If you want to push more than 500 records to your dataset, you’ll need to send multiple requests using Append

In conclusion: Append is preferable

Using Append (in combination with unique_by and delete_by) is nearly always preferable as it is quicker, provides better performance, and lets you send more data to Geckoboard. Also, a general point of note: you can send all your required data to Geckoboard and then filter out things you’re not interested in while creating the Datasets widgets on your dashboards.

Was this article helpful?

Awesome! 👍 Thanks so much for your feedback!

Sorry about that! Start a conversation now.

We're ready to help, 24 hours a day, 5 days a week

Get support
  • Fernanda Customer Success Avatar


  • Hariharan Customer Success Avatar


  • Fernanda Customer Success Avatar


  • Luis Customer Success Avatar


  • Richard Customer Success Avatar


  • Fernanda Customer Success Avatar


  • Heather Customer Success Avatar