@cryptotaxi247 / netdata-1 / commits / e5bc59000

chore(go.d): revise funcapi docs (#21617)

Ilya Mashchenko committed Jan 22, 2026 at 21:50 UTC e5bc59000ad41a2e780805988f34e25cfbb1d333
5 files changed +132 -47
src/go/pkg/funcapi/columns.go
+43 -21
@@ -2,34 +2,56 @@
2
3 package funcapi
4
5 -// ValueOptions defines per-column formatting settings.
5 +// ValueOptions defines how the UI should format values in this column.
6 type ValueOptions struct {
7 - Transform FieldTransform
7 + // Transform controls value formatting (number, duration, datetime, text, xml).
8 + Transform FieldTransform
9 + // DecimalPoints sets numeric precision when using number formatting.
10 DecimalPoints int
9 - DefaultValue any
11 + // DefaultValue includes a default value in the UI response.
12 + DefaultValue any
13 }
14
15 // Column defines a table column for function responses.
16 type Column struct {
14 - Index int
15 - Name string
16 - Type FieldType
17 - Units string
18 - Visualization FieldVisual
19 - Sort FieldSort
20 - Sortable bool
21 - Sticky bool
22 - Summary FieldSummary
23 - Filter FieldFilter
24 - FullWidth bool
25 - Wrap bool
17 + // Index is the 0-based position in each row array and must match data order.
18 + Index int
19 + // Name is the header label shown in the UI.
20 + Name string
21 + // Type controls the base data type and default rendering.
22 + Type FieldType
23 + // Units sets the unit label shown next to values (use for numeric columns).
24 + Units string
25 + // Visualization selects the visual style (value, pill, bar, rich content).
26 + Visualization FieldVisual
27 + // Sort sets the default sort direction.
28 + Sort FieldSort
29 + // Sortable allows users to change the sort order in the UI.
30 + Sortable bool
31 + // Sticky pins the column during horizontal scroll.
32 + Sticky bool
33 + // Summary defines how values aggregate when grouping rows.
34 + Summary FieldSummary
35 + // Filter selects the filter UI type (range for numbers, multiselect for categories, facet for logs).
36 + Filter FieldFilter
37 + // FullWidth lets the column expand to fill available width.
38 + FullWidth bool
39 + // Wrap enables text wrapping for long values.
40 + Wrap bool
41 + // DefaultExpandedFilter expands this filter by default.
42 DefaultExpandedFilter bool
27 - UniqueKey bool
28 - Visible bool
29 - ValueOptions ValueOptions
30 - Max *float64
31 - PointerTo string
32 - Dummy bool
43 + // UniqueKey marks the unique row identifier column.
44 + UniqueKey bool
45 + // Visible shows the column by default.
46 + Visible bool
47 + // ValueOptions controls value formatting (transform, decimals, defaults).
48 + ValueOptions ValueOptions
49 + // Max sets the upper bound for bar-with-integer visuals.
50 + Max *float64
51 + // PointerTo includes a pointer target identifier in the UI response.
52 + PointerTo string
53 + // Dummy includes a dummy flag in the UI response.
54 + Dummy bool
55 }
56
57 // BuildColumn converts a Column definition to the JSON map used by the UI.
src/go/pkg/funcapi/columns_test.go
+3 -3
@@ -10,7 +10,7 @@ import (
10 )
11
12 func TestColumnBuildColumn_AllFields(t *testing.T) {
13 - max := 99.5
13 + maxVal := 99.5
14 col := Column{
15 Index: 3,
16 Name: "CPU",
@@ -27,7 +27,7 @@ func TestColumnBuildColumn_AllFields(t *testing.T) {
27 DefaultExpandedFilter: true,
28 UniqueKey: true,
29 Visible: true,
30 - Max: &max,
30 + Max: &maxVal,
31 PointerTo: "details",
32 Dummy: true,
33 ValueOptions: ValueOptions{
@@ -54,7 +54,7 @@ func TestColumnBuildColumn_AllFields(t *testing.T) {
54 assert.Equal(t, true, result["unique_key"])
55 assert.Equal(t, true, result["visible"])
56 assert.Equal(t, "ms", result["units"])
57 - assert.Equal(t, max, result["max"])
57 + assert.Equal(t, maxVal, result["max"])
58 assert.Equal(t, "details", result["pointer_to"])
59 assert.Equal(t, true, result["dummy"])
60
src/go/pkg/funcapi/enums.go
+55 -9
@@ -4,23 +4,35 @@ package funcapi
4
5 import "encoding/json"
6
7 -// FieldType defines the column data type.
7 +// FieldType defines the column data type used for rendering and alignment.
8 type FieldType uint8
9
10 const (
11 + // FieldTypeNone uses no special type handling.
12 FieldTypeNone FieldType = iota
13 + // FieldTypeInteger is for integer counts and metrics.
14 FieldTypeInteger
15 + // FieldTypeFloat is for fractional metrics.
16 FieldTypeFloat
17 + // FieldTypeBoolean is for true/false values.
18 FieldTypeBoolean
19 + // FieldTypeString is for text and categorical values.
20 FieldTypeString
21 + // FieldTypeDetailString is used when the UI expects the detail-string type.
22 FieldTypeDetailString
23 + // FieldTypeBarWithInteger is for progress-style values; set Max for bars.
24 FieldTypeBarWithInteger
25 + // FieldTypeDuration is for duration values paired with a duration transform.
26 FieldTypeDuration
27 + // FieldTypeTimestamp is for epoch timestamps paired with datetime transforms.
28 FieldTypeTimestamp
29 + // FieldTypeArray is for array values.
30 FieldTypeArray
31 + // FieldTypeFeedTemplate is for feed template rows.
32 FieldTypeFeedTemplate
33 )
34
35 +// String returns the UI keyword used for this field type.
36 func (t FieldType) String() string {
37 switch t {
38 case FieldTypeInteger:
@@ -48,22 +60,30 @@ func (t FieldType) String() string {
60 }
61 }
62
63 +// MarshalJSON encodes the field type as a UI keyword.
64 func (t FieldType) MarshalJSON() ([]byte, error) {
65 return json.Marshal(t.String())
66 }
67
55 -// FieldVisual defines how values are rendered.
68 +// FieldVisual defines how values are rendered in the UI.
69 type FieldVisual uint8
70
71 const (
72 + // FieldVisualValue renders plain values.
73 FieldVisualValue FieldVisual = iota
74 + // FieldVisualBar renders values as bars.
75 FieldVisualBar
76 + // FieldVisualPill renders values as pills for categories/status.
77 FieldVisualPill
78 + // FieldVisualRichValue selects the richValue visualization.
79 FieldVisualRichValue
80 + // FieldVisualFeedTemplate selects the feedTemplate visualization.
81 FieldVisualFeedTemplate
82 + // FieldVisualRowOptions selects the rowOptions visualization.
83 FieldVisualRowOptions
84 )
85
86 +// String returns the UI keyword used for this visualization.
87 func (v FieldVisual) String() string {
88 switch v {
89 case FieldVisualBar:
@@ -81,23 +101,32 @@ func (v FieldVisual) String() string {
101 }
102 }
103
104 +// MarshalJSON encodes the visualization as a UI keyword.
105 func (v FieldVisual) MarshalJSON() ([]byte, error) {
106 return json.Marshal(v.String())
107 }
108
88 -// FieldTransform defines value formatting.
109 +// FieldTransform defines how raw values are formatted for display.
110 type FieldTransform uint8
111
112 const (
113 + // FieldTransformNone leaves values unformatted.
114 FieldTransformNone FieldTransform = iota
115 + // FieldTransformNumber formats numbers and respects DecimalPoints.
116 FieldTransformNumber
117 + // FieldTransformDuration formats duration values.
118 FieldTransformDuration
119 + // FieldTransformDatetime formats millisecond timestamps (simple tables).
120 FieldTransformDatetime
121 + // FieldTransformDatetimeUsec formats microsecond timestamps (log explorers).
122 FieldTransformDatetimeUsec
123 + // FieldTransformText selects the text transform.
124 FieldTransformText
125 + // FieldTransformXML selects the xml transform.
126 FieldTransformXML
127 )
128
129 +// String returns the UI keyword used for this transform.
130 func (t FieldTransform) String() string {
131 switch t {
132 case FieldTransformNumber:
@@ -117,18 +146,22 @@ func (t FieldTransform) String() string {
146 }
147 }
148
149 +// MarshalJSON encodes the transform as a UI keyword.
150 func (t FieldTransform) MarshalJSON() ([]byte, error) {
151 return json.Marshal(t.String())
152 }
153
124 -// FieldSort defines the sort direction for a column.
154 +// FieldSort defines the default sort direction for a column.
155 type FieldSort uint8
156
157 const (
158 + // FieldSortAscending orders values from low to high.
159 FieldSortAscending FieldSort = iota
160 + // FieldSortDescending orders values from high to low.
161 FieldSortDescending
162 )
163
164 +// String returns the UI keyword used for this sort direction.
165 func (s FieldSort) String() string {
166 switch s {
167 case FieldSortDescending:
@@ -138,23 +171,32 @@ func (s FieldSort) String() string {
171 }
172 }
173
174 +// MarshalJSON encodes the sort direction as a UI keyword.
175 func (s FieldSort) MarshalJSON() ([]byte, error) {
176 return json.Marshal(s.String())
177 }
178
145 -// FieldSummary defines aggregation behavior.
179 +// FieldSummary defines aggregation behavior when grouping rows.
180 type FieldSummary uint8
181
182 const (
183 + // FieldSummaryCount counts rows in each group.
184 FieldSummaryCount FieldSummary = iota
185 + // FieldSummaryUniqueCount counts unique values in each group.
186 FieldSummaryUniqueCount
187 + // FieldSummarySum sums numeric values in each group.
188 FieldSummarySum
189 + // FieldSummaryMin takes the minimum value in each group.
190 FieldSummaryMin
191 + // FieldSummaryMax takes the maximum value in each group.
192 FieldSummaryMax
193 + // FieldSummaryMean averages values in each group.
194 FieldSummaryMean
195 + // FieldSummaryMedian takes the median value in each group.
196 FieldSummaryMedian
197 )
198
199 +// String returns the UI keyword used for this summary.
200 func (s FieldSummary) String() string {
201 switch s {
202 case FieldSummaryUniqueCount:
@@ -174,29 +216,32 @@ func (s FieldSummary) String() string {
216 }
217 }
218
219 +// MarshalJSON encodes the summary as a UI keyword.
220 func (s FieldSummary) MarshalJSON() ([]byte, error) {
221 return json.Marshal(s.String())
222 }
223
181 -// FieldFilter defines filter UI type.
224 +// FieldFilter defines the filter UI type for a column.
225 type FieldFilter uint8
226
227 const (
228 + // FieldFilterNone disables filtering for the column.
229 FieldFilterNone FieldFilter = iota
230 + // FieldFilterRange is for numeric ranges.
231 FieldFilterRange
232 + // FieldFilterMultiselect is for categorical values.
233 FieldFilterMultiselect
188 - FieldFilterText
234 + // FieldFilterFacet enables faceted filters (log explorers).
235 FieldFilterFacet
236 )
237
238 +// String returns the UI keyword used for this filter.
239 func (f FieldFilter) String() string {
240 switch f {
241 case FieldFilterRange:
242 return "range"
243 case FieldFilterMultiselect:
244 return "multiselect"
198 - case FieldFilterText:
199 - return "text"
245 case FieldFilterFacet:
246 return "facet"
247 default:
@@ -204,6 +249,7 @@ func (f FieldFilter) String() string {
249 }
250 }
251
252 +// MarshalJSON encodes the filter as a UI keyword.
253 func (f FieldFilter) MarshalJSON() ([]byte, error) {
254 return json.Marshal(f.String())
255 }
src/go/pkg/funcapi/enums_test.go
-1
@@ -144,7 +144,6 @@ func TestFieldFilter_StringAndJSON(t *testing.T) {
144 {FieldFilterNone, "none"},
145 {FieldFilterRange, "range"},
146 {FieldFilterMultiselect, "multiselect"},
147 - {FieldFilterText, "text"},
147 {FieldFilterFacet, "facet"},
148 {FieldFilter(250), "none"},
149 }
src/go/pkg/funcapi/params.go
+31 -13
@@ -4,14 +4,17 @@ package funcapi
4
5 import "encoding/json"
6
7 -// ParamSelection defines the selection mode for required params.
7 +// ParamSelection defines whether a required param allows single or multiple selections.
8 type ParamSelection uint8
9
10 const (
11 + // ParamSelect allows a single choice.
12 ParamSelect ParamSelection = iota
13 + // ParamMultiSelect allows multiple choices.
14 ParamMultiSelect
15 )
16
17 +// String returns the UI keyword used for this selection mode.
18 func (p ParamSelection) String() string {
19 switch p {
20 case ParamMultiSelect:
@@ -21,6 +24,7 @@ func (p ParamSelection) String() string {
24 }
25 }
26
27 +// MarshalJSON encodes the selection mode as a UI keyword.
28 func (p ParamSelection) MarshalJSON() ([]byte, error) {
29 return json.Marshal(p.String())
30 }
@@ -28,21 +32,33 @@ func (p ParamSelection) MarshalJSON() ([]byte, error) {
32 // ParamOption defines a single option for a required param.
33 // Column is not serialized and can be used for safe SQL mapping (e.g., __sort).
34 type ParamOption struct {
31 - ID string
32 - Name string
33 - Default bool
35 + // ID is the stable identifier returned in selected values.
36 + ID string
37 + // Name is the label shown in the UI.
38 + Name string
39 + // Default marks the option as the default selection (if none are set, the first option is used).
40 + Default bool
41 + // Disabled prevents selection in the UI.
42 Disabled bool
35 - Sort *FieldSort
36 - Column string
43 + // Sort includes a sort directive with the option.
44 + Sort *FieldSort
45 + // Column is not serialized and can be used for safe SQL mapping.
46 + Column string
47 }
48
49 // ParamConfig defines a required param and its available options.
50 type ParamConfig struct {
41 - ID string
42 - Name string
43 - Help string
44 - Selection ParamSelection
45 - Options []ParamOption
51 + // ID identifies the required param in requests.
52 + ID string
53 + // Name is the label shown in the UI.
54 + Name string
55 + // Help provides UI help text for the param.
56 + Help string
57 + // Selection sets single or multi-select behavior.
58 + Selection ParamSelection
59 + // Options supplies the available choices.
60 + Options []ParamOption
61 + // UniqueView requests unique view behavior for the param in the UI.
62 UniqueView bool
63 }
64
@@ -98,7 +114,9 @@ func buildParamOptions(opts []ParamOption) []map[string]any {
114
115 // ResolvedParam holds resolved values for a required param.
116 type ResolvedParam struct {
101 - IDs []string
117 + // IDs contains selected option IDs in order.
118 + IDs []string
119 + // Options contains selected option metadata in order.
120 Options []ParamOption
121 }
122
@@ -156,7 +174,7 @@ func (p ResolvedParams) Column(id string) string {
174 return opt.ID
175 }
176
159 -// ResolveParam resolves user values against a ParamConfig, applying defaults as needed.
177 +// ResolveParam resolves user values against a ParamConfig, applying defaults or the first option when needed.
178 func ResolveParam(cfg ParamConfig, values []string) ResolvedParam {
179 byID := make(map[string]ParamOption, len(cfg.Options))
180 for _, opt := range cfg.Options {