Creating a Record

Use postRecord() to create a new record or update an existing record in the database.

This method takes two arguments:

• data: The content to save as key-value pairs. This can be an object literal, null, undefined, or a form SubmitEvent. After upload, the value is stored under the data key in the returned RecordData.

• config (required): Upload configuration, including table name, access group, index values, and more.

See the example below:

Form

<form onsubmit="skapi.postRecord(event, { table: { name: 'my_collection', access_group: 'public' } }).then(rec => {
    console.log(rec);
    /*
    Returns:
    {
        data: { something: 'Hello World' },
        table: { name: 'my_collection', access_group: 'public' },
        ...
    }
    */
})">
    <input name="something" placeholder="Say something" value="Hello World"/>
    <input type="submit" value="Submit" />
</form>

JS

// Data to be saved in key:value pairs
let data = {
    something: "Hello World"
}

// Configuration for the record to be uploaded
let config = {
    table: { name: 'my_collection', access_group: 'public' }
}

skapi.postRecord(data, config).then(rec=>{
    console.log(rec);
    /*
    Returns:
    {
        data: { something: "Hello World" },
        table: { name: 'my_collection', access_group: 'public' },
        ...
    }
    */
});

This example demonstrates using the postRecord() method to create a record in the database. When successful, the method returns RecordData.

In this example, the first argument is the data to upload. The value of something is saved as part of the record and appears under the data key in the returned RecordData.

In the second argument, the table name is set to my_collection and the access group is set to public. config.table is required.

Every record must include a table name. You can think of the table name as the top-level category for your data. Later, you can fetch records by table.

config.table.name validation rules:

• Maximum length: 128 characters
• Must not be empty
• Must not include control characters or sentinel 􏿿

If the access group is public, anyone can access the uploaded data. To use different access restrictions, see Access Restrictions.

DANGER

Both authenticated and anonymous users can upload data to your project with postRecord().

Limitations for anonymous (unsigned) users:

1. They can only create records in the public access group (see Access Restrictions).
2. They cannot edit or delete any records they create.
3. They cannot create records that use Subscription features.
4. They cannot create records with Unique ID features.

You can prevent anonymous uploads by changing your project settings in the Skapi dashboard.

WARNING

When an anonymous user uploads a record, the user_id value in the returned RecordData is temporary and should not be used for user queries.

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

postRecord(data, config):Promise<RecordData>

Note

Skapi does not require you to predefine a database schema.

If the specified table does not exist, it will be automatically created when you create the record. Conversely, if a table has no records, it will be automatically deleted.

Creating Several Records at Once

postRecords() takes a list of { data, config } items, each the two arguments of postRecord(), and saves them 100 to a request. Use it when a page writes many records in one go, such as one record per imported row or per uploaded file: a thousand records are ten requests instead of a thousand.

let result = await skapi.postRecords(
    rows.map(row => ({
        data: row,
        config: { table: { name: 'imports', access_group: 'public' } }
    }))
);

// result
{
    list: [RecordData],   // the records that were saved, in the order given
    failed: [             // the items that were not, each by its position in the list
        { index: 7, code: 'INVALID_PARAMETER', message: '...' }
    ]
}

An item that is refused does not stop the others: it is reported in failed with its index, and the same code and message postRecord() would have rejected with, while the items after it are still saved. list.length + failed.length is always the number of items given. Only a failure of a request itself (the connection, the sign-in, a server error) rejects the call, and the records saved before it stay saved.

Every item follows the rules of postRecord(): the same config keys, the same table naming rules, the same access checks. Two differences: data is an object (or null), not a form with files, and files are not attached here. Attach them to a saved record with uploadFiles(), which with many files asks for its upload permits in batches as well.

postRecords(items):Promise<PostRecordsResult>

Large Record Data

There is no separate call for a large payload. When a record's data is larger than 32 KB, Skapi stores the value as a file in your project's file storage instead of keeping it in the database, and the record keeps only a reference to it. The value then counts toward your file storage instead of your database storage, see Plans and Limits.

Reading it back needs nothing from you either. The SDK fetches the value and puts it in record.data, so what you get is what you posted, whatever its size. The file it lives in never appears in the record's bin, and it cannot be uploaded or deleted by name: "__data__/__json__.json" is a reserved file name in postRecord() and in deleteFiles().