Skip to content

Forming and Executing Queries

Jump to bottom
Eric Zhou edited this page Jul 28, 2020 · 9 revisions

Forming and Executing Queries

  1. GraphQL Endpoint
  2. Forming Queries
  3. Executing Queries

GraphQL Endpoint

The GraphQL API has only a single endpoint for queries.
During local development, the endpoint is most likely at

http://localhost:4000/graphql

Our GraphQL endpoint is at

https://api.bte.ncats.io/graphql

Forming Queries

Read about the basics of forming GraphQL queries here.

Specify Entities

To form a query for the Biothings Explorer GraphQL API, first specify an entity that you would like to find relationships for. For example, if you want to find relationships to the CXCR4 Gene (which has an NCBIGene id of 7852), the first level of the query would be

query {
  Gene(ids: "NCBIGene:7852") {
    # rest of the query
  }
}

You can query multiple ids at once by passing an array into the ids argument. For example:

query {
  Gene(ids: ["NCBIGene:1234","NCBIGene:7852"]) {
    # rest of the query
  }
}

You can also query entities of different types at the same time. For example:

query {
  Gene(ids: "NCBIGene:7852") {
    # rest of the query
  }
  ChemicalSubstance(ids: "CHEMBL.COMPOUND:CHEMBL286494") {
    # rest of the query
  }
}

Then, specify the types that you would like to query the relationship to. For example, if you want to find the diseases that the CXCR4 Gene has a relationship with:

query {
  Gene(ids: "NCBIGene:7852") {
    Disease {
      # rest of the query
    }
  }
}

You can query for multiple types by specifying it inside of Gene. For example, if you want both the diseases and biological processes related to the CXCR4 Gene:

query {
  Gene(ids: "NCBIGene:7852") {
    BiologicalProcess {
      # rest of the query
    }
    Disease {
      # rest of the query
    }
  }
}

Filtering Results

You can filter these second level (and deeper) queries by predicates and apis that are called. Both of these arguments are optional and can take a single value or an array of values.

Note: both of these arguments take enums so they should not have quotes around them. Also, if you are using GraphQL playground, autocomplete will show you which enum values are allowed for that relationship.

For example, if you only want to know the disease that the CRCX4 Gene causes using the SEMMED GENE API:

query {
  Gene(ids: "NCBIGene:7852") {
    Disease(predicates: causes, apis: SEMMED_Gene_API) {
      # rest of the query
    }
  }
}

(v2.1+) You can also limit the results per level by using maxResults and sort by specifying either ngd_overall or ngd_starred for the sortBy argument. For example:

query {
  Gene(ids: "NCBIGene:7852") {
    Disease(sortBy: ngd_overall, maxResults: 25) {
      # rest of the query
    }
  }
}

Specifying Scalar Fields

Finally, specify the scalar fields which you would like to get. Available fields include id, label, api, publication, source, and predicate. You can specify scalar fields on any level and if they do not exist, will return either an empty string or empty array.

Note: You can use the Docs tab on the right side of the GraphQL Playground to get more information about the schema and return types.

For example:

query {
  Gene(ids: "NCBIGene:7852") {
    id
    name
    Disease(predicates: causes, apis: SEMMED_Gene_API) {
      id
      label
      publication
    }
  }
}

Valid and Invalid Queries

Note: For a query to be valid, the deepest level of a query must be all scalar fields.

Invalid Query:

query {
  Gene(ids: "NCBIGene:7852") {
    Disease(predicates: causes, apis: SEMMED_Gene_API) { # invalid query since Disease is not a scalar
    }
  }
}

Valid Query:

query {
  Gene(ids: "NCBIGene:7852") {
    Disease(predicates: causes, apis: SEMMED_Gene_API) {
      # valid query since id, label, and publication all return scalars
      id
      label
      publication
    }
  }
}

Multilevel Queries

You can also do multilevel queries, although the time taken exponentially increases (not recommended to do more than 2 level queries). For example:

query {
  Gene(ids: "NCBIGene:7852") {
    id
    label
    Disease(predicates: related_to, apis: CTD_API) {
      id
      label
      api
      publication
      BiologicalProcess(predicates: related_to) {
        id
        label
        api
        publication
      }
    }
  }
}

Executing Queries

It is recommended that you use the GraphQL playground to make queries.

Visit the links below on alternate ways to query the server using post requests.

Clone this wiki locally