Knowledge Base

API_PurgeRecords | ADVANCED

API_PurgeRecords is as it sounds – the ability to purge or delete records in mass from Quick Base. This means deleting a collection of child records, a defined report, or an entire table if necessary. If you intend or want to research how to delete a single record – take a look at API_DeleteRecord.

BEST PRACTICE: Only in rare cases would I recommend deleting data through the API. There are several alternatives such as changing statuses / archiving records that are possible when you want to remove data from users view. Consider alternatives before moving to deletions.

EDITORS NOTE: This document will cover the URL Alternative for utilizing API_PurgeRecords for simplicity. The URL alternative is applicable for use in native Quick Base buttons, Webhooks, as well as GET requests in custom scripting. This article does not cover POST Requests, although the details are transferrable.

What are some common reasons you might want to delete data in mass from Quick Base?

✓ Removing child records when its parent record is cancelled or is being deleted also

✓ Deleting test data

✓ Removing data on a monthly or weekly basis that does not need to be saved

For this article – we will just focus on the API call part of the URL string. For more information about setting up the target / domain / table components, as well as how to use apptokens or usertokens, please review our other Knowledge Base articles such as API_AddRecord or API_EditRecord

The example API Documentation from Quick Base provides the following example:

https://target_domain/db/target_dbid?a=API_PurgeRecords&qid=10
&ticket=auth_ticket&apptoken=app_token

Just like with all API calls – your API call that follows ?a= will be “API_PurgeRecords”.

The part that follows, “qid=10” is a pivotal piece of the purge record call. API_PurgeRecords can be equated closely with API_DoQuery, in that you’re searching for a collection of records based on pre-defined criteria. Be aware that what you return in that query is going to be deleted forever, so your query needs to be tested thoroughly before pushing into production.

There are 3 methods of query you can pass into API_PurgeRecords:

  • qname=
  • qid=
  • query={}

I strongly recommend you don’t use qname, in that query names can change over time and you don’t want name changes to affect your purge.

Utilizing the “qid” parameter – will target an existing report from the chosen table. So from our example, let’s say you set up a report that strictly holds ‘Test’ data. You have defined the filters to only have your testing and bad data show up here. For example purposes, say this report is configured and can be found as qid=45. To purge it, you could put a button somewhere as an admin feature to review this data, then click to purge. Your URL would look like this:

https://quandarycg.com/db/tasks_table?a=API_PurgeRecords&qid=45

Once pressed, all of the records that filtered to show in your test report (qid 45) would now be deleted permanently.

The alternative to using “qid” is to write you own “query”. The more common use case for this is when you want to delete all children records from a parent. Say you had a project that was cancelled, and you wanted to purge all of its child tasks. In this case – you would want to query for all tasks related to that project to purge. For more information about building a Quick Base query and its various components, view their Components of a Query article.

From our example – we want to delete all ‘Tasks’ associated with my current project, which has a Record ID# of 150. Projects and Tasks are directly related (Projects have many tasks) via the field ‘Related Project’ – which has the field id 99 in the tasks table. Given the above information – we would have a query that looks like below:

query={'99'.EX.'150'} (Querying the Tasks Table in Quick Base)

Since we are querying tasks, we are looking to find all Tasks where ‘Related Project’ (fid 99) is equal to (EX from above) the Record ID# of my project (150).

Put it all together, and you get:

https://quandarycg.com/db/tasks_table?a=API_PurgeRecords&query={'99'.EX.'150'}

In a Quick Base formula – you would likely have it look closer to this:

"https://quandarycg.com/db/tasks_table?a=API_PurgeRecords&query={'99'.EX.'" & [Record ID#] & "'}"

This way – you’re always targeting the current project with the [Record ID#] field rather than a hard coded value. When clicked – all tasks related to this project will be deleted.

CAUTION: Always make sure you include a valid qid or query in your API_PurgeRecords call. By entering an invalid or empty qid or query – you will delete all records in your table and they cannot be recovered without intervention by Quick Base.

To re-state – its not recommended that you default to mass deletions. When possible – I suggest you add role restrictions, or archive your data rather than deleting it permanently. For more info, review an article about Conditional Record Filtering for roles.


Copyright ©2020 - Quandary Consulting Group