Request for Feedback (SQL, Plisqin)

51 views
Skip to first unread message

Ryan Kramer

unread,
Jun 21, 2019, 12:41:31 PM6/21/19
to Racket Users
Target Audience: you have 10 minutes and you're familiar with libraries that do SQL kinda like this:

(from i "Item"
      (where i".ReleaseDate > '2018-01-01'")
      (select i".ItemName"))


Context: Plisqin is my SQL generation library, but I think of it as an "alternate query language" because theoretically it doesn't have to generate SQL. (But it probably always will.)

I'm gearing up to release Plisqin 0.3 and want to improve my documentation. If I can't explain these concepts to fellow Racketeers, I don't stand a chance of explaining them to the general public.

Thanks for any feedback!

Ryan Kramer

unread,
Jun 21, 2019, 12:42:35 PM6/21/19
to Racket Users


On Friday, June 21, 2019 at 11:41:31 AM UTC-5, Ryan Kramer wrote:
Target Audience: you have 10 minutes and you're familiar with libraries that do SQL kinda like this:

(from i "Item"
      (where i".ReleaseDate > '2018-01-01'")
      (select i".ItemName"))

Alex Harsanyi

unread,
Jun 21, 2019, 9:21:23 PM6/21/19
to Racket Users

While I am familiar with SQL, I am not familiar with any of the libraries you
mention on the wiki page (Ecto, Honey SQL and Slick), so maybe I am not the
target audience...

Your sections about "Joins Are Values" and "Aggregates are self-contained"
seem difficult to follow: I think I understand the overall idea, but it is not
clear from the document how any of it can be useful.  Also, it is not clear
what `Department?` and `Course?` are in the first code snippet -- are they
functions that the user has to provide or is it something that your library
generates by looking at the database schema?

I would suggest to provide a database schema and some sample data in a
database, and use this in the subsequent examples.  Start with a simple but
complete working example and construct more complex, but still complete and
working examples from them, at each step illustrating the benefits that the
library provides.  Maybe contrast each step with how the plain SQL would look
as well?

Alex.

Ryan Kramer

unread,
Jun 22, 2019, 1:16:56 AM6/22/19
to Racket Users
Thanks Alex, that was very helpful.

 
it is not clear from the document how any of it can be useful. 

I got this same feedback from some friends on the 0.1 release.

Also, it is not clear
what `Department?` and `Course?` are in the first code snippet -- are they
functions that the user has to provide or is it something that your library
generates by looking at the database schema?

I was planning on building the "generate functions by looking at the database schema" functionality later, but now I realize it might be a prerequisite for good documentation.

I would suggest to provide a database schema and some sample data in a
database, and use this in the subsequent examples.  Start with a simple but
complete working example and construct more complex, but still complete and
working examples from them, at each step illustrating the benefits that the
library provides.  Maybe contrast each step with how the plain SQL would look
as well?

I'm glad you said this because I am planning on doing this. I wrote the post you read hoping I could revise those ideas into a shorter, punchier "opening argument" before starting the slower walkthrough. But if it wasn't clear to you, I don't think I can possibly make it clear to Plisqin's target audience (some SQL experience, no Racket experience).

Documentation is hard!

Ben Greenman

unread,
Jun 22, 2019, 11:29:31 PM6/22/19
to Ryan Kramer, Racket Users
I don't know if I understood the "Aggregates are self-contained" section. The
SQL looks self-contained, as long as you read the whole query. And one has to
read the whole query in the Plisquin version too (but definitions come first).

In the last section, I'm not sure what a "scalar" or "plural join" are.
Reply all
Reply to author
Forward
0 new messages