paul-rogers opened a new issue #11588:
URL: https://github.com/apache/druid/issues/11588
Better SQL function help strings in query-builder UI
### Affected Version
Version: 0.21
### Description
Consider the "stock" Wikipedia data source and stock Docker Druid cluster.
We want to write a query that uses some of the time functions. To see what is
described here, you'll want to follow along in the UI.
Start with the following:
```sql
SELECT
__time,
channel,
page
FROM "wikiticker-2015-09-12-sampled"
```
Now, let's round the time to an hour. What function do we use? There is no
UI to tell us the available functions, we just have to look at the
[documentation](https://druid.apache.org/docs/latest/querying/sql.html). Many
products do have a list of functions so we can stay in the query builder. So,
that's the first UI feature request: list of functions, preferably grouped as
in the documentation.
Let's say we find the `FLOOR` function in the documentation. We start to
type:
```sql
SELECT
__time,
FLOOR
...
```
We get a choice list that includes the `FLOOR` function, along with this
"help":
```text
FLOOR
Syntax:
FLOOR(expr)
Description:
Floor.
```
So, the second UI request is that the help actually be helpful: at least
give the function signature and summary from the documentation:
```text
FLOOR
Syntax:
FLOOR(timestamp_expr TO <unit>)
Description:
Rounds down a timestamp, returning it as a new timestamp. Unit can be
SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, or YEAR.
```
By contrast, if we'd typed `TIME_CEIL`, the help would have been filled in.
So, it seems the help is spotty; sometimes you win, sometimes not.
Let's continue along. We type the opening paren, the UI fills in the closing
one and places the caret in between, ready for us to type:
```sql
SELECT
__time,
FLOOR(|)
...
```
Now, what are the arguments? By now, the help (as weak as it was) is gone,
we're left guessing. (Or, in reality, we flip back over to the documentation.)
Thus, the third UI request is to give guidance for the arguments. Three ways
this is commonly done are:
* Expression builder: separate dialog to build up the call. Rather
old-school.
* Phantom placeholders: when adding the close paren, show the function as
`FLOOR(<timestamp> TO <unit>)` with the two `<arg>` elements as hints that get
replaced as soon as the user starts typing. Great, but only works for new
expressions.
* Tool-tip hover hint: hover the cursor over the function to get the help
text from earlier. This works well all the time: new expressions and looking at
existing queries.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
