awslabs
Query stats text
We had some feedback today that this is confusing:
qldb> select * from foo
+-----+
| foo |
+=====+
| bar |
+-----+
1 document in bag (read-ios: 1, server-time: 11ms, total-time: 155ms)
The feedback was: "what is a bag?". I'd like to look at alternative text: (showing singular/plural forms)
- 1 value in set, 10 values in set
- 1 value in result, 10 values in result
- 1 value, 10 values
The first is similar to MySQL's 1 row in set. The third is similar to Postgres' (1 row).
To me, "set" in the first implies that the values are unique, which isn't always the case right?
Two is maybe a little verbose but it most closely matches the naming/language of the drivers (In the JS driver at least, executing a statement returns a Result which contains a list of Ion values). If we think two is too much or we don't think mentioning Result adds much value, then I prefer three.
I'm inclined to 2 and 3 because they look straightforward. My concern is that do we have more alternatives for "value"? The result is shown as some ion structs which could contain more "value"s, like ion values. So the "value" here might be a little confusing. That being said, I didn't come up with a good word better than "value".
Agree that "set" means that the values are unique, which is not necessarily true, "bag" is clearly the precise term, but confusing to the PartiQL neophyte. So "result" while lacking precision is unsurprising and not inaccurate.
For "value": the crux of the issue here is that the results of a PartiQL SELECT may be either tuples (Structs when materialized as Ion) or other Ion Value types. Could be worth an 'if' statement in the print out to say "tuples in result" vs "values in result."
throwing a couple more options out there for consideration (more on "bag" toward the bottom)
-
1 item in bag, 10 items in bag * i.e., keep "bag" and call the contents "items"? i'm not deep enough into ion/partiql to say whether or not "item" is a valid option. "item" also kinda sounds nice if we keep "bag"
-
1 element in bag, 10 elements in bag * using "element" from PartiQL's definition of Bag
about "bag"
i almost wonder if we should keep "bag" and encourage the customer to learn about it. maybe the issue is more about the developer guide flow, or about having a simple reminder/link to PartiQL. originally when i saw "bag" i didn't find it in the glossary, so i searched a couple different pages of the developer guide, and found it in one of the sub-pages within the PartiQL reference section. this leads me to think we might want to consider mentioning the bag concept directly in the shell guide: https://docs.aws.amazon.com/qldb/latest/developerguide/data-shell.html
perhaps that is also where we could clarify things that we're raising in this discussion - tuples vs values, etc. essentially a brief section of the shell guide saying "hey here's how our shell returns things that you query." this might also be helpful if someone is scripting against the shell in a non-interactive way (which is another thing we might want to mention in the shell developer guide page)
[edit] moving the "welcome message" bit to https://github.com/awslabs/amazon-qldb-shell/issues/148
To me, "set" in the first implies that the values are unique, which isn't always the case right?
Agree that "set" means that the values are unique, which is not necessarily true, "bag" is clearly the precise term, but confusing to the PartiQL neophyte. So "result" while lacking precision is unsurprising and not inaccurate.
(Not discounting the feedback.) I think MySQL uses 'set' ala 'result set'. Not Java Set<T>.
I really like "element/s in the bag". It's accurate without requiring much expertise.