Skip to content

docs: correct the JSON_ARRAYAGG and JSON_OBJECTAGG example output - #24736

Open
tongriyaotxt wants to merge 1 commit into
pingcap:masterfrom
tongriyaotxt:fix/json-arrayagg-example-order
Open

tongriyaotxt wants to merge 1 commit into
pingcap:masterfrom
tongriyaotxt:fix/json-arrayagg-example-order

Conversation

@tongriyaotxt

@tongriyaotxt tongriyaotxt commented Nov 22, 2026 •

Copy link
Copy Markdown

First-time contributors' checklist

What is changed, added, or deleted? (Required)

Both examples on this page show an output order that the current release does not produce, and aggregate order is not guaranteed in the first place. This PR corrects the outputs and states the guarantee explicitly.

  1. JSON_ARRAYAGG() showed [2, 1] for:

    SELECT JSON_ARRAYAGG(v) FROM (SELECT 1 'v' UNION SELECT 2);

    A fresh tidb-server --store=unistore -P 4000 (master) returns [1, 2]:

    mysql> SELECT JSON_ARRAYAGG(v) FROM (SELECT 1 'v' UNION SELECT 2) t;
    +------------------+
    | JSON_ARRAYAGG(v) |
    +------------------+
    | [1, 2]           |
    +------------------+

    The output is corrected to [1, 2], followed by: "The order of the values in the resulting array is not guaranteed."

  2. JSON_OBJECTAGG() showed the three groups in the order rose, orchid, tulip. The same server returns rose, tulip, orchid for the documented query. The rows are put in that order, followed by: "The order of the rows in the result is not guaranteed."

Both statements are aggregate queries without ORDER BY, so no specific order is part of the contract. Showing one order without that caveat makes the examples look like promises about ordering, which is the part worth fixing regardless of which order a given build happens to produce.

Which TiDB version(s) do your changes apply to? (Required)

  • master (the latest development version)
  • v9.0 (TiDB 9.0 versions)
  • v8.5 (TiDB 8.5 versions)
  • v8.1 (TiDB 8.1 versions)
  • v7.5 (TiDB 7.5 versions)
  • v7.1 (TiDB 7.1 versions)
  • v6.5 (TiDB 6.5 versions)

Picking master only, because this is an example/wording correction that does not depend on a version-specific behavior change.

What is the related PR or file link(s)?

  • Related code change PR links (if applicable): none
  • This PR is translated from: none
  • Other reference link(s): none

AI agent involvement

  • The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

  • Delete files
  • Change aliases
  • Need modification after applied to another branch
  • Might cause conflicts after applied to another branch

@ti-chi-bot ti-chi-bot Bot added contribution This PR is from a community contributor. first-time-contributor Indicates that the PR was contributed by an external member and is a first-time contributor. needs-ok-to-test Indicates a PR created by contributors and need ORG member send '/ok-to-test' to start testing. labels Nov 22, 2026
@ti-chi-bot

ti-chi-bot Bot commented Nov 22, 2026

Copy link
Copy Markdown

Hi @tongriyaotxt. Thanks for your PR.

I'm waiting for a pingcap member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@ti-chi-bot

ti-chi-bot Bot commented Nov 22, 2026

Copy link
Copy Markdown

Welcome @tongriyaotxt!

It looks like this is your first PR to pingcap/docs 🎉.

I'm the bot to help you request reviewers, add labels and more, See available commands.

We want to make sure your contribution gets all the attention it needs!



Thank you, and welcome to pingcap/docs. 😃

@ti-chi-bot ti-chi-bot Bot added the missing-translation-status This PR does not have translation status info. label Nov 22, 2026
@pingcap-cla-assistant

pingcap-cla-assistant Bot commented Nov 22, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@ti-chi-bot ti-chi-bot Bot added the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label Nov 22, 2026
@coderabbitai

coderabbitai Bot commented Nov 22, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The JSON_ARRAYAGG and JSON_OBJECTAGG examples change. The documentation states that array value order and result row order are not guaranteed.

Changes: JSON Aggregate Documentation

Layer / File(s) Summary
Examples and ordering
functions-and-operators/json-functions/json-functions-aggregate.md
The JSON_ARRAYAGG example changes from [2, 1] to [1, 2], and its documentation states that array value order is not guaranteed. The JSON_OBJECTAGG example lists the orchid row before the tulip row, and its documentation states that result row order is not guaranteed.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Suggested reviewers: dveeden

Merge Risk: Minimal · up to 4bbe1

This documentation-only change corrects the example outputs for JSON_ARRAYAGG and JSON_OBJECTAGG and clarifies that result order is not guaranteed. It has no runtime impact and is ready to merge.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the two JSON aggregate functions and the kind of change (example output correction). The changeset corrects the JSON_ARRAYAGG output from [2, 1] to [1, 2] and reorders the JSON_OBJECTA…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description follows the TiDB docs template. It fills in the required sections: what changed (both example outputs corrected, with the ordering caveat added), the affected version (master only, wit…
Full details: Title check

Explanation

The title names the two JSON aggregate functions and the kind of change (example output correction). The changeset corrects the JSON_ARRAYAGG output from [2, 1] to [1, 2] and reorders the JSON_OBJECTAGG example rows, and adds ordering-not-guaranteed notes. The title is specific and matches the main change.

Full details: Description check

Explanation

The description follows the TiDB docs template. It fills in the required sections: what changed (both example outputs corrected, with the ordering caveat added), the affected version (master only, with a reason), related links (none), and AI agent involvement (checked). It also includes the contributor checklist with the CLA box ticked. The author gives concrete reproduction steps and server output for both examples, so reviewers can verify the change.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: pingcap/docs
  • Branch: master
  • File: .coderabbit.yaml
  • Commit: 919f708
  • Layers: Repository YAML
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: f8ce6040-2f25-496e-8053-d397d6e5ab8e
Commits

Reviewing files that changed from the base of the PR and between 417fe39 and 4bbe1e5.

Files selected for processing: 1

  • functions-and-operators/json-functions/json-functions-aggregate.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.

Both examples on this page showed an output order that the current release does
not produce, and aggregate order is not guaranteed in the first place:

- JSON_ARRAYAGG showed [2, 1]; the current release returns [1, 2].
- JSON_OBJECTAGG showed rose, orchid, tulip; the current release returns
  rose, tulip, orchid.

Correct both outputs and state that the order of the values in the array and the
order of the rows in the result are not guaranteed, so the examples are not read
as a promise about ordering.

Signed-off-by: YG <tongriyaotxt@users.noreply.github.com>
@tongriyaotxt tongriyaotxt changed the title docs: fix the JSON_ARRAYAGG example output docs: correct the JSON_ARRAYAGG and JSON_OBJECTAGG example output Nov 22, 2026
@ti-chi-bot

ti-chi-bot Bot commented Nov 22, 2026

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign lance6716 for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@tongriyaotxt
tongriyaotxt force-pushed the fix/json-arrayagg-example-order branch from 417fe39 to 4bbe1e5 Compare November 22, 2026 06:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

contribution This PR is from a community contributor. first-time-contributor Indicates that the PR was contributed by an external member and is a first-time contributor. missing-translation-status This PR does not have translation status info. needs-ok-to-test Indicates a PR created by contributors and need ORG member send '/ok-to-test' to start testing. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant