Restructuring Expressions

[JPryce-Aklundh]

Current Expressions section is nested in Syntax chapter.

This PR will integrate them into more helpful places in the Manual (and not create a new Expressions chapter, the title of which is too vague/encompassing to be helpful).

Specific details:

• Expressions page deleted
• New Queries section (containing CASE and expressions in general from old Expressions page)
• New Subqueries section (containing COLLECT, COUNT and EXISTS subquery expressions from old Expressions page, and the CALL subquery page (previously in Clauses)).
• Type predicate expressions moved from old Expressions page as its own page in Values and types section

Additionally:

• New Queries section contains old Tutorial page from introduction (renamed Basic queries)
• Queries section also contains new Core concepts pafe

[neo-technology-commit-status-publisher]

Thanks for the documentation updates.

The preview documentation has now been torn down - reopening this PR will republish it.

[gem-neo4j]

I really like the new structure :) Added a few comments, let me know if you have any questions :D

[stefano-ottolenghi]

Let me say this is a great improvement. Also great you did some cleanup in the ex-tutorial page. 🤸

On a broader note, I wonder whether it would be better to use MERGE in the examples in Concepts, rather than MATCH, wherever possible? This would allow people to try out the examples without any preparatory steps, which I find valuable. If we use more equals and less <, > we should be able to always get some return from all queries (if we craft them smartly, even from the shortest path match ones).

[stefano-ottolenghi]

Just a note for us to remember to put redirects for

clauses/call-subquery
syntax
syntax/expressions
introduction/cypher_tutorial

[stefano-ottolenghi]

Same as for rules above: this is too abstract, too early. These, together with the rules above, make for good summaries, but we cannot put summaries at the top and explanations afterwards, because people read top to bottom and will be extremely confused in reading digests devoid of examples that they can't understand. All this content should be exemplified (and I think it is, which is great, like the first sentence "A CALL subquery is executed once for each incoming row." which shows up exactly the same in the first example), or brought up as admonitions in the relevant sections.

---

To further make my point, I'll try an analogy.

The current form is like the following.

You see an ad about a free swimming course. You've always wanted to swim decently, and it's free, so you decide to join.

When you go to the course the first time, the teacher meets you all in front of the swimming facility. Not inside, but in front. He tells you that today you are going to learn to swim free-style and breaststroke. You'r every excited to get started! He then starts talking about swimming technique -- not about points that motivate you to swim, mind you, but technique. You don't know how to swim, you can't see a swimmer, you can't even see the water, but here he is, rambling about how important it is that when you swim free-style your arms enter the water at 90 degrees angle, that the rotation of the hips is coordinated with the turn of the shoulders, but that mind you the impulse comes from the hips and only later travels to the shoulders, while the hand must have fully spread out fingers while in the air but contract them as soon as it reaches the surface, while of course you keep your feet pointed all the time, engage your abductors during each stroke, and god knows what more.

You don't know how much this rambling is going to go on, but he's effectively barring you from entrance and delivering you this low quality podcast of extremely fine swimming details which, while true, are absolutely unhelpful to you, who, in the best case, are unaware of where your abductors are even located (while one neighbor would swear she heard conductors and is trying to fathom how electricity fits in that speech, and another is frightened to get into the water up to her waist, and talks of hip rotation with head underwater just don't even register). When you think he's finally done, he does the same, but for breaststroke. A few people leave throughout the monologue and never even enter the pool.

Then two things can happen:

1. you are let into the facility, and the teacher says "all right! time to put into practice what we've learnt just a while ago!". She goes and sits on a bench expecting you all to be proficient swimmers because hey, you got all the details you needed, no? And while a few struggle to get into the water, a few others make it in, start to swim somehow, obviously not following 80% of what the teacher mumbled about, and wonder "what was it with the hips? I feel like they're sinking all the time. He said I needed to rotate them? When? Or was that the shoulders? Or am I mixing breast and free style?" The teacher watches in disbelief what looks like a bunch of uncoordinated dogs with seizures that sloppily crawl around with nothing resembling the 90 degrees he mentioned and the hip rotation ... and it's not even clear if they're swimming free-style or breaststroke! Didn't they pay attention? 😠 God, these students get more stupid by the week. She looks at the pool in dismal, watching the only student who is at least decent as proof that his explanations were fine ("the only one who listened!", or the only one who could swim already).
2. you are let into the facility, you all and the teacher get into the water, and she starts his monologue all over again, except this time each remark is followed by him showing it in practice, and you having the time to replicate it. He doesn't talk about hips until it's time. This is going well, you feel like you're getting the hang of it a bit. You don't pay too much attention to the fact that the initial monologue was pointless and utterly unhelpful. You don't remember much to be honest, other than being bored and not understanding, but the teacher is providing all the information you now need when you need it, so it's working, and whatever. Some time later you meet again a person that left before entering the pool, and they ask you how it went afterwards. "It was the best class I had, I learnt so much!" When you split again, he'll tell his girlfriend: "that guy is nuts - he got a verbal swimming class and thinks it was the best of his life".

---

Now, of course some intro is allowed in all circumstances. You need to be told not to inhale underwater, and to always exhale there, and that's info you should get in advance. But there's this much 🥜 buffer in our brain for this stuff, and we have to mega-carefully evaluate what we bring up when. If it is vital that we define returning and unit subqueries before we enter the swimming pool so be it (but I don't think so). But sentences like

Every output row of a returning subquery is combined with the input row to build the result of the subquery.

are to me, as a subquery beginner, just words in the air.

Show me my abductors first, then tell me to engage them.