Skip to content

Unified SHOW page prototype#1531

Open
JPryce-Aklundh wants to merge 11 commits into
neo4j:devfrom
JPryce-Aklundh:show_playground
Open

Unified SHOW page prototype#1531
JPryce-Aklundh wants to merge 11 commits into
neo4j:devfrom
JPryce-Aklundh:show_playground

Conversation

@JPryce-Aklundh
Copy link
Copy Markdown
Collaborator

@JPryce-Aklundh JPryce-Aklundh commented Apr 23, 2026

A suggestion to make our docs for the various SHOW commands more consistent and easier to maintain.

Comment thread modules/ROOT/pages/clauses/index.adoc Outdated
Comment thread modules/ROOT/pages/clauses/index.adoc Outdated
Comment thread modules/ROOT/pages/clauses/index.adoc Outdated
Comment thread modules/ROOT/pages/clauses/index.adoc Outdated
Comment thread modules/ROOT/content-nav.adoc Outdated
Comment thread modules/ROOT/pages/functions/show-functions.adoc
Comment thread modules/ROOT/pages/functions/show-functions.adoc
Copy link
Copy Markdown
Contributor

@renetapopova renetapopova left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left some comments on the SHOW page.

Comment thread modules/ROOT/pages/clauses/show.adoc Outdated

The `SHOW` command can be used to show the metadata of a database or a DBMS.
This page discusses common behavior to all `SHOW` commands.
Rules pertaining to specific `SHOW` commands, as well as the different columns returned by them, are listed elsewhere in the documentation:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Rules pertaining to specific `SHOW` commands, as well as the different columns returned by them, are listed elsewhere in the documentation:
Rules pertaining to specific `SHOW` commands, as well as the different columns returned by them, are listed on other pages or in the Operations Manual as follows:

This page discusses common behavior to all `SHOW` commands.
Rules pertaining to specific `SHOW` commands, as well as the different columns returned by them, are listed elsewhere in the documentation:

* link:{neo4j-docs-base-uri}/operations-manual/current/authentication-authorization/attribute-based-access-control/#_listing_auth_rules[`SHOW AUTH RULES` (Operations Manual)]
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* link:{neo4j-docs-base-uri}/operations-manual/current/authentication-authorization/attribute-based-access-control/#_listing_auth_rules[`SHOW AUTH RULES` (Operations Manual)]
* link:{neo4j-docs-base-uri}/operations-manual/current/authentication-authorization/attribute-based-access-control/#_listing_auth_rules[Operations Manual -> `SHOW AUTH RULES`]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the standard we follow when referring to other manuals, if you want to keep it here as well. The same will apply to the rest of the links.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but here I think it makes it more difficult to follow - it is easier to follow the alphabetical order if "Ops Manual" is not inserted before most entries. So I will leave this as is.

Comment thread modules/ROOT/pages/clauses/show.adoc Outdated
[[common-behavior-and-rules]]
== Common behavior and rules

This section lists the behavior and rules common to all `SHOW` commands.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we decided some time ago not to start pages or sections with This page outlines, this section shows, etc.
Maybe you can say something like

Suggested change
This section lists the behavior and rules common to all `SHOW` commands.
All `SHOW` commands have similar behavior and comply to the same rules.

Comment thread modules/ROOT/pages/clauses/show.adoc Outdated
[[using-show-with-yield]]
=== Returning default and non-default columns using `SHOW` and `YIELD`

All `SHOW` commands have default return columns, and most have non-default return columns as well (for information about the specific columns, visit the documentation for the specific `SHOW` command listed above).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
All `SHOW` commands have default return columns, and most have non-default return columns as well (for information about the specific columns, visit the documentation for the specific `SHOW` command listed above).
All `SHOW` commands have default return columns, and most have non-default return columns as well.
For information about the specific columns, see the documentation for the specific `SHOW` command listed in <<show-commands-documentation, Table 1. Show commands documentation links>>.

Comment thread modules/ROOT/pages/clauses/show.adoc Outdated

All `SHOW` commands have default return columns, and most have non-default return columns as well (for information about the specific columns, visit the documentation for the specific `SHOW` command listed above).

To return non-default columns, `YIELD` must be used either to return only specific columns or all available columns.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To return non-default columns, `YIELD` must be used either to return only specific columns or all available columns.
Using `YIELD` returns non-default columns, either specific columns or all available columns.

Comment on lines +97 to +103
[NOTE]
====
When combining a `SHOW` command with other clauses, the `YIELD` clause is mandatory and must not be omitted.
In addition, `YIELD *` is not permitted.
Instead, the `YIELD` clause needs to explicitly list the yielded columns.
The query must also end with a valid last clause (like a `RETURN` or an updating clause).
====
Copy link
Copy Markdown
Contributor

@renetapopova renetapopova May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[NOTE]
====
When combining a `SHOW` command with other clauses, the `YIELD` clause is mandatory and must not be omitted.
In addition, `YIELD *` is not permitted.
Instead, the `YIELD` clause needs to explicitly list the yielded columns.
The query must also end with a valid last clause (like a `RETURN` or an updating clause).
====
[NOTE]
====
When combining a `SHOW` command with other clauses, the `YIELD` clause is mandatory and must not be omitted.
`YIELD` must explicitly list the yielded columns.
`YIELD *` is not permitted.
The query must also end with a valid last clause (like a `RETURN` or an updating clause).
====

@JPryce-Aklundh JPryce-Aklundh marked this pull request as ready for review May 15, 2026 07:40
Comment thread modules/ROOT/pages/clauses/show.adoc Outdated
Comment thread modules/ROOT/pages/functions/show-functions.adoc Outdated
Comment thread modules/ROOT/pages/clauses/show.adoc Outdated
Comment thread modules/ROOT/pages/functions/show-functions.adoc
Comment thread modules/ROOT/pages/functions/show-functions.adoc Outdated
Comment thread modules/ROOT/pages/functions/show-functions.adoc Outdated
Comment thread modules/ROOT/pages/functions/show-functions.adoc Outdated
@neo4j-docops-agent
Copy link
Copy Markdown
Collaborator

This PR includes documentation updates
View the updated docs at https://neo4j-docs-cypher-1531.surge.sh

New pages:

Updated pages:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants