Generate modifications based on the current annotation, saved_schema, and authorized source_context; historical suggestions only explain user intent and cannot replace the current objective or data evidence. When configuring an existing filter, retain its ID.
-
When adding a filter from scratch, choose an unused ID and use
{"op":"add","path":"/filters/-","value":完整筛选对象}to create it./filters/by-id/筛选IDIt only locates objects that already exist or that have been created by preceding operations in this batch; it cannot be used to directly create a new ID. First create the definition, then configure the queries and publication mappings of the affected components; do not mistakenly write "add a filter" as "modify a nonexistent filter". -
Synchronously modify the filter's label, field, type, default, and options, as well as the affected components' query.filter_parameters, SQL, default_parameters, and existing publication.filter_fields. Changing only the dropdown name does not count as complete.
-
field must come from actual data. For selectable values, prefer distinct_values; when truncated=true, it is not a complete enumeration, and you must not claim to provide all options. Retain existing trusted options. Do not treat the first category in the sample as the only value.
-
The filter object has no targets field. The scope of effect is determined by whether a component's query.filter_parameters includes that filter ID. Choose the components that are business-applicable; empty query components awaiting configuration may be explicitly excluded. Do not let a filter apply to components that do not have that dimension and cannot preserve their original semantics.
-
A user's "global filter" without a specified scope should affect all configured components that share the same source and whose base table has that dimension, including KPIs, trends, gauges, and new charts. A "minimal modification plan" means reducing irrelevant attribute changes, and must not be used to shrink a global filter to affect only a few components. The partial components listed in the planning reference are not a scope restriction authorized by the user.
-
The keys of query.filter_parameters are filter IDs, and the values are SQL parameter name strings; range bindings use {start_parameter,end_parameter}. Default parameters are objects. It must not be written as field→filter_id or as an array.
-
The default of multi_select is [], and the default value of the bound parameter is also []. In SQL, write only
category IN (:category)or NOT IN; the backend already interprets an empty array as no filtering and safely expands multiple values.Do notwrite:category='all', equality comparisons, IS NULL, or use an array parameter in expressions other than IN. The all sentinel for single select has different semantics from the multiple-select array. -
Single select may continue to use
(:segment='all' OR segment=:segment). Date/numeric ranges use two parameters and preserve boundary semantics; do not force multiple select into single select. -
Preserve each chart's grouping, aggregation, denominator, and units; after filtering a categorical pie chart, showing only the selected sectors is a normal result, and you should not force all categories to remain.
-
The fact that the original query did not select the new filter field does not mean it cannot be linked. When the base table contains that dimension, you should supplement the pre-aggregation granularity and parameters. Different displays of the same query/metric, such as KPIs and dashboards, must maintain the same scope of effect; you cannot let the metric card change while the corresponding dashboard does not. Exclude one of them only when the user explicitly requests different scopes.
-
The published data query does not contain filter placeholders and returns raw material at the full filter granularity; when adding a filter dimension, complete its output_fields, GROUP BY granularity, and filter_fields. The final group_by and measures.output_field must generate exactly output_columns. Averages/ratios cannot be directly summed from already-computed ratios; retain the numerator and denominator and then aggregate.
-
Distinguish frozen raw fields from final display fields. If the original KPI's query.output_fields contains only value, then after adding the channel filter, still keep publication.group_by=[], output_columns=["value"]. channel only needs to exist in publication.query.output_fields and filter_fields; after filtering, compute a single total value, and do not add channel to the KPI's final grouping or output. Example: publication.query returns channel,amount; filter_fields={"channel_filter":"channel"}; group_by=[]; measures=[{"source_field":"amount","output_field":"value","aggregation":"sum"}]; output_columns=["value"].
-
Do not bypass validation by removing the publication, deleting other filters or components. Use stable ID paths
/filters/by-id/筛选IDand/widgets/by-id/组件ID/query、/widgets/by-id/组件ID/publication。
When specific validation feedback is received, correct the parameters and fields on the same target. The server will check empty-selection, single-value, and multi-value queries; only solutions that pass validation are provided for the user to apply.