What is the 'autojoin' feature in the Fields editor, and how do I use it?

[ryan]

What does autojoin do?

• Using the 'autojoin' optimization can increase performance on fields that get used a lot.
  
• Not using it can reduce the page's memory footprint.
  

What is more desirable in each instance depends on your situation.

What sites should use autojoin?

Autojoin is most applicable with larger sites. On smaller sites, there may be no benefit to using it or not using it. But it's good to know what it's for regardless.

Where do you control autojoin?

Autojoin is controlled per-field. You can turn it on by editing each field under Setup > Fields > [your field], and you'll see it under the 'Advanced' heading.

When should you use autojoin?

Autojoin causes the field's data to be loaded automatically with the page, whether you use it or not. This is an optimization for fields that you know will be used most of the time. Fields having their data loaded with the page can increase performance because ProcessWire grabs that data in the same query that it grabs the Page.

Autojoin is a benefit for fields that are always used with the Page. This is best explained by an example. Lets say that you have a template for individual news stories called news_story. The news_story template has these fields:

• title
  
• date
  
• summary
  
• body
  
• sidebar
  

We'll assume that when you view a page using the news_story template, all of the fields above are displayed.

Fields that should have autojoin ON:

Now consider a separate news_index template that displays ALL of the news stories together and links to them. But it only displays these fields from each news story:

• title*
  
• date
  
• summary
  

In this case, the 3 fields above would be good to autojoin since they are used on both the news_index and news_story templates. If your title, date and summary fields didn't have autojoin turned on, then ProcessWire wouldn't go retrieve the value from the database until you asked for it it (via $page->summary, for example).

Because the news_index template displays all the stories at once, and always uses the title, date and summary fields, it will perform better with title, date and summary having autojoin ON than with it OFF. In this case, it reduces the query load of the news_index template by 3 for each news story. To take that further, if it were displaying 20 news stories, that would mean 60 fewer queries, which could be significant.

Fields that should have autojoin OFF:

Now lets consider the body and sidebar fields, which are only used on the news_story template:

• body
  
• sidebar
  

It would be desirable to leave autojoin OFF on those fields because there is no reason for the body and sidebar to be taking up space in memory when they are never used on the news_index template. While it might mean 2 fewer queries to view a news story, that is not significant and certainly not a worthwhile tradeoff for the increased memory footprint on the news_index template. Keeping autojoin OFF reduces a page's memory footprint.

Conclusion

Using the 'autojoin' optimization can increase performance on fields that get used a lot. Not using it can reduce the page's memory footprint. What is more desirable in each instance depends on your situation. But if your situation doesn't involve lots of pages or data, then you don't need to consider autojoin at all (and can generally just leave it off).

Additional Notes

Not all fields have autojoin capability. You won't see the option listed on fields that don't have the capability.

*The title field has autojoin on by default, so you don't need to consider that one. It was included in the examples above because I thought it's omission might cause more confusion than it's inclusion.

Be careful with multi-value fields that offer autojoin capability (page references and images, for example). Because MySQL limits the combined length of multiple values returned from a group in 1 query, autojoin will fail on multi-value fields that contain lots of values (combined length exceeding 1024 characters). If you experience strange behavior from a multi-value field that has autojoin ON, turn it OFF. If you want to play it safe, then don't use autojoin on multi-value fields like page references and images.

[jbroussia]

Oh thanks, it was one of the rare points that was unclear to me. Again, your explanations make it obvious.

[Joss]

Eleven years later, but thanks for that, Ryan!

It was exactly the explanation that I needed.

[Ivan Gretsky]

Hey, @Joss! It's amazing to se you back ?