Today we released some improvements to our API designed to improve the way you can list and select records.
With these new parameters, you can filter, sort and otherwise limit the number of records returned in a more precise way.
Let’s take a look at how they work!
New Parameters in Action
One key result of the API updates is the replacement of the list function in the Airtable Javascript library with a new function: select. (If you have already built applications using list, fear not — it will still work. You should probably switch over, though, because select is pretty great.)
For those of you not using the Javascript library, worry not: the API endpoint for reading records remains in the same place, but it now supports the new parameters.
In all of the examples below, we’ll show you how to use the select function to achieve better performance and more precise results.
Filter by formula
Where previously you would have needed to download the full list of records in a table, you can now use a formulaic expression with our filterByFormula option to return only records which pass this ad-hoc filter condition. This should be much faster (and more efficient, to boot!)
base('Cities').select({
filterByFormula: 'AND(Days > 5, Visited)',
}).eachPage(function page(records, fetchNextPage) {
}, function done(error) {
});
filterByFormula in action. Here, we’re choosing all the cities we visited for more than 5 days from the ‘Cities’ table. You can use any formula that the Airtable formula field type supports as a filter.
Sort by multiple fields
For those cases when you want to receive records in a specific order based on certain fields, you can now programmatically sort by multiple fields.
base('Cities').select({
sort: [
{field: 'Country', direction: 'asc'},
{field: 'Days', direction: 'desc'}
],
}).eachPage(function page(records, fetchNextPage) {
}, function done(error) {
});
Here, we’re sorting the cities in our base, first by their country in ascending order, and second by the number of days we spent in them, in descending order.
Limit maximum number of records
If you have a base with a large number of records, but only want to receive a certain number of records at a time, you can use maxRecords to set a specific limit on the number of records returned.
base('Cities').select({
view: 'To visit',
maxRecords: 5
}).eachPage(function page(records, fetchNextPage) {
}, function done(error) {
});
This function identifies the table view that the records will come from. Each table view is like a lens onto the same underlying table, but each may have its own row ordering and row filters applied. You can use views that you create using Airtable’s website or app; we’re using the “Cities to Visit” view that we already set up. This then limits the total number of returned records to the first 5 (our top picks.) Better not to get too overwhelmed by all the possibilities.
Limit the fields returned
By using the fields parameter, you can choose exactly which fields you want to receive, rather than receiving all of them for every record. This makes it much easier to cut down the noise and isolate exactly the information you’re looking for from a specific record.
base('Cities').select({
fields: ['Name', 'Visited']
}).eachPage(function page(records, fetchNextPage) {
}, function done(error) {
});
In this snippet, we only want to receive the name of the city and whether it has been visited, so we use the fields parameter to specify that we want only the contents of those exact fields.
So there you have it! Have any other features you’d like to see in the API? Let us know here.