{"__v":0,"_id":"5845aac1ba4f1c0f00969342","category":{"project":"55faf11ba62ba1170021a9a7","version":"55faf11ba62ba1170021a9aa","_id":"58458b4fba4f1c0f009692bb","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-12-05T15:44:15.650Z","from_sync":false,"order":6,"slug":"datasets-hub","title":"DATASETS HUB"},"parentDoc":null,"project":"55faf11ba62ba1170021a9a7","user":"5613e4f8fdd08f2b00437620","version":{"__v":35,"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","createdAt":"2015-09-17T16:58:03.490Z","releaseDate":"2015-09-17T16:58:03.490Z","categories":["55faf11ca62ba1170021a9ab","55faf8f4d0e22017005b8272","55faf91aa62ba1170021a9b5","55faf929a8a7770d00c2c0bd","55faf932a8a7770d00c2c0bf","55faf94b17b9d00d00969f47","55faf958d0e22017005b8274","55faf95fa8a7770d00c2c0c0","55faf96917b9d00d00969f48","55faf970a8a7770d00c2c0c1","55faf98c825d5f19001fa3a6","55faf99aa62ba1170021a9b8","55faf99fa62ba1170021a9b9","55faf9aa17b9d00d00969f49","55faf9b6a8a7770d00c2c0c3","55faf9bda62ba1170021a9ba","5604570090ee490d00440551","5637e8b2fbe1c50d008cb078","5649bb624fa1460d00780add","5671974d1b6b730d008b4823","5671979d60c8e70d006c9760","568e8eef70ca1f0d0035808e","56d0a2081ecc471500f1795e","56d4a0adde40c70b00823ea3","56d96b03dd90610b00270849","56fbb83d8f21c817002af880","573c811bee2b3b2200422be1","576bc92afb62dd20001cda85","5771811e27a5c20e00030dcd","5785191af3a10c0e009b75b0","57bdf84d5d48411900cd8dc0","57ff5c5dc135231700aed806","5804caf792398f0f00e77521","58458b4fba4f1c0f009692bb","586d3c287c6b5b2300c05055"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-12-05T17:58:25.582Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":28,"body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Advance Access\",\n  \"body\": \"This feature is in our advance access program. This means that, while it is fully operational, it is subject to change.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"On this page:\",\n  \"body\": \"  * [Overview](#section-overview)\\n  * [Procedure](#section-procedure)\\n  * [Step 1: Get an entity's metadata schema](#section-step-1-get-an-entity-s-metadata-schema)\\n  * [Step 2a: Filter entities](#section-step-2a-filter-entities)\\n  * [Step 2b: Count entities](#section-step-2b-count-entities)\\n  * [Next step](#section-next-step)\\n  * [Resources](#section-resources) \"\n}\n[/block]\n##Overview\n\nIssue queries with the Datasets API to filter or count a dataset's entities:\n  * **[Filter](#section-step-2a-filter-entities)** entities to return only the resources that match your query criteria.\n  * **[Count](#section-step-2b-count-entities)** entities that match your query criteria.\n\nLearn more about each dataset's entities from its [metadata page](about-metadata-for-datasets.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Procedure\n\nQueries are written in JSON and are given in terms of an entity's metadata. There are two steps to filtering or counting dataset entities using queries:\n1. Issue a [`GET` request to get an entity's schema](#section-step-1-get-an-entity-s-metadata-schema), as shown in the section below. This request lists which metadata fields are available for an entity, by consulting that entity's **metadata schema**. The metadata schema is a list of the entity's metadata fields and the permissible datatypes of their values.\n2. Construct a query using key-value pairs consisting of metadata fields and values of the appropriate datatype. Send the query as a [`POST` request to filter a dataset's entities](#section-step-2a-filter-entities) or as a [`POST` request to count a dataset's entities](#section-step-2b-count-entities).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Since every response is limited to maximum of 100 displayed results, add the `\\\"offset\\\"` property to the request body to display more results. The `\\\"offset\\\"` will return results starting from the integer value you input + 1. For example, `\\\"offset\\\": 100` will return the 101st to 200th results.\"\n}\n[/block]\nThis page shows the process for both of the above steps. Learn more about different query types from our [examples](#section-next-step).\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Step 1: Get an entity's metadata schema\n\nThis step draws upon the Datasets API's [browsing functionality](browse-datasets-via-the-datasets-api) to obtain the metadata schema for an entity within a dataset. The example request below is for TCGA but can be applied to all datasets by substituting the TCGA path below with the appropriate dataset path. To [obtain a dataset's path](browse-datasets-via-the-datasets-api#section-return-accessible-datasets), issue a `GET` request to `/datasets`.\n\nFor example, to see the metadata schema for TCGA cases, issue:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /datasets/tcga/v0/cases/schema HTTP/1.1\\nHost: cgc-datasets-api.sbgenomics.com\\nX-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96\",\n      \"language\": \"http\",\n      \"name\": \"Return metadata schema for TCGA cases\"\n    }\n  ]\n}\n[/block]\nThe response body contains the metadata schema for the case entity.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"hasPriorDiagnosis\\\": {\\n    \\\"values\\\": [\\n      \\\"Both History of Synchronous/ Bilateral and Prior Malignancy\\\",\\n      \\\"Yes, History of Synchronous and or Bilateral Malignancy\\\",\\n      \\\"No\\\",\\n      \\\"Yes, History of Synchronous/Bilateral Malignancy\\\",\\n      \\\"Not available\\\",\\n      \\\"Yes\\\",\\n      \\\"Yes, History of Prior Malignancy\\\"\\n    ],\\n    \\\"type\\\": \\\"enum\\\"\\n  },\\n  \\\"hasVitalStatus\\\": {\\n    \\\"values\\\": [\\n      \\\"Lost to follow-up\\\",\\n      \\\"Dead\\\",\\n      \\\"Alive\\\",\\n      \\\"LIVING\\\",\\n      \\\"Not available\\\",\\n      \\\"DECEASED\\\"\\n    ],\\n    \\\"type\\\": \\\"enum\\\"\\n  },\\n  \\\"id\\\": {\\n    \\\"type\\\": \\\"string\\\"\\n  },\\n  \\\"hasNewTumorEventAfterInitialTreatment\\\": {\\n    \\\"type\\\": \\\"string\\\"\\n  },\\n  \\\"hasDaysToDeath\\\": {\\n    \\\"type\\\": \\\"integer\\\"\\n  },\\n  \\\"hasClinicalT\\\": {\\n    \\\"values\\\": [\\n      \\\"T2\\\",\\n      \\\"T1c\\\",\\n      \\\"T4d\\\",\\n      \\\"T3a\\\",\\n      \\\"Ta\\\",\\n      \\\"T3\\\",\\n      \\\"T3d\\\",\\n      \\\"T1a2\\\",\\n      \\\"T2a1\\\",\\n      \\\"T1a\\\",\\n      \\\"T2a\\\",\\n      \\\"T2b\\\",\\n      \\\"T3b\\\",\\n      \\\"T0\\\",\\n      \\\"T1a1\\\",\\n      \\\"T1b1\\\",\\n      \\\"Not available\\\",\\n      \\\"T1\\\",\\n      \\\"T4\\\",\\n      \\\"T2a2\\\",\\n      \\\"T4c\\\",\\n      \\\"T2d\\\",\\n      \\\"T3c\\\",\\n      \\\"TX\\\",\\n      \\\"T1b2\\\",\\n      \\\"T2c\\\",\\n      \\\"Tis (DCIS)\\\",\\n      \\\"T4e\\\",\\n      \\\"Tis (Paget's)\\\",\\n      \\\"Tis\\\",\\n      \\\"T1mi\\\",\\n      \\\"Tis (LCIS)\\\",\\n      \\\"T1b\\\",\\n      \\\"T4b\\\",\\n      \\\"T4a\\\"\\n    ],\\n    \\\"type\\\": \\\"enum\\\"\\n  }\\n  <snip>\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response body\"\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top>top</a></div>\n\n##Step 2a: Filter entities\n\nUse an entity's metadata fields, obtained above, to write a query specifying values for certain metadata fields that you want your entities to match. The query is sent as JSON in the body of a `POST` request, as shown below. Note that the request below is for TCGA but that the same request can be issued for any dataset by substituting the TCGA path below with the appropriate dataset path.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /datasets/tcga/v0/query HTTP/1.1\\nHost: cgc-datasets-api.sbgenomics.com\\nX-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96\",\n      \"language\": \"http\",\n      \"name\": \"Filter entities\"\n    }\n  ]\n}\n[/block]\nIn the body of your request, send the query as key-value pairs as follows:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Datatype of value\",\n    \"h-2\": \"Description of value\",\n    \"0-0\": \"`entity`\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The metadata entity you wish to query.\\n\\nFor instance, you can specify an entity of `case`.\",\n    \"1-0\": \"`fields`\\n*optional*\",\n    \"1-1\": \"string\",\n    \"1-2\": \"The `fields` key is an optional field which takes a list. Here, you choose to expose metadata fields related to the `entity`.\\n\\nFor instance, for an `entity` of `case` you can supply a `fields` of a list containing one element, `hasVitalStatus`. Be sure to format your list using square brackets, `[ ]`. In this case, the response to your query will display the metadata field `hasVitalStatus` and return its value or `Not Available`.\\n\\nNote that metadata fields you enter in `fields` do *not* act as a filter. The only way to filter in a query is by entering metadata fields followed by a specific value, as described below\",\n    \"2-0\": \"<metadata_field>\",\n    \"2-1\": \"string\",\n    \"2-2\": \"The key is a metadata field followed by a specific value.\\n\\nFor instance, you can specify `hasPrimarySite` as a metadata field with a value such as `Liver`.\\n\\nRecall that the [request to obtain an entity's metadata schema](browse-datasets-via-the-datasets-api#section-return-an-entity-s-metadata-schema) provides a list of possible values for metadata fields with a type of `enum`.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"entity\\\":\\\"cases\\\",\\n   \\\"fields\\\":[\\\"hasVitalStatus\\\", \\\"hasPriorDiagnosis\\\"],\\n   \\\"hasPrimarySite\\\": \\\"Liver\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Request body\"\n    }\n  ]\n}\n[/block]\nThe request above returns details of cases whose primary cancer site is the liver. Note that as 377 cases are returned, we have omitted part of the response body.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"count\\\": 100,\\n  \\\"_embedded\\\": {\\n    \\\"cases\\\": [\\n    <snip>\\n      {\\n        \\\"hasPriorDiagnosis\\\": \\\"No\\\",\\n        \\\"hasVitalStatus\\\": \\\"Alive\\\",\\n        \\\"id\\\": \\\"11823A8A-194F-4E6B-A373-EF5A3FC7D2B9\\\",\\n        \\\"label\\\": \\\"11823A8A-194F-4E6B-A373-EF5A3FC7D2B9\\\",\\n        \\\"_links\\\": {\\n          \\\"self\\\": {\\n            \\\"href\\\": \\\"cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/cases/11823A8A-194F-4E6B-A373-EF5A3FC7D2B9\\\"\\n          }\\n        }\\n      },\\n      {\\n        \\\"hasPriorDiagnosis\\\": \\\"Yes\\\",\\n        \\\"hasVitalStatus\\\": \\\"Dead\\\",\\n        \\\"id\\\": \\\"17833039-0D7E-47F0-90E6-8CABAE94C124\\\",\\n        \\\"label\\\": \\\"17833039-0D7E-47F0-90E6-8CABAE94C124\\\",\\n        \\\"_links\\\": {\\n          \\\"self\\\": {\\n            \\\"href\\\": \\\"cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/cases/17833039-0D7E-47F0-90E6-8CABAE94C124\\\"\\n          }\\n        }\\n      },\\n      {\\n        \\\"hasPriorDiagnosis\\\": \\\"No\\\",\\n        \\\"hasVitalStatus\\\": \\\"Dead\\\",\\n        \\\"id\\\": \\\"0955D871-5413-4AB2-8FDF-B4FEB3AEEF5D\\\",\\n        \\\"label\\\": \\\"0955D871-5413-4AB2-8FDF-B4FEB3AEEF5D\\\",\\n        \\\"_links\\\": {\\n          \\\"self\\\": {\\n            \\\"href\\\": \\\"cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/cases/0955D871-5413-4AB2-8FDF-B4FEB3AEEF5D\\\"\\n          }\\n        }\\n      }\\n    <snip>\\n    ]\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response body\"\n    }\n  ]\n}\n[/block]\nFor each TCGA case satisfying the query, the response shows:\n  * **Its `id`**, such as `11823A8A-194F-4E6B-A373-EF5A3FC7D2B9`.\n  * **Its `label`**, such as `11823A8A-194F-4E6B-A373-EF5A3FC7D2B9`.\n  * **A `path`**, specified under `_links`, to which you can issue a `GET` request for more information about the case.\n  * **The `fields`** which were requested along with their values, such as `\"hasVitalStatus\": \"Alive\"`. If no value is available the following is returned:\n    * `Not Available` is returned for metadata fields with the[ type of value](browse-datasets-via-the-datasets-api#section-return-an-entity-s-metadata-schema) of enum.\n    * `null` is returned for metadata fields with a [type of value](browse-datasets-via-the-datasets-api#section-return-an-entity-s-metadata-schema) other than enum.\n\nSimilar responses are returned for alternate entities in TCGA and other datasets.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Step 2b: Count entities\n\nUse an entity's metadata fields, obtained above, to write a query counting the number of entities that satisfy your query criteria. This is done in exactly the same way as filtering entities, except that the path is appended with `/total`.\n\nTo count TCGA resources meeting your query criteria, send the request shown below. Note that the request below is for TCGA but that the same request can be issued for any dataset by substituting the TCGA path below with the appropriate dataset path.\n\nTo count TCGA resources meeting your query criteria, send the following request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /datasets/tcga/v0/query/total HTTP/1.1\\nHost: cgc-datasets-api.sbgenomics.com\\nX-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96\",\n      \"language\": \"http\",\n      \"name\": \"Count entities\"\n    }\n  ]\n}\n[/block]\nYou should include your query as the body of the request. The query is constructed in the same way as for the [API request to filter entities](#section-step-2a-filter-entities).\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Next step\n\nThe following pages in this section contain examples of queries that you can use to filter or count entities. The following example requests use TCGA data but can be issued for any dataset by substituting the TCGA path with the appropriate dataset path.\n\n* [Example query 1: Find samples connected to a case](doc:example-query-1-find-samples-connected-to-a-case) \n* [Example query 2: Count samples connected to a case](doc:example-query-2-count-samples-connected-to-a-case) \n* [Example query 3: Find cases with given age at diagnosis](doc:example-query-3-find-cases-with-given-age-at-diagnosis) \n* [Example query 4: Find all cases with a given age at diagnosis and a particular disease](doc:example-query-4-find-all-cases-with-a-given-age-at-diagnosis-and-a-particular-disease) \n* [Example query 5: Complex example for filtering TCGA data](doc:example-query-5-complex-example-for-filtering-tcga-data) \n* [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](doc: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) \n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Resources\n\n* [About metadata for datasets](doc:about-metadata-for-datasets) \n* [Browse datasets via the Datasets API](doc:browse-datasets-via-the-datasets-api)\n\n<div align=\"right\"><a href=\"#top\">top</a></div>","excerpt":"<a href=\"query-datasets\" style=\"color:#132c56\">QUERY DATASETS</a> > <a href=\"about-the-datasets-api\" style=\"color:#132c56\">About the Datasets API</a> > Query via the Datasets API","slug":"query-via-the-datasets-api","type":"basic","title":"↳ Query via the Datasets API"}

↳ Query via the Datasets API

<a href="query-datasets" style="color:#132c56">QUERY DATASETS</a> > <a href="about-the-datasets-api" style="color:#132c56">About the Datasets API</a> > Query via the Datasets API

[block:callout] { "type": "danger", "title": "Advance Access", "body": "This feature is in our advance access program. This means that, while it is fully operational, it is subject to change." } [/block] [block:callout] { "type": "warning", "title": "On this page:", "body": " * [Overview](#section-overview)\n * [Procedure](#section-procedure)\n * [Step 1: Get an entity's metadata schema](#section-step-1-get-an-entity-s-metadata-schema)\n * [Step 2a: Filter entities](#section-step-2a-filter-entities)\n * [Step 2b: Count entities](#section-step-2b-count-entities)\n * [Next step](#section-next-step)\n * [Resources](#section-resources) " } [/block] ##Overview Issue queries with the Datasets API to filter or count a dataset's entities: * **[Filter](#section-step-2a-filter-entities)** entities to return only the resources that match your query criteria. * **[Count](#section-step-2b-count-entities)** entities that match your query criteria. Learn more about each dataset's entities from its [metadata page](about-metadata-for-datasets. <div align="right"><a href="#top">top</a></div> ##Procedure Queries are written in JSON and are given in terms of an entity's metadata. There are two steps to filtering or counting dataset entities using queries: 1. Issue a [`GET` request to get an entity's schema](#section-step-1-get-an-entity-s-metadata-schema), as shown in the section below. This request lists which metadata fields are available for an entity, by consulting that entity's **metadata schema**. The metadata schema is a list of the entity's metadata fields and the permissible datatypes of their values. 2. Construct a query using key-value pairs consisting of metadata fields and values of the appropriate datatype. Send the query as a [`POST` request to filter a dataset's entities](#section-step-2a-filter-entities) or as a [`POST` request to count a dataset's entities](#section-step-2b-count-entities). [block:callout] { "type": "info", "body": "Since every response is limited to maximum of 100 displayed results, add the `\"offset\"` property to the request body to display more results. The `\"offset\"` will return results starting from the integer value you input + 1. For example, `\"offset\": 100` will return the 101st to 200th results." } [/block] This page shows the process for both of the above steps. Learn more about different query types from our [examples](#section-next-step). <div align="right"><a href="#top">top</a></div> ##Step 1: Get an entity's metadata schema This step draws upon the Datasets API's [browsing functionality](browse-datasets-via-the-datasets-api) to obtain the metadata schema for an entity within a dataset. The example request below is for TCGA but can be applied to all datasets by substituting the TCGA path below with the appropriate dataset path. To [obtain a dataset's path](browse-datasets-via-the-datasets-api#section-return-accessible-datasets), issue a `GET` request to `/datasets`. For example, to see the metadata schema for TCGA cases, issue: [block:code] { "codes": [ { "code": "GET /datasets/tcga/v0/cases/schema HTTP/1.1\nHost: cgc-datasets-api.sbgenomics.com\nX-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96", "language": "http", "name": "Return metadata schema for TCGA cases" } ] } [/block] The response body contains the metadata schema for the case entity. [block:code] { "codes": [ { "code": "{\n \"hasPriorDiagnosis\": {\n \"values\": [\n \"Both History of Synchronous/ Bilateral and Prior Malignancy\",\n \"Yes, History of Synchronous and or Bilateral Malignancy\",\n \"No\",\n \"Yes, History of Synchronous/Bilateral Malignancy\",\n \"Not available\",\n \"Yes\",\n \"Yes, History of Prior Malignancy\"\n ],\n \"type\": \"enum\"\n },\n \"hasVitalStatus\": {\n \"values\": [\n \"Lost to follow-up\",\n \"Dead\",\n \"Alive\",\n \"LIVING\",\n \"Not available\",\n \"DECEASED\"\n ],\n \"type\": \"enum\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"hasNewTumorEventAfterInitialTreatment\": {\n \"type\": \"string\"\n },\n \"hasDaysToDeath\": {\n \"type\": \"integer\"\n },\n \"hasClinicalT\": {\n \"values\": [\n \"T2\",\n \"T1c\",\n \"T4d\",\n \"T3a\",\n \"Ta\",\n \"T3\",\n \"T3d\",\n \"T1a2\",\n \"T2a1\",\n \"T1a\",\n \"T2a\",\n \"T2b\",\n \"T3b\",\n \"T0\",\n \"T1a1\",\n \"T1b1\",\n \"Not available\",\n \"T1\",\n \"T4\",\n \"T2a2\",\n \"T4c\",\n \"T2d\",\n \"T3c\",\n \"TX\",\n \"T1b2\",\n \"T2c\",\n \"Tis (DCIS)\",\n \"T4e\",\n \"Tis (Paget's)\",\n \"Tis\",\n \"T1mi\",\n \"Tis (LCIS)\",\n \"T1b\",\n \"T4b\",\n \"T4a\"\n ],\n \"type\": \"enum\"\n }\n <snip>\n}", "language": "json", "name": "Response body" } ] } [/block] <div align="right"><a href="#top>top</a></div> ##Step 2a: Filter entities Use an entity's metadata fields, obtained above, to write a query specifying values for certain metadata fields that you want your entities to match. The query is sent as JSON in the body of a `POST` request, as shown below. Note that the request below is for TCGA but that the same request can be issued for any dataset by substituting the TCGA path below with the appropriate dataset path. [block:code] { "codes": [ { "code": "GET /datasets/tcga/v0/query HTTP/1.1\nHost: cgc-datasets-api.sbgenomics.com\nX-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96", "language": "http", "name": "Filter entities" } ] } [/block] In the body of your request, send the query as key-value pairs as follows: [block:parameters] { "data": { "h-0": "Name", "h-1": "Datatype of value", "h-2": "Description of value", "0-0": "`entity`", "0-1": "string", "0-2": "The metadata entity you wish to query.\n\nFor instance, you can specify an entity of `case`.", "1-0": "`fields`\n*optional*", "1-1": "string", "1-2": "The `fields` key is an optional field which takes a list. Here, you choose to expose metadata fields related to the `entity`.\n\nFor instance, for an `entity` of `case` you can supply a `fields` of a list containing one element, `hasVitalStatus`. Be sure to format your list using square brackets, `[ ]`. In this case, the response to your query will display the metadata field `hasVitalStatus` and return its value or `Not Available`.\n\nNote that metadata fields you enter in `fields` do *not* act as a filter. The only way to filter in a query is by entering metadata fields followed by a specific value, as described below", "2-0": "<metadata_field>", "2-1": "string", "2-2": "The key is a metadata field followed by a specific value.\n\nFor instance, you can specify `hasPrimarySite` as a metadata field with a value such as `Liver`.\n\nRecall that the [request to obtain an entity's metadata schema](browse-datasets-via-the-datasets-api#section-return-an-entity-s-metadata-schema) provides a list of possible values for metadata fields with a type of `enum`." }, "cols": 3, "rows": 3 } [/block] [block:code] { "codes": [ { "code": "{\n \"entity\":\"cases\",\n \"fields\":[\"hasVitalStatus\", \"hasPriorDiagnosis\"],\n \"hasPrimarySite\": \"Liver\"\n}", "language": "json", "name": "Request body" } ] } [/block] The request above returns details of cases whose primary cancer site is the liver. Note that as 377 cases are returned, we have omitted part of the response body. [block:code] { "codes": [ { "code": "{\n \"count\": 100,\n \"_embedded\": {\n \"cases\": [\n <snip>\n {\n \"hasPriorDiagnosis\": \"No\",\n \"hasVitalStatus\": \"Alive\",\n \"id\": \"11823A8A-194F-4E6B-A373-EF5A3FC7D2B9\",\n \"label\": \"11823A8A-194F-4E6B-A373-EF5A3FC7D2B9\",\n \"_links\": {\n \"self\": {\n \"href\": \"cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/cases/11823A8A-194F-4E6B-A373-EF5A3FC7D2B9\"\n }\n }\n },\n {\n \"hasPriorDiagnosis\": \"Yes\",\n \"hasVitalStatus\": \"Dead\",\n \"id\": \"17833039-0D7E-47F0-90E6-8CABAE94C124\",\n \"label\": \"17833039-0D7E-47F0-90E6-8CABAE94C124\",\n \"_links\": {\n \"self\": {\n \"href\": \"cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/cases/17833039-0D7E-47F0-90E6-8CABAE94C124\"\n }\n }\n },\n {\n \"hasPriorDiagnosis\": \"No\",\n \"hasVitalStatus\": \"Dead\",\n \"id\": \"0955D871-5413-4AB2-8FDF-B4FEB3AEEF5D\",\n \"label\": \"0955D871-5413-4AB2-8FDF-B4FEB3AEEF5D\",\n \"_links\": {\n \"self\": {\n \"href\": \"cgc-datasets-api.sbgenomics.com/datasets/tcga/v0/cases/0955D871-5413-4AB2-8FDF-B4FEB3AEEF5D\"\n }\n }\n }\n <snip>\n ]\n }\n}", "language": "json", "name": "Response body" } ] } [/block] For each TCGA case satisfying the query, the response shows: * **Its `id`**, such as `11823A8A-194F-4E6B-A373-EF5A3FC7D2B9`. * **Its `label`**, such as `11823A8A-194F-4E6B-A373-EF5A3FC7D2B9`. * **A `path`**, specified under `_links`, to which you can issue a `GET` request for more information about the case. * **The `fields`** which were requested along with their values, such as `"hasVitalStatus": "Alive"`. If no value is available the following is returned: * `Not Available` is returned for metadata fields with the[ type of value](browse-datasets-via-the-datasets-api#section-return-an-entity-s-metadata-schema) of enum. * `null` is returned for metadata fields with a [type of value](browse-datasets-via-the-datasets-api#section-return-an-entity-s-metadata-schema) other than enum. Similar responses are returned for alternate entities in TCGA and other datasets. <div align="right"><a href="#top">top</a></div> ##Step 2b: Count entities Use an entity's metadata fields, obtained above, to write a query counting the number of entities that satisfy your query criteria. This is done in exactly the same way as filtering entities, except that the path is appended with `/total`. To count TCGA resources meeting your query criteria, send the request shown below. Note that the request below is for TCGA but that the same request can be issued for any dataset by substituting the TCGA path below with the appropriate dataset path. To count TCGA resources meeting your query criteria, send the following request: [block:code] { "codes": [ { "code": "GET /datasets/tcga/v0/query/total HTTP/1.1\nHost: cgc-datasets-api.sbgenomics.com\nX-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96", "language": "http", "name": "Count entities" } ] } [/block] You should include your query as the body of the request. The query is constructed in the same way as for the [API request to filter entities](#section-step-2a-filter-entities). <div align="right"><a href="#top">top</a></div> ##Next step The following pages in this section contain examples of queries that you can use to filter or count entities. The following example requests use TCGA data but can be issued for any dataset by substituting the TCGA path with the appropriate dataset path. * [Example query 1: Find samples connected to a case](doc:example-query-1-find-samples-connected-to-a-case) * [Example query 2: Count samples connected to a case](doc:example-query-2-count-samples-connected-to-a-case) * [Example query 3: Find cases with given age at diagnosis](doc:example-query-3-find-cases-with-given-age-at-diagnosis) * [Example query 4: Find all cases with a given age at diagnosis and a particular disease](doc:example-query-4-find-all-cases-with-a-given-age-at-diagnosis-and-a-particular-disease) * [Example query 5: Complex example for filtering TCGA data](doc:example-query-5-complex-example-for-filtering-tcga-data) * [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](doc: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) <div align="right"><a href="#top">top</a></div> ##Resources * [About metadata for datasets](doc:about-metadata-for-datasets) * [Browse datasets via the Datasets API](doc:browse-datasets-via-the-datasets-api) <div align="right"><a href="#top">top</a></div>