Preparing Data for Import


This topic is under construction.

LabKey Server provides a variety of different data structures for different uses: Assay Designs for capturing instrument data, Datasets for integrating heterogeneous clinical data, Lists for general tabular data, etc. Some of these data structures place strong constraints on the nature of the data to imported, for example Datasets make numerous uniqueness constraints on the data; other data structures make few assumptions about incoming data. This topic explains how to best prepare your data for import into each of these data structures in order to meet any constraints set up by the target container.

Summary Table

Data StructureDescriptionRequired ColumnsData ConstraintsDocumentation
Demographic DatasetsDemographic data in a folder of type 'Study'. Records permanent (or relatively permanent) features over time, such as birth gender, eye color, etc.
  • Some column containing participant ids 
  • Some column containing timepoint ids.
Uniqueness constraint: Participant id values must be unique. 
Clinical DatasetsClinical data in a folder of type 'Study'. Records features that change over time, such as blood pressure, weight.
  • Some column containing participant ids 
  • Some column containing timepoint ids.
Uniqueness constraint: Participant id + time point values must be unique.  
Study SpecimensTable for holding specimen vial and tissue data.See Import Specimen Spreadsheet DatatodoLabKey Data Structures
Sample Sets    
General Assay Type    

Demographic Datasets



Clinical Datasets









General Tips

Field name mapping

  • On import, the system matches the field names in the file to the field name or label in the target table, or to any import alias that have been configured. Use import alias to be unambiguous.
  • Data grid views display field labels (not names). The system adds a space if inner capital letters are found, for example "InnerCapitalLetters" becomes "Inner Capital Letters".
  • On export, behavior is target-dependent.
    • If exporting to an Excel file, the system uses the field labels.
    • If exporting to a text file, the system uses field names. (Use text if just transferring data.)

Field data types

  • Use data type 'text' if the field contains inconsistently formatted dates or numbers.
  • Field validators can enforce ranges and text patterns.
  • If your spreadsheets contain multiple data sets: use cut and paste, or create an assay with an associated transform script.

Column Names


When you import a data table into LabKey Server, it generates both a "name" and a "label" for each column it encounters in the table. The name is used as the internal database field, while the label is used as an external, user-facing field for display. In general special characters and white spaces are stripped out to form the name, while these characters are left in place in the label. The table below provides examples of how LabKey Server generates names and labels from table columns.


Original Column NameLabKey Column NameLabKey Column LabelNotes
Lymphocyte Count (cells/mm3)Lymphocyte Count _cells_mm3_Lymphocyte Count (cells/mm3)Parentheses are replaced with underscores in names.
Signature?Signature_Signature?Question marks are replaced with underscores in names.
blank fieldcolumn1blank fieldBlank columns are given a generic name, "column1", "column2", etc.

Related Topics


expand all collapse all