Custom Queries
Connecting to the ESP Database
Use the following connection settings to connect to the ESP Database. You can use any database tool of your choice, but we would recommend DBeaver for this course.
{ "host": "localhost", "user": "l7esp", "port": 1487, "ssl": false, "database": "lab7", "password": "" }

Note
You may need to leave the ‘Username’ field blank in order to connect. Additionally, if you do leave it blank, navigate to the “PostgreSQL” tab and check the box labelled “Show all databases”

Example: Returning to Workflow Turnaround Time
If you’re trying to pull data from ESP and none of the APIs will give you exactly what you want, your next option is to write a SQL query. If we were going to walk through a query that gives us Workflow Turnaround Time we’d want to consider:
Database structure
Connecting to the ESP database locally
The most common tables you’ll interact with
Running a custom query via REST
Running a custom query via backend APIs
Recursive queries in postgres and when you might need them

Most commonly-used tables for implementations:
resource
Common joins:
resource_val
(viaresource_val.bound_resource_id
↔︎resource.resource_id
FK relationship)
workflowable_resource
- resources that can be run through workflows, including Entities, Containers, and Inventory Items (Containers and Inventory Items are specialized Entity types).resource_var
Common joins:
resource
(viaresource_var.resource_var_id
↔︎resource.resource_id
FK relationship)
resource_val
Common joins:
resource_var
(viaresource_val.resource_var_id
↔︎resource_var.resource_var_id
FK relationship)
step_instance_sample
Common joins:
resource_val
(viastep_instance_sample.association_id
↔︎resource_val.step_instance_sample_id
FK relationship)
resource_dependency
Primary use-case for recursive queries
resource_action
Audit log.

Baseline query for selecting LIMS data:
select rvar.name field_name, val.value field_value, rsamp.name sample_name, rprotdef.name protocol_name from resource_val val join resource_var var on val.resource_var_id = var.resource_var_id join resource rvar on var.resource_var_id = rvar.resource_id join step_instance_sample sis on val.step_instance_sample_id = sis.association_id join workflowable_resource samp on sis.sample_id = samp.sample_id join resource rsamp on samp.sample_id = rsamp.resource_id join step_instance_base sib on sis.instance_id = sib.instance_id join step_definition_base sdb on sib.definition_id = sdb.definition_id join protocol_definition pd on sdb.definition_id = pd.protocol_id join resource rprotdef on pd.protocol_id = rprotdef.resource_id
Custom Queries
You can add new custom queries to ESP by adding an appropriately formatted YAML file to content/queries
. Note that in general, adding a query does NOT require any make
command for the query to be recognized due to the way the content directory is handled in the docker container.
YAML template for queries:
name: New Query description: |+ New Query Description query: | select resource.name from resource where uuid in :uuids parameters: uuids: description: UUIDS to fetch type: list
If the filename for the custom query is query_template.yaml
(and your host is localhost:8002
), you can hit this custom query with http://localhost:8002/api/v2/queries/<custom query name>?uuids=[<uuids list>]
, where <custom query name>
is query_template
and <uuids list>
is the list of uuids you wish to fetch, as in http://localhost:8002/api/v2/queries/query_template?uuids=["1c5f3c56-d073-4eb8-a68e-d6fbc33e6b69", "428d4c41-2f1d-4a53-a118-5b9fa325bc73"]
The custom query can then be called as follows:
from REST API:
/api/v2/queries/<custom query name>
from ESP client:
esp.utils.query
from Dashboard report/applet:
ReportApp.utils.getApiQueryResults
from Server side extension:
lab7.main.api.run_named_query