Cypher25 default language

[renetapopova]

Replaces #2153

[Hunterness]

Only got started on the review, have looked at 11/21 files and have all the big ones left. But figured I'd post the comments I have so far as I'm pausing for the day.

Status: 3 open comments

[Hunterness]

I feel like it's a bit odd to have the new label when only parts of the command is new. most of it is not introduced in this version 🤔

[Hunterness]

or is this to indicate that Cypher 25 in general is introduced then 🤔

[renetapopova]

The label means that they can use this Cypher 25 syntax with this version (whichever it will be). However, what you say is also valid. I'll discuss it with Natalia and Jens.

[Hunterness]

feels like you missed the default language part here? (especially with the \| at the end of the SET OPTION option value row)

[renetapopova]

I haven't missed it. See above.

[Hunterness]

if you didn't miss it you should remove the \| at the end, but as it should be available in both Cypher 5 and in Cypher 25 I still think you missed it, see my motivation on the comment below (in list of comments)/above (when looking at the file)

[Hunterness]

is there actually any syntax differences in alter that would require the tabbed examples? 🤔 the previous PR didn't do tabs for alter 🤷

[renetapopova]

Do we have SET DEFAULT LANGUAGE CYPHER {5\|25} now? If yes, from which version of the server is it available? It's not in the docs.

[Hunterness]

Marks PR was the one to add it to docs so yeah, it's not documented yet...

The command has been merged to both Cypher 5 and 25, but only the SET ... 5 version is generally available as the 25 option is hidden behind the cypher 25 feature flag. We decided that we didn't want to add it to documentation until both values were available, and then document that it exists in both Cypher 5 and Cypher 25.

So for both create and alter, all 4 of:

CYPHER 5 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 5
CYPHER 5 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 25
CYPHER 25 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 5
CYPHER 25 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 25 

will be valid once we release Cypher 25, but at the moment only

CYPHER 5 CREATE/ALTER DATABASE foo SET DEFAULT LANGUAGE CYPHER 5

is, hence us skipping documenting it until all 4 is allowed if that makes sense

[Hunterness]

Still have 2 files left to look at, the privilege file (how did you get over 700 lines changed from our 90 something on the previous PR? XD) and the manage aliases for standard database file (only like 200 more lines changed than the previous PR :P)

Status: 5 open comments

[Hunterness]

Suggested change

	The most common variations include parts of the commands that are optional, or that can have multiple values.
	This page summarizes the various command syntax options.
	Some variations are indicated using special characters.
	See <<administration-syntax-reading,Reading the administration commands syntax>> for details.
	It also includes examples for both Cypher 5 and Cypher 25 when available.
	The most common variations include parts of the commands that are optional, or that can have multiple values.
	Some variations are indicated using special characters.
	See <<administration-syntax-reading,Reading the administration commands syntax>> for details.
	This page summarizes the various command syntax options.
	It also includes examples for both Cypher 5 and Cypher 25 when available.

it felt weird to me to split the two parts talking about the variations

[Hunterness]

I know this isn't from this PR but I'm not sure what

Starting with Neo4j 2025.04, a database alias can also be set as the default database for a composite database.

above even means?

[renetapopova]

https://github.com/neo-technology/neo4j/pull/29748

[Hunterness]

so

Starting with Neo4j 2025.04, a database alias can also be set as the DBMS default database.

same as the regular alias page?

because I think "default database for a composite" doesn't make sense, the composite doesn't have a default database attached to it. (and if you mean alias in composite the composite bit should not go there)

Additionally I don't think constituent aliases can be default database still 🤔 (since you should only be able to access them though the composite and not on it's own) but I'd have to confirm that

[renetapopova]

Should I remove it then?

[Hunterness]

same as in the syntax page, we shouldn't have the hanging \| at the end of the line, and should not need to tab the examples either as there is no syntax difference between Cypher 5 and Cypher 25, both add the set default language clause (with the same syntax in difference to create that have different syntax in the two versions)

[renetapopova]

Does SET DEFAULT LANGUAGE CYPHER {5\|25} exist in 2025.04, 2025.05?

[Hunterness]

Review of alias page

[Hunterness]

do you need this here if it's also in the list right above?

[renetapopova]

Yes, I think so. This is kind of a summary of the remote database aliases.

[renetapopova]

Actually, I can move the note below being changed now and applies to both.

[Hunterness]

Started on the privilege file updates

[Hunterness]

since some of these are not in this page it might still be nice to have the links? Maybe not as a separate list but then combined with the list above

[Hunterness]

* Load data.

should this maybe say Manage load data security. to match the other ones (based on that we previously had a link to the LOAD privileges page to read more about it)

[Hunterness]

Suggested change

	You can also create a custom administrator role that can perform almost all DBMS capabilities, excluding database management.
	You can also create a custom administrator role that can perform almost all DBMS capabilities, excluding database management.

[Hunterness]

the example below doesn't copy the admin role though 🤔

We're still only granting and denying privileges on our own.

[Hunterness]

looks like we previously only had two examples of the second option/custom role as well 🤷

[Hunterness]

looking back in the docs history it looks like we had for 4.0 and 4.1 just one example that did copy admin and deny things (since we didn't have all privileges available to be granted yet at that point). Then in 4.2 it was updated to two examples, neither copying the admin role anymore 🤷

[Hunterness]

both of these examples are still nice on their own as they are, maybe add a third example that actually do CREATE ROLE newRole AS COPY OF admin and then revoke the ability to read/write/load data?

CREATE ROLE newRole AS COPY OF admin;
REVOKE GRANT MATCH {*} ON GRAPH * NODE * FROM newRole;
REVOKE GRANT MATCH {*} ON GRAPH * RELATIONSHIP * FROM newRole;
REVOKE GRANT WRITE ON GRAPH * FROM newRole;
REVOKE GRANT LOAD ON ALL DATA FROM newRole;

potentially also remove the index/constraint/name management

REVOKE GRANT CONSTRAINT MANAGEMENT ON DATABASE * FROM newRole;
REVOKE GRANT INDEX MANAGEMENT ON DATABASE * FROM newRole;
REVOKE GRANT NAME MANAGEMENT ON DATABASE * FROM newRole;
REVOKE GRANT SHOW CONSTRAINT ON DATABASE * FROM newRole;
REVOKE GRANT SHOW INDEX ON DATABASE * FROM newRole;

If you want to be fancy we could also change what they have access on to system only:

REVOKE GRANT ACCESS ON DATABASE * FROM newRole;
GRANT ACCESS ON DATABASE system TO newRole; 

[Hunterness]

also found a typo

Suggested change

	ALTER USER jake REMOVE AUTH 'native SET AUTH 'oidc-okta' { SET id 'jakesUniqueOktaUserId' }
	ALTER USER jake REMOVE AUTH 'native' SET AUTH 'oidc-okta' { SET id 'jakesUniqueOktaUserId' }

[Hunterness]

not changing the info line above this example?

A user that is granted the `SET USER STATUS` privilege is allowed to run the `ALTER USER` administration command with only the `SET STATUS` part:

vs

The `SET USER STATUS` privilege allows the user to run the `ALTER USER` administration command with only the `SET STATUS` part.

[Hunterness]

more missed updates below

A user that is granted the `SET USER HOME DATABASE` privilege is allowed to run the `ALTER USER` administration command with only the `SET HOME DATABASE` or `REMOVE HOME DATABASE` part:

vs

The `SET USER HOME DATABASE` privilege allows the user to run the `ALTER USER` administration command with only the `SET HOME DATABASE` or `REMOVE HOME DATABASE` part.

[Hunterness]

it feels odd to have this note in the home database section, either it should be in all of the sub-privilege sections or maybe move up to the ALTER USER section? 🤔

[neo4j-docops-agent]

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

New pages:

• Configure the Cypher default version
• Alter composite databases
• Start and stop composite databases
• Start and stop databases

Updated pages:

• DBMS privileges
• Configuration
• Managing database aliases in composite databases
• Managing database aliases for standard databases
• Create composite databases
• List composite databases
• Alter databases
• Configuration parameters
• Create databases

[Hunterness]

Next chunk of the privilege file updates

[Hunterness]

why remove the link to the page about how to read the syntax summaries?

[Hunterness]

I can see we had this comment before as well, not sure why we add it here since that is true for all privileges 🤔 the role you try to grant a privilege to must exist regardless of which privilege it is 🤷

[Hunterness]

a) the It is also possible to deny and revoke that privilege. probably belonged to the above example and not this one
b) that also feels like a more generic privilege thing

so I think we could skip the (or revoke) here in general and remove the old sentence 🤷

Suggested change

	You can grant (or revoke) the privilege to impersonate specific users or a subset of users using the following query:
	You can grant the privilege to impersonate specific users or a subset of users using the following query:

[Hunterness]

with the reordering you introduced some inaccurate statements. Now it was inaccurate already since we use the same role without actually removing the old privileges anyway but it got more so now.

Lets take a stab at having your order and make it work/accurate:

=== Grant privilege to impersonate all users

You can grant the privilege to impersonate all users using the `IMPERSONATE (*)` privilege.
For example:

.Query
[source, cypher, role=noplay]
----
GRANT IMPERSONATE (*) ON DBMS TO allUserImpersonator
----

As a result, the `allUserImpersonator` role has privileges that allow impersonating all users.
To list all privileges for the role `allUserImpersonator` as commands, use the following query:

.Query
[source, cypher, role=noplay]
----
SHOW ROLE allUserImpersonator PRIVILEGES AS COMMANDS
----
.Result
[options="header,footer", width="100%", cols="m"]
|===
| command
| "GRANT IMPERSONATE (*) ON DBMS TO `allUserImpersonator`"
a|Rows: 1
|===
----

=== Grant privilege to impersonate specific users

You can also grant the privilege to impersonate specific users or a subset of users.
For example:

.Query
[source, cypher, role=noplay]
----
GRANT IMPERSONATE (alice, bob) ON DBMS TO userImpersonator
----

As a result, the `userImpersonator` role has privileges that allow impersonating only `alice` and `bob`.
Then, you deny the privilege to impersonate `alice`:

.Query
[source, cypher, role=noplay]
----
DENY IMPERSONATE (alice) ON DBMS TO userImpersonator
----

As a result, the `userImpersonator` user would be able to impersonate only `bob`.

Things I updated:

• The all user example has a new role name (so it would need to be added to the test setup)
• The last sentence is updated to reflect what happens within this example and role instead of being a mix of this and the all user one
• Updated the intro sentence to not have both the following query: and For example:
• While I didn't add it here, it might be nice to add a SHOW for userImpersonator as well, showing both the grant on alice and bob and the deny on alice?

[Hunterness]

Another alternative for the deny example if we want to keep it being impersonate all users, except `alice` is to have a third role which gets both the GRANT IMPERSONATE (*) and DENY IMPERSONATE (alice) privileges (or reuse the role from the all example, but then you'd need to mention that we already have the GRANT IMPERSONATE (*) I think)

[Hunterness]

here as well as above, why remove this?

[Hunterness]

@NataliaIvakina this one too

[Hunterness]

same as the above ones, why remove this link?

[Hunterness]

so

Starting with Neo4j 2025.04, a database alias can also be set as the DBMS default database.

same as the regular alias page?

because I think "default database for a composite" doesn't make sense, the composite doesn't have a default database attached to it. (and if you mean alias in composite the composite bit should not go there)

Additionally I don't think constituent aliases can be default database still 🤔 (since you should only be able to access them though the composite and not on it's own) but I'd have to confirm that

[Hunterness]

Suggested change

	The DBMS privileges for alias management can be granted, denied and revoked like other privileges and can be applied to both local and remote aliases.
	The DBMS privileges for alias management can be granted, denied and revoked like other privileges and applies to both local and remote aliases.

might actually be better, saying can be applied to might indicate that you can have/have two versions of the privileges, one for each 🤔

[Hunterness]

Got through the file, now everything have been looked at once

[Hunterness]

same as the ones yesterday, why remove this linking?

[Hunterness]

I can see you removed the one at least in the next section as well, I'll not add more comments on these but I don't think any of them should have been removed as they are links to read more about how to read the syntax summaries right below

[Hunterness]

wouldn't you need to create the serverManager and serverLister roles as well to the test setup at the top of the file? 🤔

[Hunterness]

since we just wrote about requiring two privileges it feels a bit like For example connects to that and not just this privilege :(

maybe just having a new like in between is enough to separate them and make it clearer that the example is for this section/privilege and not connected to the sentence just before it?

Suggested change

	For example:
	For example:

[Hunterness]

I think most other sections have ...Shower and not ...Lister for the roles that can only show things? 🤔

[Hunterness]

Looks like the alias section has Lister but the roles, users and privileges has Shower (the others don't have just show privileges)

[Hunterness]

Feels odd to me to have the For example: on the same line as A user with this privilege is allowed to execute `GRANT` and `DENY` administration commands. if you have a line break after the first line 🤔

I would probably prefer either having all of them on new lines:

You can grant the privilege to assign privileges using the `ASSIGN PRIVILEGE` privilege.
A user with this privilege is allowed to execute `GRANT` and `DENY` administration commands.
For example:

or no newlines:

You can grant the privilege to assign privileges using the `ASSIGN PRIVILEGE` privilege. A user with this privilege is allowed to execute `GRANT` and `DENY` administration commands. For example:

or do as I thought on the previous section and add one empty line before the For example::

You can grant the privilege to assign privileges using the `ASSIGN PRIVILEGE` privilege.
A user with this privilege is allowed to execute `GRANT` and `DENY` administration commands.

For example:

(all examples of how it would look rendered and not in code with the +/line breaks between sentences)

I can see we also have this in the sections further below (and the one just above), so whatever we decide on should probably be the same in all those places as well.

[Hunterness]

I know this is from before but allow querying settings feels odd to me, allow showing settings/allow listing settings/allow viewing settings might be better?

[Hunterness]

Suggested change

	=== Grant privilege to show specific settings
	=== Grant privilege to show execute all but some settings

[Hunterness]

Suggested change

	You can grant the privilege to show all settings using `SHOW SETTINGS *` and deny the unwanted settings. +
	You can grant the privilege to show all but a few settings using `SHOW SETTINGS *` and deny the unwanted settings. +

[Hunterness]

so just above here we have

As the query result shows, access to any setting starting with `dbms.security` are blocked, but the rest can still be queried.

which have the same weirdness around saying querying and now also access.

[Hunterness]

I also saw it in at least the syntax table so I think it's just throughout this section

[l-heemann]

Yeah I think we have some language weirdness going on.
query is overloaded in meaning both:
"I query (ask) the database" and "I send a query (question) to the database"

and access has somewhat special meaning in the cypher-operations context where I think "Access to the setting" may be misinterpreted as "The ability to interact/modify the setting" rather than "The ability to view/see/show the setting"

[Hunterness]

since I can't comment below:

* Create, alter, and drop databases and aliases.
* Enable, alter, rename, reallocate, deallocate, and drop servers

should both probably also say show? (show databases might not be a privilege as such but show aliases are at least and those lines are combined into one so (plus the database privileges affect which databases are returned by show databases so it's not that wrong 🤷))