Record numerator and denominator bases for local table ratios — what should the operator record?
A ratio can look precise even when its numerator and denominator come from different scopes. Before calculating one from returned evidence, define both bases and their relationship. This is a table-handling check, not a claim that the resulting fraction measures the underlying source population or a causal effect of observed activity.
Avoid dividing incompatible returned subsets or treating unavailable totals as known denominators.
Use numerator_definition, denominator_definition and input_revision references. Identify whether each value counts distinct objects, relationship rows or observations, and require compatible source context, time scope and inclusion rules before arithmetic is allowed in the working artifact.
Keep numerator, denominator, computed_value and ratio_state together with the contract revision. Describe the result as a fraction within the admitted returned set, preserving actual coverage limits and avoiding an estimate of platform-wide prevalence without an appropriate supported denominator.Name both membership bases
Use numerator_definition, denominator_definition and input_revision references. Identify whether each value counts distinct objects, relationship rows or observations, and require compatible source context, time scope and inclusion rules before arithmetic is allowed in the working artifact.
Check subset logic
When the interpretation requires numerator membership to be within the denominator, verify that relation by qualified keys. A numerically smaller numerator does not prove subset membership, especially when the inputs came from different query branches or permission contexts with unrelated objects.
Handle zero and unknown
A known zero denominator should produce an explicitly undefined result, while an unavailable denominator remains unknown. Neither case should become zero percent or an automatically suppressed blank that makes recipients assume the ratio was computed successfully from complete data.
Test incompatible fixtures
Use labeled tables with equal counts but disjoint keys and confirm the subset check rejects the calculation. Add a mixed-precision time-window case so scope incompatibility is detected before the formula produces an attractive but unsupported exact percentage.
Publish the ratio basis
Keep numerator, denominator, computed_value and ratio_state together with the contract revision. Describe the result as a fraction within the admitted returned set, preserving actual coverage limits and avoiding an estimate of platform-wide prevalence without an appropriate supported denominator.
Keep the boundaries clear.
- Avoid dividing incompatible returned subsets or treating unavailable totals as known denominators.
- Operational record: Name both membership bases. 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.