A post and its comments. A thread and its replies. An uploaded file and the rows cut from it. Most apps are built on records that point at other records, and skapi-js 2.2.35 makes reading them one request instead of many. It is out now, and this article covers everything that changed since our last update, when skapi-js was at 2.2.22: a new way to fetch, how much work it saves, what it means for how you write a query, two old forms we are retiring, and what changed beyond the database.
Fetch by reference alone
Give getRecords() a reference and nothing else:
const res = await skapi.getRecords({
reference: 'record id or unique id of the post'
});
console.log(res.list); // every record that references the post, in any table, that this user can readNo table, no access group, no loop. The server looks in every table of the project and returns the records that reference the post, as one list. The reference can be a record ID or a unique ID, written as a string or as { record_id } / { unique_id }.
Until now, a signed-in user who was not the project owner had to ask one table and one access group at a time. Now any signed-in user can ask once.
Who sees what
One rule decides what comes back:
The user who uploaded a record, and the users it was shared with, have every right to read the records that reference it.
| The user who asks ... | Gets |
|---|---|
uploaded the post, or it was shared with them with grantPrivateRecordAccess() |
every record that references it: every access group from public to admin, every private record, every subscription record |
| anyone else | the referencing records in access groups from public up to their own. No private records, not even their own, and only the subscription records they uploaded |
Think of a support ticket. The customer who opened it sees every note attached to it, including private notes written by staff and notes in a higher access group. Another customer who can read the ticket sees only the notes their access group allows, and never a private one. Share the ticket with a colleague using grantPrivateRecordAccess(), and they see everything the customer sees.
A user's own private records that reference something they did not upload, and that was not shared with them, are not in this list. Read those from their table with access_group: 'private'.
Signed-out visitors still need to name a table. deleteRecords() is unchanged: a reference alone never widens what anyone can delete.
How much faster it is
Picture a document in a project with 40 tables. Its pages, rows and notes reference the document, spread over a few of those tables. Before, collecting them meant asking every table, and most of the answers were empty:
// Before: one request per table
const { list: tables } = await skapi.getTables();
const found = [];
for (const t of tables) {
const res = await skapi.getRecords({
table: { name: t.table, access_group: 'authorized' },
reference: docId
});
found.push(...res.list);
}
// 2.2.35: one request
const { list: found2 } = await skapi.getRecords({ reference: docId });| Before | 2.2.35 | |
|---|---|---|
| Requests to collect the document's records | 41 (the table list, then one per table) | 1 |
| Waiting, at an example 80 ms per round trip, one after another | about 3.3 seconds | about 0.08 seconds |
| As the project adds tables | every lookup gets slower | no change |
The last row matters most. With the loop, the cost grows with the project, not with the data: add a table and every lookup gets longer, even when the document's own records never change. One request stays one request.
Fuller pages. When a user may read only some of the records that reference a record, the server now fills each page up to your limit before it answers, instead of sending back short or empty pages for you to page through. Keep paging with { fetchMore: true } until endOfList is true; you just get there in fewer round trips. A page can still come back short, so go by endOfList, not by the page size.
We saw what the old way costs at scale. One app walked every table like the loop above for each lookup, and ended up sending around 175 requests a second for hours, almost all of them answering with nothing. That app was the reason we built this. BunnyQuery uses the same call when it indexes your files, so its indexing now lists a file's records in one request instead of one per table.
If your app has a loop like the one above, replace it with the single call. Requests from skapi-js older than 2.2.30 are limited to 3,000 getRecords() calls a minute per signed-in session (the SDK waits and retries on its own past that), which a normal app never reaches, but a loop per table can.
record_id, unique_id and reference need no table
A reference that works without a table changes how a whole query reads. Three ways to ask for records now work with no table at all:
| You give | Table |
|---|---|
record_id or unique_id |
Not needed. It fetches that one record. |
reference: a record ID or a unique ID |
Not needed. It searches every table, by the rule above. Add a table to read one table in one access group. |
reference: your own user ID |
Not needed. Every record you uploaded, in every table. |
reference: another user's ID, index, tag, or listing a table |
Needed, with its access group. |
So if you know which record you want, or which record the ones you want point at, you no longer need to know where they are stored.
Two ways of writing a table are deprecated
When you do name a table, it is always one table in one access group: { name, access_group }. Two shorter forms are deprecated in 2.2.35:
// Deprecated
await skapi.getRecords({ table: 'notes' });
await skapi.getRecords({ table: { name: 'notes' } });
// Write this
await skapi.getRecords({ table: { name: 'notes', access_group: 'public' } });Why. Each short form left the access group for someone else to guess, and the guesses did not agree. For a regular user, { name } meant public records in a listing, but for a while it meant "every group I can read" in a reference read. For the project owner it meant the whole table. Same code, different answers depending on who ran it and what else was in the query. With the group always written, a query means exactly what it says, to you, to the person reading your code later, and to the server.
What still works.
table: 'notes'still reads (and deletes) the public records of that table, exactly as before. 2.2.35 says it is deprecated once per page load in the console, and the TypeScript types no longer list it.table: { name: 'notes' }withoutaccess_groupis still answered by the server with the public records, so apps on an older SDK keep working. 2.2.35 itself asks for the group before sending ("table.access_group" is required), so add the group when you update.
To read across every table and access group, leave the table out and send reference alone.
Deletes that cannot go wrong
A list of ids in one call. deleteRecords() takes up to 1000 ids in record_id or unique_id:
await skapi.deleteRecords({ record_id: ['Vam2zoGfoC0Um66N', 'Vam2z9IViO6f7MUs'] });Every record is still checked: you delete your own records, or any record as an admin.
An empty id is an error. deleteRecords({ record_id: '' }) or { record_id: [] } used to read as "no id given", and the call became a delete by query. For an admin, a query with nothing in it meant "a page of any records in the project". Now the SDK refuses an empty id before sending anything, and the server refuses a delete that names no table, reference, record_id or unique_id. No call can delete records you did not name.
Also in 2.2.35
The database is the headline, but 2.2.35 carries everything since 2.2.22:
- Realtime that holds up. A message to a big group reaches its members faster (5,000 members in about 2 seconds, down from about 10). Busy groups get their messages grouped and paced, and your callback still receives each message on its own, in order. Messages from one sender arrive in the order they were sent. A connection that dies without closing (a phone changing networks, a laptop waking from sleep) is noticed within about a minute, at once when the user returns to the tab, and the SDK switches to a fresh connection before the two-hour limit, so nothing is lost. A message over 32 KB is refused before it is sent.
- Video calls on a thin connection.
encoding.audioandencoding.videotake apriority, so you can keep the voice clear while the picture gets blurry. A call that was running when the realtime connection renewed no longer loses its hang-up and recovery signals. - Anonymous accounts. A temporary account that expired while the page was in the background is noticed as soon as the user comes back, and the page signs out cleanly. New skapi.com projects have Anonymous Login on from the start.
- Plan limits refuse, not suspend. A project over its storage limit is no longer suspended. Writes past the limit are refused with a clear message, everything already stored keeps working, and the owner gets an e-mail at 80% and 100%.
- Clearer errors. A missing, invalid or unknown project ID now says "Project ID" instead of "Service ID". The error codes are unchanged.
Update to 2.2.35
$ npm i skapi-js@latest
or, with a script tag:
<script src="https://cdn.jsdelivr.net/npm/skapi-js@2.2.35/dist/skapi.js"></script>Run await skapi.version() in the browser console to check. Older versions keep working, but versions before 2.2.29 cannot fetch by reference alone (they refuse it with "table" is required. before sending), and they do not have the reading rule, the fuller pages or the safer deletes described above.
For the details, see Fetching every record that references a record, What a query needs and Deprecated: table as a string in the docs.
Thank you
Thank you for building with Skapi. Almost everything in this release started with a real app hitting a real edge, so if there is a place in yours where one call turns into many, tell us at support@broadwayinc.com.