Importing your data

Learn how you import a file and add it to a table.

Import your data files through either the web interface or API. Cradle supports .csv, .tsv, and .xlsx file formats. API uploads additionally support .parquet format. The maximum file size is 100MB, for larger files split them into smaller files before import.

File requirements

Before uploading, ensure your data meets the formatting requirements below.

Protein sequence

Your protein sequence data must follow these formatting rules:

Sequence formatting requirements:

• Use only capital letters for canonical amino acids.
• If you have multiple measurements for the same sequence, report them as separate rows rather than grouping or averaging them.

Supported	Unsupported
A C D E F G H I K L M N P Q R S T V W Y	-_ * . ; :

Clean amino acid sequences

Ensure your amino acid sequences are clean. Exclude purification segments like His-tags, but don't remove essential parts like C-terminal residues

Assay data

Your assay measurements must be properly formatted for accurate model training:

Data formatting requirements:

• Each cell must contain either a numeric value or be empty
• Use empty cells or NaN for missing values
• Never use zeros to represent missing data

Using zeros instead of empty cells for missing values will cause models to incorrectly learn associations between sequences and extremely low measurement values, compromising training quality.

Non-numeric characters, such as %, NA, or -, are not supported.

Importing your file

After preparing your data you are ready to import your file. You can import data to tables through the UI or API.

UI

To upload a file in the UI, go through the following steps:

1. 1

   Start the import

   Click + New import to begin the process.

2. 2

   Upload your file

   Select the file you want to import. Verify that the correct number of rows and columns were detected.

   
3. 3

   Select destination table

   Choose the table where you want to add your data.

   
4. 4

   Map columns

   Match the columns in your file to the corresponding columns in the destination table schema.

   
5. 5

   Review and confirm

   Review the data mapping and click Finish import to complete the process.

   

   Your file structure must match the destination table. If there are data type conflicts, you'll be prompted to resolve them before proceeding.

Your data is now imported. View it by navigating to Data and selecting your destination table.

API

To upload a file in the API, go through the following steps:

1. 1

   Create a load

   Use POST /v2/workspace/{workspace}/data/load:create to create a data load. Specify the context and table references you want to import the data file to.

   required	ContextProject (object) or ContextRound (object) (Context) The context the loaded data will be associated with. The data will either live within a Project (visible to all rounds) or within a specific Round of a project (visible only to that round).
   	object (Tables) A map of table references to table schemas. The map keys define the tables for which data is uploaded. The map values define the schema and file format for a given table.

   {

   • "context": {

     • "kind": "PROJECT",
     • "project_id": "string"

     },
   • "tables": {

     • "property1": {

       • "columns": [

         • {

           • "type": "BOOL",
           • "name": "string",
           • "metadata": {

             • "description": "string",
             • "deprecated": false

             },
           • "nullable": true

           }

         ],
       • "format": "CSV"

       },
     • "property2": {

       • "columns": [

         • {

           • "type": "BOOL",
           • "name": "string",
           • "metadata": {

             • "description": "string",
             • "deprecated": false

             },
           • "nullable": true

           }

         ],
       • "format": "CSV"

       }

     }

   }
2. 2

   Upload your file

   Upload your file using POST /v2/workspace/{workspace}/data/load:uploadFile. This stages your file in cloud storage but doesn't ingest it yet.

   Verify the upload using POST /v2/workspace/{workspace}/data/load:list to check for errors.

3. 3

   Finalize data load

   Complete the import using POST /v2/workspace/{workspace}/data/load:finalize to ingest your file into the destination table.

You have now successfully imported the file into the platform. To view the recently imported data use POST /v2/workspace/{workspace}/data/load:list or go to Data in the UI.

Undoing a load

If you need to remove an imported file due to errors, you can undo the import through the API. This removes the data from new table versions without permanently deleting it.

Undo a load: Use POST /v2/workspace/{workspace}/data/load:undo

Restore a undone load: Use POST /v2/workspace/{workspace}/data/load:redo

To permanently delete data from your workspace, contact your Customer Success manager.