Frequently Asked Questions

Technical Features & Query Complexity

What is query complexity in Hygraph and why does it matter?

Query complexity in Hygraph refers to the computational resources required to fulfill a GraphQL (GQL) query. Complexity increases with the number of fields and the depth of the query. Managing query complexity is crucial for efficient data retrieval and optimal performance. For example, scalar fields each contribute one point to complexity, while relations and unions multiply complexity based on nesting. Learn more in the official documentation.

How can I manage and reduce query complexity in Hygraph?

You can manage and reduce query complexity by splitting large queries into smaller ones, limiting query depth, fetching only necessary fields, and using pagination. These practices help optimize performance and prevent queries from failing due to excessive resource demands. For step-by-step guidance, see Splitting GQL Queries.

What are best practices for splitting GraphQL queries in Hygraph?

Best practices include limiting the depth of queries to avoid heavy nesting, fetching only the fields you need, and using pagination arguments like first, last, skip, before, and after. These techniques reduce complexity and improve efficiency. For examples, visit Limiting Query Depth and Using Pagination.

How does Hygraph support pagination in queries?

Hygraph supports pagination using arguments such as first, last, skip, before, and after. The default result size for queries fetching multiple entries is 10, with a maximum of 100 for first or last arguments. Projects created before June 14, 2022, have a higher limit (100/1000). For more details, see Pagination Documentation.

What is the complexity tree JSON output and how can it help optimize queries?

The complexity tree JSON output provides a detailed breakdown of the estimated and actual costs of a GraphQL query, including the number of documents fetched and the cost per field. By analyzing this output, you can identify which fields contribute most to query complexity and optimize accordingly. To access the complexity tree, add the "x-inspect-complexity": true header in the API playground. Learn more at Complexity Tree Documentation.

How can I optimize union queries in Hygraph?

Union queries can be optimized using enhanced query splitting with the Entity type or by using the Node interface. The Entity type approach is preferred for better performance, allowing you to fetch id and __typename first, then query specific entities. This method reduces complexity and improves efficiency, especially for dynamic layouts with multiple content types. For implementation details, see Enhanced Query Splitting.

What are the benefits of enhanced query splitting with Entity type?

Enhanced query splitting with Entity type offers reduced query complexity, enhanced performance, and flexible data fetching. It allows you to split queries into manageable parts and target specific content types efficiently, which is especially useful for websites with dynamic layouts. For more information, visit Benefits of Enhanced Query Splitting.

API Features & Integrations

Does Hygraph provide an API for content management?

Yes, Hygraph offers a powerful GraphQL API for efficient content fetching and management. You can learn more about its capabilities at the Hygraph API Reference.

What integrations are available with Hygraph?

Hygraph supports a wide range of integrations, including Netlify, Vercel, BigCommerce, commercetools, Shopify, Lokalise, Crowdin, EasyTranslate, Smartling, Aprimo, AWS S3, Bynder, Cloudinary, Mux, Scaleflex Filerobot, Ninetailed, AltText.ai, Adminix, and Plasmic. For a full list, visit Hygraph Integrations.

Performance, Security & Compliance

How does Hygraph optimize content delivery performance?

Hygraph is designed for optimized content delivery, ensuring rapid distribution and responsiveness. This leads to improved user experience, higher engagement, and better search engine rankings. For more details, visit this page.

What security and compliance certifications does Hygraph have?

Hygraph is SOC 2 Type 2 compliant, ISO 27001 certified, and GDPR compliant. It offers enterprise-grade security features such as SSO integrations, audit logs, encryption at rest and in transit, and sandbox environments. For more details, visit Hygraph Security Features.

Documentation & Support

Where can I find technical documentation for Hygraph?

Comprehensive technical documentation is available at Hygraph Documentation, covering everything from building and deploying projects to API references and developer guides.

What support options are available for Hygraph users?

Hygraph offers 24/7 support via chat, email, and phone. Enterprise customers receive dedicated onboarding and expert guidance. All users can access documentation, video tutorials, and a community Slack channel. For more details, visit Hygraph Contact Page.

Pricing & Plans

What is Hygraph's pricing model?

Hygraph offers a free forever Hobby plan, a Growth plan starting at $199/month, and custom Enterprise plans. For full details, visit the pricing page.

Use Cases, Pain Points & Success Stories

What problems does Hygraph solve for its users?

Hygraph addresses operational pains (e.g., reliance on developers for content updates, outdated tech stacks, conflicting global team needs, clunky content creation), financial pains (high operational costs, slow speed-to-market, expensive maintenance, scalability challenges), and technical pains (boilerplate code, overwhelming queries, evolving schemas, cache problems, OpenID integration challenges). For more details, visit our product page.

Who can benefit from using Hygraph?

Hygraph is ideal for developers, IT decision-makers, content creators, project/program managers, agencies, solution partners, and technology partners. It serves modern software companies, enterprises seeking to modernize, and brands aiming to scale, improve development velocity, or re-platform from traditional solutions. Source: ICPVersion2_Hailey.pdf

Can you share specific customer success stories with Hygraph?

Yes. Komax achieved 3X faster time to market, Autoweb saw a 20% increase in website monetization, Samsung improved customer engagement with a scalable platform, and Dr. Oetker enhanced their digital experience using MACH architecture. More stories are available at Hygraph Customer Stories.

What industries are represented in Hygraph's case studies?

Industries include food and beverage, consumer electronics, automotive, healthcare, travel and hospitality, media and publishing, eCommerce, SaaS, marketplace, education technology, and wellness and fitness. For more, see Hygraph Case Studies.

Getting Started & Ease of Use

How easy is it to get started with Hygraph?

Hygraph is praised for its intuitive interface and ease of use. Even non-technical users can start quickly by signing up for a free account and using onboarding guides and documentation. For example, Top Villas launched a new project in just 2 months. Learn more at Hygraph Documentation.

Customer Proof

Who are some of Hygraph's customers?

Hygraph is trusted by companies such as Sennheiser, Holidaycheck, Ancestry, Samsung, Dr. Oetker, Epic Games, Bandai Namco, Gamescom, Leo Vegas, and Clayton Homes. For more details and logos, visit Hygraph Case Studies.

Help teams manage content creation and approval in a clear and structured way
Hygraph
Docs

#Query complexity

#Overview

When working with GraphQL (GQL) queries, it's important to manage the complexity of your queries to ensure efficient and effective data retrieval.

In the context of GQL, query complexity refers to the computational resources needed to fulfill a query. The complexity of a query increases with the number of fields and the depth of the query.

  • Scalar fields: Each scalar field in a query contributes one point to the query complexity.
  • Relations / Unions: Relations multiply their complexity times the level of nesting in the query.

For example, if a query retrieves a list of posts and each post has multiple comments, the complexity of the query increases with each nested comment.

This guide will help you with the following:

#Splitting GQL queries

To manage query complexity, you can split your GQL queries into smaller, more manageable parts:

SuggestionDescription
Limit the depth of your queriesAvoid deeply nested queries. Instead, break them up into multiple smaller queries. This can help reduce the complexity and make your queries more efficient.
Fetch only necessary fieldsMinimize the number of fields you're retrieving in each query. Only fetch the fields that are necessary for your current operation.
Use paginationHygraph supports various arguments for paginating content entries. By using these features, you can manage the amount of data retrieved in each query, thereby reducing the complexity.

Remember that the goal is to reduce the complexity of your queries to ensure efficient and effective data retrieval. By limiting the depth of your queries, fetching only necessary fields, and using pagination, you can manage the complexity of your GQL queries effectively.

The following examples show you how you can split your GQL queries:

#Example 1: Limiting query depth

Instead of a deeply nested query like this:

{
posts {
id
comments {
id
author
replies {
id
text
user {
id
name
}
}
}
}
}

You can split it into two separate queries:

#Example 2: Fetching only necessary fields

Intead of retrieving all fields, like this:

{
post(where: { id: "..." }) {
id
title
body
author
comments
}
}

You can retrieve only the necessary fields, like this:

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

#Example 3: Using pagination

Hygraph supports various arguments for paginating content entries:

  • first: Seek forwards from the start of the result set.
  • last: Seek backwards from the end of the result set.
  • skip: Skip result set by a given amount.
  • before: Seek backwards before a specific ID.
  • after: Seeks forwards after a specific ID.

The default result size of results returned by queries fetching multiple entries is 10. You can provide a maximum of 100 to the first, or last arguments.

You can use first, last, skip, before, and after arguments with any nested relations. In the following example, the posts model has comments:

{
posts {
id
comments(first: 6, skip: 6) {
id
createdAt
}
}
}

#Union queries

Union types allow to setup relational fields that point to different model types, while this feature allows for very flexible modelling of content, it can also open the door to queries that might not perform as well and could use some optimizations. Below we document means to optimize querying for content that is backed by a Union relation.

Unions are typically queried like so:

{
page(where: { id: "ckrks0ge0334m0b52onduq7r2" }) {
id
title
blocks {
__typename
... on Hero {
title
ctaLink
}
... on Grid {
title
subtitle {
markdown
}
}
... on Gallery {
photos {
url
handle
}
}
}
}
}

As schemas evolve and Union relations expand to many models, querying unions this way can become problematic. Particularly when every single possible type is queried with this format within the same query.

#Optimizing union queries

We offer two ways of optimizing your union queries:

  • Enhanced Query Splitting with Entity Type (Preferred solution)
  • Optimizing union queries using Node

#Enhanced query splitting with Entity type

Hygraph has introduced an improved query splitting feature using the Entity type and entities query entrypoint.

This approach is particularly beneficial for handling complex union relationships and modular components.

#Implementation

The Entity type provides a more streamlined approach compared to the traditional Node interface. It makes use of the typename to substantially increase performance.

To do this, follow these two steps:

Step 1: Initial query using Entity type

This initial query fetches id and __typename for each block within a page, preparing for the detailed query in the next step.

query {
page {
id
blocks {
__typename
... on Entity {
id
}
}
}
}

Step 2: Detailed query for specific types

The second query specifically targets Hero, Grid, and Gallery entities based on the id and __typename obtained from the first query. Results are returned in the order of the where input.

query {
entities(where: [{id: "ckrks0ge0334m0b52ienf67ag", typename: "Hero", stage: "DRAFT"},
{id: "ckrks0ge0334m0b52firha74a", typename: "Grid", stage: "DRAFT"},
{id: "ckrks0ge0334m0b52ifh2sd6a", typename: "Gallery", stage: "DRAFT"}]) {
... on Hero {
id
title
}
... on Grid {
id
layout
}
... on Gallery {
id
images
}
}
}

#Benefits

BenefitDescription
Reduced Query ComplexitySimplifies queries by splitting them into manageable parts.
Enhanced PerformanceImproves efficiency by reducing the load in fetching complex data types.
Flexible Data FetchingOffers more control and precision in querying specific content types.

#Example Use Case

Consider a website with a dynamic layout consisting of Hero, Grid, and Gallery sections. Enhanced query splitting with Entity type would allow for efficient identification and retrieval of specific content types, ensuring high performance and flexibility in data handling.

#Optimizing union queries using Node

In order to avoid performance impacts due to a large number of Union types in a relation, it is possible to change the way the content is queried so that it is done in a 2 step approach.

Below we will be using the same query from the previous section as an example:

Step 1: Find out which documents are in fact connected

We will get the __typename and the id for all the connected documents in the union relation by using the Node interface like so:

Step 2: Query the connected types by id

With the retrieved information we can construct queries dynamically to fetch the affected documents. Considering the response we received from the previous query in Step 1, we will now go over the response and generate another query that will in fact get only the connected documents by id:

query heroBlocks {
heros(where: { id_in: ["cks8t3o943h1l0d099v8xd072"] }) {
title
ctaLink
}
}
query gridBlocks {
grids(
where: {
id_in: ["cksj3dxww0o2r0c57savzceub", "cksrocxds3mwa0a07rdtj7qvx"]
}
) {
title
subtitle {
markdown
}
}
}
query galleryBlocks {
galleries(where: { id_in: ["cks8t36i83iq70b6035caxp6n"] }) {
photos {
url
handle
}
}
}

Alternatively, you can combine these into a single query by using aliasing:

query blocks {
heroBlocks: heros(where: { id_in: ["cks8t3o943h1l0d099v8xd072"] }) {
title
ctaLink
}
gridBlocks: grids(
where: {
id_in: ["cksj3dxww0o2r0c57savzceub", "cksrocxds3mwa0a07rdtj7qvx"]
}
) {
title
subtitle {
markdown
}
}
galleryBlocks: galleries(
where: { id_in: ["cks8t36i83iq70b6035caxp6n"] }
) {
photos {
url
handle
}
}
}

#Complexity tree JSON output

The complexity tree JSON output provides a detailed breakdown of the estimated and actual costs of your GraphQL query. This information can help you understand the computational resources required to fulfill your query and guide you in optimizing your queries for better performance.

#JSON Output

Here is a brief explanation of the keys in the JSON output:

  • total_estimated_docs: The total number of documents estimated to be fetched by the query.
  • total_actual_docs: The total number of documents actually fetched by the query.
  • total_estimated_cost: The total estimated cost of the query. This includes the cost of fetching documents and any additional costs.
  • total_actual_cost: The total actual cost of the query.
  • complexityTree: A nested structure that breaks down the cost of each field in the query.

Each node in the complexityTree has the following keys:

  • field_name: The name of the field in the query.
  • xpath: The path to the field in the query.
  • estimated_no_of_docs: The estimated number of documents fetched by this field.
  • additional_cost: Any additional cost associated with this field.
  • estimated_cost: The total estimated cost of this field (the sum of estimated_no_of_docs and additional_cost).
  • actual_no_of_docs: The actual number of documents fetched by this field.
  • actual_cost: The actual cost of this field.
  • children: Any nested fields within this field. Each child is also a node with the same structure.

#JSON Output Example

Consider the following query and its related complexity tree JSON output:

This JSON output shows us that the total estimated cost of the query is 1116, which includes fetching 1110 documents and additional costs. However, since the query did not return any content for this example(there was no real content in the project), the actual costs and documents fetched are 0. Despite this, the query is still costly due to the nested structure, hence the high estimated cost.

The complexityTree provides a breakdown of the costs for each field in the query. For example, the posts field is estimated to fetch 10 documents with an additional cost of 2, resulting in an estimated cost of 12. Within the posts field, the comments field is estimated to fetch 100 documents with an additional cost of 2, resulting in an estimated cost of 102. The authors field within comments is estimated to fetch 1000 documents with an additional cost of 2, resulting in an estimated cost of 1002. This is because of the multiplication of nested fields that we mentioned before.