Skip to content

Fetching Records ​

The getRecords() method allows you to fetch records from the database. It retrieves records based on the specified query parameters and returns a promise that resolves to the DatabaseResponse containing the RecordData object.

It takes two arguments:

  • query: Specifies the query parameters for fetching records.
  • fetchOptions: (optional) Specifies additional configuration options for fetching database records For more information, see Database Fetch Options.

What a query needs ​

Every getRecords() call reads by one of these, and only some of them need a table:

You givetable
record_id or unique_idNot needed. It fetches that one record.
reference: a record ID or unique IDNot needed: without table it searches every table (who sees what). Add a table to read one table and one access group.
reference: your own user IDNot needed: every record you uploaded, in every table.
reference: another user's user IDRequired.
nothing else (list a table), index, tag, or subscriptionRequired.

A table is always a name and an access group, together.

js
table: { name: 'notes', access_group: 'authorized' }  // one table, one access group
table: { name: 'notes' }                              // refused: "table.access_group" is required

index and tag always need the table. They search inside one table and one access group, so a query with index or tag must also have table with both name and access_group.

Fetching Records from a Table ​

js
let query = {
    table: { name: 'my_collection', access_group: 'public' }
}

skapi.getRecords(query).then(response=>{
    // response
    /**
     * endOfList: true,
     * list: [
     *  ...
     * ],
     * startKey: 'end',
     * ...
     */
});

The example above retrieve records from a table named 'my_collection' with access_group that are public The table parameter in the query argument sets the table name you want to fetch records from. The retrieved records are accessed through the response.list property.

When fetching the records with access restrictions, see Access Restrictions.

For more detailed information on all the parameters and options available with the getRecords() method, please refer to the API Reference below:

getRecords(query, fetchOptions?): Promise<DatabaseResponse<RecordData>> ​

Fetching Record by ID ​

You can fetch a record by its unique ID using the getRecords() method. When fetching a record by ID, you don't need to provide any additional configuration parameters.

js
let query = {
    record_id: 'record_id_to_fetch'
};

skapi.getRecords(query).then(response => {
    // response
    /**
     * endOfList: true,
     * list: [{
     *  ... // only 1 result
     * }],
     * startKey: 'end' // startKey is 'end' as no more records can be retrieved
     */
});

In this example, the query object includes the record_id property set to the ID of the record you want to fetch. record_id is a unique identifier for each record in the database.

The response.list will contain the record data if the record exists.

Fetching Records That Reference a Record ​

A signed in user can fetch every record that references a record, across all tables, in one request:

js
skapi.getRecords({ reference: 'record id or unique id' }).then(response => {
    console.log(response.list); // referencing records in every table and access group this user can read
});

See Fetching every record that references a record for what the list includes.

Request rate ​

For a signed-in user, getRecords() requests from skapi-js older than 2.2.30 are limited to 3,000 a minute per signed-in session. Past that, the server answers 429 TOO_MANY_REQUESTS with Retry-After: 60; the SDK waits and retries on its own. Requests from skapi-js 2.2.30 or later are not limited this way, so keep the SDK up to date:

$ npm i skapi-js@2.3.0

A normal app never comes close to this. It is reached by code that loops one request per table, for example to collect the records that reference a record. Use one getRecords({ reference }) call instead.

Database Fetch Options ​

FetchOptions can control the number of the record per fetch, fetching the next batch of records, fetching the records by ascending/descending order... etc.

This is used globally for all database related methods that allows optional FetchOptions argument.

See full list of parameters: FetchOptions

Limit Results with fetchOptions.limit ​

By default, 50 sets of the data will be fetched per call. You can adjust the limit to your preference, allowing up to 1000 sets of data, by using the limit key.

Fetch More Results with fetchOptions.fetchMore ​

To fetch the next batch of results, you can set the fetchOption.fetchMore to true. When set to false(default), database will always return the first batch of the data.

This allows you to retrieve results in batches until the end of the list is reached.

Order results with fetchOptions.ascending ​

By default, the database fetch the data in ascending order. If set to false, list of data can be fetched in descending order

For example, let's say there is millions of record in the database table 'my_collection'. We can fetch the first 100 data, then paginate to the next 100 data by setting fetchOptions.fetchMore to true.

js
let query = {
    table: { name: 'my_collection', access_group: 'public' }
}

let fetchOptions = {
  limit: 100, // Limit each fetch to 100 data.
  fetchMore: false, // When false, database always gives you the first batch of data.
  ascending: false // Fetch in decending order.
}

skapi.getRecords(query, fetchOptions).then(res=>{
  console.log(res.list); // List of up to 100 data in the database.
  
  if(!res.endOfList) {
    // If there is more data to fetch, and if user chooses to, they can retrieve the next batch of 100.

    fetchOptions.fetchMore = true;
    if(confirm('Fetch more records?')) {
        skapi.getRecords(query, fetchOptions)
            .then(res=>{
                console.log(res.list); // List of the next 100 data from the database.
            }
        );
    }
  }
});

In this example, after the first call to the database, we see the endOfList value is not true. This means there are more data left to fetch in the database.

To fetch more data in the database, we set fetchOptions.fetchMore to true and call the method again. This allows to fetch the next batch of 100 data on each execution until the end of the list is reached.

TIP

When using the fetchMore parameter, you must check if the response's endOfList value is true before making the next call. The database will always return an empty list if the fetchOptions.fetchMore is set to true and it had reached the end of list and.

You can however, initialize your fetch and refetch from start by toggling fetchOptions.fetchMore back to false.

TIP

You can fetch all the data at once by recursively calling the method until the endOfList value is true. However for efficiency, avoid trying to fetch all the data at once. Fetch only data the user needs and paginate when necessary.