Skip to content

Querying the Gencove database

In addition to submitting jobs to a cluster and storing files on S3, Gencove Explorer enables users to easily interact with the Gencove platform. Samples can be:

  1. Queried using the Query object
  2. Restored from the Gencove Archive using the Sample.restore_samples() method

The Query object

The Query object enables users to query samples available in their account on the Gencove platform.

The samples() method of the Query object accepts four arguments:

  1. filters - filters for selecting samples to be returned from the query
    • Multiple filters can be chained with & and have to be wrapped in parentheses
  2. include_related - enables users to select which sample-related objects to return along with the sample itself.
    • A list of objects from the models module:
      • Project
      • SampleMetadata
      • File
      • QualityControl
      • Ancestry
      • TraitScore
      • Microbiome
  3. file_types - list of file types to return when specifying File in include_related
    • For this parameter to have an effect, File must be specified in include_related
  4. quality_control_types - list of file types to return when specifying QualityControl in include_related
    • For this parameter to have an effect, QualityControl must be specified in include_related

As an example, this query would pull the imputed vcf file for all samples matching the client_id HG00102-1-0-0-2.

from gencove_explorer.query import Query
from gencove_explorer.filters import SampleFilter
from gencove_explorer.models import File

samples = Query().samples(
    filters=SampleFilter.client_id == "HG00102-1-0-0-2",
    include_related=[File],
    file_types=["impute-vcf"])

The full list of query parameters and options can be found in the SDK Reference documentation.

Restoring samples from the Gencove Archive

Samples can be restored from the Gencove Archive by specifying:

  • Project id - restores all samples in the project
  • List of sample ids - restore the specified samples

For example: 

from gencove_explorer.models import Sample

Sample.restore_samples(project_id="7481fcb8-7a86-4599-bcdd-59fded7a2c36")
Sample.restore_samples(sample_ids=[
    "5f9e9892-003a-41f7-803e-7e83eb979aef",
    "478f370e-2d99-412a-864b-46b6f6b59ffa",
    "5ea8f124-fea2-47e2-86d5-fa7401f40151"
])