Skip to main content

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": ""
}
4155277402.png

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”

4155277409.png

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

4155244653.png

Most commonly-used tables for implementations:

  • resource

    • Common joins: resource_val (via resource_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 (via resource_var.resource_var_id ↔︎ resource.resource_id FK relationship)

  • resource_val

    • Common joins: resource_var (via resource_val.resource_var_id ↔︎ resource_var.resource_var_id FK relationship)

  • step_instance_sample

    • Common joins: resource_val (via step_instance_sample.association_id ↔︎ resource_val.step_instance_sample_id FK relationship)

  • resource_dependency

    • Primary use-case for recursive queries

  • resource_action

    • Audit log.

simple-lims-schematic.png

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