V2 Records API
Using the V2 Records API with the Flatfile TypeScript API package
The V2 Records API provides an interface for reading and writing records from Flatfile sheets. It is optimized for performance when working with large numbers of records.
@flatfile/api
package in version 1.18.0.Overview
The V2 Records API is accessible through the records.v2
property on the Flatfile client.
The V2 API uses a specialized JSON Lines (JSONL) format that is optimized for performance and usage with streaming requests.
Reading Records
getRaw()
Retrieve records from a sheet in raw JSONL format.
Returns an array of JsonlRecord
objects containing the raw data structure from the API including special fields like __k
(record ID), __v
(version), etc.
Example:
getRawStreaming()
Stream records from a sheet in raw JSONL format.
The most memory-efficient way to process large datasets as records are yielded individually.
Example:
Writing Records
writeRaw()
Write records to a sheet in raw JSONL format.
Parameters:
records
- Array of JsonlRecord objects to writeoptions
- Write configuration optionsrequestOptions
- Optional request configuration
Example:
writeRawStreaming()
Stream records to a sheet in raw JSONL format.
Efficiently write large datasets by streaming records to the server.
Example:
JSONL Record Format Reference
The V2 Records API uses JSONL (JSON Lines) format for raw record operations. JSONL is a text format where each line is a valid JSON object representing a single record.
Special Fields
Flatfile uses special fields prefixed with __
(double underscore) to store metadata and system information:
Field | Description | Example |
---|---|---|
__k | Record ID (unique identifier) | "us_rc_123456" |
__nk | New record ID (for creation) | "temp_123" |
__v | Record version ID | "v_789" |
__s | Sheet ID | "us_sh_123" |
__n | Sheet slug | "contacts" |
__c | Record configuration | {"locked": true} |
__m | Record metadata | {"source": "import"} |
__i | Validation messages | {"email": [{"type": "error", "message": "Invalid format"}]} |
__d | Deleted flag | true |
__e | Valid flag | false |
__l | Linked records | [{...}] |
__u | Updated timestamp | "2023-11-20T16:59:40.286Z" |
Note that many special fields will not be included unless the corresponding query parameter is included,
such as includeMessages
to include the __i
field with validation messages.
Field Values
Regular field values are stored directly as properties on the JSONL record:
Validation Messages
If included, the __i
field contains validation messages for fields that have errors or warnings.
The messages are structured as an array of objects. Each validation message object will be structured
as {"x": <field key of message>, "m": <validation message>}
.
Complete Example
A complete JSONL record with all common fields:
Record Operations
The V2 write records endpoint can be used to create, update, or delete records into a sheet all in a single request. The operation performed depends on which special keys are provided.
Create New Record
To create a new record, the record can simply be passed with a sheet ID in __s
and no record ID.
Update Existing Record
To update an existing record, provide the record ID in the __k
field.
Delete Record
To delete a record, provide the record ID in the __k
field and pass the delete flag
in the __d
field.