Skip to content

Show columns clarifications #1826

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 30, 2024
Merged

Show columns clarifications #1826

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
44515fc
Update the column descriptions for SHOW ROLES
Hunterness Sep 25, 2024
5d52151
Update the column description for SHOW PRIVILEGES AS COMMANDS
Hunterness Sep 25, 2024
d0033de
address review comments
Hunterness Sep 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions modules/ROOT/pages/authentication-authorization/manage-privileges.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -439,9 +439,25 @@ Other users' privileges cannot be listed when using a non-native auth provider.
When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted.

For an easy overview of the existing privileges, it is recommended to use the `AS COMMANDS` version of the `SHOW` command.
This returns the column `command` of type `STRING` containing the privileges as the commands that are granted or denied.
This returns two columns:
[options="header", width="100%", cols="2a,4,2m"]
|===
| Column
| Description
| Type

| command
| The privilege as the command that is granted or denied.
Or in the `AS REVOKE COMMANDS` case, the command to revoke the privilege. label:default-output[]
| STRING

| immutable
| Whether or not the privilege is immutable.
| BOOLEAN
|===

When omitting the `AS COMMANDS` clause, results will include multiple columns describing privileges:
When omitting the `AS COMMANDS` clause, results will include multiple columns describing privileges instead.
They are all returned by default.
Copy link
Collaborator

Choose a reason for hiding this comment

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

This sounds like some of the details are not returned by default. I would suggest to remove it.

Suggested change
They are all returned by default.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Not sure what you mean? they are all default columns returned without a YIELD which is what this is marking. A lot of other tables like this has either another column (or two) showing if they are returned by default for the command or need a yield or they have the default label on them. But since that would be true for all rows in this table we just have this comment instead.

If this is about the column only returned by the SHOW USER PRIVILEGE versions, then it is still a default column by the definition we use it for (not requiring YIELD) it is just not available for all versions of the command.

Copy link
Collaborator

Choose a reason for hiding this comment

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

I couldn't get from the message that the default was without YIELD.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think it comes from that being the language we have used throughout the admin command sections, we talk about what is returned by default and what columns you need a YIELD for 🤷


[options="header", width="100%", cols="4m,6a,2m"]
|===
Expand Down Expand Up @@ -475,8 +491,6 @@ E.g., the entire DBMS, a specific database, a graph, or sub-graph access.

| immutable
| Whether or not the privilege is immutable.

This column is also available for the `AS COMMAND` variant using `YIELD`.
| BOOLEAN

| user
Expand Down
41 changes: 33 additions & 8 deletions modules/ROOT/pages/authentication-authorization/manage-roles.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ Lists the privileges granted to the specified roles.

When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted.

For more information, see xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges].
The `SHOW ROLE name PRIVILEGES` command is described in xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges].

| Required privilege
a|
Expand Down Expand Up @@ -340,8 +340,21 @@ For more information, see xref:authentication-authorization/dbms-administration.


Available roles can be seen using `SHOW ROLES`.
This returns a single column `role` of type `STRING`, containing the role name.

This returns a single column.
[options="header", width="100%", cols="2a,4,2m"]
|===
| Column
| Description
| Type

| role
| Role name
| STRING
|===

.List all roles
====
[source, cypher, role=noplay]
----
SHOW ROLES
Expand All @@ -363,6 +376,7 @@ This is the same command as `SHOW ALL ROLES`.

1+a|Rows: 6
|===
====

When first starting a Neo4j DBMS, there are a number of built-in roles:

Expand All @@ -379,9 +393,21 @@ More information about the built-in roles and their privileges can be found in x
There are multiple versions of this command, the default being `SHOW ALL ROLES`.
To only show roles that are assigned to users, the command is `SHOW POPULATED ROLES`.
To see which users are assigned to which roles, `WITH USERS` can be added to the command.
This will return an additional `STRING` column, `member`, containing the username.
The command produces a row per role per user and yields the following column in addition to the one output by `SHOW ROLES`:
[options="header", width="100%", cols="2a,4,2m"]
|===
| Column
| Description
| Type

| member
| User name
| STRING
|===
Since this gives a result with one row for each user, if a role is assigned to two users it will show up twice.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
Since this gives a result with one row for each user, if a role is assigned to two users it will show up twice.
Since this gives a result with one row for each user, it shows up twice if a role is assigned to two users.


.Show roles with users
====
[source, cypher, role=noplay]
----
SHOW POPULATED ROLES WITH USERS
Expand Down Expand Up @@ -415,9 +441,12 @@ The table of results will show information about the role and what database it b

2+a|Rows: 6
|===
====

It is also possible to filter and sort the results by using `YIELD`, `ORDER BY` and `WHERE`:
It is also possible to filter and sort the results by using `YIELD`, `ORDER BY` and `WHERE`.

.Show roles with ordering and filtering
====
[source, cypher, role=noplay]
----
SHOW ROLES YIELD role
Expand All @@ -443,10 +472,6 @@ It is also possible to use `SKIP` and `LIMIT` to paginate the results.

1+a|Rows: 3
|===

[NOTE]
====
The `SHOW ROLE name PRIVILEGES` command is found in xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges].
====


Expand Down