GraphQL Content Delivery API

[Alpha : 0.0.1]

Introduction

Overview

GraphQL Content Delivery API is a more efficient alternative to the Content Delivery APIs. It lets you fetch customized response or retrieve data of nested or multiple resources through a single API request.

So, for example, you can get just the Title and Description of an entry, instead of the data of all the fields, in a response. It allows you to do so by defining the structure of its request.

Let’s look at a basic query to understand the concept well.

Consider you want to fetch only the Title of an entry of the Product content type. The query should be as follows:

query {
  product(uid: "blt12cc15b692d0f3cf") {
    title
  }
}

The response body will bring up the following content:

{
"data": {
  "product" {
    "title": "Galaxy Note",
  }
}

Likewise, you can build longer, more complex queries to retrieve the exact data that you want.

Note: The Contentstack GraphQL Content Delivery API is currently available in Alpha version. We will release the Beta version soon.

Authentication

GraphQL API requests must be authenticated using the following details in the URL:

  • Stack API key
  • Delivery token of the concerned environment

You need to pass the stack API Key and the delivery token in the URL to authenticate your request.

The API Key is a unique key assigned to each stack. The delivery token is a read-only token, meaning this token can be used to fetch published content only, and not to edit or create new content in your stack.

To create a new delivery token or view existing tokens navigate to SETTINGS > Tokens. You can get the Stack API key on the same page.

Only the Developers, Admins, and Owners of the stack can view or create tokens. Learn more about delivery tokens.

Let’s look at a basic GraphQL API request to understand how these credentials will be passed:

https://graphql.contentstack.com/stacks/blt20962a819b57e233?access_token=cscd5a86465a89929407f8fd9c&environment=production&query={all_product(where:%20{title:%20%22Galaxy%20Note%22})%20{%20items%20{%20title%20price_in_usd%20}%20}%20}

Note: To use Delivery Tokens in the calls given below, use the value of the delivery token against the access token key.

Rate Limiting

The rate limit is the maximum number of requests you can make using Contentstack's API in a given period. When you execute a GraphQL query, it fetches content using Contentstack's CDN cache. There are, therefore, no limits on the number of GraphQL requests that you can make.

For requests to the origin server, we have set a maximum limit of 1 request per second per organization.

API Conventions

  • The domain name for the Contentstack GraphQL API is graphql.contentstack.com.
  • While Contentstack’s REST API has numerous endpoints, Contentstack GraphQL API has a single endpoint. You can perform all the operations using this single endpoint: https://graphql.contentstack.com/stacks/{stack_api_key}?access_token={delivery_token}&environment={environment_name}
  • The Contentstack GraphQL API endpoint for both entries and assets is the same. It can be used to fetch content (both entries and assets) across multiple content types.
  • Every field element of an HTTP request can be specified within a single GraphQL query.

Anatomy of a GraphQL Query

Let’s look at the basic parts of a simple GraphQL query.

GraphQL_Sample_Query.jpeg
  • Operation Type: GraphQL queries use the query keyword to indicate the type of operation we are performing.
  • Arguments: An argument consists of a parameter-value set that can be used to specify arguments such as locale, skip, limit, where (conditions), etc.
  • Fields: You can define the set of data for which you are asking.

The above query would look as follows when written in the form of a request:

https://graphql.contentstack.com/stacks/blt20962a819b57e233?access_token=cscd5a86465a89929407f8fd9c&environment=production&query={all_product(where:%20{title:%20%22Galaxy%20Note%22})%20{%20items%20{%20title%20description%20}%20}%20}

Within this request query, we state the stack API key , the delivery token, and the publishing environment, followed by your query.

Note: The API request will require an environment parameter at all times.

Errors

If there is something wrong with the API request, Contentstack returns an error.

Contentstack uses conventional, standard HTTP status codes for errors, and returns a JSON body containing details about the error. In general, codes in the 2xx range signify success. The codes in the 4xx range indicate error, mainly due to information provided (for example, a required parameter or field was omitted). Lastly, codes in the 5xx range mean that there is something wrong with Contentstack’s servers; it is very rare though.

Let’s look at the errors that Contentstack returns when there is an issue with the GraphQL request:

 

Error in response Description
api_key - ['is not valid'] The entered API key is invalid.
organization: ['is not valid'] The organization has been disabled.
access_token: ['is not valid'] The entered access token is not valid.
environment: ['is not valid'] The entered environment name is invalid.
plan: [' "graphql" is not enabled. Please contact support@contentstack.com to enable'] GraphQL has not been enabled in your plan.
{ "errors": [{ "message": "Failed to fetch items", "locations": [{ "line": 2, "column": 3 }], "path": ["Query field"], "extensions": { "errors": [{ "limit": ["should not be greater than 100"] }], "statusCode": 412 } }], "data": { "all_assets": null } } The number of entries requested for exceeds the allowed limit.

Reference

Retrieving Entries

In this section, we learn how to fetch specific fields or all the fields of an entry.

Get Specific Fields of an Entry

You can fetch data of only certain fields of a specific entry of a content type. To do this, you need to specify the content type uid, the entry uid and the fields in the query.

So, for instance, if you want only the values of the Title and Color fields of the Product content type published in English - United States, the query for this request would look as follows:

query {
    product(uid: "blt12cc15b692d0f3cf", locale: "en-us") {
      title
      color
    }
}

The ‘locale’ parameter in the argument is optional. If you specify one or more locales, the request will fetch the content of only those locales. If you do not specify a locale, it will fetch the content of the master locale.

Note: If your content type UIDs and field UIDs start with a number, you won't be able to run any GraphQL queries.

Get Specific Fields of an Entry


Get Specific Fields of All Entries

You can also pull up the values of specific fields for all the entries of a particular content type. Let us consider a scenario where you need to fetch the titles of all the entries of the Product content type which are published in English - United States.

Here, the GraphQL query will look as follows:

query {
      all_product(locale: "en-us") {
        total
        items {
          title
        }
      }
}


The ‘total’ parameter in the above query fetches the total count of all the entries available in the content type. It is an optional parameter.

Note: If your content type UIDs and field UIDs start with a number, you won't be able to run any GraphQL queries.

Get Specific Fields of All Entries


Query Operators

Queries help you fetch filtered results. You can use almost all the queries that are part of our Content Delivery APIs. Let’s look at how to use these queries with GraphQL.

Equals Operator

Get data of entries containing the field values matching the specified condition.

Example: In the Product content type, you have a field named Title. If, for instance, you want to retrieve certain fields of all the entries in which the value for the ‘Title’ field is Galaxy Note, your query will be formed as follows:

query {
  all_product(where: {title: "Galaxy Note"}) {
    items {
      title
      price_in_usd
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query and include details of just the ‘Title’ and ‘Price in USD’ fields.

Try 'Equals' Operator

Equals Operator within Group

Get entries where the value of a field within a Group field matches the condition in the query. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers and, within this Group field, we have a subfield named Card Type. If, for instance, you want to retrieve the entries in which the value for the Card Type field is Credit Card, your query will look as follows:

query {
  all_product(where: {bank_offers: {card_type: "Credit Card"}}) {
    items {
      price_in_usd
      description
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and include details of just the ‘Price in USD’ and ‘Description’ fields.

Try 'Equals' Operator within Group

Equals Operator within Modular Blocks

Get entries where the value of a field within a Modular Blocks field matches the condition in the query. This query uses inline fragments to retrieve values of fields that lie within a particular block of a Modular Blocks field.

Example: In the Product content type, we have a Modular Blocks field named Additional Info that contains the Deals block. And, within this Deals block, we have a field named Deal Name. If, for instance, you want to retrieve the entries in which the value for the Deal Name field is 'Christmas Deal', your query will look as follows:

query {
  all_product(where: {additional_info: {deals: {deal_name: "Christmas Deal"}}}) {
    items {
      additional_info {
       ...RelatedProducts
      }
    }
   }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
        products {
      title
    }
      }
  }
  ... on ProductAdditionalInfoRating {
    rating {
           stars
      }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields from the ‘Deals’ block of the modular block named ‘Additional Info.’

Try 'Equals' Operator within Modular Blocks

Not-equals Operator

Get all the entries in which the value of a field does not match the value provided in the condition.

Example: In the Product content type, you have a field named Price in USD. If, for instance, you need to retrieve all entries where the value of this field is not equal to '200', your query will look as follows:

query {
  all_product(where: {price_in_usd_ne: 200}) {
    items {
      title
      size
      color
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title,’ ‘Size,’ and ‘Color’ fields.

Try 'Not Equals' Operator

Not-equals Operator within Group

Get entries where the value of a field does not match the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers and, within this Group field, we have a subfield named Card Type. If, for instance, you want to retrieve the entries in which the value for the Card Type field is NOT 'Debit Card', your query will look as follows:

query {
  all_product(where: {bank_offers: {card_type_ne: "Debit Card"}}) {
    items {
      title
      color
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Color’ fields.

Try 'Not Equals' Operator within Group

Not-equals Operator within Modular Blocks

Get entries where the value of a field within the Modular Blocks field matches the condition in the query. This query uses inline fragments to retrieve values of fields that are part of any block within a Modular Block field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Deals block. And, within this Deals block, we have a field named Deal Name. If, for instance, you want to retrieve the entries in which the value for the Deal Name field is NOT 'Summer Deal,' your query will look as follows:

query {
  all_product(where: {additional_info: {deals: {deal_name_ne: "Summer Deal"}}}) {
    items {
      additional_info {
       ...RelatedProducts
      }
    }
   }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
        products {
      title
    }
      }
  }
  ... on ProductAdditionalInfoRating {
    rating {
           stars
      }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'Not Equals' Operator within Modular Blocks

In Operator

Get entries in which the value of a field matches any of the given values. This parameter will compare field values of entries to that of the values provided in the condition.

Example: In the Product content type, you have a field named Size. If, for instance, you need to retrieve all the entries where the value of this field is one among the given set of values, your query will look as follows:

query {
  all_product(where: {size_in: [8, 16, 32]}) {
    items {
      title
      color
      size
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query and will include details of just the 'Title,' 'Size,' and ‘Color’ fields.

Try 'In' Operator

In Operator within Group

Get entries where the value of a field, within a Group field, matches any of the given values. This parameter will compare field values of entries to that of the values provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have a subfield named Card Type. If, for instance, you want to retrieve the entries in which the values for the Card Type field are ‘Credit Card’ and 'Debit Card', your query will look as follows:

query {
  all_product(where: {bank_offers: {card_type_in: ["Credit Card", "Debit Card"]}}) 
    {
      items {
        title
        color
      }
    }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Color’ fields.

Try 'In' Operator within Group

In Operator within Modular Blocks

Get entries where the value of a field within Modular Blocks matches any of the given values. This query uses inline fragments to retrieve values of fields that are part of any block within a Modular Block field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Deals block. And, within this Deals block, we have a field named Deal Name. If, for instance, you want to retrieve the entries in which the values for the Deal Name field are 'Christmas Deal’, ‘Summer Deal', and ‘Independence Day Deal’, your query will look as follows:

query {
  all_product(where: {additional_info: {deals: {deal_name_in: ["Christmas Deal", "Summer Deal", "Independence Day Deal"]}}}) {
    items {
      additional_info {
       ...RelatedProducts
      }
    }
   }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
        products {
      title
    }
      }
  }
  ... on ProductAdditionalInfoRating {
    rating {
           stars
      }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'In' Operator within Modular Blocks

Not In Operator

Get all entries in which the value of a field does not match any of the given values. This parameter will compare field values of entries to that of the values provided in the condition, and the query will retrieve entries that have field values that do not match any of the values provided.

Example: In the Product content type, you have a field named Title. If, for instance, you need to retrieve the entries where the field value does not fall in the given set, your query will look as follows:

query {
  all_product(where: {title_nin: ["Redmi 3S", "Galaxy Note", "Redmi Note Prime"]}) {
    items {
      title
      price_in_usd
      size
      color
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the 'Title', ‘Price in USD’, Size, and ‘Color’ fields.

Try 'Not In' Operator

Not In Operator within Group

Get entries in which the value of a field does not match any of the values provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have a subfield named Discount In Percentage. If, for instance, you want to retrieve the entries in which the values for the Discount In Percentage field are NOT ‘8’, '25', and '30', your query will look as follows:

query {
  all_product(where: {bank_offers: {discount_in_percentage_nin: [8, 30, 25]}})      
    {
      items {
      title
      color
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Color’ fields.

Try 'Not In' Operator within Group

Not In Operator within Modular Blocks

Get entries where the values of the fields within Modular Blocks match the condition in the query. This query uses inline fragments to retrieve values of fields that are part of any block within a Modular Block field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Deals block. And, within this Deals block, we have a field named Deal Name. If, for instance, you want to retrieve the entries in which the values for the Deal Name field are NOT 'Christmas Deal’, ‘Independence Day Deal’, and ‘Summer Deal', your query will look as follows:

query {
  all_product(where: {additional_info: {deals: {deal_name_nin: ["Summer Deal", "Christmas Deal", "Independence Day Deal"]}}}) {
    items {
      additional_info {
       ...RelatedProducts
      }
    }
   }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
        products {
      title
    }
      }
  }
  ... on ProductAdditionalInfoRating {
    rating {
           stars
      }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'Not In' Operator within Modular Blocks

Include Referenced Entries

Get entries of a content type that have a reference field along with the content of the specified entry. This query is specifically for fields that are part of an entry within the reference field.

Example: In the Product content type, there is a reference field called Categories, which refers entries of another content type. Let’s assume that you had created an entry for the Product content type, and the value selected in the Categories content type was ‘Mobiles’. If you fetch the entry using the ‘Get a Single Entry’ API request, you would get all the details of the entry in the response, but the value against the Categories field would be UID of the referenced entry (i.e., UID of the ‘Mobiles’ entry in this case).

Note: When you query reference fields that refer to content types other than the first 100 available, the query will only return the UID of the reference field. If referenced entries are not published, then the UIDs of those fields will be resolved to null.

To directly fetch the referenced entry with the Title field’s value as ‘Mobiles’, you can run the following query:

query {
  all_product {
    total
    items {
      title
      categories {
        title
      }
    }
  }
}

Note: Contentstack’s GraphQL queries can fetch referenced entries up to five levels deep.

Try 'Including Referenced Entries'

Search within Referenced Entries

Get entries having values based on referenced fields. This query retrieves all entries that satisfy query conditions made on referenced fields.

Let us use the equals operator to search based on the Title field of a referenced content type, Category.

Example: In the Product content type, if you wish to retrieve all entries that have their category title set to ‘Mobiles’, your query will look as follows:

query {
  all_product(where: {categories: {title: "Mobiles"}}) {
    total
    items {
      title
      categories {
        title
      }
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ field of the Category content type. Similarly, all the query operators listed in this guide can be applied to search based on the values of referenced fields.

Note: Only up to one level deep of referenced fields can be used within the where argument to filter the requested entries.

Try 'Reference Search Equals' Operator


Get Entries by Referenced Asset

Get entries by using asset data to query a content type.

Example: In the Product content type, if you wish to retrieve all entries that have an image stored by the name in-galaxy-note-5-n9208-sm-n9208zdvins-000000003-back-gold.jpg within the Images field, your query will look as follows:

query {
  all_product(where: {images: {title: "in-galaxy-note-5-n9208-sm-n9208zdvins-000000003-back-gold.jpg"}}) {
    total
    items {
      title
      categories {
        title
      }
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ field of the Category content type.

Note: You cannot query content types based on the URL field of an asset.

Get Entries by Referenced Asset

Search by Regex

Get entries by using regular expressions to query fields of a content type. These regex queries will help to retrieve all the entries of a content type that have field values matching the condition provided in the query parameter.

Example: In the Product content type, you have a field named Title in your content type, and you want to retrieve all the entries within this content type that have values for this field starting with 'Red'. Your query will look as follows:

query {
  all_product(where: {title_regex: "Red"}) {
    items {
      title
      price_in_usd
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Price in USD’ and ‘Title’ fields.

Try 'Search by Regex' Operator

Search by Regex within Group

Get entries by using regular expressions to query fields of a Group field. These regex queries will help to retrieve all the entries of a content type that have field values matching the condition provided in the query parameter. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have a subfield named Card Type. If, for instance, you want to retrieve the entries in which the values for the Card Type field start with ‘Credit', your query will look as follows:

query {
  all_product(where: {bank_offers: {card_type_regex: "Credit"}}) {
    items {
      title
      color
      size
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’, ‘Color’, and ‘Size’ fields.

Try 'Search by Regex' Operator within Group

Search by Regex within Modular Blocks

Get entries by using regular expressions to query fields of a content type. These regex queries will use inline fragments to retrieve all the entries of a content type that have field values matching the condition provided in the query parameter.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Deals block. And, within this Deals block, we have a field named Deal Name. If, for instance, you want to retrieve all the entries within this content type that have values for this field starting with 'Sum', your query will look as follows:

query {
  all_product(where: {additional_info: {deals: {deal_name_regex: "Sum"}}}) {
    items {
      additional_info {
       ...RelatedProducts
      }
    }
   }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
        products {
      title
    }
      }
  }
  ... on ProductAdditionalInfoRating {
    rating {
           stars
      }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'Search by Regex' Operator within Modular Blocks

AND Operator

Get entries that satisfy all the conditions provided in the 'AND' query.

Example: Let’s say you want to retrieve entries in which the Title field is set to 'Redmi Note 3' and the Color field is 'Gold'. Your query will look as follows:

query {
  all_product(where: {AND: [{title: "Redmi Note 3"}, {color: "Gold"}]}) {
    items {
      title
      price_in_usd
      size
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’, ‘Size’, and ‘Price in USD’ fields.

Try 'AND' Operator

AND Operator within Group

Get entries that satisfy all the conditions provided in the AND query. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have fields named Card Type and Discount in Percentage. If, for instance, you want to retrieve the entries wherein the value for Card Type is ‘Credit Card’ and ‘Discount in Percentage’ is '12', your query will look as follows:

query {
  all_product(where: {AND: [
    {bank_offers: {card_type: "Credit Card"}},
    {bank_offers: {discount_in_percentage: 12}}
  ]}) {
    items {
      title
      price_in_usd
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Price in USD’ fields.

Try 'AND' Operator within Group

AND Operator within Modular Blocks

Get entries that satisfy all the conditions provided in the AND query. This query uses inline fragments to retrieve values of fields that lie within a particular block of a Modular Blocks field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Deals and Rating blocks. And, within the Deals and Rating blocks, we have the Deal Name and Stars fields, respectively. If, for instance, you want to retrieve the entries wherein the values for Deal Name and Stars fields are ‘Christmas Deal’ and '2', respectively, your query will look as follows:

query {
  all_product(where: {AND: [{additional_info: {deals: {deal_name: "Christmas Deal"}}}, {additional_info: {rating: {stars: 2}}}]}) {
    items {
      additional_info {
        ...RelatedProducts
      }
    }
  }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
      products {
        title
      }
    }
  }
  ... on ProductAdditionalInfoRating {
    rating {
      stars
    }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'AND' Operator within Modular Blocks

OR Operator

Get all entries that satisfy at least one of the given conditions provided in the 'OR' query.

Example: Let’s say you want to retrieve entries in which either the value for the Color field is 'Gold' or 'Black', your query will look as follows:

query {
  all_product(where: {OR: [
    {color: "Black"},
    {color: "Gold"}
  ]}) {
    items {
      title
      price_in_usd
      brand
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’, ‘Brand’, and ‘Price in USD’ fields.

Try 'OR' Operator

OR Operator within Group

Get all entries that satisfy at least one of the given conditions provided in the OR query. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have a field named Card Type. If, for instance, you want to retrieve the entries where either the value for Card Type is ‘Debit Card’ or ‘Credit Card’, your query will look as follows:

query {
  all_product(where: {OR: [
    {bank_offers: {card_type: "Credit Card"}},
    {bank_offers: {card_type: "Debit Card"}}
  ]}) {
        items {
          title
          price_in_usd
          color
        }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’, ‘Color’, and ‘Price in USD’ fields.

Try 'OR' Operator within Group

OR Operator within Modular Blocks

Get all entries that satisfy at least one of the given conditions provided in the OR query. This query uses inline fragments to retrieve values of fields that are part of any block within a Modular Block field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Deals and Rating blocks. And, within the Deals and Rating blocks, we have the Deal Name and Stars fields, respectively. If, for instance, you want to retrieve the entries wherein either the value for Deal Name is ‘Christmas Deal’ and Stars is '2', respectively, your query will look as follows:

query {
  all_product(where: {OR: [{additional_info: {deals: {deal_name: "Christmas Deal"}}}, {additional_info: {rating: {stars: 2}}}]}) {
    items {
      additional_info {
        ...RelatedProducts
      }
    }
  }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
      products {
        title
      }
    }
  }
  ... on ProductAdditionalInfoRating {
    rating {
      stars
    }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'OR' Operator within Modular Blocks

Less Than Operator

Get entries in which the value of a field is lesser than the value provided in the condition.

Example: Let’s say you want to retrieve all the entries that have the value of the Price in USD field set to a value that is less than but not equal to 150. Your query will look as follows:

query {
  all_product(where: {price_in_usd_lt: 150}) {
    items {
      title
      price_in_usd
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Price in USD’ fields.

Try 'Less Than' Operator

Less Than Operator within Group

Get entries in which the value of a field is lesser than the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have a subfield named Discount in Percentage. If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field is less than ‘40’, your query will look as follows:

query {
  all_product(where: {bank_offers: {discount_in_percentage_lt: 40}}) {
    items {
      title
      color
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Color’ fields.

Try 'Less Than' Operator within Group

Less Than Operator within Modular Blocks

Get entries in which the value of a field is lesser than the value provided in the condition. This query uses inline fragments to retrieve values of fields that are part of any block within a Modular Block field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Rating block. And, within this Block field, we have a field named Stars. If, for instance, you want to retrieve the entries in which the value for the Stars field is less than ‘3’, your query will look as follows:

query {
  all_product(where: {additional_info: {rating: {stars_lt: 3}}}) {
    items {
      additional_info {
        ...RelatedProducts
      }
    }
  }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
      products {
        title
      }
    }
  }
  ... on ProductAdditionalInfoRating {
    rating {
      stars
    }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'Less Than' Operator within Modular Blocks

Less Than Or Equal To Operator

Get entries in which the value of a field is lesser than or equal to the value provided in the condition.

Example: Let’s say you want to retrieve all the entries that have the value of the Price in USD field set to a value that is less than or equal to 150. Your query will look as follows:

query {
  all_product(where: {price_in_usd_lte: 150}) {
    items {
      title
      price_in_usd
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Price in USD’ fields.

Try 'Less Than Or Equal To' Operator

Less Than Or Equal To Operator within Group

Get entries in which the value of a field is lesser than or equal to the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have a subfield named Discount in Percentage. If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field are less than or equal to ‘30’, your query will look as follows:

query {
  all_product(where: {bank_offers: {discount_in_percentage_lte: 30}}) {
    items {
      title
      color
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Color’ fields.

Try 'Less Than Or Equal To' Operator within Group

Less Than Or Equal To Operator within Modular Blocks

Get entries in which the value of a field is lesser than or equal to the value provided in the condition. This query uses inline fragments to retrieve values of fields that are part of any block within a Modular Block field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Rating block. And, within this Rating block, we have a field named Stars. If, for instance, you want to retrieve the entries in which the values for the Stars field are less than or equal to ‘3’, your query will look as follows:

query {
  all_product(where: {additional_info: {rating: {stars_lte: 3}}}) {
    items {
      additional_info {
        ...RelatedProducts
      }
    }
  }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
      products {
        title
      }
    }
  }
  ... on ProductAdditionalInfoRating {
    rating {
      stars
    }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'Less Than Or Equal To' Operator within Modular Blocks

Greater Than Operator

Get entries in which the value for a field is greater than the value provided in the condition.

Example: Let’s say you want to retrieve all the entries that have the value of the Price in USD field set to a value that is greater than 180. Your query will look as follows:

query {
  all_product(where: {price_in_usd_gt: 180}) {
    items {
      title
      price_in_usd
      color
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’, ‘Price in USD’, and ‘Color’ fields.

Try 'Greater Than' Operator

Greater Than Operator within Group

Get entries in which the value for a field is greater than the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have a subfield named Discount in Percentage. If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field is greater than ‘20’, your query will look as follows:

query {
  all_product(where: {bank_offers: {discount_in_percentage_gt: 20}}) {
    items {
      title
      color
      price_in_usd
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’, ‘Price in USD’, and ‘Color’ fields.

Try 'Greater Than' Operator within Group

Greater Than Operator within Modular Blocks

Get entries in which the value for a field is greater than the value provided in the condition. This query uses inline fragments to retrieve values of fields that are part of any block within a Modular Block field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Rating block. And, within this Block field, we have a field named Stars. If, for instance, you want to retrieve the entries in which the values for the Stars field are greater than ‘3’, your query will look as follows:

query {
  all_product(where: {additional_info: {rating: {stars_gt: 3}}}) {
    items {
      additional_info {
        ...RelatedProducts
      }
    }
  }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
      products {
        title
      }
    }
  }
  ... on ProductAdditionalInfoRating {
    rating {
      stars
    }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'Greater Than' Operator within Modular Blocks

Greater Than Or Equal To Operator

Get entries in which the value of a field is greater than or equal to the value provided in the condition.

Example: Let’s say you want to retrieve all the entries that have the value of the Price in USD field set to a value that is greater than or equal to 200. Your query will look as follows:

query {
  all_product(where: {price_in_usd_gte: 200}) {
    items {
      title
      price_in_usd
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Price in USD’ fields.

Try 'Greater Than Or Equal To' Operator

Greater Than Or Equal To Operator within Group

Get entries in which the value of a field is greater than or equal to the value provided in the condition. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have a subfield named Discount in Percentage. If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field is greater than or equal to ‘30’, your query will look as follows:

query {
  all_product(where: {bank_offers: {discount_in_percentage_gte: 30}}) {
    items {
      title
      price_in_usd
    }
  }
}

The response body of this query will include all entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Price in USD’ fields.

Try 'Greater Than Or Equal To' Operator within Group

Greater Than Or Equal To Operator within Modular Blocks

Get entries in which the value of a field is greater than or equal to the value provided in the condition. This query uses inline fragments to retrieve values of fields that are part of any block within a Modular Block field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Rating block. And, within this Rating block, we have a field named Stars. If, for instance, you want to retrieve the entries in which the values for the Stars field are greater than or equal to ‘3’, your query will look as follows:

query {
  all_product(where: {additional_info: {rating: {stars_gte: 3}}}) {
    items {
      additional_info {
        ...RelatedProducts
      }
    }
  }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
      products {
        title
      }
    }
  }
  ... on ProductAdditionalInfoRating {
    rating {
      stars
    }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will include details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'Greater Than Or Equal To' Operator within Modular Blocks

Limit Operator

The limit parameter will return a specific number of entries in the output. So for example, if the content type contains more than 100 entries and you wish to fetch only the first 2 entries, you need to specify '2' as the value in this parameter. Your query will look as follows:

query {
  all_product(limit: 2) {
    items {
      title
      description
    }
  }
}

The response body of this query will include only the first two entries of the Product content type that satisfy the query, and will include details of just the ‘Title’ and ‘Description’ fields.

Try 'Limit' Operator

Skip Operator

The skip parameter will skip a specific number of entries in the output. So, for example, if the content type contains around 12 entries and you want to skip the first 5 entries to get only the last 7 in the response body, you need to specify ‘5’ here. Your query will look as follows:

query {
  all_product(skip: 5) {
    items {
      title
      color
    }
  }
}

The response body of this query will skip the first five entries and only include the last seven entries of the Product content type that satisfy the query, displaying details of just the ‘Title’ and ‘Color’ fields.

Try 'Skip' Operator

Order by Asc Operator

When fetching entries, you can sort them in the ascending order with respect to the value of a specific top-level field in the response body.

Note: The ‘Order by Asc’ operator cannot be used on nested fields (fields of ‘Group’ or ‘Modular Blocks’), fields that are marked as ‘Multiple’, or fields that accept chunks of data (‘Rich Text Editor’, ‘Multi Line Textbox’, and ‘Markdown’). It is also not applicable on ‘Reference’ fields.

Example: In the Product content type, if you wish to sort the entries with respect to their titles, your query will look as follows:

query {
  all_product(order_by: [title_ASC]) {
    items {
      title
      price_in_usd
      color
    }
  }
}

The response body of this query will display all the entries of the Product content type that satisfy the query in an ascending order, including details of just the ‘Title’, ‘Color’, and ‘Price in USD’ fields.

Try 'Order by Asc' Operator

Order by Desc Operator

When fetching entries, you can sort them in the descending order with respect to the value of a specific top-level field in the response body.

Note: The ‘Order by Desc’ operator cannot be used on nested fields (fields of ‘Group’ or ‘Modular Blocks’), fields that are marked as ‘Multiple’, or fields that accept chunks of data (‘Rich Text Editor’, ‘Multi Line Textbox’, and ‘Markdown’). It is also not applicable on ‘Reference’ fields.

Example: In the Product content type, if you wish to sort the entries with respect to the value of their Title fields, your query will look as follows:

query {
  all_product(order_by: [title_DESC]) {
    items {
      title
      price_in_usd
    }
  }
}

The response body of this query will display all the entries of the Product content type that satisfy the query in a descending order, including details of just the ‘Title’ and ‘Price in USD’ fields.

Try 'Order by Desc' Operator

Exists Operator

Get entries if the value of the field mentioned in the condition exists.

Example: In the Product content type, we have a field named Price in USD. If, for instance, you want to retrieve all the entries in the content type in which the field exists, your query will look as follows:

query {
  all_product(where: {price_in_usd_exists: true}) {
    items {
      title
      color
    }
  }
}

The response body of this query will display all the entries of the Product content type that satisfy the query, including details of just the ‘Title’ and ‘Color’ fields.

Try 'Exists' Operator

Exists Operator within Group

Get entries if the value of the field mentioned in the condition exists. This query is specifically for fields that are part of the Group field.

Example: In the Product content type, we have a Group field named Bank Offers. And, within this Group field, we have a subfield named Discount in Percentage. If, for instance, you want to retrieve the entries in which the values for the Discount in Percentage field exists, your query will look as follows:

query {
  all_product(where: {bank_offers: {discount_in_percentage_exists: true}}) {
    items {
      title
      color
      description
    }
  }
}

The response body of this query will display all the entries of the Product content type that satisfy the query, including details of just the ‘Title’, ‘Color’, and ‘Description’ fields.

Try 'Exists' Operator within Group

Exists Operator within Modular Blocks

Get entries if value of the field mentioned in the condition exists. This query uses inline fragments to retrieve values of fields that are part of any block within a Modular Block field.

Example: In the Product content type, we have a Modular Group field named Additional Info that contains the Deals block. And, within this Block field, we have a field named Deal Name. If, for instance, you want to retrieve the entries in which the value for the Stars field exists, your query will look as follows:

query {
  all_product(where: {additional_info: {rating: {stars_exists: true}}}) {
    items {
      additional_info {
        ...RelatedProducts
      }
    }
  }
}

fragment RelatedProducts on ProductAdditionalInfo {
  ... on ProductAdditionalInfoRelatedProducts {
    related_products {
      products {
        title
      }
    }
  }
  ... on ProductAdditionalInfoRating {
    rating {
      stars
    }
  }
  ... on ProductAdditionalInfoDeals {
    deals {
      deal_name
      deal_details
    }
  }
}

The response body of this query will display details of the ‘Deal Name’ and ‘Deal Details’ fields of the ‘Deals’ block.

Try 'Exists' Operator within Modular Blocks

Total

The total field returns the number of entries for a specified content type.

Example: If you wish to know the total number of entries in the Product content type that contain a value within the Price in USD field, you need to run the following query:

query {
  all_product(where: {price_in_usd_exists: true}) {
    total
    items {
      title
      price_in_usd
    }
  }
}

The total field will display the number of entries where the ‘Price in USD’ field exists for a product within the response body, including details of just the ‘Title’ and ‘Price in USD’ fields.

Try 'Total' Function

Pagination

When fetching all the entries of a particular content type, the GraphQL API allows you to provide arguments that paginate the response body.

If you have more than 100 items in your response, you can get the rest of the items in batches using the skip parameter in subsequent requests. To paginate the output of the request, you can use the limit parameter.

Example: In the Product content type, we have a field named Price in USD. Now, you want to retrieve all the entries in the content type in which the field exists.

If you get more than 100 items, you can get the rest of the items in batches using the skip: 2 parameter in subsequent requests. You can paginate the output of the request by using the limit parameter. So, instead of getting all the 100 items at once, use limit: 7 to get 7 items per page.

The pagination query will look as follows:

query {
  all_product(limit: 7, skip: 2) {
    total
    items {
      title
      price_in_usd
    }
  }
}

The total field will display the number of entries where the ‘Price in USD’ field exists for a product within the response body, including details of just the ‘Title’, ‘Brand’, and ‘Price in USD’ fields. However, through the use of the skip and limit parameters, the response body will now only show the first seven matching entries initially.

Try "Pagination"

Image Transformations

You can use the parameters of Contentstack’s Image Delivery API in GraphQL queries to transform images while fetching them.

The following table consists of the different parameters that Contentstack GraphQL supports for image delivery, along with their acceptable values:

ParameterSupported Values
auto
  • WEBP
width
  • String
height
  • String
disable
  • UPSCALE
format
  • GIF
  • PNG
  • JPG
  • PJPG
  • WEBP
  • WEBPLL
  • WEBPLY
fit
  • BOUNDS
  • CROP
quality
  • Integer
crop
  • String
trim
  • String
orient
  • DEFAULT
  • HORIZONTALLY
  • BOTH
  • VERTICALLY
  • ROTATE90LEFT
  • ROTATE90RIGHT
overlay
  • String
overlay_align
  • TOP
  • BOTTOM
  • LEFT
  • RIGHT
  • MIDDLE
  • CENTER
overlay_repeat
  • X
  • Y
  • BOTH
overlay_width
  • String
overlay_height
  • String
pad
  • String
bg_color
  • String
dpr
  • String
disposition
  • ATTACHMENT
  • INLINE

Let us look at a few simple and complex examples to understand how Contentstack’s Image Delivery parameters work with GraphQL queries to transform images.

Using a Single Parameter

Let’s get started by using a single format parameter to understand how these parameters function.

To convert an image placed on your Contenstack website from one format to another, use the format parameter. For example, we have set the format parameter to GIF in the following image transformation query.

query {
  all_assets(limit: 100) {
    total
    items {
        title
            url(transform: {format: GIF})
    }
  }
}

This query will convert the current image format to a GIF format.

Try 'Format' Parameter

Using Multiple Parameters

Let’s look at a few sample GraphQL queries that make use of multiple parameters.

Changing the Width and Height

To dynamically resize the width and height of your output image, use the width and height parameters. For example, we have set the values of the width and height parameters to ‘650’ and ‘400’, respectively, in the following image transformation query.

query {
  all_assets(limit: 100) {
    total
    items {
        title
      url(transform: {width: "650", height: "400", disable: UPSCALE})
    }
  }
}

This query will render an output image with width and height values of 650 and 400 pixels, respectively.

Note: We have also set the disable parameter to UPSCALE to disable the upscale image feature for the output image in the above image transformation query.

Try 'Width' and 'Height' Parameters

Using the Overlay and Overlay Align Parameters

To place one image on top of another, use the overlay parameter. In addition, use the overlay_align parameter to define the position of the overlay image.

For example, we have specified the value of the overlay parameter as the URL of the image to be placed on top. We have also set the value of the overlay_align parameter as ‘LEFT’ in the following image transformation query.

query {
  all_assets(limit: 100) {
    total
    items {
        title
      url(transform: {overlay: "/v3/assets/blteae40eb499811073/bltb21dacdd20d0e24c/59e0c401462a293417405f34/download", overlay_align: LEFT})
    }
  }
}

This query will place the image lying at the specified URL on top of the original image. It will also align the overlay image toward the left side of the original image.

Try 'Overlay' and 'Overlay Align' Parameters

Limitations

There are certain limitations that we have applied for Contentstack GraphQL. Let’s understand what they are:

  • You can fetch a maximum of 100 items (entries and/or assets) in a single GraphQL query.
  • The ‘Order by’ operator cannot be used on nested fields (fields of ‘Group’ or ‘Modular Blocks’), fields that are marked as ‘Multiple’, or fields that accept chunks of data (‘Rich Text Editor’, ‘Multi Line Textbox’, and ‘Markdown’). It is also not applicable on ‘Reference’ fields.
  • You can only query referenced entries up to five levels of nested reference.
  • If your content type UIDs and field UIDs start with a number, you won't be able to run any GraphQL queries.
  • GraphQL only creates introspection schema for the first 100 content types on the explorer.
  • GraphQL does not support fields with dynamic datatypes, such as JSON datatype (prebuilt extension).

Change Log

March 29, 2019 - GraphQL Alpha 2

  • Contentstack GraphQL API now allows you to fetch fields of an entry based on asset data. To know more about this, refer the Get Entries by Referenced Asset section.
  • Contentstack GraphQL API now uses the same format that GraphQL deploys to show error messages. The following table displays the changes in the error specifications used in GraphQL Alpha 2:
    New error response Old error response
    {
      "errors": [
        {
          "message": "Failed to run query.",
          "extensions": {
            "errors": [
              {
                "api_key": [
                  "is not valid"
                ]
              }
            ],
            "statusCode": 412
          }
        }
      ]
    }
    {
      "errors": [
        {
          "api_key": [
            "is not valid"
          ]
        }
      ],
      "message": "Failed to run query"
    }

top-arrow