Fragments and aliases

13 min

Fragments let you define reusable units of query logic. Use fragments to encapsulate common field selections and apply them across multiple queries. This reduces repetition and ensures consistency in the data you retrieve. Fragments are useful when working with complex queries that involve different content types or when you want to maintain a clean, organized query structure.

Aliases let you rename fields in your query results. Use aliases when you want to query the same field with different parameters or when you need to resolve naming conflicts between fields. Aliases let you create descriptive, meaningful names for the data returned by your queries.

Benefits of using fragments

Reusability – Define once and use in multiple queries.

Consistency – Ensure uniform data retrieval across different parts of your application.

Readability – Simplify complex queries by breaking them into manageable parts.

When to use fragments

Use fragments to render referenced blocks inside the main content items in your query. They are useful for handling different content types and reducing query repetition.

Fragment examples

Fragment for reusability

Fragments help you reuse common field selections across multiple queries. The following query defines a reusable ArticleFields fragment for consistent data retrieval across multiple queries:

fragment ArticleFields on ArticlePage {
  Name
  RelativePath
  TeaserText
  StartPublish
  PageImage {
    Url
  }
  Category {
    Name
    Description
  }
}

query GetRecentArticles {
  ArticlePage(
    orderBy: { StartPublish: DESC }
    limit: 5
  ) {
    items {
      ...ArticleFields
    }
  }
}

query GetFeaturedArticles {
  ArticlePage(
    where: { Name: { contains: "Featured" } }
  ) {
    items {
      ...ArticleFields
    }
  }
}

Inline fragments for different content types

Query for base types or interfaces and create inline fragments or named fragments for each concrete type that inherits or implements the base type or interface. The following query uses inline fragments to query multiple content types in a single query with type-specific fields:

query GetMixedContent {
  SitePageData(limit: 10) {
    items {
      # Common fields for all content types
      Name
      RelativePath
      _typeName
      
      # Type-specific fields using inline fragments
      ... on ArticlePage {
        TeaserText
        MainBody
      }
      
      ... on ProductPage {
        TeaserText
        MainBody
        PageImage {
          Url
        }
      }
      
      ... on StandardPage {
        MainBody
        MetaTitle
        MetaDescription
      }
    }
  }
}

Named fragments for content types

The following query uses named fragments to simplify complex queries by encapsulating fields for specific content types:

fragment ArticleDetails on ArticlePage {
  Name
  RelativePath
  TeaserText
  MainBody
  StartPublish
}

fragment ProductDetails on ProductPage {
  Name
  RelativePath
  TeaserText
  MainBody
  PageImage {
    Url
  }
}

fragment StandardPageDetails on StandardPage {
  Name
  RelativePath
  MainBody
  MetaTitle
  MetaDescription
}

query GetContentByType {
  SitePageData(limit: 20) {
    items {
      _typeName
      
      ...ArticleDetails
      ...ProductDetails  
      ...StandardPageDetails
    }
  }
}

Fragment best practices

Limit use of inline fragments

Avoid including too many inline fragments in a query. The more content types involved in a query, the slower it is to execute. The following query demonstrates improved query performance by limiting content types and using specific queries:

# Poor performance – too many content types
query OverlyComplexQuery {
  SitePageData {
    items {
      ... on ArticlePage { Name TeaserText MainBody }
      ... on StandardPage { Name MainBody }
      ... on ProductPage { Name TeaserText MainBody }
      ... on LandingPage { Name HeroTitle }
      ... on BlogPostPage { Name TeaserText Topic }
      ... on ContactPage { Name ContactInfo }
      ... on EventPage { Name EventDate EventLocation }
      ... on NewsPage { Name NewsDate NewsCategory }
      ... on TestimonialPage { Name TestimonialAuthor }
      ... on FAQPage { Name FAQCategory }
      # ... 10+ more content types
    }
  }
}

# Better performance – specific query for needed content type
query GetSpecificContent($contentType: String!) {
  SitePageData(where: { _typeName: { eq: $contentType } }) {
    items {
      ... on ArticlePage {
        Name
        TeaserText
        MainBody
      }
    }
  }
}

Fragments for referenced blocks

Fragments are useful for rendering blocks within content. The following query shows how to use fragments to render blocks within content for modularity and reuse:

fragment ImageBlockFields on ImageBlock {
  Name
  Image {
    Url
  }
  AltText
  Caption
}

fragment TextBlockFields on TextBlock {
  Name
  Heading
  MainBody
}

query GetPageWithBlocks($path: String!) {
  StandardPage(where: { RelativePath: { eq: $path } }) {
    item {
      Name
      MainBody
      
      # Render referenced blocks using fragments
      MainContentArea {
        ... on ImageBlock {
          ...ImageBlockFields
        }
        
        ... on TextBlock {
          ...TextBlockFields
        }
      }
    }
  }
}

Aliases

Use aliases if you need to resolve conflicts resulting from different types.

Benefits of using aliases

Conflict resolution – Handle fields with the same name but different parameters.

Descriptive naming – Provide clearer and more meaningful names for query results.

Multiple usages – Query the same field in different ways within a single query.

Alias examples

Aliases for conflict resolution

The following query shows alias usage to rename query results for clarity and conflict resolution:

query GetArticlesWithAliases {
  # Query recent articles with alias
  recentArticles: ArticlePage(
    orderBy: { StartPublish: DESC }
    limit: 5
  ) {
    items {
      Name
      RelativePath
      StartPublish
    }
  }
  
  # Query featured articles with alias  
  featuredArticles: ArticlePage(
    where: { Name: { contains: "Featured" } }
    limit: 3
  ) {
    items {
      Name
      RelativePath
      StartPublish
    }
  }
}

Aliases for different parameters

The following query uses aliases to query the same field with different parameters within a single query structure:

query GetArticlesByDifferentCriteria($searchTerm: String!) {
  # Articles matching in title
  titleMatches: ArticlePage(
    where: { Name: { match: $searchTerm } }
    limit: 10
  ) {
    items {
      Name
      RelativePath
    }
  }
  
  # Articles matching in content
  contentMatches: ArticlePage(
    where: { MainBody: { match: $searchTerm } }
    limit: 10
  ) {
    items {
      Name
      RelativePath
    }
  }
}

Aliases best practices

Avoid using aliases unless necessary. Use aliases only in the following cases:

Naming conflicts between different queries.

A need to query the same type with different parameters.

A need for more descriptive names for the response structure.