Document main IR classes

[GregoryTravis]

Pull Request Description

Important Notes

Checklist

Please ensure that the following checklist has been satisfied before submitting the PR:

• The documentation has been updated, if necessary.
• Screenshots/screencasts have been attached, if there are any visual changes. For interactive or animated visual changes, a screencast is preferred.
• All code follows the
  Scala,
  Java,
  TypeScript,
  and
  Rust
  style guides. In case you are using a language not listed above, follow the Rust style guide.
• Unit tests have been written where possible.
• If meaningful changes were made to logic or tests affecting Enso Cloud integration in the libraries,
  or the Snowflake database integration, a run of the Extra Tests has been scheduled.
  • If applicable, it is suggested to paste a link to a successful run of the Extra Tests.

[radeusgd]

In the first paragraph it says that column expression is one of Column/Operation/Constant/Literal/Text_Literal, and only later we see it can also be the Let.

I'd rephrase to also include Let/Let_Ref in the first paragraph perhaps with a note "which are explained later".

[radeusgd]

I'd distinguish Query from Literal_Values - they differ quite a lot.

Suggested change

	table built from other tables (`Join`, `Union`), or a constant value (`Query`,
	`Literal_Values`).
	table built from other tables (`Join`, `Union`), from a raw SQL query passed as text (`Query`) or constructed from constants
	`Literal_Values`).

[radeusgd]

This sentence ("can be thought o as not being attached to a particular table") is a bit confusing to me.

The DB_Column is standalone and not necessarily directly tied to a DB_Table, but from SQL/DB standpoint it often is tied to some table (or more complex context).

Maybe,

Suggested change

	values can be thought of as not being attached to a particular table. Instead,
	values are standalone and not directly tied to `DB_Table` instance. Instead,

[radeusgd]

Perhaps this may be worth mentioning:

And also we can 'merge' DB Columns that have the same Context into a single DB_Table e.g. via DB_Table.set, allowing to add more derived expressions to existing tables. This is verified by the check_integrity method.

[radeusgd]

I'd rephrase something about this - both of these 'serve as a table expression' it is not bringing that much information. I think we can try to describe them in a more distinct way.

I'd say that (but still needs a bit better phrasing): the Context is everything that is after the FROM clause in SQL - from where we are taking the data (the From_Spec) as well as other modifiers - WHERE, ORDER BY etc. The From_Spec is then just the 'shape' that the FROM part itself can take. It is not a table expression on its own IMHO - it may just refer to tables or their combinations, but a table expression is more.

[radeusgd]

Do you remember from the London meetings if we wanted to rename these? Because I think there was some suggestions but I don't remember know what it was. We should probably find the sketches we made.

[radeusgd]

I think this is not exactly true. The 'alias' is just one 'use-case'.

What Sub_Query does is it nests a full sub query into the From_Spec, meaning that a whole Context plus a set of column expressions (SQL_Expression) are nested in it and then a new set of columns that reference this new context can reference the columns from within that nested subquery.

It allows more than aliases, as the subquery can contain more complicated expressions that from now on can be referenced just by their names.

Well after a thought perhaps that's what you mean by 'replacing column expressions with aliases', but it was not immediately clear to me so I was wondering if we could add some details, and perhaps an example here?

To show that e.g. when we have a query SELECT 1+2*T.A, T.B FROM T the subquery allows to refer to the 'complex' expression 1+2*T.A by a simple alias name: e.g. becoming SELECT SUB.EXPR1, SUB.B FROM (SELECT 1+2*T.A AS EXPR1, T.B AS B FROM T) AS SUB.

---

I don't know, perhaps I'm overcomplicating this explanation too much. I just wanted to more clearly show that Sub_Query allows 'baking' in some complex expressions and giving them 'simpler' names - in that regard it has some similarity to the Let construct as well although it has different use-cases because it also creates the sub-expression which (as you noted) makes any ORDER BY etc. from the outer query independent from the inner.

[radeusgd]

Ooops I completely missed that you actually described this very well in a section some lines below 🤦 Sorry.

The explanation below looks perfect. I'd then just add 'see section ... for more explanation of subqueries'.