Query And Filter Patterns

Pattern

Use queries for durable object-selection meaning and query parameters for runtime variation.

  • put shared business selection into the base query
  • put user-adjustable narrowing into runtime filters
  • use filter lists for curated reusable value sets
  • use permission queries when access depends on object state

Recommendations

Name Queries By Intent

  • choose the query role based on why the query exists, not only where it might be reused later
  • use View queries for durable list and screen behavior
  • use Property queries for selector-safe object sets
  • use Permission queries as policy statements that describe access scope clearly

Separate Baseline State From Runtime State

  • keep baseline business meaning in the stored query
  • use regular parameters for defaults users are expected to refine at runtime
  • use fixed parameters only for rules downstream users should not override
  • remember that tags, folders, visible columns, sorting, and pagination belong to runtime state as much as to the stored query contract

Choose Reuse Mechanisms Intentionally

  • use filter lists for governed reusable inclusion and exclusion sets on supported string and number filters
  • use tags for operational classification layered on top of the core model
  • use relations, enumerations, and ordinary properties when the value is really part of the domain schema

Escalate To Custom Queries Sparingly

  • prefer configured queries until the builder model is genuinely not enough
  • treat custom_query_available_params as a stable contract if views, selectors, or integrations depend on the query
  • remember that custom-query behavior pushes the implementation toward more explicit documentation and review

Good Scenarios

  • "My team's work" as a reusable query
  • current date, tag, or folder narrowing as runtime parameters
  • reusable region list as a filter list
  • ownership-based edit access as a permission query
  • a selector-limited Active suppliers for contract form query with query_type = Property
  • a Projects editable by regional manager query with query_type = Permission

Best Practices

  • keep reusable meaning in named queries
  • name permission queries as policy statements, not generic data sets
  • do not hardcode the same candidate set in multiple places
  • use filter lists only where the value set itself is the reusable asset
  • do not replace core business fields with tags because they are easier to add
  • use nested filters only when they remain understandable
Previous← Governance And Rollout Patterns