The Benchling Warehouse is a database solution that tracks assay data, registry entities, and sample data. For an overview of the warehouse, check out https://docs.benchling.com/docs/overview

Configuration

Setting up warehouse credentials

Note: You will need to contact your Benchling Customer Success Manager to access the Warehouse on your account and enable creation of Warehouse Credentials.

Warehouse credentials are used to access data uploaded to the Benchling warehouse using third party tools such as Spotfire, Tableau etc.

Warehouse credentials are obtained via the Account Settings page on Benchling. From the settings page, users generate new credentials by clicking on “Create credentials” under the Warehouse credentials section.  If you do not see this option, contact your Benchling Customer Success Manager to enable API access on your account.

Note. Be sure to copy the password when generating credentials, since you will not be able to access it again.

Setting up API access credentials

Use the API credentials to read and write data to Benchling. The API will be used by any service that writes instrument data to Benchling.

To create API credentials, click the Generate API Key button at the bottom of your User Settings Page.

Writing data (via the API)

Definitions for uploading assay data to Benchling

  • Assay run: The parameters about the assay. This is information about the assay known ahead of time such as instrument parameters, plate ID, etc.
  • Assay result: The result values recorded for the assay. Typically, results will specify what assay run they are associated with. We use this association for two reasons:
  1. Reviewing results: assay runs and results are reviewed together
  2. Marking invalid: when an assay run is marked invalid, all the associated results are also marked as invalid. 

Reference: https://docs.benchling.com/v2/reference#create-assay-results

Read data (Through the Warehouse)

Connect third party visualization tools to the warehouse. For each run/result, you'll see:

  1. Raw tables (e.g. my_assay_result$raw): contain unreviewed data
  2. View (e.g. my_assay_result): contains only valid, reviewed data

Generally, you'll want to query the view when unsure. Query the raw table if you want to see unreviewed data. Note that each run/result is uploaded to a project, and you'll only be able to see runs/results in projects you can access.

https://docs.benchling.com/v2/docs/getting-started

Connecting to the warehouse

To connect to the warehouse, use the following parameters in your data visualization tool:

  • Host Name: postgres-warehouse.*yourdeployname*.benchling.com.  Be sure to replace *yourdeployname* with your enterprise specific domain (that means the part before your enterprise's benchling.com URL)
  • Port: 5432
  • Database: warehouse
  • username: the username you generated above
  • password: the password you generated above

Using psql:

psql -h postgres-warehouse.*yourdeployname*.benchling.com \
  -U 'u$benchlingsupport' \
  -p 5432 \
  warehouse

Note: replace the username and *yourdeployname* as needed

Using a third-party visualization tool
Some accounts may require SSL to be turned on.

Reading data

Permissions
Permission to view assay runs and results is derived from the project in which they are placed. Project for an assay result will be specified through:

  1. If manually entered, the permissions for the assay data is the same as the permissions of the entry in which it is recorded
  2. If uploaded via a script, the project id can be specified at time of upload.
  3. When a run is included for review in an ELN entry, we move the runs and results to the project for the runs/results.

API
Assay runs and results can be individually searched for or read in bulk.

See links below for more information:
https://docs.benchling.com/v2/reference#bulk-get-assay-results
https://docs.benchling.com/v2/reference#search-assay-results

FAQ

Error trying to connect to database 'warehouse'

1) It could be that SSL isn't turned on.  To fix, try to:

  • Append the following string to the end of the query: ?ssl=true&sslmode=require at the end of your query.
  • For example, jdbc:postgresql://postgres-warehouse.*yourdeployname*.benchling.com:5432/warehouse?ssl=true&sslmode=require

2) Bash is interpreting the username as a variable.  To fix:

  • Be sure to use psql -U 'u$benchlingsupport' instead of psql -U u$benchlingsupport (replace benchlingsupport with your user ID)

3) Machine might not being able to validate RDS’s certificate

The warehouse is displaying entities that have been archived on Benchling.

  • This is due to an issue with Archiving and Unregistering at the same time. Benchling thinks that the entity is still there in the registry but can't archive it.

Did this answer your question?