This topic is under construction for the 17.3 release of LabKey Server. For current documentation of this feature, click here.

This topic explains how to create custom grid views and tailor them to your needs. The default set of columns displayed are not always what you need to see. Custom grid views allow you to display columns you want in the order you wish, with filters, sorts and aggregate functions applied. Custom grid views can be saved for easy reference, or used as the default display for a dataset. Editors, administrators, and users granted "Shared View Editor" access can create and share customized views with other users.

Customize a Grid View

To open the grid view customizer for a given dataset, select (Grid Views) > Customize Grid.

  • Tabs: The tabs contain tools for
  • Available Fields: Shows the fields available for display. Place a checkmark next to a field to display it. Greyed out items are not fields, but table names. Click and buttons to expand/collapse fields in those tables.
  • Selected Fields: Shows the list of fields currently shown in the grid.
  • Delete: Deletes the current grid view. You cannot delete the default grid view.
  • Revert: Returns the grid to its original default state.
  • View Grid: Click to preview your changes. When viewing a modified grid with unsaved changes, the top bar will include revert, edit, and save buttons.
  • Save: Click to save your changes as the default view or as a new named grid. Saved grid views appear on the (Grid Views) pulldown menu.

Add/View/Remove Fields

  • To add a column to the grid, place a checkmark next to the field in the Available Fields pane. The field will be added to the Selected Fields pane.
  • Hover over any selected field name to see a popup with more information about the key and datatype of that field, as well as a description if one has been added.
  • To change the column display name, click the null icon.
  • To remove a field, hover over the field in the Selected Fields pane, and click the null icon.

  • You can also remove a column by clicking the column header and selecting Remove Column.
  • Click Save to save your grid changes.

Reorder Fields

To reorder the columns in the grid view, drag and drop the fields in the Selected Fields pane. Columns will appear left to right as they are listed top to bottom. Note that the display order is changed, but no changes happen to the underlying data table.

Join Fields from Other Datasets

In the Available Fields panel, a button indicates fields that are linked to other datasets through joins. When two or more datasets share a key field, that field can be used to construct joins between datasets. In this way, you can see columns from two or more datasets in one view. This combined view is the equivalent of a SQL SELECT query with one or more inner joins. For more information on joined views, see Join Columns from Multiple Tables.

  • To add fields from other datasets, expand the plus sign next to the "DataSets" node.
  • Expand the node of the dataset of interest.
  • Check boxes next to the desired fields.

Named Grid Views

  • Finalize your set of columns.
  • You can further refine the data grid, applying filters and sorts.
  • Clicking the column headers directly and apply filters and sorts.
  • Select (Grid Views) > Customize Grid.
  • Find your filters and sorts on the Filter and Sort tabs. A number in parentheses will indicate the number present.
TBD from here


    • To accept the changes, click Save.
  • After clicking the Save button, select Named, and enter a title for the new grid view.
  • By default a customized grid is private to you; only you can see it in the drop-down box or modify it. If you have "Editor" permissions (or higher) in the current folder, you can make a grid available to all users by checking the box Make this grid view available to all users.
  • The new named grid view is added to the Grid Views dropdown menu.

Customize the Default Grid View

  • To customize the default grid, make the desired changes, and preview the changes by clicking the View Grid button. Hover over the message "The current grid view is unsaved." to reveal buttons:
    • To reject the changes, click Revert.
    • To continue editing, click Edit.
    • To accept the changes, click Save.
  • After clicking the Save button, select Default view for this page.
  • By default a customized grid is private to you; only you can see it in the drop-down box or modify it. If you have "Editor" (or higher) permissions in the folder, you can make a view available to all users by checking the box Make this grid view available to all users.

Reset the Default Grid View

  • To set the default view to an existing view, select Grid Views > Set Default.
  • Select the grid you prefer from the list available.

Revert to the Original Default Grid View

  • To revert any customizations to the default grid view, open it using Grid Views > default.
  • Select Grid Views > Customize Grid.
  • Click the Revert button.

Control Visibility of Customized Grid Views

By default a customized grid is private to you; only you can see it, see in the drop-down box, or modify it. If you have "Editor" access or are an administrator in the folder, you can make it visible to all users by checking the box Make this grid view available to all users when you save.

Important: If a view is available to all users, whether it's the default view or a custom view, it's possible to filter it in a way that's unexpected to the user. For example, if you filter the Issues grid on all issues whose priority is 0, 1, or 2 (e.g., Pri less than or equal to 2), and the user filters on issues whose priority is 3, no rows will be returned. But this does not necessarily mean that there are no Pri=3 rows in the table, because they are already being filtered out by the pre-defined filter.

Views Web Part

To create a web part listing all the customized views in your folder, an administrator can create an additional web part:

  • In the lower left, select Views from the Select Web Part dropdown.
  • Click Add.
  • The webpart will show saved grid views, reports, and charts sorted by categories you assign. For example, in the


FAQ: In a study, why can't I customize my grid to show a particular field from another dataset?

Background: To customize your grid view of a dataset by adding columns from another dataset, it must be possible to join the two datasets. The columns used for a dataset's key influence how this dataset can be joined to other tables. Certain datasets have more than one key column (in other words, a "compound key"). In a study, you will typically encounter three types of datasets:

  • Demographic datasets use only one column as a key. Their key is the participantID. This means that only one line of data (for any date) can be associated with a participant in such a dataset.
  • Clinical or standard datasets use participant/visit pairs as a compound key. This means that each row is uniquely identified by participant/visit pairs, not by participant identifiers alone.
  • Assay datasets copied into a study also use compound keys. Assay datasets use participant/visit/rowID columns as compound keys, so only the trio of these columns uniquely identifies a row. In other words, a participant can have multiple assay rows associated with any individual visit - these are uniquely differentiated only by their rowIDs.
Consequences: When customizing the grid for a table, you cannot join in columns from a table with more key columns. For example, if you are looking at a clinical dataset in a study, you cannot join to an assay dataset because the assay dataset has more columns in its key, and thus can have multiple rows per participant/visit. So there isn't a unique mapping from a participant/visit pair in the 'originating' clinical dataset to a specific row of data in the assay dataset.

Guidance: To create a grid view combining columns from disparate datasets, start with the dataset with more columns in the key. Then select a column from the table with fewer columns in the key. There can be a unique mapping from the compound key to the simpler one - some columns will have repeated values for several rows, but rows will be unique.

Related Topics





expand all collapse all