Skip to main content

Introduction

Custom queries Pro Feature let you create GraphQL queries to retrieve specific data from WordPress beyond what's available through built-in data sources. While built-in data sources provide contextual WordPress data automatically, custom queries give you precise control over data retrieval, arguments, and relationships.

When You Need Custom Queries​

Built-in data sources work perfectly for standard WordPress scenarios, but custom queries become essential when you need:

  • Advanced filtering: Products under $50, events happening next month, posts by specific authors
  • Cross-context data: Show category posts on single post templates, user lists on any page
  • Smart relationships: Related posts by shared tags, author's other content, hierarchical data
  • Mixed content types: Combine posts, users, and taxonomy data in unified displays
  • Performance optimization: Request only needed fields, replace multiple database calls

What Custom Queries Look Like​

Here's a simple custom query that gets recent blog posts with specific fields:

{
  posts_query(
    arguments: {
      post_type: "post"
      posts_per_page: 5
      orderby: "date"
      order: "DESC"
    }
  ) {
    posts {
      ID
      post_title
      post_excerpt
      post_date
      featured_image {
        file_url
        alt_text
      }
    }
  }
}

This query gives you complete control over which posts appear and exactly which data fields are available in your template.

GraphQL Foundation​

All dynamic data in Builderius uses GraphQL. Built-in data sources are pre-written GraphQL queries that match WordPress template contexts. Custom queries let you write your own GraphQL for specific requirements.

Key distinction:

  • Built-in data sources: Pre-written queries for common scenarios ([[wp.post.title]])
  • Custom queries: User-written GraphQL for specific needs ([[my_query.posts_query.posts]])

Tag Syntax Comparison:

<!-- Single values -->
<h1>[[wp.post.title]]</h1>
<p>[[wp.post.excerpt]]</p>
<img src="[[wp.post.featured_image.file_url]]">

<!-- Collection loops -->
<!-- Data source: [[wp.archive.posts_query.posts]] -->
<article>
  <h2>{{post_title}}</h2>
  <p>{{post_excerpt}}</p>
  <img src="{{featured_image.file_url}}">
</article>

The only difference is the variable name, wp vs my_query. The bracket syntax and field access work identically, and both accessed in the same way using dynamic data dropdown.

Custom Query Workflow​

  1. Open GraphQL Editor: Access from Dynamic Data tab, create new variable
  2. Write Query: Use snippets, auto-completion, and syntax highlighting
  3. Test Results: "Get Data" button shows live JSON preview
  4. Bind to Templates: Your query appears in dynamic data dropdown
  5. Use in Elements: Standard [[]] syntax or Collection elements for loops, and {{}} for loop item fields

Performance Benefits​

  • Single Database Query: Replace multiple WordPress functions with one optimized request
  • Field Selection: Request only needed data, reducing memory and transfer time
  • Efficient Caching: GraphQL results cache based on query structure
  • Reduced PHP Processing: Database handles filtering instead of PHP loops

Getting Started​

Custom queries maintain Builderius's visual approach while providing developer-level data control. Start with simple filtering and build toward complex relationships as your confidence grows.

Next steps:

Custom queries bridge the gap between simple built-in data and sophisticated WordPress functionality, enabling sites that automatically adapt to any content strategy.