GH-46270: [C++][Parquet] Clarify GeoStatistics docstring

[paleolimbot]

Rationale for this change

The distinction between "invalid" and "empty" is not clear in the current documentation!

What changes are included in this PR?

The docstring for GeoStatistics was improved.

Are these changes tested?

Just documention!

Are there any user-facing changes?

No

• GitHub Issue: [C++][Parquet] Misleading GeoStatistics::dimension_empty docstring #46270

[pitrou]

Thank you, this is useful.

[pitrou]

@paleolimbot I'm curious about this in the method docstrings:

  /// For statistics read from a Parquet file, dimension_empty() will always contain
  /// false values because there is no mechanism to communicate an empty interval
  /// in the Thrift metadata.

Why was it done that way, if emptiness is a useful information to have? And is there a point in exposing emptiness in our geostats APIs? Usually, people want to filter from a Parquet file read from disk, not one that is being constructed in-memory...

[paleolimbot]

Why was it done that way, if emptiness is a useful information to have?

The PR where we discussed this is apache/parquet-format#494 ...the consensus was that checking the null_count for a column chunk against the number of rows in the row group would catch the most common case (row group is all null). We then discovered that we don't currently write null counts for unsorted logical types, but hopefully we can fix that ( #46275 ).

And is there a point in exposing emptiness in our geostats APIs?

We use the same API for producing and consuming GeoStatistics (this was modelled after the regular Statistics). We could move the write path only use internals although I am not sure this would be less confusing.

[conbench-apache-arrow]

After merging your PR, Conbench analyzed the 4 benchmarking runs that have been run so far on merge-commit 8d44eea.

There were 68 benchmark results with an error:

• Commit Run on arm64-t4g-2xlarge-linux at 2025-06-02 21:59:00Z
  • tpch (R) with engine=arrow, format=parquet, language=R, memory_map=False, query_id=TPCH-07, scale_factor=1
  • tpch (R) with engine=arrow, format=native, language=R, memory_map=False, query_id=TPCH-09, scale_factor=1
• and 66 more (see the report linked below)

There were no benchmark performance regressions. 🎉

The full Conbench report has more details. It also includes information about 3 possible false positives for unstable benchmarks that are known to sometimes produce them.