GraphQL Content Delivery API

[Beta]

Introduction

Base URL

For US region: https://graphql.contentstack.com

For European region: https://eu-graphql.contentstack.com

Overview

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

GraphQL is a flexible, customizable API query language. Contentstack’s GraphQL API gives you the power to query for exactly what you need and nothing more, for instance, you can even fetch data from multiple content types via a single API request. You can customize your responses by defining the structure of your requests. Currently, Contentstack GraphQL supports only queries and each requested resource’s GraphQL types are generated in real time, so your content remains current.

Note: Contentstack's GraphQL API does not support mutations and subscriptions.

If you are familiar with GraphQL, and want to get a hands-on experience of the API, here’s a quick link to our sample stack:

Query our sample stack

Note: The Contentstack GraphQL API is currently available in Beta version. Go through the Change Log to understand what has changed from the previous GraphQL Alpha version.

Authentication

GraphQL API requests must be authenticated using the following details:

  • Stack API key
  • Environment
  • Delivery token of the concerned environment

You need to pass the stack API Key in the URL and the publishing environment as a query parameter. Use the value of the delivery token against the access_token key in the header to authenticate your API 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.

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 3 requests per second per organization.

API Conventions

  • The Contentstack GraphQL Content Delivery API is available at the following endpoint for the United States (US) region:
    https://graphql.contentstack.com/stacks/{stack_api_key}?environment={environment_name}
    You can use this endpoint to fetch content from Contentstack. Pass the delivery token of the concerned environment in the header while making an API request:
    access_token: "{delivery_token}"
  • For the European region, the domain name changes to:
    eu-graphql.contentstack.com
  • 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.

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/blt95a0a7afb9613f51?environment=production&query={all_product(where: {title: Galaxy Note}) { items { title description } } }

Within this API request, we state the stack API key and the publishing environment, followed by your query. The delivery token is passed as value of the access_token key in the header.

Introspection

Introspection system offers the ability to introspect what type of queries can run on the generated GraphQL schema. It provides a detailed description of the different object types that can be fetched from the schema.

For example, each content type in your stack has a corresponding GraphQL type and name. The introspection system would help you understand what fields can be queried, the arguments supported by those fields, and what output types can be returned by them.

We recommend that you structure your GraphQL queries by referring to the introspection schema. To explore the introspection schema, you can use Contentstack’s GraphiQL explorer.

You can also paginate the response schema returned by the Introspection system by passing the skip and limit parameters in the query. By default, the content types in the schema are sorted based on title_ASC and cannot be modified.

Note: The 'Asset' GraphQL type will not be available in the subsequent paginated Introspection queries.

GraphiQL Explorer

Contentstack’s GraphiQL explorer allows you to explore the GraphQL Content Delivery API. You can structure your GraphQL queries based on the available schema and test them out.

The GraphiQL explorer provides information about the content types and fields that are part of the schema.

GraphiQL_Explorer.png

 You can also enter your own stack details and the required parameters in the GraphiQL Explorer to try out the API.

Postman Collection

About Contentstack Postman Collection

The Contentstack Postman collection is a set of preconfigured RESTful and GraphQL API requests that will make it easy for you to get started with the Contentstack APIs and try out our API requests through the popular Postman REST client.

Install Postman

To use the Contentstack Postman collection you will need to have the Postman desktop app installed on your device.

Note: If you have already installed Postman for your device, go to the Download Latest Postman Collection for Contentstack section.

Postman is available for Windows (x32), Windows (x64), Mac, and Linux environments.

Download Latest Collection

Once you have installed Postman for your device, click on the following button to download and install our latest Postman collection that covers all the GraphQL Content Delivery API endpoints for Contentstack.

Note: The Contentstack Postman collection does not support the now deprecated Postman Chrome extension. Make sure you have installed the latest version of the Postman desktop app.

After selecting the appropriate variant of Postman, the collection will open the Postman app and appear in the left pane:

graphQL.png

Download Collection from GitHub Page

We have also hosted our Postman collection on GitHub. You can follow the steps mentioned in the Readme file to download and start using it.

You can also choose to watch the latest Postman collection to get notifications of new releases or updates.

To do so, click on the following Watch button and select Watching.

Configure Environment Variables

When you download and install the latest version of the GraphQL Content Delivery API Postman collection, you also download and import the respective environment along with the environment variables.

Once your environment is imported, next you need to set your Contentstack account specific values.

Note: As these environment variables are referenced across multiple API requests, once you set the variables, it becomes a lot more convenient to make repeated use of the Postman collection.

Some of the important variables that you need to set are as follows:

Environment Variable Value
base_url graphql.contentstack.com
api_key your_stack_api_key
access_token your_environment-specific_delivery_token

Note: The Contentstack Postman collection will require a valid environment-specific Delivery token to make API calls. Check out the Authentication section for more details.

If you want to add your own environment variables, you can follow the procedure in the next section.

Add Other Environment Variables

To add any new environment variables for your Postman collection, perform the following steps:

  1. Identify the environment variables that you want to define.
  2. In the top right corner of Postman, click on the “Manage Environments” settings cog.
    settings-cog-graphql.png
  3. Click on your environment GraphQL API - Environment.
  4. In the VARIABLE field, enter the name of the environment variable.
    In the INITIAL VALUE field, enter your Contentstack-account-specific value that will replace the variable when the call is made.
    manage-env-graphql.png
  5. Once you have defined your variables, click on Update.

Update Environment Variables

With every new API request added, we update our environment file. So, to get the latest environment variables, you need to download the collection along with the updated environment file again, compare your existing environment with the latest environment, identify and add the new variables to your existing environment.

Next, let’s see how you can run API Requests from your Contentstack Postman collection using your environment.

Make an API Request

With the Contentstack Postman Collection loaded into the Postman app (on the left pane) and the environment created, you can now make API requests to the Contentstack API via Postman.

To make an API request, perform the following steps:

  1. Select the respective environment, GraphQL API - Environment, from the dropdown.
  2. Select an API Request from the Contentstack Postman Collection. In this example, we will use the Get Specific Fields of Multiple Entries request which is a part of the Retrieving Entries folder.

    Note: If you want to make changes to your parameters or want to add parameters of your own, you can do it here.

  3. Next, click on Send at the top right to make the API request.
    run-graphql-call.png

The API call should return with a response under the Body tab in the bottom half of the screen.

api-response-graphql.png

Understand a GraphQL query

A GraphQL query is a combination of three parts: Operation Type, Arguments, and Fields.

Let’s understand a GraphQL query with an example. You have an entry titled “Galaxy Note”. Now instead of getting whole details of that entry, you can retrieve the details of only the “title” and “descriptions” fields.

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

This query defines the following parts:

  • Operation Type: Indicates the type of operation that you want to perform.In this case, query is the Operation Type
  • Arguments: The (where: {title: "Galaxy Note"}) is an argument passed to get an entry whose title is “Galaxy Note”
  • Fields: The title and description are the fields whose details you want to retrieve

Secure API Keys and Tokens

We strongly advise against storing your API keys and tokens in your collection permanently. If you or someone else shares the collection by mistake, other users will be able to export it along with these keys.

We recommend that you provide your Contentstack account-specific API keys and tokens in your environment or directly to the sample requests.

Postman Collection Updates

We keep our Postman Collection updated. To get the latest version of our Postman Collection, all you need to do is to download the Postman Collection along with the updated environment again and you are good to go.

You can also choose to watch for the latest Postman Collection updates on our GitHub repository and get notifications of new releases or updates to the repository. The GitHub Readme doc will help you with the steps that you need to follow.

Reference

Retrieving Entries

In this section, we learn how to fetch one or more entries or specific fields of those entries. We also learn how to fetch entries from multiple content types.

Get Specific Fields of a Single 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 field UIDs in the query.

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

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

The “locale” parameter in the argument is optional but helps you narrow down your result as follows:

  • If you specify the locale, the request will fetch the content of only that locale.
  • If you do not specify a locale, it will fetch the content of the master locale.

Warning: 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 Multiple Entries

You can also pull up the values of specific fields for some or 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.

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

Get Entries from Multiple Content Types

You can retrieve entries of multiple content types through a single API request. Within the GraphQL query, you can also define the specific fields of which you need to fetch data.

Note: Contentstack’s GraphQL queries can fetch entries of up to three different content types through a single API request.

Example: So, for instance, our stack comprises the following content types: Product, Category, and Brand. Now, suppose you want to fetch values of the Title, Description, and Price_in_USD fields for every entry in the Product content type. Subsequently, you also wish to fetch the list of categories and brands available for the product. Your GraphQL query would look as follows:

query {
  all_product(
    locale: "en-us"
  ) {
    total
    items {
      title
      description
      price_in_usd
    }
  }
  all_category {
    total
    items {
      title
      description
    }
  }
  all_brand {
    total
    items {
      title
      description
    }
  }
}

The total parameter in the above query fetches the total number of entries available in each of the content types. It is an optional parameter.

Get Global Fields while Retrieving Entries

You can fetch data of only certain fields of a Global field that is referred within a specific entry of a content type. To do this, you need to specify the content type UID, the entry UID, the Global field UID, and the UIDs of the fields that are part of the Global field in the query. Read more about Global fields.

So, for instance, the Bank Address Global field has been referred to within the Bank content type. This Global field comprises the following fields:

  • House No
  • Street Name
  • Landmark
  • City

If you want to retrieve the entries in which the value for the Street Name field is Hollywood Boulevard, the query for this request would look as follows:

query {
  all_bank(
    where: {
      bank_address: {
        street_name:"Hollywood Boulevard"
      }
    }) {
    items {
      bank_address {
        house_no
        street_name
        landmark
        city
      }
    }
  }
}

Get Group Fields while Retrieving Entries

You can fetch data of only certain fields of a Group field that is used within a specific entry of a content type. To do this, you need to specify the content type UID, the entry UID, the Group field UID, and the UIDs of the fields that are part of the Group field in the query. Read more about Group fields.

So, for instance, the Product content type has a Group field named Bank Offers and, within this Group field, we have a subfield named Card Type. If you want to retrieve the entries in which the value for the Card Type field is Debit Card, the query for this request would look as follows:

query {
  all_product(
    where: {
      bank_offers: {
        card_type: "Debit Card"
      }
    }) {
    items {
      bank_offers {
        card_type
        discount_in_percentage
      }
    }
  }
}

Get Custom Fields while Retrieving Entries

You can fetch the data of Custom Field Extensions added to the entries of a content type. To do this, you need to specify the content type UID, the extension UID, and the UIDs of other fields that you want to fetch in the query.

Contentstack allows you to retrieve the details of custom fields with input datatypes such as Number, Text, Boolean, Date, File, Reference, and JSON. Read more about Extensions.

Example: In the Product content type, we have a "Star Rating" custom field named Product Rating. If, for instance, you want to retrieve the value for this field, your query will look as follows:

query {
  all_product {
    items {
      title
      product_rating
    }
  }
}

The response body of this query will include details of the ‘Product Rating’ custom field and the ‘Title’ field. The extension field data will be displayed in JSON format.

Retrieving Referenced Entries or Assets

In this section, we learn how to fetch one or more entries referred in the reference fields or assets used in the entries while retrieving the entries of a content type. To do this, Contentstack’s GraphQL API uses relay specification.

Relay specification measures the Reference-Graph-Object structure for an application. The data graph specifies the different connections that exist between each entity of the stack. The following entities form a part of the graph structure:

  • Node: A node represents an individual resource of the stack, for example, an entry, an asset, or a specific content type (e..g., Product).
  • Edges: Edges represent the connection between two content types, for instance, when a Product content type refers to the entries of another content type (e.g., Category).
  • Connection: Connection represents the one-to-many relationships between a parent content type and its referenced child content types. It allows you to paginate the referenced entries or assets returned in the response body using the skip and limit parameters.

You can only paginate the response returned for the referenced items items:

  • Referenced items (entries/assets)
  • Assets marked as “Multiple”

For instance, if you wish to view only the first three entries referenced by the Related Blogs reference field (multi content type referencing), then you can use the limit parameter in your query as follows:

{
  all_blogs {
    items {
      related_blogsConnection(limit: 3) {
        totalCount
        edges {
          node {
            ... on Blogs {
              title
            }
            ... on SalesBlogs {
              title
            }
            ... on MarketingBlogs {
              title
            }
          }
        }
      }
    }
  }
}

Tip: To fetch data for multi content type Reference fields through the node, the GraphQL API uses inline fragments.

Let us fetch reference fields and assets while retrieving entries.

Include Single Content Type Reference Fields

Get entries of a content type along with the comprehensive details of the specified referenced entry. This query uses relay specification to retrieve the details of the entries referred in reference fields.

Note: You can use the skip and limit parameters while querying Reference fields that refer to a single content type and have been marked as “Multiple”.

Example: In the Product content type, there is a reference field called Categories, which refers entries of another content type named Category.

Note: When you query reference fields that refer to content types other than the first 100 available, the query will return an error in the response body of the GraphQL API request. If referenced entries are not published or have been deleted, then the query will return { edges: [] }.

To fetch all entries of the “Product” content type along with the corresponding referenced entry from the “Category” content type, you can run the following query:

query {
  all_product {
    total
    items {
      title
      categoriesConnection {
        totalCount
        edges {
          node {
           ... on Category{
             title
           }
          }
        }
      }
    }
  }
}

The totalCount field returns the number of referenced entries for a specific Reference field.

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

Try 'Include Single Content Type Reference Fields'

Include Multi Content Type Reference Fields

Get entries of a content type along with the comprehensive details of the specified referenced entries. This query uses inline fragments and relay specification to retrieve details of entries referring to multiple content types.

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

Within the inline fragments section, you need to specify the name of the content type. Subsequently, you need to append the Connection term as postfix for the content type UID.

{reference_field_UID}Connection {
        totalCount
        edges {
          node {
            ... on {Referenced_Content_Type_Name_in_PascalCase} {
              {field_name}
            }
          }
        }
      }

The node specifies the referenced content types related to the parent content type.

Example: In the Product content type, we have a multi content type Reference field named Frequently Bought Together. This Reference field refers to entries of the following content types: Electronics and Kitchen Appliances.

So, for instance, if you need to fetch referenced entries from both content types, Electronics and Kitchen Appliances, your query will look as follows:

query {
  all_product {
    items {
      title
      frequently_bought_togetherConnection {
        edges {
          node {
            ... on KitchenAppliances {
              title
              kitchen_appliance_details
            }
            ... on Electronics {
              title
              appliance_details
            }
          }
        }
      }
    }
  }
}

Note: When you query reference fields that refer to content types other than the first 100 available, the response body will return an error. If referenced entries are not published or have been deleted, then the query will return { edges: [] }.

Try 'Include Multi Content Type Reference Fields'

Include Assets Added to a Content Type

Get entries of a content type along with the comprehensive details of an asset that has been used in the entries. This query uses relay specification to fetch asset details such as the title of an asset or its URL.

Specify the asset UID while retrieving the asset information. Subsequently, you need to append the Connection term to the asset UID as a postfix.

Note: You can use the limit pagination parameter only while querying assets that have been marked as “Multiple”.

Example: In the Product content type, you need to retrieve all entries along with comprehensive details of the image stored within the Images field. To fetch only the first five assets while retrieving the entries, use the limit parameter.

Your query will look as follows:

query {
  all_product {
    items {
      title
      imagesConnection(limit: 5) {
        edges {
          node {
            title
            description
          }
        }
      }
    }
  }
}

The response body of this query will include details of the ‘Title’ field of the Product content type and the ‘Title’ and ‘Description’ of the assets stored in the Images field. It will only return the first five assets.

Try 'Include Assets Added to a Content Type'

Search within Referenced Entries from a Single Content Type

Get entries having values based on referenced fields. This query retrieves all entries that satisfy query conditions made on referenced fields that refer to a single content type.

Let us use the equals operator to search based on the Title field of the 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
      categoriesConnection {
        edges {
          node {
            title
          }
        }
      }
    }
  }
}

The response body 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 'Search Referenced Entries from a Single Content Type'

Search within Referenced Entries from Multiple Content Types

Get entries having values based on referenced fields. This query uses inline fragments to retrieve all entries that satisfy query conditions made on referenced fields that refer to multiple content types.

Example: In the Product content type, we have a multi content type Reference field named Frequently Bought Together. This Reference field refers to entries of the following content types: Electronics and Kitchen Appliances.

Let us use the MATCH operator to search entries of the two referenced content types: Electronics and Kitchen Appliances on the basis of their Title field. The “Match” operator filters the entries to return only the entries that match the specified condition(s). You can enter the following values for the Match operator:

  • ALL: The ALL option returns only those entries that match all the conditions specified
  • ANY: The ANY option returns only those entries that match any one of the conditions specified

If you do not specify the MATCH operator, then the query uses the ALL option by default.

To fetch the referenced entries where the value of the Title field is one among the following: Sony Bravia LED Smart TV and Glenmark Cooktop, set the MATCH operator to ANY. Your query will appear as follows:

query {
  all_product(
    where: {
      frequently_bought_together: {
        MATCH: ANY,
        electronics: {
          title: "Sony Bravia LED Smart TV"
        },
        kitchen_appliances: {
          title: "Glenmark Cooktop"
        }
      }
    }) {
    items {
      title
      frequently_bought_togetherConnection {
        edges {
          node {
            ... on KitchenAppliances {
              title
              kitchen_appliance_details
            }
            ... on Electronics {
              title
              appliance_details
            }
          }
        }
      }
    }
  }
}

The response body will include all entries of the Electronics and Kitchen Appliances content types that satisfy the query, and will include details of just the “Title” field of these content types. 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 'Search Referenced Entries from Multiple Content Types'

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 referenced 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
      categoriesConnection {
        edges {
          node {
            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

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 {
      title
      additional_info {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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

Equals Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If, for instance, you want to retrieve certain fields of all the entries in which the value for the "Coupon Name" field is Lucky Twenty, your query will be formed as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_name: "Lucky Twenty"
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'Equals' Operator within Nested 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 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 NOT 'Summer Deal,' your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          deal_name_ne: "Summer Deal"
        }
      }
    }) {
    items {
      additional_info {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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

Not-equals Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If, for instance, you need to retrieve all entries where the value of the "Coupon Name" field is not equal to "Lucky Twenty", your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_name_ne: "Lucky Twenty"
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'Not Equals' Operator within Nested 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 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 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

In Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If, for instance, you need to retrieve all the entries where the value of the "Coupon Discount Rate" field is one among the given set of values, your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_discount_rate_in: [5, 20, 50]
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'In' Operator within Nested 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 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 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

Not In Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If, for instance, you need to retrieve the entries where the value of the "Coupon Discount Rate" field does not fall in the given set, your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_discount_rate_nin: [5, 20, 50]
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'Not In' Operator within Nested Modular Blocks

Search by Regex

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

Note: Contentstack’s GraphQL API only supports case-insensitive character patterns in its regular expressions (Regex).

In the where argument, you need to specify the following syntax for the regex expression:

where: {
      {field_uid}_regex: {
            pattern: "{regex_value}"
          }
    }

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: {
        pattern: "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: {
          pattern: "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 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 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: {
            pattern: "Sum"
          }
        }
      }
    }) {
    items {
      additional_info {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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

Search by Regex within Nested Modular Blocks

You can use inline fragments to search based on values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If, for instance, you want to retrieve all the entries within the Product content type that have values for the "Coupon Name" field starting with "Lucky", your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_name_regex: {
                pattern: "Lucky"
              }
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'Search by Regex' Operator within Nested 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 Blocks 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 {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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

AND Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If you want to retrieve entries in which the "Coupon Name" field is set to "Lucky Twenty" and the "Coupon Discount Rate" field is 20, your query will look as follows:

query {
  all_product(
    where: {
      AND: [
        {
          additional_info: {
            deals: {
              coupons: {
                daily_coupons: {
                  coupon_name: "Lucky Twenty"
                }
              }
            }
          }
        },
        {
          additional_info: {
            deals: {
              coupons: {
                daily_coupons: {
                  coupon_discount_rate: 20
                }
              }
            }
          }
        }
      ]
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'AND' Operator within Nested 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
      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

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 Blocks 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 {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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

OR Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If you want to retrieve the entries where either the value for "Coupon Name" is "Lucky Twenty" or "Early Bird Coupon", your query will look as follows:

query {
  all_product(
    where: {
      OR: [
        {
          additional_info: {
            deals: {
              coupons: {
                daily_coupons: {
                  coupon_name: "Lucky Twenty"
                }
              }
            }
          }
        },
        {
          additional_info: {
            deals: {
              coupons: {
                daily_coupons: {
                  coupon_name: "Early Bird Coupon"
                }
              }
            }
          }
        }
      ]
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'OR' Operator within Nested 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 Blocks 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 {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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 Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If you want to retrieve all the entries that have the value of the "Coupon Discount Rate" field set to a value that is less than but not equal to 40, your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_discount_rate_lt: 40
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'Less Than' Operator within Nested 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 Blocks 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 {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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

Less Than Or Equal To Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If you want to retrieve all the entries that have the value of the "Coupon Discount Rate" field set to a value that is less than or equal to 50, your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_discount_rate_lte: 50
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'Less Than Or Equal To' Operator within Nested 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 Blocks 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 {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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 Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If you want to retrieve all the entries that have the value of the "Coupon Discount Rate" field set to a value that is greater than 20, your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_discount_rate_gt: 20
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'Greater Than' Operator within Nested 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 Blocks field.

Example: In the Product content type, we have a Modular Blocks 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 {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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

Greater Than Or Equal To Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If you want to retrieve all the entries that have the value of the "Coupon Discount Rate" field set to a value that is greater than or equal to 20. Your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_discount_rate_gte: 20
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'Greater Than Or Equal To' Operator within Nested 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 the following system-defined fields in the response body:

  • Created at
  • Updated at

Note: The ‘Order by Asc’ operator can only be used on the ‘Created at’ and ‘Updated at’ system-defined fields. It is not applicable to any other fields.

Example: In the Product content type, if you wish to sort the entries with respect to the date specified in the ‘Created at’ field, your query will look as follows:

query {
  all_product(
    order_by: [
      created_at_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 the following system-defined fields in the response body:

  • Created at
  • Updated at

Note: The ‘Order by Desc’ operator can only be used on the ‘Created at’ and ‘Updated at’ system-defined fields. It is not applicable to any other fields.

Example: In the Product content type, if you wish to sort the entries with respect to the date specified in the ‘Updated at’ field, your query will look as follows:

query {
  all_product(
    order_by: [
      updated_at_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 Blocks 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 {
        ... on ProductAdditionalInfoRelatedProducts {
          related_products {
            productsConnection {
              edges {
                node {
                  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

Exists Operator within Nested Modular Blocks

You can use inline fragments to retrieve values of fields that lie within a particular block of a Nested Modular Blocks field. Within the inline fragments section, you need to specify the content type UID, modular blocks UID, block UID, nested modular blocks UID, and the nested block UID.

Example: In the Product content type, you have a Coupons Modular Blocks field that is nested within the Deals block of the Additional Info Modular Blocks field. The Coupons Modular Blocks field contains a Daily Coupons block:

... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
  daily_coupons {
    coupon_name
    coupon_details
    coupon_discount_rate
  }

If you want to retrieve all the entries in the Product content type in which the "Coupon Discount Rate" field exists, your query will look as follows:

query {
  all_product(
    where: {
      additional_info: {
        deals: {
          coupons: {
            daily_coupons: {
              coupon_discount_rate_exists: true
            }
          }
        }
      }
    }) {
    items {
      title
      additional_info {
        ... on ProductAdditionalInfoDeals {
          deals {
            deal_name
            deal_details
            coupons {
              ... on ProductAdditionalInfoDealsBlockCouponsDailyCoupons {
                daily_coupons {
                  coupon_name
                  coupon_details
                  coupon_discount_rate
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsFaqs {
                faqs {
                  coupon_faqs {
                    question
                    answer
                  }
                }
              }
              ... on ProductAdditionalInfoDealsBlockCouponsSpecialCoupons {
                special_coupons {
                  special_coupon_name
                  special_coupon_details
                  special_coupon_discount_rate
                }
              }
            }
          }
        }                
      }
    }
  }
}

The response body of this query will also include details of the fields that lie within the Coupons Nested Modular Blocks field.

Try 'Exists' Operator within Nested 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: 25) {
    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: 25) {
    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: 25) {
    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

Change Log

July 23, 2020

Deprecation
  • Access tokens should now be passed via the header and not in the query parameters of the API request. The new Contentstack GraphQL API endpoint will look as follows:
    https://graphql.contentstack.com/stacks/{stack_api_key}?environment={environment_name}
API Breaking Changes
  • You can no longer fetch Reference field data using the traditional Reference UID based syntax. Contentstack GraphQL API now uses relay specification logic to traverse through the schema of a Reference field.

    The change in the Reference field syntax is as follows:
    Reference Field Type Old New
    Single Content Type Referencing
    query {
      all_product {
        total
        items {
          categories {
            title
          }
        }
      }
    }
    
    query {
      all_product {
        total
        items {
          categoriesConnection {
            totalCount
            edges {
              node {
                title
              }
            }
          }
        }
      }
    }
    
    Multiple Content Type Referencing
    query {
      all_product {
        items {
          home_appliances {
            ... on Electronics {
              title
              appliance_details
            }
            ... on KitchenAppliances {
              title
              kitchen_appliance_details
            }
          }
        }
      }
    }
    
    query {
      all_product {
        items {
          home_appliancesConnection {
            edges {
              node {
                ... on Electronics {
                  title
                  appliance_details
                }
                ... on KitchenAppliances {
                  title
                  kitchen_appliance_details
                }
              }
            }
          }
        }
      }
    }
    

    Note: If a Reference field with an old query schema is marked as “Multiple”, then you will be able to use the limit parameter to paginate the response returned by this field.

  • You can no longer fetch asset information by specifying the asset UID in the query. Contentstack’s GraphQL API now uses relay specification to fetch asset data.

    The change in the syntax is as follows:
    Old New
    query {
      all_product {
        items {
          title
          images {
            title
            description
          }
        }
      }
    }
    
    query {
      all_product {
        items {
          title
          imagesConnection {
            edges {
              node {
                title
                description
              }
            }
          }
        }
      }
    }
    

    Note: You can use the skip and limit parameters while querying assets that have been marked as “Multiple”.

  • The error messages now provide comprehensive information that helps debug the errors efficiently. Read more about Errors in GraphQL.
  • After this release, you will be able to fetch only 25 items (entries/assets) from the root-level content types by default. For more information, contact our Support team.
  • Changes in the GraphQL definition:
    • The “Where” condition type for Global fields, Group fields, and Modular Blocks fields has changed from ‘{NestedFieldUid}Filter’ to ‘{NestedFieldUid}Where’
    • The ‘Assets’ type has changed to ‘Asset’
    • The ‘{ContentTypeUID}.system._content_type_uid’ type has changed to ‘{ContentTypeUID}.system.content_type_uid’
    • The ‘Asset.system._content_type_uid’ system field previously returned ‘built_io_upload’, but will now return ‘sys_assets’
    • The GraphQL scalar type for Date fields has changed from 'ISODate' to 'DateTime' 
  • Contentstack GraphQL API changed the syntax for the regular expressions it uses to filter out results of a query. The change in the syntax for regex queries is as follows:
    Old syntax New syntax
    where: {
          field_uid_regex: "regex_value"
        }
    
    where: {
          field_uid_regex: {
            pattern: "regex_value"
          }
        }
    
  • You can no longer use the ‘Order by Asc’ and ‘Order by Desc’ operators on any top-level fields. After this release, you will be able to use these operators only on the following system-generated fields:
    • Created at
    • Updated at

January 24, 2020 - GraphQL Alpha 3

The following types of referenced entries will no longer return comprehensive details in the response body of their GraphQL API requests:

  • Referenced entries that have been deleted
  • Referenced entries that are not published
  • Referenced entries that refer to content types other than the first 100 available

If the Reference field has been marked as "Multiple", then the query will return an empty array. While, a Reference field of the type "Single" will be returned as null.

So, for instance, the "Branches" Reference field is of "Single" type while the "Managers" Reference field has been marked as "Multiple". While fetching references, unpublished (draft) or deleted referenced entries OR referenced entries whose content types have failed to load (100 content types limit) will no longer appear in the API response body.

The following table displays the changes in the API response body:

Old Response BodyNew response body
{
    "items": [
        {
            "branches": ["bltxyz1232bamln"],
            "managers": ["bltxyz1232bamln", "bltbacc1232bamln"]
        }
    ]
}
{
    "items": [
        {
            "branches": null,
            "managers": []
        }
    ]
}

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:
    Old error response New error response
    {
      "errors": [
        {
          "api_key": [
            "is not valid"
          ]
        }
      ],
      "message": "Failed to run query"
    }
    
    {
      "errors": [
        {
          "message": "Failed to run query.",
          "extensions": {
            "errors": [
              {
                "api_key": [
                  "is not valid"
                ]
              }
            ],
            "statusCode": 412
          }
        }
      ]
    }
    

Query Complexity

Query complexity is the total number of entries and/or assets that can be retrieved through a single GraphQL API request. Contentstack sets limits on query complexity to enable safer query execution over its GraphQL Content Delivery API. At a time, a query can fetch a maximum of 10,000 items in its response.

Let us try to calculate query complexity for the following GraphQL query.

query {
  all_blogs(limit:100) {
    items {
      related_blogsConnection(limit: 5) {
        totalCount
        edges {
          node {
            ... on Blogs {
              title
            }
          }
        }
      }
    }
  }
}

The above query can retrieve up to 100 blog posts and up to 500 related articles, i.e. up to 5 related articles for each of the 100 blog posts.

The query complexity is 600.

Let us look at another complex query to understand how a maximum limit of 10,000 helps avoid extremely complex and abusive API requests to Contentstack’s servers.

{
  all_blogs(limit:100) {
    items {
      related_blogsConnection(limit:100) {
        totalCount
        edges {
          node {
            ... on Blogs {
              title
            }
          }
        }
      }
    }
  }
}

The above query can retrieve up to 100 blog posts and up to 10,000 related articles, i.e. up to 100 related articles for each of the 100 blog posts. The query complexity is 10,100. Such a complex query can result in overload on the database server.

Contentstack’s GraphQL Content Delivery API calculates the complexity value for a query through the x-query-complexity response header. When a query exceeds the set query complexity limit (10,000), the API returns a MAX_DOCUMENT_LIMIT_EXCEEDED error.

Response Headers

Contentstack returns response headers to specify information about the status of an API request. These headers also contain details about other objects that you are retrieving through the API.

Let’s learn about these response headers and what to infer from the possible values that you may get.

x-api-key

This header provides the API Key of the stack that you are trying to access. The API Key can be used to authorize GraphQL API requests.

The possible values for this header can be of string datatype, for example, blt7263876d7362.

x-contentstack-organization

This header provides the Organization ID of the organization to which the stack that you are trying to access belongs.

The possible values for this header can be of string datatype, for example, blt72663654f6532.

x-query-complexity

This header calculates the complexity value for each API request made to the Contentstack database server. It represents the total number of entries and/or assets that were retrieved from the server by a specific GraphQL API request. Read more about it in the Query Complexity section.

x-reference-depth

This header specifies the depth up to which a specific GraphQL query traverses to retrieve nested items (entries and/or assets).

x-runtime

This response header specifies the time (in milliseconds) that Contentstack takes to process a single GraphQL API request.

The x-runtime header is an integer value specified in the milliseconds unit of time, e.g., 15 ms.

Errors in GraphQL

Contentstack returns comprehensive error responses when a GraphQL API request fails to execute.

The “code” key in the error message provides a unique identity that highlights the main reason for partial or complete failure of the API request.The error responses also contain an additional key named “details”, which provides specific hints related to the entity causing the error. These hints also include requests to debug the GraphQL schema and check for possible discrepancies.

Let us look at the different keys that are returned within the error description:

  • code: Distinct identifier that highlights the main reason for partial or complete failure
  • message: Human-readable text message that describes the error
  • details: Specific hints to help debug the error

The following syntax represents an API error response:

{
    "errors": [
        {
            "message": "Failed to run query.",
            "extensions": {
                "errors": [
                    {
                        "code": "error_code",
                        "message": "Message.",
                        "details": {
                            "hint": "Hint to resolve the issue."
                        }
                    }
                ]               
            }
        }
    ]
}

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

HTTP Status Code Error Message
412 Message
{
  code: 'MISSING_API_KEY',

  message: `The api_key is required.`,

  details: {

    hint: "The url pattern should be '/stacks/{stack_api_key}?environment={env_name}'."

  }

}
Description
The request URL does not contain the stack API Key.
412 Message
{
  code: 'MISSING_ACCESS_TOKEN',
  message: `The access_token is required.`,
  details: {
    hint: "Pass the access_token in the headers 'access_token: {access_token}'."
  }
}
Description
The value of the access_token key is not provided in the request.
412 Message
{
  code: 'MISSING_ENVIRONMENT',
  message: `The environment query parameter is required.`,
  details: {
    hint: "The url pattern should be '/stacks/{stack_api_key}?environment={env_name}'."
  }
}
Description
The publishing environment has not been passed as a query parameter.
401 Message
{
  "code": "AUTHENTICATION_FAILURE",
  "message": "The api_key, access_token or environment is not valid.",
  "details": {
    "hint": "The url pattern should be '/stacks/{stack_api_key}?environment={env_name}'. Pass 'access_token' via the headers."
  }
}
Description
Any or a combination of the following entered parameters are invalid:
  • API key of the stack (authentication parameter)
  • Delivery token passed as value of the access_token key (header)
  • Publishing environment (query parameter)
500 Message
{
  "code":"UPGRADE_PLAN",
  "message":"The organization does not have GraphQL enabled.",
  "details":{
    "hint":"Kindly contact 'support@contentstack.com' to upgrade your plan."
  }
}
Description
This error message is returned for the following scenarios:
  • GraphQL has not been enabled in your plan
  • Invalid plan
  • Disabled organization
422 Message
{
  code: 'INVALID_LOCALE',
  message: `The queried locale '${options.locale}' is invalid.`,
  details: {
    hint: `Pass the locale which is present in your stack.`
  }
}
Description
The locale you are trying to fetch data from does not exist within the specified stack.
400 Message
{
  "code": "INVALID_REQUEST",
  "message": "Query or body is not valid.",
  "details": {
    "hint": "The request should have a valid body OR query parameters."
  }
}
Description
This error message is returned for the following scenarios:
  • GET API request provides an invalid query
  • POST API request provides an invalid JSON-formatted request body
422 Message
{
  code: 'MAX_REFERENCE_DEPTH_LIMIT_EXCEEDED',
  message: `Max allowed nested reference depth limit is '{ALLOWED_DEPTH}', but the query has '{CURRENT_DEPTH_OF_REQUEST}' nested references.`,
  details: {
    hint: "Try reducing the total no. of reference nested within one another OR contact 'support@contentstack.com' to increase limits."
  }
}
Description
The GraphQL query exceeds the maximum depth limit for retrieving nested referenced items (entries and/or assets), i.e. three.
422 Message
{
  code: 'MAX_DOCUMENT_LIMIT_EXCEEDED',
  message: `Max allowed documents in a  single query is '{ALLOWED_LIMIT}', but the query has requested '${CURRENT_REQUESTED_DOCUMENTS}' documents.`,
  details: {
    hint: "Try reducing the total no. of references queried OR pass in skip/limit arguments in references OR contact 'support@contentstack.com' to increase limits."
  }
}
Description
The GraphQL query is trying to fetch more than 10,000 documents. A document may contain queries, content types, assets, entries, and their referenced assets and entries. The maximum number of documents that can be returned to the client in a single GraphQL query is 10,000.
422 Message
{
  code: 'MAX_ALLOWED_CONTENT_TYPE_LIMIT_EXCEEDED',
  message: `Max allowed content types that can be used in a query is '{ALLOWED_CONTENT_TYPES}', but the query uses '${CURRENT_REQUEST_CONTENT_TYPES}' content types.`,
  details: {
    hint: "Try reducing the total no. of reference fields being queried OR contact 'support@contentstack.com' to increase limits."
  }
}
Description
The GraphQL query exceeds the maximum limit for the number of content types that can be fetched at a time. You can generate a GraphQL schema for a maximum of 100 content types through a single API request.
500 Message
{
  code: 'MAX_QUERIES',
  message: `Only 1 query is allowed at a time.`,
  details: {
    hint: "Pass only 1 query in the request"
  }
}
Description
The API request exceeds the maximum allowed limit for the number of queries that can be passed in a single request.
422 Message
{
  code: 'MAX_QUERIED_CONTENT_TYPE_LIMIT_EXCEEDED',
  message: `Max allowed content types queried at a time is '{ALLOWED_CONTENTE_TYPES_TO_QUERY}', but the query has requested '${CURRENT_REQUESTED_CONTENT_TYPES}' content types.`,
  details: {
    hint: "Try reducing the total no. of content types queried OR contact 'support@contentstack.com' to increase limits."
  }
}
Description
The API request exceeds the maximum allowed limit for the number of content types that can be queried in a single GraphQL API request. The maximum limit is three.
422 Message
{
  code: 'SCHEMA_BUILD_ERROR',
  message: 'Unable to generate GraphQL types. Check details for more info.',
  details: options.errors
}
Description
The server could not generate the GraphQL schema as it found invalid GraphQL types.
422 Message
{
  code: 'MAX_REFERENCE_LIMIT_EXCEEDED',
  message: `Max allowed limit per reference for your organization is '{ALLOWED_LIMIT}', but the query requested '{REQUESTED_LIMIT}'.`,
  details: {
    hint: `The field '{field_uid}' has 'limit: {REQUESTED_LIMIT}' Pass a limit value between 0 and '{ALLOWED_LIMIT}'.`
  }
}
Description
The query exceeds the maximum limit allowed for the number of referenced entries or assets that can be retrieved from a specific Reference field in a single GraphQL API request. The maximum limit is 100.

Limitations

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

Features Limitations
GraphQL
  • If there are any typename collisions on GraphiQL Explorer, the introspection schema will fail to load.
  • Avoid using special characters while naming content types or fields to prevent typename collisions.
  • If your content type UIDs and field UIDs start with a number, you won't be able to run any GraphQL queries.
Maximum content types fetched in a single requestThe maximum limit for the number of content types that can be fetched in a single API request is 100.
SortingThe ‘Order by Asc’ and ‘Order by Desc’ operators can only be used on the following system-defined fields:
  • Created at
  • Updated at
Searching based on referenceYou can use referenced fields that lie up to one level deep in the “where” argument to search for top-level content.
Nested reference fetching depthThe maximum depth limit for fetching nested items (entries and/or assets) is three.
Maximum objectsThe maximum objects that can be fetched in a single query is 10,000.
Maximum reference objects for a single Reference fieldThe maximum referenced items that can be fetched for a single Reference field is 100.
Querying multiple content typesThe maximum content types that can be queried in a single request is three.
Response SizeThe maximum size limit for the response returned by a GraphQL query is 7 MB.

top-arrow