Overview
Introduction
Data frames represent tabular data and are manipulated via Analyses. An important concept with data frames is column type; the values of data frame columns of a specific type are represented by a canonical format (e.g. Date columns all have the same format).
When creating data frames via the API, Benchling processes the provided file by validating and converting values to their canonical format. After creation, querying the resulting file (e.g. using GET /data-frames) will return a validated and converted version of the CSV.
This guide is a reference covering the specifics of the ingestion process, and how Benchling validates and converts input CSV files into their canonical form.
Supported file formats
Data frames can only be ingested as .csv files with comma-separated values using utf-8 encoding. Benchling supports files up to 15MB in size. The GET /data-frames endpoint will return a FAILED_VALIDATION status after processing if the provided file format is not supported, and the PATCH /data-frames endpoint will return a 400 error if the input file size is too large. The FAILED_VALIDATION status is additionally used in cases where the CSV file is badly formatted (e.g. inconsistent column number per row).
How values are interpreted during ingestion
During ingestion, Benchling interprets column values flexibly, and later converts to a canonical format. Generally, an entire column has to be the same type for that column to be recognized and converted as a type. Exceptions are null values (i.e. any column can contain null values) and Benchling objects (i.e. a variety of Benchling objects can be present in a single column).
The following types are not possible to interpret during ingestion and are always interpreted as strings:
- UUIDs
- Lists
- JSON
While these types cannot be ingested by the Data frames API, they can still exist in data frames created via Benchling’s in-app data frame creation tools; which is why they are listed in Types of values below.
Types of values
Data frames support the following value types. Values Benchling interprets as one of these types will be converted to their canonical form. Data frames support the following types of values:
For the subset of value types that Benchling supports, the following table outlines the acceptable values, as well as some examples that can be ingested and converted to the canonical format: