Flairtable Docs

List records

Table of Contents

Setting up

To list records you need two things: the baseId and tableId. The tableId is very easy to find: it's just the name of the tab in your Airtable base.

The baseId is a bit trickier. You need to go to the Airtable API docs and click on the base you wish to use. The baseId is something that's immediately shown.

Airtable love

The List records call is 1:1 translated to Flairtable. If you prefer their docs (they're really good): you can just follow along there.

Remember to use the Flairtable SDK, base URL and API key though!

Usage

If you have your baseId and tableId you can list records with the select method.

Returned records do not include any fields with "empty" values, e.g. "", [], or false.

Query Params

You can use the following parameters to filter, sort, and format the results:

fields

array of strings

Only data for fields whose names are in this list will be included in the result.

If you don't need every field, you can use this parameter to reduce the amount of data transferred.

For example, to only return data from Date and Notes, send these two query parameters:

fields: ["Date", "Notes"]
filterByFormula

string

A formula used to filter records. The formula will be evaluated for each record, and if the result is not 0, false, "", NaN, [], or #Error! the record will be included in the response.

If combined with the view parameter, only records in that viewwhich satisfy the formula will be returned.

For example, to only include records where Date isn't empty, pass in NOT({Date} = '') as a parameter like this:

filterByFormula: "NOT({Date} = '')"
maxRecords

number

The maximum total number of records that will be returned in your requests. If this value is larger than pageSize (which is 100 by default), you may have to load multiple pages to reach this total. See the Pagination section below for more.
pageSize

number

The number of records returned in each request. Must be less than or equal to 100. Default is 100. See the Pagination section below for more.
sort

array of objects

A list of sort objects that specifies how the records will be ordered. Each sort object must have a field key specifying the name of the field to sort on, and an optional direction key that is either "asc" or "desc". The default direction is "asc".

The sort parameter overrides the sorting of the view specified in the view parameter. If neither the sort nor the view parameter is included, the order of records is arbitrary.

For example, to sort records by Date in descending order, send these two query parameters:

sort%5B0%5D%5Bfield%5D=Date
sort%5B0%5D%5Bdirection%5D=desc

Or as JS objects:

[{field: "Date", direction: "desc"}]
view

string

The name or ID of a view in the Table 1 table. If set, only the records in that view will be returned. The records will be sorted according to the order of the view unless the sort parameter is included, which overrides that order. Fields hidden in this view will be returned in the results. To only return a subset of fields, use the fields parameter.
cellFormat

string

The format that should be used for cell values. Supported values are:

json: cells will be formatted as JSON, depending on the field type.

string: cells will be formatted as user-facing strings, regardless of the field type. Note: You should not rely on the format of these strings, as it is subject to change.

The default is json.
timeZone

string

The time zone that should be used to format dates when using string as the cellFormat. This parameter is required when using string as the cellFormat.
userLocale

string

The user locale that should be used to format dates when using string as the cellFormat. This parameter is required when using string as the cellFormat.

Code samples

select returns a query object. To fetch the records matching that query, use the eachPage or firstPage method of the query object.

// each page
var Flairtable = require('flairtable');
var base = Flairtable({apiKey: 'YOUR_API_KEY'}).base('YOUR_BASE_ID');
base('YOUR_TABLE_ID').select({
    // Selecting the first 3 records in Grid view:
    maxRecords: 3,
    view: "Grid view"
}).eachPage(function page(records, fetchNextPage) {
    // This function (`page`) will get called for each page of records.
    records.forEach(function(record) {
        console.log('Retrieved', record.get('Date'));
    });
    // To fetch the next page of records, call `fetchNextPage`.
    // If there are more records, `page` will get called again.
    // If there are no more records, `done` will get called.
    fetchNextPage();
}, function done(err) {
    if (err) { console.error(err); return; }
});
// If you only want the first page of records, you can
// use `firstPage` instead of `eachPage`.
base('YOUR_TABLE_ID').select({
    view: 'Grid view'
})
.firstPage(function(err, records) {
    if (err) {
        console.error(err); return;
    }
    records.forEach(function(record) {
        console.log('Retrieved', record.get('Date'));
    });
});

You can also omit the done or callback parameter. This will result in a 'thenable' promise.

base('YOUR_TABLE_ID').select({
     view: 'Grid view'
})
.firstPage()
.then(function(err, records) {
    if (err) {
        console.error(err); return;
    }
    records.forEach(function(record) {
      console.log('Retrieved', record.get('Date'));
    });
});

Prev

Auth changed listener

Next

Retrieve a record