REQ: Examples for documentation

[spazm]

I like the README. I think it would be improved by adding a specific use case to make it feel less abstract to a potential new user. Something like a SYNOPSIS section in a man page or perldoc.

Ideas for what would make a good example?

1. an example query where a dba might ask to change the query to improve query plan or similar, or change a join order. Then we could show breaking that down with named bindings, maybe splitting the subquery into it's own testable import?

I don't have the context, but I'm sure this a query or two that you've had to clean up (especially deep in the billing code!).

[soulstompp]

I like the README. I think it would be improved by adding a specific use case to make it feel less abstract to a potential new user. Something like a SYNOPSIS section in a man page or perldoc.

Now that we have a database easily available adding in some good examples to the docs won't be hard and I'd like to have a consistent schema throughout all of the examples and documentation.

Ideas for what would make a good example?

I think we could come up with some really nice examples using the [https://musicbrainz.org/doc/MusicBrainz_Database/Download](MusicBrainz database). We should be able to come up with very complex queries without making them too contrived. There is also a large dataset available for their schema, which is usually hard to find.

Also, lots of composers in that data ;)

1. an example query where a dba might ask to change the query to improve query plan or similar, or change a join order.  Then we could show breaking that down with named bindings, maybe splitting the subquery into it's own testable import?

Since this is a public domain database with pretty cool use cases, there are actually quite a few questions about it on stack overflow. We might find some good questions about queries on that db to use as a starting point.

[soulstompp]

A lot more examples to choose from than I expected on stack exchange actually: https://stackoverflow.com/questions/tagged/musicbrainz

[soulstompp]

Well most of those were related to the service but I found a nice simple example for binding:

• https://stackoverflow.com/questions/35795931/musicbrainz-sql-database
  And then a couple of really nice complex query questions that look like the kind of queries I get handed in the real world:
• https://stackoverflow.com/questions/47393677/musicbrainz-unable-to-count-artists-by-country
• https://stackoverflow.com/questions/45118550/query-sql-list-the-pairs-of-artists-who-have-never-collaborated-with-each-other
• https://stackoverflow.com/questions/50667063/sql-self-join-to-find-two-label-with-a-release-in-common-with-a-third-label