search

PRQL / prql

PRQL is a modern language for transforming data — a simple, powerful, pipelined SQL replacement
https://prql-lang.org
Apache License 2.0
9.93k stars 217 forks source link

SQL formatting of examples #3518

Open max-sixty opened 1 year ago

max-sixty commented 1 year ago

What's up?

There was a surprising amount of chatter on HN about the formatting of the SQL examples on our home page. For example:

It may be typical of many SQL users and formatters, but it leaves a poor taste in the mouth that you aren't interested in an actual comparison but in marketing.

Stepping back — the examples are used both to a) allow folks to easily understand what PRQL is doing and b) demonstrate how PRQL syntax is better than SQL syntax.

We want the best formatted SQL examples to use as a comparison to PRQL — I strongly agree that using a straw-man as a comparison is poor form.

Currently we're using the output of https://github.com/shssoichiro/sqlformat-rs, the canonical rust SQL formatter. While it's difficult to imagine we're doing that as part of a scheme to make the SQL look bad, we could make an adjustments for the examples if it's not producing well-formatted SQL.

Do folks have views on what the best formatted SQL is? Do we cut the line-breaks?

eitsupi commented 1 year ago

I was a dbt user (I recently changed jobs so I don't use it anymore), so I was using sqlfmt. sqlfmt prefers lowercase, but I'm not sure if this is common.

AaronMoat commented 1 year ago

It may be worth clarifying whether the goal of the homepage examples are for:

  1. To show here's what PRQL compiles to
  2. To show here's what you'd write in SQL

The HN comments indicate it is conveyed as 2.

If the goal is 1, formatting may not be the only solution (text or design changes, e.g. saying "compiles to...") could help reframe. Better/different formatting may also help.

If the goal is the 2, would handwriting the SQL be better, to give the best chance at being fair?

max-sixty commented 1 year ago

I do think it's both goals — similar to the two I listed above.

I'm happy to handwrite the SQL — do we have a view of what the "best" SQL is though?

AaronMoat commented 1 year ago

I think in the context of other issues like https://github.com/PRQL/prql/issues/1284 maybe a way forward isn't handwriting the examples, but handwritten formatting rules for the output of the compiler? If there's custom formatting logic in the repo it can be tuned over time (over trying to find the exact one everyone's happy with). Maybe directly when converting the query to a string over stringifying then formatting?

max-sixty commented 1 year ago

I definitely agree better SQL formatting would be helpful, and #1284 is a good issue for that...

But I would have thought that PRQL's needs are mostly the same as anything else looking for SQL formatting (though #1284 is a counter-example). And that it's no small effort to build a formatter!

If someone were really keen on this as a project, I wouldn't refuse it, but I would caution them on whether this was a good investment (and I think investing in PRQL generally is a great investment...). Instead, improving sqlformatter-rs seems like something that would have a wider impact, without much relative loss to PRQL...