Update PPL Command Documentation #4562

ritvibhatt · 2025-10-15T01:24:18Z

This PR standardizes the structure and content of PPL command documentation files to improve consistency and user experience.

Changes Made

Documentation Structure Standardization

Implemented consistent section ordering across all PPL command files:

Description - Clear explanation of command functionality
Syntax - Command syntax with parameter details
Optional sections - Behavior notes, configuration details, or usage guidance as needed
Examples - Practical usage examples with expected output
Limitations - Known constraints or considerations

Content Cleanup and Modernization

Removed version information - Eliminated outdated version references (e.g., "Version:
3.3.0") to keep documentation current and reduce maintenance overhead
Extracted aggregation functions - Moved aggregation function documentation to dedicated
functions file (/functions/aggregations.rst) for better organization

Related Issues

Resolves #[Issue number to be closed when this PR is merged]
#4220

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.

Signed-off-by: Ritvi Bhatt <[email protected]>

Signed-off-by: ritvibhatt <[email protected]>

Signed-off-by: Ritvi Bhatt <[email protected]>

ritvibhatt · 2025-10-22T16:35:05Z

Hi @ritvibhatt, thanks for the changes! Quick question: should we also update the documentation in condition.rst for recently added functions like coalesce?

Hi @aalva500-prog, thanks for bringing that up! I have now updated the functions documentation as well

ahkcs · 2025-10-28T20:24:16Z

Hi @ritvibhatt , reviewed bin, replace, fillnull commands and I think it looks good, for multisearch command, can you rebase it due to the newly merged PR: #4512? Thanks!

Swiddis

crashes my web viewer of the diff, lgtm

Swiddis · 2025-10-29T17:45:23Z

docs/user/ppl/index.rst

+  ==============================================================  ==================  ========================  ==============================================================================================
+  Command Name                                                    Version Introduced  Current Status              Command Description
+  ==============================================================  ==================  ========================  ==============================================================================================
+  `search command <cmd/search.rst>`_                              1.0                 stable (since 1.0)        Retrieve documents from the index.


Nice work on the summaries

Swiddis · 2025-10-29T17:47:36Z

docs/user/ppl/index.rst

+* **Functions**

-  - `top command <cmd/top.rst>`_
+  - `Aggregation Functions <functions/aggregation.rst>`_


question: Should we have descriptions or some further info for these too?

Not clear how to find e.g. the SUM function (is it an aggregation function or a math function?).

Yeah that makes sense to do! Was thinking of a follow up PR to update some of the functions content as well as add to index.rst since this PR is already pretty big

LantaoJin · 2025-10-30T01:39:43Z

docs/user/ppl/cmd/stats.rst

-    | ["Amber","Dale","Hattie","Nanette"] |
-    +-------------------------------------+
+* aggregation: mandatory. An aggregation function.
+* bucket_nullable: optional. Controls whether the stats command includes null buckets in group-by aggregations. When set to ``false``, the aggregation ignores records where the group-by field is null, resulting in faster performance by excluding null bucket. **Default:** determined by ``plugins.ppl.syntax.legacy.preferred``:


@ritvibhatt can you review your preview pages. It seems introduce many unexpected formatting.
For example, lines of bucket_nullable and span-expression in your preview
https://github.com/ritvibhatt/sql/blob/update-docs/docs/user/ppl/cmd/stats.rst are bold.

Hi @LantaoJin, just rechecked previews for all of the files and fixed all of the nested bullet points to be formatted properly thanks!

@ritvibhatt the issue I mentioned above is still existing: the whole line of bucket_nullable is bold

You're right, I was missing a commit the issue should be fixed now. Have double checked the preview

opensearch-trigger-bot · 2025-11-13T15:22:27Z

This PR is stalled because it has been open for 2 weeks with no activity.

Signed-off-by: Ritvi Bhatt <[email protected]>

LantaoJin · 2025-11-19T04:13:13Z

can u help to fix the typo in https://github.com/ritvibhatt/sql/blob/update-docs/docs/user/ppl/functions/condition.rst#regexp-match

Usage: regex_match(string, pattern) returns ..

change to

Usage: regexp_match(string, pattern) returns ...

Signed-off-by: Ritvi Bhatt <[email protected]>

ritvibhatt · 2025-11-19T04:19:41Z

can u help to fix the typo in ritvibhatt/sql@update-docs/docs/user/ppl/functions/condition.rst#regexp-match
Usage: regex_match(string, pattern) returns ..
change to
Usage: regexp_match(string, pattern) returns ...

@LantaoJin Updated to be regexp_match!

LantaoJin

LGTM, will keep eyes on CI.

* remove version info Signed-off-by: Ritvi Bhatt <[email protected]> * fix defaults Signed-off-by: Ritvi Bhatt <[email protected]> * update main docs and move aggregate functions Signed-off-by: Ritvi Bhatt <[email protected]> * fix format Signed-off-by: Ritvi Bhatt <[email protected]> * fix heading underlines Signed-off-by: Ritvi Bhatt <[email protected]> * fix typos/content Signed-off-by: Ritvi Bhatt <[email protected]> * fix formatting Signed-off-by: Ritvi Bhatt <[email protected]> * update rex limitations Signed-off-by: Ritvi Bhatt <[email protected]> * update underlines and bullet points Signed-off-by: Ritvi Bhatt <[email protected]> * update function files Signed-off-by: Ritvi Bhatt <[email protected]> * update index.rst with commands table Signed-off-by: Ritvi Bhatt <[email protected]> * update formatting Signed-off-by: Ritvi Bhatt <[email protected]> * update wording Signed-off-by: Ritvi Bhatt <[email protected]> * move syntax Signed-off-by: Ritvi Bhatt <[email protected]> * update note Signed-off-by: Ritvi Bhatt <[email protected]> * fix append docs Signed-off-by: Ritvi Bhatt <[email protected]> * fix subbullet formatting Signed-off-by: Ritvi Bhatt <[email protected]> * fix subbullet formatting Signed-off-by: Ritvi Bhatt <[email protected]> * fix bullet points Signed-off-by: Ritvi Bhatt <[email protected]> * fix bin format Signed-off-by: Ritvi Bhatt <[email protected]> * fix bullet points Signed-off-by: Ritvi Bhatt <[email protected]> * update index.rst Signed-off-by: Ritvi Bhatt <[email protected]> * fix stats Signed-off-by: Ritvi Bhatt <[email protected]> * fix type in regexp_match Signed-off-by: Ritvi Bhatt <[email protected]> --------- Signed-off-by: Ritvi Bhatt <[email protected]> Signed-off-by: ritvibhatt <[email protected]>

ritvibhatt added 3 commits October 13, 2025 11:43

remove version info

8445ebb

Signed-off-by: Ritvi Bhatt <[email protected]>

fix defaults

81e2da1

Signed-off-by: Ritvi Bhatt <[email protected]>

update main docs and move aggregate functions

3ea70a5

Signed-off-by: Ritvi Bhatt <[email protected]>

ritvibhatt marked this pull request as ready for review October 15, 2025 04:04

Merge branch 'main' into update-docs

0dc4a62

Signed-off-by: ritvibhatt <[email protected]>

ritvibhatt marked this pull request as draft October 15, 2025 04:13

fix format

3c67613

Signed-off-by: Ritvi Bhatt <[email protected]>

Swiddis previously approved these changes Oct 29, 2025

View reviewed changes

LantaoJin reviewed Oct 30, 2025

View reviewed changes

LantaoJin mentioned this pull request Oct 30, 2025

Support 'usenull' option in PPL top and rare commands #4696

Merged

8 tasks

dai-chen mentioned this pull request Nov 4, 2025

Mvexpand feature #4675

Closed

1 task

opensearch-trigger-bot bot added the stalled label Nov 13, 2025

Merge remote-tracking branch 'upstream/main' into update-docs

e9f085b

ritvibhatt dismissed Swiddis’s stale review via e9f085b November 17, 2025 18:55

ritvibhatt force-pushed the update-docs branch from f43765d to e9f085b Compare November 17, 2025 18:55

ritvibhatt added 7 commits November 17, 2025 11:05

fix append docs

fbccb99

Signed-off-by: Ritvi Bhatt <[email protected]>

fix subbullet formatting

6db22e0

Signed-off-by: Ritvi Bhatt <[email protected]>

fix subbullet formatting

6570f02

Signed-off-by: Ritvi Bhatt <[email protected]>

fix bullet points

aa3128d

Signed-off-by: Ritvi Bhatt <[email protected]>

fix bin format

e4d4ba1

Signed-off-by: Ritvi Bhatt <[email protected]>

fix bullet points

e5a5936

Signed-off-by: Ritvi Bhatt <[email protected]>

update index.rst

724a4d6

Signed-off-by: Ritvi Bhatt <[email protected]>

opensearch-trigger-bot bot removed the stalled label Nov 18, 2025

Swiddis previously approved these changes Nov 18, 2025

View reviewed changes

fix stats

0f3c5ee

Signed-off-by: Ritvi Bhatt <[email protected]>

ritvibhatt dismissed Swiddis’s stale review via 0f3c5ee November 19, 2025 03:36

fix type in regexp_match

30e698f

Signed-off-by: Ritvi Bhatt <[email protected]>

LantaoJin approved these changes Nov 19, 2025

View reviewed changes

qianheng-aws approved these changes Nov 19, 2025

View reviewed changes

LantaoJin merged commit bf37067 into opensearch-project:main Nov 19, 2025
35 checks passed

LantaoJin added the v3.4.0 label Nov 19, 2025

Update PPL Command Documentation #4562

Update PPL Command Documentation #4562

Uh oh!

Conversation

ritvibhatt commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes Made

Documentation Structure Standardization

Content Cleanup and Modernization

Related Issues

Check List

Uh oh!

ritvibhatt commented Oct 22, 2025

Uh oh!

ahkcs commented Oct 28, 2025

Uh oh!

Swiddis left a comment

Choose a reason for hiding this comment

Uh oh!

Swiddis Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

Swiddis Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

ritvibhatt Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

LantaoJin Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ritvibhatt Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

LantaoJin Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

ritvibhatt Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

opensearch-trigger-bot bot commented Nov 13, 2025

Uh oh!

LantaoJin commented Nov 19, 2025

Uh oh!

ritvibhatt commented Nov 19, 2025

Uh oh!

LantaoJin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

ritvibhatt commented Oct 15, 2025 •

edited

Loading

LantaoJin Oct 30, 2025 •

edited

Loading