docs: guidance for WITH MUTUALLY RECURSIVE

[jseldess]

Documentation request

Plan is to document some practical examples of how to use this feature in the context of our priority use cases, in addition to reference docs.

Affected Pages

No response

Related work

No response

[aalexandrov]

@jseldess This issue is for the guidance docs, but I would like to start with the reference docs next week. I have some questions:

1. I have create a dedicated issue for the reference docs (#19483). Feel free to rename it / edit the issue description with guidelines about the contribution process and / or the document layout that you expect to see.
2. Is there an established high-level how a reference doc for a SQL-level concept should be structured, or am I free to invent one (I think that #18427 might relevant here)?

[jseldess]

Thanks for creating that reference doc issue, @aalexandrov. We don't have have a fixed style guide for reference docs, but I think it's possible to identify some basic conventions from existing pages.

In this case, though, I think the first question is:

Do we want to cover WITH MUTUALLY RECURSIVE as a new clause on the SELECT page, possible under the general category of CTEs (it is technically a CTE, right?)? Or do we want to create a standalone reference page? The latter would be breaking a convention, as we seem to have reference pages only for top-level SQL commands, but it might be worth considering. For example, we could add a page under SQL commands for WITH queries that cover the broader category of CTEs, and that we link to from the SELECT page. What are your thoughts? Also interested in @benesch's thoughts, in case there are strict historical rules that we should have SQL reference pages only for top-level commands, not clauses.

[benesch]

I'm not the historical expert here! I think @sploiselle has the context.

We have JOIN reference documentation under "transform data": https://materialize.com/docs/transform-data/join/. Possibly that is its own glitch, in that the reference doc is not under the "reference" section.

Anyway, the tl;dr here is that we have precedent for reference docs for clauses having top-level pages.

Hot take, having thought about this for about 60s, is that perhaps both JOIN and WITH MUTUALLY RECURSIVE should be subpages of the /sql/select page.

[benesch]

(it is technically a CTE, right?)

Yes!

[sploiselle]

WITH MUTUALLY RECURSIVE definitely deserves its own page given how unfamiliar users will be with it; I don't think adhering to convention/precedent should supersede making the docs as useful as possible.

I don't have any real historical context to provide other than I tried to get the docs built quickly and envisioned replacing the side nav with a search box eventually. Any lack of structure or inconsistency likely stems from that mindset.

[jseldess]

Thanks, @benesch and @sploiselle.

Given ^, @aalexandrov, I'd recommend we add a new WITH MUTUALLY RECURSIVE page under SQL commands and start with the basic structure on other SQL reference pages:

• Intro: Succinct description of the clause and its purpose.
• Syntax: Railroad diagram and table explaining fields and their use.
• Details: More detailed description of the feature and important things to note. (This section is most up in the air, to me, but I'd encourage you to write what you think users need to know and I'll help structure it).
• Examples: Concrete usage examples.

[aalexandrov]

@jseldess I've copy-pasted the above comment in #19483 and moved this issue (for the guidance docs) under the Follow-up Issues section in the enclosing #17012 epic. The plan is to add those after we collect some data points from our users.

If you think we should absolutely have this before we roll out the feature, I can move it back to the Required section.

[aalexandrov]

Copy-pasting links from offline conversation:

• https://github.com/MaterializeInc/demos/tree/main/ecommerce/loadgen
• https://github.com/MaterializeInc/materialize/tree/main/doc/user/content/quickstarts

Maybe those can be used as a starting point for tutorials that demonstrate the use of recursive queries.

[jseldess]

Thanks, @aalexandrov. I agree it's best to start with reference and work on guidance one we have more insight from users.

[ggevay]

Linking a non-trivial pattern that we should consider including: https://materializeinc.slack.com/archives/C02PPB50ZHS/p1685946750398139?thread_ts=1685759927.913449&cid=C02PPB50ZHS