Add per_second function support for timechart command

[dai-chen]

Description

This PR adds per_second() support to the timechart command by implementing Option 3 (Eval Transformation). As a short-term solution, it extends the Timechart AST to recognize the per_second function and rewrites into the equivalent math formula shown in the examples below. See issue #4350 for background and alternatives.

Examples

-- Original
source=events
| timechart span=5m per_second(packets)

-- Rewritten
source=logs
| timechart span=5m sum(packets) as `per_second(packets)`
| eval `per_second(packets)` = `per_second(packets)` / 300   -- 5 minutes = 300 seconds

For spans whose length varies with the calendar (month/quarter/year), the number of seconds depends on actual start/end timestamps (e.g., September has 30 days; October has 31 days; February in a leap year has 29 days). To ensure correctness, the rewrite computes the exact bucket length dynamically:

-- Example: span=2mon
source=logs
| timechart span=2mon sum(packets) as "per_second(packets)"
| eval `per_second(packets)` = `per_second(packets)` /
    timestampdiff(
      SECOND,
      @timestamp,                                  -- span start
      timestampadd(MONTH, 2, @timestamp)           -- span end   (start + 2 months)
    )

Related Issues

Resolves partially #4350.

Check List

• New functionality includes testing.
• New functionality has been documented.
• New functionality has javadoc added.
• New functionality has a user manual doc added.
• New PPL command checklist all confirmed.
• API changes companion pull request created.
• Commits are signed per the DCO using --signoff or -s.
• Public documentation issue/PR created.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[RyanL1997]

Hi @dai-chen , thanks for the change.

[RyanL1997]

What happens if the span evaluates to 0 seconds (e.g., with millisecond spans or edge cases)? Should there be validation or error handling for division by zero?

[dai-chen]

Good catch. Let me check if timechart has the validation or not. Thanks!

[dai-chen]

I quick tested timechart command and found negative span value is not allowed in our grammar. But zero-span validation is missing. Let me create an issue and raise separate PR to fix.

opensearchsql> source=test_data_2023 | timechart span=0m per_second(packets);
TransportError(500, 'SearchPhaseExecutionException', {'error': 
{'reason':'Error occurred in OpenSearch engine: all shards failed', 'details': 'Shard[0]:
  java.lang.IllegalArgumentException: Zero or negative time interval not supported\n\n
    For more details, please send request for Json format to see the raw response from OpenSearch engine.',
      'type': 'SearchPhaseExecutionException'}, 'status': 400})

opensearchsql> source=test_data_2023 | timechart span=-1m per_second(packets);
{'reason': 'Invalid Query', 'details': "[-] is not a valid term at this part of the query: '...23
  | timechart span=-' <-- HERE. extraneous input '-' expecting {SPANLENGTH, INTEGER_LITERAL}",
    'type': 'SyntaxCheckException'}

[dai-chen]

Created issue: #4527. Thanks!