Created by: vovakulikov

Related to https://github.com/sourcegraph/sourcegraph/issues/33933

Background

I'm just trying to develop a more straightforward API than our existing one in this PR. By this I mean going away from chart type abstraction in our mutations (createLineChart, createBarChart, cratePieChart ...etc) and moving to mutation that are based on our domain insight model (create<SearchInsight | Capture group | Lang stats | ... > mutations)

This PR aims to solve only the insight entity part in our GQL API. The dashboard model is outside of the scope of this PR. This should be used for informational purposes only and should not be used or merged anywhere in the backend codebase.

Data types

So, in a nutshell, in this PR schema, I split all insights that we have into two categories

• Series like (data that represents points through time)
• Categorical like (data that doesn't have any timeline-like information and has a clear set of categories and their values)

After that, we can express all possible insights that we currently have through those types.

• Capture group insight - series-like
• Search based insight - series-like
• Lang stats insight - categorical like
• Compute? - categorical like

If we need to add a new type of insight - let's say treemap we won't change anything about the existing API and extend our API with another type. See NewInsight union type in this PR schema.

Chart types

We can determine a set of visual settings for the insight model based on data types. This means that the data type determines the set of possible chart types.

• Series-like data - line chart, bar chart
• Categorical-like data - pie chart, bar chart (but with ordinary x axis), bubble chart ...

By this, we force only possible chart types for insight data that we have in our API. For example, it doesn't make sense to have Pie Chart for series-like data. (In theory, we could introduce another presentation chart type as a series of pie chart snapshots, but this is out of this PR's scope)

Another good thing is in this system, it is possible to have a strict set of chart type settings in GQL types because charts from one group should have the same amount of settings. See related slack message about this

From this slack message

From my understanding, if we have data that goes through time (series-like data), there is no difference between different chart types in terms of their visual settings.

For example, if we have a line chart and we change it to a bar chart, then

• line colour becomes bar colour
• stacked line setting (when we stacked one line on another) becomes a stacked bar
• start from zero setting is also applicable for the bar (maybe not, not sure, maybe it always should be active for the bar chart)

Same thing for categorical line chart? Let's say we change the pie chart to the bar chart

• pie arc colour becomes bar colour
• ... something else?

Also, here is another issue in which we may want to introduce new chart/insight settings https://github.com/sourcegraph/sourcegraph/issues/33327

Mutations

Well, here, things have been simplified dramatically. Data types and chart types are related to feature details and the settings world.

The insight model itself comes from the domain model of our product. So I decided to pick this abstraction for the mutations rather than implement mutation with data-type and chart-type attributes because it makes more sense when creating entities and matches our domain better, for example.

We have different pages for each insight type (search-based, capture group, lang-stats), which means we have a clear separation between insight types, and this is good because each type has a different amount of domain settings.

So mutations look like

createSearchInsight(input: SearchInsightInput): SeriesLikeInsight
createCaptureGroupInsight(input: CaptureGroupInsightInput): SeriesLikeInsight
createLangStatsInsight(input: LangStatsInsightInput): CategoricalLikeInsight

updateSearchBasedInsight(input: SearchInsightInput): SeriesLikeInsight
updateCaptureGroupInsight(input: CaptureGroupInsightInput): SeriesLikeInsight
updateLangStatsInsight(input: LangStatsInsightInput): CategoricalLikeInsight

SearchInsightInput, CaptureGroupInsightInput, LangStatsInsightInput contain business and view logic, in output we have data-type models.