LogoLogo
Siteglide.comAdminRoadmap
  • 👋Welcome
  • Get Started
    • 🚀Quickstart Guides
    • ❔Support & FAQs
      • â„šī¸Siteglide Support Policy
      • â„šī¸Siteglide Technology Stack
      • â„šī¸External Resources
      • â„šī¸Front-end Browser Support
  • Portal
    • Account
    • Sites
      • 🚀Quickstart: Create a Site
      • â„šī¸Site Details
      • â„šī¸Site Users
      • 📋Install & Manage Modules
      • đŸ’ŗGo Live
      • đŸ’ŗSubscription
      • 🌍Domains
        • 📋Add a Fully Delegated Domain
        • 📋Add an External Domain
        • đŸ’ģSubdomain on a separate instance
        • 📋How to setup a multi domain start page
      • â˜ī¸Site Backups and Disaster Recovery
    • Users
      • 📋User Roles
      • 📋Invite & Manage Users
    • Billing
      • đŸ’ŗBilling Setup
      • đŸ’ŗSubscriptions and Changes
      • đŸ’ŗAutomatic Site Upgrades
      • đŸ’ŗInvoices
    • Tickets
    • Marketplace
    • Agencies
      • 👩‍đŸ’ģAgency Account
      • 👩‍đŸ’ģClients
      • 👩‍đŸ’ģSite Copies
      • 👩‍đŸ’ģAgency Whitelabelling
  • Developer Tools
    • CLI
      • 🚀Quickstart: CLI
      • â„šī¸About
      • 📋Site Setup
      • ❔Troubleshooting
      • đŸ’ģReference
      • đŸ›ŗī¸CLI Changelog
      • đŸ§™â€â™‚ī¸Go Further: CLI
        • Creating WebApps via CLI
    • Liquid
      • â„šī¸About
      • đŸ’ģReference
      • Accessing Data in Liquid Variables - Tutorial 1 - Using Dot Notation
      • Accessing Data in Liquid Variables - Tutorial 2 - Iterating over Arrays and Objects
      • Using Collections with WebApps and Modules
      • Accessing Data from the Global Context Variable
      • Truthiness - Using Liquid to determine if a field is empty or blank
      • 📋Alternatives to Storing and Executing Liquid from Database Items
    • GraphQL
      • â„šī¸About GraphQL
      • 📋Tutorials
        • Tutorial 1 - Your First Query
        • Tutorial 2 - Pagination
        • Tutorial 3 - Filtering the Results
        • Tutorial 3 - (Answers)
        • Tutorial 4 - Advanced Filtering
        • Tutorial 4 - (Answers)
        • Tutorial 5 - Using Liquid to run GraphQL queries on your Site
        • Tutorial 6 - Variables
        • Tutorial 6 - (Answers)
        • Tutorial 7 - Sorting
        • Tutorial 8 - Building a Liquid API GET Endpoint Page powered by GraphQL queries
        • Tutorial 9 - Using Mutations to Create New Records
        • Tutorial 10 - Using Mutations to Edit a Record
        • Tutorial 11 - Using Mutations to Delete an Item
        • Tutorial 12 - Related Records and Datasources
    • Configuration
      • â„šī¸Field Types
      • â„šī¸Custom Field IDs
    • Zapier Integration
      • â„šī¸Formatting arrays correctly
    • Developer Marketplace
      • â„šī¸About Building Modules
      • â„šī¸Module Setup
      • â„šī¸Site Template Modules - and How to Make Your Own
      • â„šī¸Create Folder Structure
      • â„šī¸Updating Modules
      • â„šī¸Submit Module for Approval
      • â„šī¸Adding Payment to a Module
      • â„šī¸Theme Module Example
      • â„šī¸Data & UI Module Example
      • đŸ’ģReference
      • đŸŒŗFile Structure
    • Release Notes
      • đŸ›ŗī¸Siteglide Admin/API - Changelog
      • đŸ›ŗī¸Module - System Files - Changelog
      • đŸ›ŗī¸Module - eCommerce - Changelog
      • đŸ›ŗī¸Module - Menu - Changelog
      • đŸ›ŗī¸Module - Slider - Changelog
      • đŸ›ŗī¸Module - Secure Zones - Changelog
      • đŸ›ŗī¸Module - FAQ - Changelog
      • đŸ›ŗī¸Module - Events - Changelog
      • đŸ›ŗī¸Module - Blog - Changelog
  • SiteBuilder
    • Build Sites Faster
      • 🚀Quickstart: SiteBuilder
      • About
      • Site Setup
        • đŸ—ī¸Marketplace Themes & Templates
        • đŸ—ī¸Create Site From Template
        • đŸ—ī¸Install SiteBuilder Module
        • đŸ—ī¸Create a Page Template
        • đŸ—ī¸Set Up Tailwind CSS with the recommended CLI method
      • Styling
        • đŸ—ī¸Editing Tailwind CSS using the recommended CLI method
        • đŸ—ī¸Tailwind CSS Themes - Choosing a Build Method
        • đŸ—ī¸Tailwind CSS - Preview Mode
        • đŸ—ī¸Tailwind's JIT Compiler Via CDN (deprecated)
        • đŸ—ī¸Theme Presets
        • đŸ—ī¸Example Tailwind Project Setup
      • Layouts
        • đŸ—ī¸Insert Static Layouts
        • đŸ—ī¸Installing Dynamic Layouts
        • đŸ—ī¸Editing Dynamic Layouts
        • About Layouts
          • đŸ—ī¸Dynamic Layouts
          • đŸ—ī¸Static and Dynamic Form Layouts
          • đŸ—ī¸Sliders
      • đŸ’ģReference
    • Advanced Features
      • 🧞SiteBuilder Live Updates API
        • 👀Live Updates Reference
        • 🔹Live Updates Markup Example
        • 📋Steps to Setting Up Live Updates API in a Module/WebApp Layout
        • 🔹Live Updates Example - Enforcing Filters
        • 📋Steps to Use Live Updates Methods
        • 📋Steps to Initialise Live Updates with JS
        • đŸ—“ī¸Live Updates Changelog
      • â„šī¸SiteBuilder JavaScript
        • â„šī¸Forms JS
        • â„šī¸Social Sharing JS
        • â„šī¸Sliders JS
        • â„šī¸Dark Mode JS
        • â„šī¸Cookie Settings JS
      • â„šī¸SiteBuilder Liquid Includes
        • â„šī¸Pagination
      • â„šī¸SiteBuilder Liquid Functions
        • â„šī¸Detail Page Valid
        • â„šī¸Field Mapping
        • â„šī¸Get Table Config
        • â„šī¸Case From Order ID
      • đŸ—“ī¸SiteBuilder Changelog
    • Extend SiteBuilder
      • â„šī¸Create SiteBuilder Themes
      • â„šī¸Create Marketplace Modules
      • â„šī¸Adding Dynamic Layouts to Themes & Modules
      • â„šī¸Adding Static Layouts to your Theme
      • đŸ’ģReference
  • CMS
    • Dashboard
    • Pages
      • 🚀Quickstart: Pages
      • 🎨Studio Alpha Release
      • â„šī¸Studio
      • â„šī¸Code View & Toolbox
      • â„šī¸About Pages
        • â„šī¸Page Settings
        • â„šī¸Custom Fields in Pages
        • â„šī¸Pages with Siteglide CLI
      • â„šī¸About Page Templates
        • â„šī¸Page Templates with Siteglide CLI
        • Preventing Duplicate Content
      • â„šī¸System Pages
      • đŸ’ģReference
      • đŸŒŗFile Structure
    • Content Sections
    • File Manager
      • 🔹About Assets
      • 🔹Linking to Assets Explained
      • 🔧Assets Troubleshooting
      • 🔹Siteglide Scripts Explained
      • đŸ’ģAssets with CLI
      • đŸ”ŧMigrating Assets
      • 📋Steps to Optimise Images on the Fly with Cloudinary
      • 🔹siteglide_head_scripts and siteglide_footer_scripts Explained
      • đŸŒŗAssets File Structure
      • 👀Tags for Assets
    • Forms
      • Quickstart: Forms
      • â„šī¸About Forms
      • 📋Guides: Forms
        • 📋Steps to Using Separate Fields for First Name and Surname in a Form
        • 📋Steps to Programmatically Redirecting after a Form Submission
        • 📋Steps to Adding Form Confirmation Pages
        • 📋Steps to Adding a Progress Bar
        • 📋Steps to Changing Form Styling on Submission Using CSS
        • 📋Steps to Using Custom Field Set fields in a Form's Custom Layout
      • đŸ§™â€â™‚ī¸Go Further: Forms
        • â„šī¸Migrating Forms
        • â„šī¸Explained - Preventing Spam Form Submissions and Captchas
        • â„šī¸Explained - Show Clearly When a User is Already Logged in When Submitting a Form
        • â„šī¸Forms Error Callback and Validation
        • â„šī¸Forms Success Callback
        • â„šī¸File Upload Previews
      • đŸŒŗForms File Structure
      • đŸ’ģReference
      • ❔Troubleshooting
    • Automations
      • 🚀Quickstart: Automations
      • â„šī¸About
        • â„šī¸Email Templates
        • â„šī¸Email Automations and Email Templates with Siteglide CLI
      • 📋Guides
        • â„šī¸Integration Automations
        • â„šī¸A Transactional Email Example
        • â„šī¸An API Call Action Example
        • â„šī¸A Custom Liquid Action Example
        • 📋Steps to Testing Emails on a Staging Site
        • 📋Steps to Authenticating Sendgrid Emails on Live Sites
      • đŸ§™â€â™‚ī¸Go Further
      • đŸ’ģReference
      • đŸŒŗFile Structure
    • Categories
      • 🚀Quickstart: Categories
      • â„šī¸About
        • â„šī¸Outputting Categories on WebApp / Module / eCommerce Layouts
        • â„šī¸Filtering WebApps and Modules by Categories Using Liquid Parameters
      • đŸŒŗFile Structure
      • đŸ’ģReference
    • Company Information
      • â„šī¸About
      • đŸ’ģReference
      • ❔Troubleshooting
    • URL Redirects
  • Modules
    • Core Modules
      • MenuBuilder
        • 🚀Quickstart: Menu Builder
        • â„šī¸About
      • Secure Zones
        • 🚀Quickstart: Secure Zones
        • â„šī¸About
          • 📋Dynamically Assign a Secure Zone during Form Submission
        • đŸ§™â€â™‚ī¸Go Further
          • â„šī¸Secure Zones with Siteglide CLI
          • â„šī¸Using the context.current_user object
      • Media Downloads
        • 🚀Quickstart: Media Downloads
        • â„šī¸Layouts
        • đŸ’ģReference
      • Blog & Authors
        • 🚀Quickstart: Blog & Authors
        • 🔹Blog Archive & Date Filtering
        • 🔹Blog Search
        • 🔹Blog Filter by Category
        • 🔹Blog Filter by Author
        • đŸŒŗFile Structure
        • đŸ’ģReference
      • Events
        • 🚀Quickstart: Events
        • â„šī¸Standard List View
        • â„šī¸Getting Started with Event Filtering & Searching
        • â„šī¸Filter by Category
        • â„šī¸Filter By Host (Author)
        • â„šī¸Filter by Event Dates
        • â„šī¸Datasourcing the Event Host
        • â„šī¸Search
        • â„šī¸Map List View
        • â„šī¸Calendar List View
      • FAQ
        • 🚀Quickstart: FAQ
        • đŸ’ģReference
      • Testimonials
        • 🚀Quickstart: Testimonials
        • đŸ’ģReference
      • Slider
        • 🚀Quickstart: Slider
        • đŸ’ģReference: Slider
    • Community Modules
      • đŸ—ī¸SiteBuilder
      • 🚀CRM Sync
        • â„šī¸About CRM Sync Module
        • 📋Steps to Set Up CRM Sync on an Automation
        • đŸ—“ī¸CRM Sync Changelog
    • Go Further: Modules
      • â„šī¸Front-end Submit Modules
  • WebApps
    • 🚀Quickstart: WebApps
    • WebApp Items
      • 📋Create WebApp Items
      • 📋Importing and Exporting
    • Layouts
      • â„šī¸WebApp List Layout
      • â„šī¸WebApp Detail Layouts
    • Go Further: WebApps
      • 📋Searching by Location
      • 📋Searching - Advanced Filtering
      • 📋Searching - By Keyword
      • 📋Front End Create Forms
      • 📋Front End Update Forms
      • 📋Front End Delete
  • WebApp Troubleshooting
  • eCommerce
    • 🚀Quickstart: eCommerce
    • Get Started
      • 💡About the eCommerce Module
      • Settings
      • 📂Cart, Checkout and Quotes
        • 💡About Cart, Checkout and Quotes
        • 📋Steps to Implement a Guest Checkout Flow
        • 📂Product Views
          • 🔹Product Layouts
          • 🔹Product List Layout
          • 🔹Product Detail Layout
          • 🔹Add to Cart Button
          • 📋Steps to Datasource and Display Related Products
          • 🔹Dynamic Product Layouts based on Categories
          • 📂Attribute Selection
            • 🔹Attribute Layout - Presenting the Choice to the Customer
            • 🔹Attributes - Changing Product Price after Change
          • 📂Discount Selection
            • Discount Codes Layout
            • Minimum Payments
          • 📂Shipping Selection
            • Shipping Options Layout
        • Managing Products
          • Creating and Editing
          • Securing Products
          • Location
          • Custom Fields
          • Edit Module Structure
          • Product Custom Field Sets
          • Inventory
          • Managing Attributes
          • Pricing
          • Product Categories
          • Open Graph Fields
          • SEO Fields
          • Standard Fields
          • Product Import and Export
          • Discounts
        • 📂Cart
          • 🔹Cart Layouts
          • Checking Inventory in Cart
          • Updating Quantity in Cart
          • Updating Displayed Cart Quantity
        • 📋How to Set Up a Shopping Cart and Guest Checkout - Tutorial
        • 📂Checkout Forms
          • 🔹Checkout Form Layouts
          • 🔹Checkout Forms with PayPal
        • 📂Orders
          • Order Confirmation
          • Re-Ordering
          • 🔹Orders Layouts
        • 📋Steps to Add Secure Zones and User Orders View to your Checkout Flow
        • Quotes
        • Selling Digital Products
        • 🔹Volume Pricing
        • 📋Steps - Alternatives to Product Grouping
      • 📂Basic Payment Forms
        • 💡About Basic Payment Forms
        • 📋Steps to Set up a Basic Payment Form (with a Fixed Payment Amount)
        • 📋Authorize.net Basic Payment Forms
        • 📋PayPal Basic Payment Forms
        • 📋Steps to Allow User to Decide Amount they Will Pay
        • 📋Step-by-step Basic Payment Confirmations
        • 👀Basic Payment Forms Reference
        • â„šī¸ecommerce/basic_payment
      • 📂Payment Gateways
        • đŸ’ģBuilding a Custom Payment Gateway
          • 📋Steps to Support Basic Payment Forms with your Custom Payment Gateway
          • 📋Steps to Support Checkout with your Custom Payment Gateway
        • 🔹Paypal Custom Parameters
        • 🔹Styling Stripe Card Elements
        • 💡About Payment Gateways
        • 📋Steps to Switching Payment Gateway
        • 🔹Test Cards
      • 📂Currency and Tax
        • 💡About Tax Codes
        • Currency Changer
        • Tax Code Changer
        • Formatting Currency
      • 📂Subscriptions
        • 💡About Subscriptions
        • Managing Subscriptions
          • Creating Subscription Products
          • Changing Price and Billing Interval
          • Creating a Form for Signing Up and Changing Payment Details
          • Subscription Order Status Explained
          • Terms and Conditions (Good Practice)
        • 📋Subscriptions Payment Gateway Setup
        • Subscriptions List Layout
        • Subscriptions Detail Layout
        • User's Active Subscriptions
        • Subscription Action Required
        • Cancelling Subscriptions
      • đŸŒŗBasic Payment Forms Folder Structure
      • đŸŒŗCart and Checkout Folder Structure
  • CRM
    • 🚀Quickstart: CRM
    • Users
      • User Details
      • User Secure Zones
      • How Users Edit their Email and Password Front End
      • Custom Field Sets & CRM Custom Fields
      • Storing User's Favourite WebApp / Module Items
    • Companies
    • Cases
      • User's Form Submissions (Cases)
  • Site Manager
    • Code Editor
    • Templates (Pages & Email)
    • Headers & Footers
    • Code Snippets (Includes)
      • 🔧Includes Troubleshooting
      • 👀constants_json
      • 👀constants
      • đŸŒŗIncludes File Structure
      • đŸ’ģIncludes with Siteglide CLI
      • 🔧Tags for Includes
    • System Pages
      • Automatic Site Maps
    • System Emails
    • Data Management
    • Admin Menu Editor
    • Integrations
  • Reporting
    • 🚀Quickstart: Reports
  • Miscellaneous
    • System Features
      • Pagination on Liquid Tags
      • Custom Pagination Layouts
      • Timezones in the Siteglide Admin and on the front-end of your Site
      • Module/WebApp Caching
      • Getting Started with Liquid Caching - to Reduce Server Response time and Improve Performance
      • Translating Dates
      • Site Search
      • About Site Search
      • AI Tools for the Rich Text Editor
      • Cookies on Siteglide Sites
    • Front-End Performance
      • Video Embeds
      • Forms Above the Fold
Powered by GitBook
On this page
  • Introduction
  • Glossary of Terms
  • Building your first query using Related Records
  • Step 1) Write your query to fetch Blog Posts
  • Step 2) Find out which fields match across the two tables
  • Step 3) Add related_records inside results
  • Step 4) Rename the related_record
  • Step 5) Set the join_on_property
  • Step 6 - Set the Foreign Property
  • Step 7 - Set the Table
  • Step 8 - Results
  • Step 9 - Working with the Results
  • A many:1 alternative
  • Step 1) Change the initial query to fetch Authors first and rename:
  • Step 2) Change join on property to Author's ID
  • Step 3) Change foreign property to Blog's property which contains Author's ID
  • Step 4) Change related table to Blog
  • Step 5) Change related_record to related_records and rename
  • Step 6) Change Results
  • Step 7) Liquid example
  • Further Learning

Was this helpful?

Export as PDF
  1. Developer Tools
  2. GraphQL
  3. Tutorials

Tutorial 12 - Related Records and Datasources

Introduction

In this tutorial we're going to show you how you can use a single query to get not only results in a single table, but at the same time return related results from another table.

For example:

  • Products may be related to categories- and each category may be related to some help articles.

  • Blog Articles may each be related to an Author, and that Author may have a relationship with some Secure Zones.

Using related_records is powerful because:

  • It allows you to build more complex applications - giving you complete control over getting the data you need.

  • It's flexible - if you've stored enough data, you can define relationships in your query without changing any settings.

  • Combining multiple queries into one will give you much better performance than any other way of getting this data, e.g. nesting Siteglide include tags inside each other.

Glossary of Terms

Here are a few of the terms you may come across in this topic:

Term
Definition

relational database

A relational database describes a database comprised of tables, where there may be predefined relationships between records in different tables. platformOS's database is a kind of relational database.

join

In many query languages e.g. SQL, a join defines how two tables are linked together. In platformOS, a join on property is used to define which field should be used to find other related_records.

tables

In platformOS, as in many other databases, a table is a set of data which contains records of a certain type, with a certain set of properties.

records

In platformOS, as in many other databases, a record is a single entry of data in a database.

related_records

In platformOS, records which share a relationship. It can be single:single, many:many or single:many. This is effectively the same concept as a datasource.

datasource

In Siteglide, a datasource is where there is a relationship between records in the same table or in a different table, and data can be "sourced" from that other table. It can be single:single, many:many or single:many. This is effectively the same concept as platformOS's related_records.

datasource and datasource_multi field types

foreign

In platformOS, a foreign property refers to a property outside of the current record. The foreign property is matched with the join on property in order to fetch related records which share a relationship.

data graph

In computing a data graph describes the relationships between different nodes of data. Think of a node like a city and the relationships like roads. One of the reasons GraphQL is called GraphQL is that it is trying to give queries an intuitive graph-like structure- we define the relationships in the query itself, and the results return with the same relationship structure.

Building your first query using Related Records

The great thing about related records being as flexible as they are is that there are a lot of examples we could choose from. Our first example though will try to keep things simple by fetching Blog posts with their associated authors.

Step 1) Write your query to fetch Blog Posts

We've already covered how to write a records query and filter it so it contains only blog posts. Here's an example:

query blogsWithAuthors {
  records(
    per_page: 20,
    filter: {
      table: {
        value: "module_3"
      }
    }
  ) {
    results {
      id
      properties
    }
  }
}

Step 2) Find out which fields match across the two tables

Since these two modules - the Blog and Authors Module - are both created by Siteglide, they already store the information needed to join them inside their properties. We only need to look at the existing properties in detail to get the information we need to build our query.

For this exercise, we'd be looking at module_3 for blog and module_6 for authors.

In Blog, scroll down or use ctrl-f to search for author The form configuration will contain both the human-friendly name and the Siteglide ID for each field:

module_field_3_4:
      name: Author
      type: datasource
      live: true
      hidden: false
      order: 0
      editable: true
      datasource_id: module_6
      required: false
      validation: {}

Great! It's a datasource field, which is pefect, because it will already be set up to contain IDs of Author records related to each Blog record. We don't need to look at the Author record now to know that the module_field_3_4 property of the Blog and the id of the Author should match. Sometimes, you'll need to look at both.

Since this is a GraphQL tutorial- here's an alternative way to check the form-configurations- using a query (see how we use filter to look for only the Blog and Author configurations)!

query findBlogAndAuthorProperties {
  admin_forms(filter: {name: {value_in: ["module_3","module_6"]}}) {
    results {
      fields
    }
  }
}

In the Siteglide Admin, we can check that some of the Blogs already have authors set in the datasource field, in this case this Blog item has an Author ID of 100 in the field:

Step 3) Add related_records inside results

To start with, look inside results in explorer: related_record and related_records appear as possible results. By including these special objects inside the results object, we can define a branching tree of related results.

The two options are similar but have one key difference:

  • related_record - Use this to define a 1:1 or a many:1 relationship. It will return a single record as an object. This may give you better performance, if you know for example there's only one author.

  • related_records - Use this to define a 1:many or a many:many relationship. It will return multiple records as an array.

The main reason to pay attention to which you choose is that it will change the way you structure your Liquid to access the data- remember if there is an array in the data you may need to loop over it in order to access it.

For now, let's use related_record, as we have a datasource field to join with, and only one Author per Blog record:

query blogsWithAuthors {
  records(per_page: 20, filter: {table: {value: "module_3"}}) {
    results {
      id
      properties
      related_record() {
        
      }
    }
  }
}

Step 4) Rename the related_record

Remember, we use a string with no spaces and a colon to "rename" things in GraphQL. It's a good idea to rename this related_record to describe what it will return. In this case, it describes a single author.

query blogsWithAuthors {
  records(per_page: 20, filter: {table: {value: "module_3"}}) {
    results {
      id
      properties
      author: related_record() {
        
      }
    }
  }
}

This will make it easier to understand the results and allow you to add other related_records in future (it won't let you if names clash).

Step 5) Set the join_on_property

As mentioned in the glossary, the join_on_property is used to define the property in the current result record which will be used to match with a related record. In step 3 we worked out it was module_field_3_4.

  • We don't need to write the value of the module_field_3_4 field, just the Siteglide field ID.

  • you also don't need to add properties before the field ID, as you may when filtering a query; here, platformOS works this out automatically

  • this goes inside the curly brackets as an argument

query blogsWithAuthors {
  records(per_page: 20, filter: {table: {value: "module_3"}}) {
    results {
      id
      properties
      author: related_record(
        join_on_property: "module_field_3_4"
      ) {
        
      }
    }
  }
}

Step 6 - Set the Foreign Property

The foreign property is the counterpart to the join_on_property, but it refers to the property in the record we are looking for, in this case the Author record is the record, and the property is id.

query blogsWithAuthors {
  records(per_page: 20, filter: {table: {value: "module_3"}}) {
    results {
      id
      properties
      author: related_record(
        join_on_property: "module_field_3_4",
        foreign_property: "id"
      ) {
        
      }
    }
  }
}

Note the syntax is the same, even though module_field_3_4 is a custom property and id is a core property in platformOS.

Step 7 - Set the Table

table here is a filter, despite not being inside a filter object. It must be set to describe the table we should look in for these related records. In this case, the ID of the Authors module: module_6

query blogsWithAuthors {
  records(per_page: 20, filter: {table: {value: "module_3"}}) {
    results {
      id
      properties
      author: related_record(
        join_on_property: "module_field_3_4",
        foreign_property: "id",
        table: "module_6"
      ) {
        
      }
    }
  }
}

Step 8 - Results

We've already defined which results we want for Blog items, and that we want to return a related author per blog item, but we also need to define which authors properties should be returned.

We could return the whole properties object, but where possible it's worth being extra efficient when working with relationships. There is more work for the query to do, and it may run more slowly. Maybe we just need the author's name and an image (I use the information we looked at in step 2 to find the module_6 image field ID)?

The results go in the new object under related_record after the arguments; no results key is needed:

query blogsWithAuthors {
  records(per_page: 20, filter: {table: {value: "module_3"}}) {
    results {
      id
      properties
      author: related_record(
        join_on_property: "module_field_3_4",
        foreign_property: "id",
        table: "module_6"
      ) {
        name: property(name: "name")
        image: property(name: "module_field_6_4")
      }
    }
  }
}

That's the query itself done!

Step 9 - Working with the Results

The results in JSON may look like the below (we've minimised Blog properties which aren't useful to the example):

{ 
 "data": {
   "records": {
     "results": [
       {
         "id": "97",
         "properties": {...}, # note - this record 97 did NOT have a match with an author. Maybe the Author has been deleted or maybe the ID has not been stored in the field we're joining on.
         "author": null 
       },
       {
         "id": "8",
         "properties": {...}, # note this blog item with ID of 8 DID match with an author- the author's fields we asked for are below!
         "author": { 
           "name": "Jese Leos",
           "image": "https://cdn.staging.oregon.platform-os.com/instances/10093/assets/jese-leos.png"
         }
       },
       {
         "id": "10",
         "properties": {...},
         "author": {
           "name": "Karen Nelson",
           "image": "https://cdn.staging.oregon.platform-os.com/instances/10093/assets/karen-nelson.png"
         }
       }
     ]
   }
 }
}
{% graphql blogs_with_authors = "blogsWithAuthors" %}
{% for blog in blogs_with_authors.records.results %}
  <h2>{{blog.properties.module_field_3_1}}</h2>
  <div>
    By: {{blog.author.name}}
    <img src="{{blog.author.image | asset_url}}">
  </div>
{% endfor %}

A many:1 alternative

What if you need this to fetch information the other way around, e.g. you are on a page which displays information about an author and you wish to display a list of the Author's Blog Posts? An additional aspect to this is that this is a 1:many relationship- it's no problem- we'll use related_records plural instead of related_record to return an array instead of an object.

Starting with the query above, lets make some changes:

Step 1) Change the initial query to fetch Authors first and rename:

query AuthorsAndTheirArticles { #renamed
  records(per_page: 20, filter: {table: {value: "module_6"}}) { #change table
    results {
      id
      properties
      author: related_record(
        join_on_property: "module_field_3_4",
        foreign_property: "id",
        table: "module_6"
      ) {
        name: property(name: "name")
        image: property(name: "module_field_6_4")
      }
    }
  }
}

Step 2) Change join on property to Author's ID

query AuthorsAndTheirArticles { #renamed
  records(per_page: 20, filter: {table: {value: "module_6"}}) { #change table
    results {
      id
      properties
      author: related_record(
        join_on_property: "id", #edit join
        foreign_property: "id",
        table: "module_6"
      ) {
        name: property(name: "name")
        image: property(name: "module_field_6_4")
      }
    }
  }
}

Step 3) Change foreign property to Blog's property which contains Author's ID

query AuthorsAndTheirArticles { #renamed
  records(per_page: 20, filter: {table: {value: "module_6"}}) { #change table
    results {
      id
      properties
      author: related_record(
        join_on_property: "id",#edit join
        foreign_property: "module_field_3_4", # edit foreign
        table: "module_6"
      ) {
        name: property(name: "name")
        image: property(name: "module_field_6_4")
      }
    }
  }
}

Step 4) Change related table to Blog

query AuthorsAndTheirArticles { #renamed
  records(per_page: 20, filter: {table: {value: "module_6"}}) { #change table
    results {
      id
      properties
      author: related_record(
        join_on_property: "id",#edit join
        foreign_property: "module_field_3_4", # edit foreign
        table: "module_3" # edit table
      ) {
        name: property(name: "name")
        image: property(name: "module_field_6_4")
      }
    }
  }
}

Step 5) Change related_record to related_records and rename

query AuthorsAndTheirArticles { #renamed
  records(per_page: 20, filter: {table: {value: "module_6"}}) { #change table
    results {
      id
      properties
      articles: related_records(
        join_on_property: "id",#edit join
        foreign_property: "module_field_3_4", # edit foreign
        table: "module_3" # edit table
      ) {
        name: property(name: "name")
        image: property(name: "module_field_6_4")
      }
    }
  }
}

Step 6) Change Results

query AuthorsAndTheirArticles { #renamed
  records(per_page: 20, filter: {table: {value: "module_6"}}) { #change table
    results {
      id
      properties
      articles: related_records(
        join_on_property: "id",#edit join
        foreign_property: "module_field_3_4", # edit foreign
        table: "module_3" # edit table
      ) {
        title: property(name: "module_field_3_1")
        slug: property(name: "slug")
      }
    }
  }
}

Step 7) Liquid example

{% graphql authors_and_their_articles = "AuthorsAndTheirArticles" %}
{% for author in authors_and_their_articles.records.results %}
  <h2>{{author.properties.name}}</h2>
  <div>
    Articles Published:
    <ul>
      {% for article in author.articles %}
        <li>
          <a href="/siteglide-blogs/{{article.slug}}>{{article.title}}</a>
        </li>
      {% endfor %}
    </ul>
  </div>
{% endfor %}

Further Learning

Next, you could experiment with some of these options:

  • using filters to further filter related records e.g. Authors with Blog posts which are enabled

  • using related_users an alternative to related_records which fetches CRM users with a relationship to your record. You don't need to specify a table, but join and foreign properties work the same.

  • Additional nesting. Inside your related_records results, you can define related_records again. This allows you to build a complex results tree containing as many layers of related results as you like, for example adding to our example above- you could return the categories of each Blog the Author had published- and display a list of category names.

PreviousTutorial 11 - Using Mutations to Delete an ItemNextConfiguration

Last updated 4 months ago

Was this helpful?

In Siteglide, some fields can be given the datasource and datasource_multi field types: These are designed to store IDs of other records to make joining easy. However, you can also in GraphQL join other types of fields.

There are several ways to do this. One of the easiest to do on an everyday basis is to use to pull your site, then to look in marketplace_builder/form_configurations e.g. 'marketplace_builder/form_configurations/forms/form_1.liquid' or 'marketplace_builder/form_configurations/modules/module_3.liquid':

As always, when outputting in Liquid, you can use dot notation (see or ) to access the results, until you get to an array. Since we only asked for a single author, we can use dot notation inside the blog record to access the author. We still need to loop over the blog results as always:

📋
Introducing Siteglide CLI
Liquid Dot Notation
Tutorial 5 - Using Liquid to run GraphQL queries on your Site
Field Types