A RecordQueryResult represents a set of records. It's a little bit like a one-off View in Airtable: it contains a bunch of records, filtered to a useful subset of the records in the table. Those records can be sorted according to your specification, and they can be colored by a select field or using the color from a view. Just like a view, you can either have all the fields in a table available, or you can just ask for the fields that are relevant to you. There are two types of QueryResult:
- TableOrViewQueryResult is the most common, and is a query result filtered to all the
records in a specific Table or View. You can get one of these with
table.selectRecords()
orview.selectRecords()
. - LinkedRecordsQueryResult is a query result of all the records in a particular
linked record cell.
You can get one of these with
record.selectLinkedRecordsFromCell(someField)
.
Once you've got a query result, you need to load it before you can start working with it - extensions don't load record data by default. We recommend using useRecords, useRecordIds, useRecordById or useLoadable to handle this.
If you're not using a query result in a React component, you can manually load the data and unload it when you're finished:
async function fetchRecordsAndDoSomethingAsync(myTable) {// query for all the records in "myTable"const queryResult = myTable.selectRecords();// load the data in the query result:await queryResult.loadDataAsync();// work with the data in the query resultdoSomething(queryResult);// when you're done, unload the data:queryResult.unloadData();}
Whilst loaded, a query result will automatically keep up to date with what's in Airtable:
records will get added or removed, the order will change, cell values will be updated, etc.
Again, if you're writing a React component then our hooks will look after that for you. If not,
you can get notified of these changes with .watch()
.
When calling a .select*
method, you can pass in a number of options to control the sort order,
fields loaded and coloring mode of records: see RecordQueryResultOpts for examples.