Add approximatePercentile aggregated value function

[nikhilkumarjadhav-toast]

Summary

Adds an approximatePercentile field to the aggregatedValues API for Float, Int, JsonSafeLong, LongString, Date, DateTime, and LocalTime fields, backed by the datastore's percentiles aggregation.

type FloatAggregatedValues {
  approximateAvg: Float
  approximateSum: Float!
  exactMin: Float
  exactMax: Float
  approximatePercentile(percentile: Float!): Float
}

Callers request a specific percentile rank via the percentile argument (e.g. percentile: 50 for the median), and can request multiple ranks in a single query by aliasing the field selection:

{
  amountCents {
    p50: approximatePercentile(percentile: 50)
    p99: approximatePercentile(percentile: 99)
  }
}

This shape (as opposed to a list-return shape accepting an array of percentiles) keeps query validity statically verifiable: each aliased selection independently validates its own rank and always returns exactly one value, avoiding the ambiguity a list-argument API would have around duplicate or out-of-range requests. Percentiles are computed using an approximate algorithm (t-digest) regardless of field type, so there's no exactPercentile counterpart the way there is for min/max/sum.

@myronmarston and I discussed and agreed on this API shape beforehand.

Implementation notes

• ComputationDetail gains an optional function_arg_name, and Computation gains a function_arg_value, so a function that needs a query-time argument (like percentile) can fold the resolved value into both the emitted datastore clause and the aggregation key. This avoids key collisions between multiple aliased selections of the same field with different argument values.
• The datastore's percentiles aggregation is requested with keyed: false and a single-element percents array per Computation, so the response is a small array ("values" => [{"key" => ..., "value" => ...}]) rather than a string-keyed hash — this avoids reconstructing the datastore's float-formatted string key to look up the single requested value.
• Verified end-to-end against a running datastore (both a Float/Int field and a DateTime field, confirming value_as_string formatting carries through the same as the other aggregated value functions) before writing the automated tests.

Test plan

• Unit tests: Computation#key/#clause for the percentiles function; QueryAdapter builds distinct computations for aliased selections with different percentile args; resolver tests including empty-bucket (null) and DateTime formatting
• Integration test against a real datastore: median/p99 over a small dataset, plus the empty-result-set case
• Acceptance tests: aliased multi-percentile query, and percentile alongside groupedBy
• Extended existing built_in_types_spec.rb/for_built_in_types_spec.rb SDL and runtime-metadata assertions for the new field on all 7 supported types
• script/quick_build passes (spellcheck, lint, type_check, schema_artifacts:check, full spec suite at 100% line/branch coverage, site validation)
• Added a validated example query (config/site/examples/music) and doc-site prose in query-api/aggregations/aggregated-values.md

[CLAassistant]

All committers have signed the CLA.

[myronmarston]

Great work @nikhilkumarjadhav-toast! As noted in my comments below, I'm working on #1331 and #1332 which should make this much easier. You'll want to rebase on top of that and rework your solution after those land.

[myronmarston]

Suggested change

	a.documentation "The percentile rank to compute, from `0` to `100` (e.g. `50` for the median, `99` for the 99th percentile)."
	a.documentation "The percentile rank to compute, from `0` to `100` (e.g. `0` for the min, `100` for the max, `50` for the median, `99` for the 99th percentile)."

/nit I was initially unsure if "from 0 to 100" was an inclusive or exclusive range until I thought about it a bit and realized that 0 = min and 100 = max. Seems useful to say that explicitly.

[myronmarston]

I think #1331 removes the need for adding this (and #1332 does away with this class entirely!).

[myronmarston]

Suggested change

	def define_temporal_aggregated_values(aggregated_values_type, scalar_type, &block)

...now that we include percentile in addition to exact_min_max_and_approx_avg. (And be sure to update the callers).

[myronmarston]

Suggested change

	This example query aggregates the values of the `Artist.lifetimeSales` field using all 4 of the basic numeric

(I think "percentile" is a pretty standard numeric aggregation function, but it's useful to split off below, and is a bit more "advanced" than these "basic" ones).

[myronmarston]

I made a suggestion about the SDL docs. Be sure to apply that here as well.

[myronmarston]

Can these use .and be_approximately(...) to also assert on the value like the others--not just the type?

BTW feel free to use the 0th or 100th percentile for this example so you can just do .max or .min in the value part of the assertion--that's easier than writing an arithmetic expression to compute the median.

[myronmarston]

Let's fold these two new examples into the existing ones rather than adding standalone examples.

Acceptance tests here are by far our most expensive layer — each example boots a real datastore
round-trip and re-indexes its own fixtures. The established pattern in this file is to index once
and then assert a lot against that one indexed state (see it "returns aggregates (terms, date histogram) and nested aggregates", which indexes 5 records and then runs ~40 distinct grouping
scenarios against them). Two new examples that each index 4 fresh widgets to check one function is a
meaningful cost increase for coverage we can get for free.

Concretely:

1. Treat approximatePercentile like every other aggregated value function

Add it to all_amount_aggregations (line 1842) alongside approximate_sum / exact_sum /
approximate_avg / exact_min / exact_max, and add the expected entries to
expected_aggregated_amounts_of (line 856):

# in all_amount_aggregations (and the nested `cost { amount_cents { ... } }` block)
p50: approximate_percentile(percentile: 50)
p99: approximate_percentile(percentile: 99)

# in expected_aggregated_amounts_of
"p50" => float_of(...),
"p99" => float_of(...)

This gets us, at zero additional indexing cost, everything the two new examples were checking plus a
lot more:

• Multiple aliased selections of the same function under one parent field — the collision-avoidance
  behavior that motivated folding function_arg_value into the aggregation key. This is the single most
  important thing to cover, and all_amount_aggregations exercises it in every scenario rather than once.
• Grouped and ungrouped — makes the second new example ("supports grouping alongside an aliased approximate_percentile selection") redundant outright; amount_aggregation / all_amount_aggregations
  are already run against ~40 different grouped_by shapes.
• Nested under a sub-object (cost { amount_cents { ... } }) — verifies the field path is encoded into
  the key correctly alongside the arg value. Not covered today.
• Empty buckets — the pre-index assertion at line 52 checks expected_aggregated_amounts_of([]), so we'd
  get empty_bucket_value: nil coverage for free. Also not covered today.

Two things to watch when doing this:

• float_of uses a 0.1%-relative tolerance, which is tighter than the be_within(5).percent_of the new
  p99 example needed. Rather than loosening float_of globally, I'd suggest picking percentile ranks whose
  expected values are consistent for the fixture sizes involved (e.g. p75 or p90). Worth confirming empirically what the datastore returns for the small (1–3 doc)
  groupings — t-digest interpolation on tiny sets isn't obvious, so please pin the expected values from an
  actual run rather than assuming a plain linear median.
• percentile: 0 and percentile: 100 are exactly min and max regardless of interpolation, so a
  p0/p100 pair is a cheap way to get a tight, deterministic assertion. Could be a nice complement to a
  looser p50.

2. Cover the calendar types

approximatePercentile is defined on Date, DateTime, and LocalTime aggregated values too (via
define_exact_min_max_and_approx_avg_on_aggregated_values), and returns the formatted string type
(): Date in the schema, not Float). That path goes through the value_as_string fallback in
Resolvers::AggregatedValues, and it does so through the percentiles-specific
result.fetch("values").first unwrapping — i.e. a combination nothing currently exercises. If the
datastore ever stopped returning value_as_string inside the keyed: false array entries, we'd
silently start returning raw epoch millis and no test would catch it.

Please add it to it "supports using aggregations for calendar types (Date, DateTime, LocalTime)"
(line 1266), which already indexes exactly the right fixtures:

created_at { exact_min, exact_max, approximate_avg, approximate_distinct_value_count, p50: approximate_percentile(percentile: 50) }
created_on { ... }
created_at_time_of_day { ... }

with the expected formatted-string values added to the contain_exactly hash below.

3. Delete both new examples

Once 1 and 2 are in place, both new examples are strictly subsumed, and per our "avoid duplicate
tests" guidance they should go.

[myronmarston]

Encoding the args in the aggregation key feels a bit messy and brittle. I think there's a better way: we can use the field alias. I'm working on a prep refactoring PR (#1331) that should obviate the need for this.

[myronmarston]

Having conditional logic based on the aggregation function here (and in elasticgraph-graphql/lib/elastic_graph/graphql/aggregation/resolvers/relay_connection_builder.rb, elasticgraph-graphql/lib/elastic_graph/graphql/aggregation/computation.rb, etc) is a big of a smell. These abstractions are designed to be agnostic to the specific aggregation function.

Unfortunately, the internal abstractions EG currently has aren't currently good enough for this, so you're forced to add if computation_detail.function == :percentiles conditionals. I'm working on a prep refactoring in #1332 that should solve this.

[myronmarston]

Another thing that I thought of after submitting my review above: we should make sure that out-of-range percentiles are handled properly. I checked out your branch and ran bundle exec rake boot_locally to try it out and found that percentile values out side the 0 to 100 range cause OpenSearch/Elasticsearch to throw exceptions:

We should return a GraphQL validation error instead. (Would be good to cover that in the acceptance test).