Query the GraphQL API

Ponder uses your schema.graphql file to generate a GraphQL API for your app. With the dev server running, open http://localhost:42069 in your browser to use the GraphiQL (opens in a new tab) interface. GraphiQL is a useful tool for exploring your schema and testing queries during development.

Schema generation

Ponder creates a singular and a plural query field for each entity type in your schema. For example, if your schema contains a Person entity, Ponder will create a person and a persons field on the root Query type. The singular query field returns a single entity (or null), while the plural query field returns a list of entities.

type Person @entity {
  id: Int!
  name: String!
  age: Int!
}

type Query {
  person(id: Int!): Person
  persons(
    where: PersonFilter
    first: Int
    skip: Int
    orderBy: String
    orderDirection: String
  ): [Person!]!
}

Filtering

The GraphQL API supports filtering through the where arguments. The where argument is an object that contains filter options for each field you want to filter on. Here are the filter options available for each field type.

For the following examples, assume these entities exist in your database.

[
  { "id": 1, "name": "Barry", "age": 57 },
  { "id": 2, "name": "Lucile", "age": 32 },
  { "id": 3, "name": "Sally", "age": 22 },
  { "id": 4, "name": "Pablo", "age": 71 },
]

Get all Person entities with an age greater than 32:

query {
  persons(where: { age_gt: 32 }) {
    name
    age
  }
}

{
  "persons": [
    { "name": "Barry", "age": 57 },
    { "name": "Pablo", "age": 71 },
  ]
}

Get all Person entities with a name that does not end with "y":

query {
  persons(where: { name_not_ends_with: "y" }) {
    name
    age
  }
}

{
  "persons": [
    { "name": "Lucile", "age": 32 },
    { "name": "Pablo", "age": 71 },
  ]
}

Pagination

The GraphQL API supports pagination through the first and skip arguments.

query {
  persons(first: 2, skip: 1) {
    name
    age
  }
}

{
  "persons": [
    { "name": "Lucile", "age": 32 },
    { "name": "Sally", "age": 22 },
  ]
}

Sorting

The GraphQL API supports sorting through the orderBy and orderDirection arguments.

query {
  persons(orderBy: "age", orderDirection: "desc") {
    name
    age
  }
}

{
  "persons": [
    { "name": "Pablo", "age": 71 },
    { "name": "Barry", "age": 57 },
    { "name": "Lucile", "age": 32 },
    { "name": "Sally", "age": 22 },
  ]
}