As your application expands, your data volume increases. Over time, obsolete events, outdated records, and raw drill data accumulate, silently increasing storage costs and cluttering your dashboard. Maintaining clean data is not just housekeeping; it affects performance, costs, and the reliability of analytics.
This guide covers why data deletion is important, the options Countly offers, and how to implement each, whether through a user interface or scripts.
Why Data Deletion Matters
Here are the most common reasons teams choose to delete data in Countly:
- Reduce storage costs: Raw event data and drill records grow continuously. Removing data you no longer need keeps your database lean and your infrastructure costs in check.
- Improve dashboard performance: Excess data slows down queries. Cleaning up old or unused records improves load times and makes reports more responsive.
- Remove clutter from the UI: Outdated event keys and view names remain visible in your dashboard even after they stop receiving data, making it harder to find what matters.
- Prevent accidental re-use: Unused event keys that linger in your system can be unintentionally triggered again by a future SDK update or a misconfiguration.
- Meet data retention policies: Many organizations have internal or regulatory requirements around how long user data is kept. Countly’s deletion tools make compliance easier.
Deletion Options in Countly
Countly provides three methods for data deletion, each targeting a different type of data and use case. Understanding the differences will help you choose the right approach.
| Goal | Method | Affects Aggregated? | Affects Drill? | Removes Key from UI? |
|---|---|---|---|---|
| Reduce old event/view counts | Clear Data Older Than X (UI) | Yes | No | No |
| Auto-delete raw event data after X years | TTL Indexes (Scripts) | No | Yes | No |
| Fully remove unused event/view keys | Deletion API or Custom Script | Yes | Yes | Yes |
Deletion Methods in Detail
Select a method below to see the full procedure, including what it does, where it deletes from, and how to use it.
What It Does
This is the easiest choice and needs no scripting. It removes aggregated data for Events and Views older than a time frame you choose. For example, 6 months or 1 year. Updates are immediately shown in the dashboard metrics.
This method only affects aggregated data (e.g., event counts, durations, unique users). It does not delete raw drill data, nor does it remove event or view keys from lists such as the Events Page or Data Manager.
What Happens After Deletion
After clearing old data, you will notice:
- Reduced counts for events and views that had activity in the deleted time range.
- A count of 0 for events or views that had no activity within the selected period.
- Event and view keys remain visible in the dashboard. They are stored as metadata in separate collections and are not touched by this operation.
For example, if an event called "Login" had 800 total counts and you clear data older than 6 months, you might see the count drop to 500, because 300 of those events occurred more than 6 months ago.
Where It Deletes From
This option removes data from the following aggregated collections:
countly.eventscountly.app_viewdata(APP_name)
How to Use It
- Go to your Countly dashboard.
- Navigate to Management > Applications.
- Click on the ellipsis dots
(...)on the upper right side: - Select your desired time range.
- Confirm the deletion.
What It Does
TTL (Time-To-Live) indexes are a MongoDB feature that automatically deletes raw (drill) data after a specified period. For example, 2 years. Once set up, this runs as an ongoing background process, so you do not need to manually trigger deletions.
This is the recommended approach for managing raw event data at scale over the long term.
TTL indexes operate on the cd (creation date) field of drill collections. MongoDB runs the cleanup job approximately every 60 seconds.
Where It Deletes From
TTL indexes apply to granular drill collection: countly.drill_drill_events
How It Works
A TTL index is set on the cd field of the collection with an expireAfterSeconds value. For example, to retain 2 years of data:
{ expireAfterSeconds: 63072000 } // 2 years in seconds
MongoDB will automatically remove any document in that collection where the cd value is older than the specified duration.
How to Set It Up
TTL indexes are typically configured via scripts. Countly provides the following script options depending on your needs:
- Overall Data Purge Script: Use this script to purge all data from your system. It sets TTL indexes based on the cd field, deleting data as it reaches the specified age.
-
Single App Purge Script: Use this script to remove data from a single application. It functions similarly to the overall purge script but targets data from one specific app.
- For Countly v24.05 and older: use this script
- For Countly v25.03 (batch-based): use this script
- Multiple App Purge Script: For purging data from multiple applications simultaneously, use this script. It also sets TTL indexes based on the cd field across multiple app collections.
After running the script, you should notice increased resource usage as the database processes the TTL indexes. This is normal and indicates that the script is working correctly.
Verifying the TTL Index Is Active
You can confirm the index was created by checking the collection indexes. You should see an entry like this:
{ "key": { "cd": 1 }, "name": "cd_1", "expireAfterSeconds": 31536000 }
You can also navigate to Management > DB Viewer in your dashboard to inspect collections and monitor deletion progress.
Scheduled vs. Immediate Deletion
There are two variants of the purge script:
- Scheduled (TTL-based): Data is deleted gradually as it ages past the expireAfterSeconds threshold. For example, if you run the script on 1 July with a 1-year retention window, data older than 1 year will start being removed from 1 August onward.
- Immediate (batch-based): Deletes data immediately based on the ts (timestamp) field, which reflects when the event occurred on the device. Use this when you need to purge large volumes of data right away without waiting for TTL to kick in. Note: this script must be re-run periodically to handle new data.
What It Does
The previous two methods reduce or remove data counts, but they do not remove the event or view key itself from the Countly UI. If you want to fully clean up your Events Page, Views Page, or Data Manager, removing keys that are no longer in use, you need to use the Deletion API or a custom script.
This is the most complete form of data deletion: it removes both aggregated and drill data, and deletes the key from the UI.
When to Use This
- You have event or view keys that are no longer tracked by your SDK.
- You want to prevent old keys from cluttering your dashboard.
- You want to prevent accidental reactivation of a deprecated event.
Deleting Unused Events via the Data Manager or API Endpoint
Deleting unused Events from Countly can also be done via the Data Manager.
For more detailed information, check the documentation here.
Alternatively, you can also use the following API endpoint to delete one or two events:
/i/events/delete_events?apikey=APIKEY&appid=APP_ID&events=["event1","event2"]
Replace APIKEY and APP_ID with your credentials, and list the event keys you want to delete inside the array.
Note
Deleting events can be quite resource-intensive depending on the number of events and your server's data volume and resources.
For larger operations, we recommend using custom scripts rather than the Data Manager or API endpoint, as both are subject to server and HTTP timeouts. Custom scripts connect directly to the database and are not bound by these constraints.
Deleting Unused Events via a Script
Deleting unused Events can also be achieved via the custom script we prepared here.
This method lets you run the script in a "test run" by setting DRY_RUN to true. This gives you a better overview by outputting the events that will be deleted for verification before the actual deletion.
Once you have verified the events to be deleted, set DRY_RUN to false and run the script again to start the actual deletion process.
Deleting Unused Views via a Script
Deleting view metadata requires running a custom script. You can find the script here.
Best Practice: Blocking Deleted Keys
After deleting an event or view key, it is strongly recommended to also block the deleted keys via Filtering Rules. This prevents the key from being re-ingested if it is accidentally triggered again by your application.
Without this step, Countly will automatically re-create the key in its metadata collections the next time an event with that name arrives, undoing your cleanup.
Lastly, we recommend performing data cleanup of unused events/views at the SDK level; this is essential when deleting keys due to a naming change or a deprecated feature, and it is important that old code paths cannot accidentally resurrect a deleted event/view.
Choosing the Right Method
Not sure which option to use? Here is a quick guide:
- Use Clear Data Older Than X if you want a quick, UI-based way to reduce old event or view counts without touching raw data.
- Use TTL Indexes if you want a hands-off, automated approach to managing raw drill data retention over the long term.
- Use the Deletion API or custom script if you need to fully remove an event or view key from your system, including from the dashboard UI.
- Combine methods for comprehensive cleanup: use the Deletion API or customer script to remove the key, and block it at the SDK level to prevent re-ingestion.