Extensions

Press shift + S to search API reference.

Model

RecordQueryResult

View source

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() or view.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 result
doSomething(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.

Members

class RecordQueryResult extends AbstractModelWithAsyncData<DataType, WatchableRecordQueryResultKey>
readonly fieldsArray<Field> | null

The fields that were used to create this QueryResult. Null if fields were not specified, which means the QueryResult will load all fields in the table.

readonly idstring

The ID for this model.

readonly isDataLoadedboolean
readonly isDeletedboolean
readonly recordIdsArray<RecordId>

The record IDs in this QueryResult. Throws if data is not loaded yet. Can be watched.

readonly recordsArray<Record>

The records in this RecordQueryResult. Throws if data is not loaded yet. Can be watched.

getRecordById
function (recordId: RecordId) => Record
recordId

the ID of the Record you want

Get a specific record in the query result, or throws if that record doesn't exist or is filtered out. Throws if data is not loaded yet. Watch using 'recordIds'.

getRecordByIdIfExists
function (recordId: RecordId) => Record | null
recordId

the ID of the Record you want

Get a specific record in the query result, or null if that record doesn't exist or is filtered out. Throws if data is not loaded yet. Watch using 'recordIds'.

getRecordColor
function (recordOrRecordId: RecordId | Record) => Color | null
recordOrRecordId

the record or record ID you want the color of.

Get the Color of a specific record in the query result. Returns null if the record has no color in this query result. Throws if the record isn't in the RecordQueryResult. Watch with the 'recordColors' and 'recordIds keys.

hasRecord
function (recordOrRecordId: RecordId | Record) => boolean
recordOrRecordId

the record or record id to check the presence of

Check to see if a particular record or record id is present in this query result. Returns false if the record has been deleted or is filtered out.

loadDataAsync
function () => Promise<void>

Will cause all the async data to be fetched and retained. Every call to loadDataAsync should have a matching call to unloadData.

Returns a Promise that will resolve once the data is loaded.

toString
function () => string

A string representation of the model for use in debugging.

unloadData
function () => void
unwatch
function (keys: WatchableRecordQueryResultKey | ReadonlyArray<WatchableRecordQueryResultKey>, callback: FlowAnyFunction, context?: FlowAnyObject | null) => Array<WatchableRecordQueryResultKey>
keys

the keys to unwatch

callback

the function passed to .watch for these keys

context

the context that was passed to .watch for this callback

Unwatch keys watched with .watch.

Should be called with the same arguments given to .watch.

Unwatching a key that needs to load data asynchronously will automatically cause the data to be unloaded.

Returns the array of keys that were unwatched

watch
function (keys: WatchableRecordQueryResultKey | ReadonlyArray<WatchableRecordQueryResultKey>, callback: FlowAnyFunction, context?: FlowAnyObject | null) => Array<WatchableRecordQueryResultKey>
keys

the keys to watch

callback

a function to call when those keys change

context

an optional context for this in callback.

Get notified of changes to the query result.

Watchable keys are:

  • 'records'
  • 'recordIds'
  • 'cellValues'
  • 'recordColors'
  • 'isDataLoaded'
  • 'cellValuesInField:' + someFieldId

Every call to .watch should have a matching call to .unwatch.

Watching a key that needs to load data asynchronously will automatically cause the data to be fetched. Once the data is available, the callback will be called.

Returns the array of keys that were watched.