Queries

GraphCMS automatically generates queries for fetching single, and multiple entries for each defined content type belonging to your project.

You will need a Permanent Auth Token, or your Public API Permissions configured to query any data from your project.

Auto-generated queries

When a new model is added to your project, there are two generated GraphQL queries added to your schema. The queries are named after the API ID, and Plural API ID.

For example, let’s assume we have the model Post in our schema, and opted to keep the default generated API ID, and Plural API ID. The following queries would be generated by the API automatically:

• post
• posts
• postVersion
• postsConnection

Fetching a single entry

The post query is what you would use to fetch one entry from the CMS.

You can fetch an individual entry by id, or any unique non-localized field defined in your content type.

{
  post(where: { id: "..." }) {
    id
    title
  }
}

Fetching multiple entries

The posts query is what you should use to fetch multiple entries from the CMS.

{
  posts {
    id
  }
}

Fetching relations

Imagine posts have a one to many relation with comments. With GraphQL you can query the related comments in the same request.

Here we will get all posts, and their comments.

{
  posts {
    id
    comments {
      id
      author
    }
  }
}

Learn more about Relations.

Fetching localizations

When fetching one or more entry, you can also fetch the localized entries. The default locale is set to en.

{
  post(where: { id: "..." }, locales: [en, fr, de]) {
    title
  }
  posts(locales: [en, fr, de]) {
    title
  }
}

Learn more about Localization.

Fetching stages

When fetching entries, you can also specify the content stage.

The default content stage is set to DRAFT.

{
  post(where: { id: "..." }, stage: PUBLISHED) {
    title
  }
  posts(stage: PUBLISHED) {
    title
  }
}

Learn more about Content Stages.

Fetching versions

You can fetch all data of a specific entry at a point in time using the automatically generated version query.

For example, using the postVersion query from above, we can make a request to get the specific revision through a query:

{
  postVersion(where: { id: "abc123", revision: 1, stage: PUBLISHED }) {
    id
    revision
    data
  }
}

Learn more about Versioning.

Combining arguments

It is also possible to pass more than one query argument at a time.

For example, here we can get the first 3 posts, ordered by the created timestamp, where the title contains "GraphCMS", and is published.

{
  posts(
    where: { title_contains: "GraphCMS" }
    orderBy: createdAt_DESC
    first: 3
    stage: PUBLISHED
  ) {
    id
  }
}

Learn more about these query arguments:

• Filtering
• Ordering
• Pagination
• Content Stage

Combining queries

Multiple queries can be executed in parallel via a single request to your endpoint.

For example, let's fetch our a single, and multiple posts in one request.

{
  post(where: { id: "..." }) {
    id
    title
  }
  posts {
    id
    title
  }
}

For example, here we query for all events, and alias a second query with previous to better represent the applied filter.

{
  events(where: { start_gt: "2020-10-07T09:00:00+00:00" }) {
    start
  }
  previous: events(where: { start_lt: "2020-10-07T09:00:00+00:00" }) {
    start
  }
}

Fetching with Relay

GraphCMS also implements the Relay specification for querying records for all projects. You can fetch a single entry using the node query, or multiple entries with the postsConnection type.

When fetching a single entry with node, you will need to also pass the Edge Type inside the query.

Node

{
  node(id: "...") {
    ... on Post {
      id
      title
    }
  }
}

You can use the generated Relay connection query for querying multiple entries.

Connection / Edges

{
  postsConnection {
    edges {
      cursor
      node {
        id
        title
      }
    }
  }
}

Learn more about the system fields for connection type queries.