FOCUS #492: ConsumedQuantity and ConsumedUnit and Unused commitment

specification/columns/consumedquantity.md

@@ -2,7 +2,16 @@
 
 The Consumed Quantity represents the volume of a given SKU associated with a [*resource*](#glossary:resource) or [*service*](#glossary:service) used, based on the [Consumed Unit](#consumedunit). Consumed Quantity is often derived at a finer granularity or over a different time interval when compared to the [Pricing Quantity](#pricingquantity) (complementary to [Pricing Unit](#pricingunit)) and focuses on *resource* and *service* consumption, not pricing and cost.
 
-ConsumedQuantity column MUST be present in the billing data when the provider supports the measurement of usage. This column MUST NOT be null if [ChargeCategory](#chargecategory) is "Usage" and  [ChargeClass](#chargeclass) is not "Correction". This column MUST be null for other ChargeCategory values. This column MUST be of type Decimal and MUST conform to [Numeric Format](#numericformat) requirements. The value MAY be negative in cases where [ChargeClass](#chargeclass) is "Correction".
+The ConsumedQuantity column adheres to the following requirements:
+
+* ConsumedQuantity MUST be present in the billing data when the provider supports the measurement of usage.
+* ConsumedQuantity MUST be of type Decimal and MUST conform to [Numeric Format](#numericformat) requirements.
+* ConsumedQuantity MUST NOT be null if [ChargeCategory](#chargecategory) is "Usage", unless [ChargeClass](#chargeclass) is "Correction" or [CommitmentDiscountStatus](#commitmentdiscountstatus) is "Unused".
+* ConsumedQuantity MAY be null if ChargeCategory is "Usage" and ChargeClass is "Correction"
+* ConsumedQuantity MUST be null if CommitmentDiscountStatus is "Unused" or for other ChargeCategory values.
+* ConsumedQuantity value MAY be negative in cases where ChargeClass is "Correction".
+
+The ConsumedQuantity column MUST NOT be used to determine values related to any pricing or cost metrics.
 
 ## Column ID
 

specification/columns/consumedunit.md

@@ -2,7 +2,15 @@
 
 The Consumed Unit represents a provider-specified measurement unit indicating how a provider measures usage of a given SKU associated with a [*resource*](#glossary:resource) or [*service*](#glossary:service). Consumed Unit complements the [Consumed Quantity](#consumedquantity) metric. It is often listed at a finer granularity or over a different time interval when compared to [Pricing Unit](#pricingunit) (complementary to [Pricing Quantity](#pricingquantity)), and focuses on *resource* and *service* consumption, not pricing and cost.
 
-The ConsumedUnit column MUST be present in the billing data when the provider supports the measurement of usage. This column MUST be of type String. ConsumedUnit MUST NOT be null if [ChargeCategory](#chargecategory) is "Usage" and [ChargeClass](#chargeclass) is not "Correction". This column MUST be null for other ChargeCategory values. Units of measure used in ConsumedUnit SHOULD adhere to the values and format requirements specified in the [UnitFormat](#unitformat) attribute. The ConsumedUnit column MUST NOT be used to determine values related to any pricing or cost metrics.
+The ConsumedQuantity column adheres to the following requirements:
+
+* ConsumedUnit MUST be present in the billing data when the provider supports the measurement of usage.
+* ConsumedUnit MUST be of type String, and the units of measure used in ConsumedUnit SHOULD adhere to the values and format requirements specified in the [UnitFormat](#unitformat) attribute.
+* ConsumedUnit MUST NOT be null if [ChargeCategory](#chargecategory) is "Usage", unless [ChargeClass](#chargeclass) is "Correction" or [CommitmentDiscountStatus](#commitmentdiscountstatus) is "Unused".
+* ConsumedUnit MAY be null if ChargeCategory is "Usage" and ChargeClass is "Correction"
+* ConsumedUnit MUST be null if CommitmentDiscountStatus is "Unused" or for other ChargeCategory values.
+
+The ConsumedUnit column MUST NOT be used to determine values related to any pricing or cost metrics.
 
 ## Column ID
 

supporting_content/columns/consumedquantity.md

@@ -16,3 +16,16 @@ Current column mappings found in available data sets:
 * The examples in "Rows  per Scenario V2" sheet in [this google sheet](https://docs.google.com/spreadsheets/d/1zA0brhrEntfWlzt5VNcNLBFnKPEiarajTF84o4ATeEw/edit#gid=1134244055) were helpful in understanding the need for a separate 'Consumed Quantity' as opposed to a single 'FooQuantity' (which later was voted to be 'ActualQuantity'). Rows 30/31/52/54/22 were helpful in showing the need to understand both the 'used' quantity and the quantity that you were charged for.
 * Consensus was reached based on needing to support Staircase pricing - where you maybe charged for a quantity based on the 'stair' but you use less than that. It leads to the classic usage-optimization scenario in FinOps. For example, Slot usage in GCP BigQuery is charged based on a one minute minimum and per second granularity beyond that. Snowflake has similar scenario for warehouses. If you run a bunch of queries that use one-second, you're being charged for 60 seconds each time. Practitioners want to identify these and optimize their usage patterns to better utilize what they're paying for. To correctly identify the potential optimization opportunity, you need both pieces of data to show up in the data. ConsumedQuantity allows for the used amount to be presented in a consistent manner and is easily understood.
 * The second column needed for the staircase pricing scenario above, a potential 'DistinctPricingQuantity' column, could be introduced in the future to identify the 60 seconds that you were 'charged' for in singular units. Today, you may have to use pricing quantity - which may have block pricing - therefore you may may need to do math to get 'distinct' units). Alternatively, we could introduce a 'factor' to remove the block portion of the pricing unit. This need was discussed and determined to be something that needs to be thought through and evaluated in detail post v1.0.
+
+## ConsumedQuantity and ConsumedUnit normatives overview
+
+| ChargeCategory | ChargeClass | CommitmentStatus | ConsumedQuantity | ConsumedUnit     |
+|----------------|-------------|------------------|------------------|------------------|
+| Usage          | (null)      | Used             | MUST not be null | MUST not be null |
+| Usage          | Correction  | Used             | MAY be null      | MAY be null      |
+| Usage          | (null)      | Unused           | MUST be null?    | MUST be null?    |
+| Usage          | Correction  | Unused           | MUST be null?    | MUST be null?    |
+| Purchase       |             |                  | MUST be null     | MUST be null     |
+| Credit         |             |                  | MUST be null     | MUST be null     |
+| Adjustment     |             |                  | MUST be null     | MUST be null     |
+| Tax            |             |                  | MUST be null     | MUST be null     |