A
list is a basic way of storing tabular information. LabKey lists are flexible, user-defined tables that can have as many columns as needed. Lists must have a primary key field that ensures rows are uniquely identified.
The
list design is the set of columns and types, which forms the structure of the list, plus the identification of the primary key field, and properties about the list itself.
Create New List and Set Basic Properties
- In the project or folder where you want the list, select (Admin) > Manage Lists.
- Click Create New List.
- Name the list, i.e. "Technicians" in this example.
- If the name is taken by another list in the container, project, or /Shared project, you'll see an error and need to choose another name. You may also want to use that shared definition instead of creating a new list definition.
- Adding a Description is optional, but can give other users more information about the purpose of this list.
- Use the checkboxes to decide whether to Allow these Actions for the list:
- Delete
- Upload
- Export & Print
- Continue to define fields and other settings before clicking Save.
Set Advanced Properties
- Click Advanced Settings to set more properties (listed below the image).
- Default Display Field: Once some fields have been defined, use this dropdown to select the field that should be displayed by default when this list is used as a lookup target.
- Discussion Threads let people create discussions associated with this list. Options:
- Disable discussions (Default)
- Allow one discussion per item
- Allow multiple discussions per item
- Search Indexing Options (by default, no options are selected):
- Index entire list as a single document
- Index each item as a separate document
- Index file attachments
- Learn more about indexing options here: Edit a List Design
- Click Apply when finished.
Continue to define the list fields before clicking
Save.
Define List Fields and Set Primary Key
The fields in the list define which columns will be included. There must be a primary key column to uniquely identify the rows. The key can either be an integer or text field included with your data, OR you can have the system generate an auto-incrementing integer key that will always be unique. Note that if you select the auto-incrementing integer key, you will not have the ability to
merge list data.
You have three choices for defining fields:
Manually Define Fields
- Click the Fields section to open the panel.
- Click Manually Define Fields (under the drag and drop region).
- Key Field Name:
- If you want to use an automatically incrementing integer key, select Auto integer key. You can rename the default Key field that will be added.
- If you want to use a different field (of Integer or Text type), first define the fields, then select from this dropdown.
- Use Add Field to add the fields for your list.
- Specify the Name and Data Type for each column.
- Check the Required box to make providing a value for that field mandatory.
- Open a field to define additional properties using the expansion icon.
- Remove a field if necessary by clicking the .
- Details about adding fields and editing their properties can be found in this topic: Field Editor.
- Scroll down and click Save when you are finished.
Infer Fields from a File
Instead of creating the list fields one-by-one you can infer the list design from the column headers of a sample spreadsheet. When you first click the
Fields section, the default option is to import or infer fields. Note that inferring fields is only offered during initial list creation and cannot be done when editing a list design later. If you start manually defining fields and decide to infer instead, delete the manually defined fields and you will see the inferral option return. Note that you cannot delete an auto integer key field and will need to restart list creation from scratch if you have manually chosen that key type already.
- Click here to download this file: Technicians.xls
- Select (Admin) > Manage Lists and click Create New List.
- Name the list, i.e. "Technicians2" so you can compare it to the list created above.
- Click the Fields section to open it.
- Drag and drop the downloaded "Technicians.xls" file into the target area.
- The fields will be inferred and added automatically.
- Note that if your file includes columns for reserved fields, they will not be shown as inferred. Reserved fields will always be created for you.
- Select the Key Field Name - in this case, select Auto integer key to add a new field to provide our unique key.
- If you need to make changes or edit properties of these fields, follow the instructions above or in the topic: Field Editor.
- In particular, if your field names include any special characters (including spaces) you should adjust the inferral to give the field a more 'basic' name and move the original name to the Label and Import Aliases field properties. For example, if your data includes a field named "CD4+ (cells/mm3)", you would put that string in both Label and Import Aliases but name the field "CD4" for best results.
- Below the fields section, you will see Import data from this file upon list creation?
- By default the contents of the spreadsheet you used for inferral will be imported to this list when you click Save.
- If you do not want to do that, uncheck the box.
- Scroll down and click Save.
- Click "Technicians2" to see that the field names and types are inferred forming the header row, but no data was imported from the spreadsheet.
Export/Import Field Definitions
In the top bar of the list of fields, you see an
Export button. You can click to export field definitions in a JSON format file. This file can be used to create the same field definitions in another list, either as is or with changes made offline.
To import a JSON file of field definitions, use the
infer from file method, selecting the .fields.json file instead of a data-bearing file. Note that importing or inferring fields will overwrite any existing fields; it is intended only for new list creation.
You'll find an example of using this option in the first step of the
List TutorialLearn more about exporting and importing sets of fields in this topic:
Field Editor
Shortcut: Infer Fields and Populate a List from a Spreadsheet
If you want to both infer the fields to design the list
and populate the new list with the data from the spreadsheet, follow the
inferral of fields process above, but leave the box checked in the
Import Data section as shown below. The first three rows are shown in the preview.
- Click Save and the entire spreadsheet of data will be imported as the list is created.
Note that data previews do not apply field formatting defined in the list itself. For example, Date and DateTime fields are always shown in ISO format (yyyy-MM-dd hh:mm) regardless of source data or destination list formatting that will be applied after import. Learn more
in this topic.
Related Topics
