Declare grouping grain before summarizing a research table — what should the operator record?
A group-by operation can be technically correct while counting the wrong object. Flattened references, repeated observations and overlapping categories all change what a row represents. Declare the aggregation grain and input lineage before summarizing so the resulting table does not imply more independent evidence or broader coverage than the actual returned set supports.
Keep grouped row counts, distinct objects and observations separate in derived summaries.
Record whether an input row is an object, observation or relationship pair. Include parent-key definitions where arrays were expanded, because the physical row count of that representation may exceed the number of distinct source objects carried by the response.
Check grouped membership against the authorized input and document overlapping category behavior. Category totals may exceed distinct objects when multiple labels are allowed; explain that representation rather than forcing the summary to resemble a mutually exclusive population distribution.Describe the input grain
Record whether an input row is an object, observation or relationship pair. Include parent-key definitions where arrays were expanded, because the physical row count of that representation may exceed the number of distinct source objects carried by the response.
Choose the measure
Name measures explicitly, such as returned_relationship_rows or distinct_source_keys. Do not use an unlabeled count column when several plausible counting objects coexist, and keep requested targets and any supported source totals outside the aggregate's locally computed measures.
Specify grouping fields
Use actual validated categories or clearly labeled local annotations, preserving unknown and not-applicable groups. Dropping null group labels by default can hide admitted rows and make the summary appear to describe all input membership when it only covers populated categories.
Test aggregation fixtures
Use labeled parent objects with repeated child rows and missing category values. Verify distinct-object and row counts differ as expected and that unknown categories remain visible rather than vanishing through the grouping library's default handling of null keys.
Reconcile the output
Check grouped membership against the authorized input and document overlapping category behavior. Category totals may exceed distinct objects when multiple labels are allowed; explain that representation rather than forcing the summary to resemble a mutually exclusive population distribution.
Keep the boundaries clear.
- Keep grouped row counts, distinct objects and observations separate in derived summaries.
- Operational record: Describe the input grain. Context badges do not certify access.
Start with a read-only check: ask your agent to report actual source coverage before collecting records or exporting an audience.
Primary references
Documentation reviewed 2026-11-15. Product capabilities, client availability and plans can change. Third-party marks identify their products, not an affiliation.