Antlers and query builders

[robdekort]

I ran into an issue that had me very much confused today. I'm looping over a bunch of images coming from the asset fieldtype. The following code returns all items in the images array which is not at all what I expected.

{{ block:images | first }}
  {{ url }}
{{ /block:images }}

However this code does the expected: it only returns the first item in the array.

{{ block:images limit="1" }}
  {{ url }}
{{ /block:images }}

And then this doesn't work.

{{ block:images | limit('1') }}
  {{ url }}
{{ /block:images }}

Via @jacksleight I learned on Discord that there's such a thing as getting a query builder returned. He referred me here. However this is an asset fieldtype and not an entries and I didn't find a mention that that returns a query builder as well.

This stuff left me a bit confused and I have a few concerns I wanted to drop here as food for thought.

1. To me aliasing an array because you get something else returned seems counter intuitive. I don't really understand what a query builder is and I'm not sure if I even should in template land.
2. There doesn't seem to be any documentation on this. Not on the concept of query builders and not on a fieldtype and modifier level. This all matches how the docs describe stuff should work.
3. Some modifiers work on query builders (shuffle), others don't (reverse).
4. All syntaxes work on arrays, some on query builders.

I'm curious what others think and if there's something here that could be improved or clarified.

[jackmcdade]

Your second code block is way this is meant to work. I've never once thought of using first this way 🤔

{{ block:images limit="1" }}
  {{ url }}
{{ /block:images }}

[robdekort]

Docs would definitely be welcome here. At least for me :-). Mind you: I'm trying to convey the confusion from the point of view of a frontender just working with Antlers. When stuff looks the same but it isn't and behaves differently depending on the context I think that's a valid concern.

[jasonvarga]

We could make the first modifier work like you'd expect, that's probably doable.

[robdekort]

Could be nice for sure. To be clear: I'm in no way expecting changes ont his front. Just sharing my confusion regarding these behaviour and syntax differences.

[jasonvarga]

Yup but I'm saying if first worked like you expected then this post probably wouldn't have been started.

[robdekort]

Haha fair! It was the syntax that threw me off at first though. And I could see myself running into it trying to use other modifiers on query builders like this.