GuidesAPIDatasets HubRelease Notes
API Reference
CGC

Example query 6: Find TCGA cases with or without a prior diagnosis and related samples from a particular tissue source site and return the sample type code for each of these samples

post https://cgc-api.sbgenomics.com/v2

QUERY DATASETS > About the Datasets API > Query via the Datasets API > Example query 6: Find TCGA cases...

The example shown on this page applies specifically to TCGA. However, this page also demonstrates nested queries in the request body which is applicable to other datasets. This same nesting behavior is returned in the response body.

Use the following query for TCGA if you want to see all cases which contain samples from a specific tissue source site, and you also want to know (1) the sample type code for each sample and (2) whether or not each case has a prior diagnosis.

Request

POST /datasets/tcga/v0/query HTTP/1.1
Host: cgc-datasets-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9304ea9d9273156740f74

{
   "entity":"cases",
   "fields": ["hasPriorDiagnosis"],
   "hasSample" : {
       "hasTissueSourceSiteCode": "ZJ",
       "fields": ["hasSampleTypeCode"]
    }
}

This query specifies values for the metadata field hasSample. In addition, this metadata field exhibits nesting, which is possible when a metadata field refers to another entity, in this case sample. Recall that metadata consists of entities and their properties. These properties can either describe the entity or relate the entity to another entity. As such, the entity hasSample has related metadata properties, such as hasTissueSourceSiteCode, as is queried above. The query thus looks for cases with samples from a particular tissue source site.

This query also uses the optional key fields twice. fields exposes metadata fields to be returned by the query. For instance, the above query will return the sample type code for each sample and whether or not each case has a prior diagnosis.

Response body

{
  "count": 16,
  "_embedded": {
    "cases": [
      {
        "hasPriorDiagnosis": "No",
        "hasSample": [
          {
            "id": "A19FDDB5-123A-456B-A56C-A736F25596CC",
            "hasSampleTypeCode": "01",
            "label": "A19FDDB5-123A-456B-A56C-A736F25596CC",
            "_links": {
              "self": {
                "href": "cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/samples/A19FDDB5-123A-456B-A56C-A736F25596CC"
              }
            }
          },
          {
            "id": "A19FDDB5-123A-456B-A56C-A736F25596CC",
            "hasSampleTypeCode": "10",
            "label": "A19FDDB5-123A-456B-A56C-A736F25596CC3",
            "_links": {
              "self": {
                "href": "cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/samples/A19FDDB5-123A-456B-A56C-A736F25596CC"
              }
            }
          }
        ],
        "id": "B02DEB95-123A-49CB-7890-A711D42D6FB9",
        "label": "B02DEB95-123A-49CB-7890-A711D42D6FB9",
        "_links": {
          "self": {
            "href": "cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/cases/B02DEB95-123A-49CB-7890-A711D42D6FB9"
          }
        }
      },
 
    < snip >
   ]
  }
}

Note that the response exhibits the same nesting as was issued in the original query. For each entity matching the query, the response contains:

  • Its href, a path that can be used to obtain full information about the sample. In the example above, the href is located towards the end of the response (cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/cases/B12DEB95-6AA1-49CB-A3C5-A711D42D6FB9). To see all information, issue a GET request to this path. See Example query 1: Find samples connected to a case for details. Note that the above response also contains href for each listed sample relating to the case (e.g., cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/samples/A29FDDB5-B032-43EB-A56C-A736F25596CC).
  • Its TCGA id, such as B12DEB95-6AA1-49CB-A3C5-A711D42D6FB9. Note that the above response also contains the id for each listed sample relating to the case (e.g., A29FDDB5-B032-43EB-A56C-A736F25596CC).
  • Its TCGA label, such as B12DEB95-6AA1-49CB-A3C5-A711D42D6FB9. Note that the above response also contains the label for each listed sample relating to the case (e.g., A29FDDB5-B032-43EB-A56C-A736F25596CC).
  • Whether or not each case has a prior diagnosis. Note that this value can be Yes, No, or Not Available. This exposed field does not act as a filter.
  • The sample type code for each sample. Note that this value can be an integer or Not Available. This exposed field does not act as a filter.
Language