[Lens] Discuss whether calculations should use a text-based or form-based interface

[wylieconlon]

As proposed in #57289, one of the ways we could expose calculations in Lens is by asking our users to type into a text box. Another way that was not considered in that issue is a form-based approach, more like how some of our own products like TSVB are set up.

The main questions to answer are:

• Is a text-based grammar the best user interface, as opposed to a form-based interface?
• How much overlap in functionality is there with other grammars that we already maintain, such as the expression language, TinyMath, and painless?

Text-based vs form-based

Pros of text	Cons of text	Pros of forms	Cons of forms
Highly expressive for users	Harder to learn for users, even in the best case	Easy to learn for users	Less expressive and composable
Fits in a small space	Longer development time		Uses a lot more space
Powerful once learned	Users have to make more decisions	The product can make more decisions for the user

How much overlap in functionality is there?

We have many grammars that already solve different problems for users. I think that when we are looking at building a new grammar, we need to first see if we can teach users an existing grammar. Before evaluating the existing languages, we need to look at the requirements for calculations:

Requirement	Comments
Define ES aggregations	Examples of composing many aggregations in TSVB are good for this use case
Combine two tables	This is required for time comparison, or any calculation involving a lookup
Basic math	Self-explanatory
Relational algebra	Users should be able to apply SQL-like operations on any data that they have, which is the highest level of functionality we can provide on data

Name	Can create aggregations	Can combine two tables	Can do basic math	Relational algebra
Query DSL	Yes, with JSON	No	Using painless	Bucket selector and bucket script let you do some, but not all
Painless	No	No	Yes, but only in certain context	No
Expressions	Very hard to type, but technically possible	Not currently, but could be added	Yes, using TinyMath	Some, using mapColumn or filterRows- Joins not yet supported
TinyMath	Not exactly	No	Yes	No
KQL	No	No	No	No
Timelion	Yes	Yes	Yes	Several options

Proposal for discussion

I think that a form-based approach is overall easier for users and easier to build, but for handling basic math we should pick one of the existing grammars that we already support. This will let us hide almost all of the complexity from users, as well as build the system incrementally. I could be proven wrong if one of these assumptions I am making is wrong:

• Our target user is interested in a low learning curve
• Our target user wants Lens to feel like a consistent user experience
• The set of features we are targeting involves time comparison, composing aggregations, basic math, and some relational algebra.

Also, I propose that we should separate out two parts of the user flow:

• Defining queries, including composing aggregations
• Defining a set of calculations to happen after the queries are run

This separation will improve the user experience, since building Elasticsearch aggregations has different requirements than what Lens can support for table logic.

[elasticmachine]

Pinging @elastic/kibana-app (Team:KibanaApp)

[flash1293]

I agree, @wylieconlon , thanks for putting these pros and cons together.

Besides the languages already widely supported in Kibana a user has to learn, there is also SQL and EQL on the roadmap (coming with their own overlapping functionality) which are very close to the use case we are trying to cover here.

Designing a syntax that can cover advanced use cases is very time consuming and will create a lot of maintenance costs for years to come. A form-based UI sounds more suitable for our use case.

The proposal sounds good to me - a form based approach for everything besides math using the already established TinyMath library.

As we are compiling to an expression under the hood anyway, we can give the user access to the expression later which will achieve a similar goal (giving the user a way to edit the data fetching in text form).

[monfera]

Good topics! Some of it relates to ongoing questions in kibana-expressions, eg. TinyMath is a parser+interpreter for numbers, is there, or should there be an extension for strings etc.

Besides text and flow, there are flow based representations. Those are sometimes applied at coarser grained functions, nodes being analogous to calc nodes in kibana expressions, but there are finer grained variations too where every operator eg. + is represented as a node in the graph.

We could look at user expectations, and analytics tools a user may be experienced with; these tools usually provide freeform text entry for expressions as mainstream entry, while also providing configuration (forms) based options for common cases eg. fitting a line on a series of points, or calculating percentages or a running total.

[AlonaNadler]

In general, I like the form-based approach, if done right it creates simplicity and really helps users understand the options.
My concern is that looking at what users are doing, I'm having a hard time imagining an effective way to represent it in a form that will solve a big portion of the need and will be easy and friendly.
Given a good solution, I'm happy to change my mind on this.

To me, syntax like painless, DSL, expression Timelion is not a valid option. It requires expertise and while I understand we prefer not to introduce another syntax. Using these syntaxes will continue the problems we currently have - hard to learn, complicated which require expertise. In addition in the future where Lens is the leading editor and the new runtime fields which Kibana will have in the future. Painless, Timelion would be used less and should not be a consideration. I suggest focusing on the right syntax for our users instead of consistency.

Many visualizations tools in the market have the ability to create calculations. The majority of them are using text-based syntax. Ideally, since it is a feature that should be used by users of all types, the low common denominator is spreadsheet formulas. This should help us with the many industries our users are coming from.

[VijayDoshi]

From what I've seen in this space, users tend to be able to master a text based model over time. Having one-click shortcuts for really common operations and an in-line guidance mechanism are really important though to help folks get over the initial hump and learn the grammar and language.

I worry the forms based approach will lead to composability complexity that will be never-ending. Happy to be wrong about that though, if there is a viable model. In my experience forms based approaches tend to be a tree and the need is a graph. This example is % difference, there is a one-click operation that gives you a formula.

[wylieconlon]

I appreciate these comments which are pointing out many of the positive elements of text-based systems. I am still proposing that we do not build one because of the negative elements that are associated with that kind of system.

[VijayDoshi]

@wylieconlon can you set up some time to walk me (and anyone else interested) through how you are thinking of accomplishing a forms based model; or point me to relevant content to review.

Also, would authoring in a form based model result in a text based output that could be edited?

[timductive]

@wylieconlon Some of the assumptions that you are making about the cons of a text-based editor may not be true as shown by @VijayDoshi, mainly, that it is harder to learn for users. I also suspect that the assumption about not wanting users to make more decisions is worth discussing.

I'm sure there are a lot more details to go through but it feels like we are trying to shut down this discussion prematurely.

[wylieconlon]

I do think it's important to separate out the discussion into small, incremental steps, and one of the parts of the proposal that I haven't gotten feedback on yet is that I proposed that we do math using TinyMath: this breaks down all calculations into two steps:

1. Configure the query using forms
2. Type your math using references to the preconfigured forms

There is more detail about how I propose using math here: #68969

[flash1293]

I think we decided about an approach here, more discussion will happen offline. If there's need to do more async discussion let's open a new issue as this one contains too much outdated context