diff --git a/antora.yml b/antora.yml index ae0223347..497091fec 100644 --- a/antora.yml +++ b/antora.yml @@ -7,5 +7,5 @@ nav: asciidoc: attributes: neo4j-version: '5' - neo4j-version-minor: '5.12' - neo4j-version-exact: '5.12.0' + neo4j-version-minor: '5.13' + neo4j-version-exact: '5.13.0' diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 2010ac6a9..c163f5e20 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -84,38 +84,22 @@ ** xref:constraints/syntax.adoc[] ** xref:constraints/examples.adoc[] -* xref:query-tuning/index.adoc[] -** xref:query-tuning/query-options.adoc[] -** xref:query-tuning/query-profile.adoc[] -** xref:query-tuning/indexes.adoc[] -** xref:query-tuning/basic-example.adoc[] -** xref:query-tuning/advanced-example.adoc[] -** xref:query-tuning/using.adoc[] - -* xref:execution-plans/index.adoc[] -** xref:execution-plans/db-hits.adoc[] -** xref:execution-plans/operator-summary.adoc[] -** xref:execution-plans/operators.adoc[] -** xref:execution-plans/shortestpath-planning.adoc[] +* xref:planning-and-tuning/index.adoc[] +** xref:planning-and-tuning/execution-plans.adoc[] +** xref:planning-and-tuning/operators/index.adoc[] +*** xref:planning-and-tuning/operators/operators-detail.adoc[] +** xref:planning-and-tuning/runtimes/index.adoc[] +*** xref:planning-and-tuning/runtimes/concepts.adoc[Concepts] +*** xref:planning-and-tuning/runtimes/reference.adoc[] +** xref:planning-and-tuning/query-tuning/index.adoc[] +*** xref:planning-and-tuning/query-tuning/indexes.adoc[] +*** xref:planning-and-tuning/query-tuning/using.adoc[] +*** xref:planning-and-tuning/query-tuning/query-options.adoc[] * xref:query-caches/index.adoc[] ** xref:query-caches/unified-query-caches.adoc[] * xref:administration/index.adoc[] -** xref:administration/databases.adoc[] -** xref:administration/aliases.adoc[] -** xref:administration/servers.adoc[] -** xref:administration/access-control/index.adoc[] -*** xref:administration/access-control/manage-users.adoc[] -*** xref:administration/access-control/manage-roles.adoc[] -*** xref:administration/access-control/manage-privileges.adoc[] -*** xref:administration/access-control/built-in-roles.adoc[] -*** xref:administration/access-control/privileges-reads.adoc[] -*** xref:administration/access-control/privileges-writes.adoc[] -*** xref:administration/access-control/database-administration.adoc[] -*** xref:administration/access-control/dbms-administration.adoc[] -*** xref:administration/access-control/limitations.adoc[] -*** xref:administration/access-control/privileges-immutable.adoc[] * xref:syntax/index.adoc[] ** xref:syntax/parsing.adoc[] @@ -127,7 +111,7 @@ ** xref:syntax/comments.adoc[] * xref:deprecations-additions-removals-compatibility.adoc[] -* xref:keyword-glossary.adoc[] * Appendix ** xref:styleguide.adoc[] +** xref:appendix/tutorials/index.adoc[] diff --git a/modules/ROOT/images/privileges_grant_and_deny_syntax.svg b/modules/ROOT/images/privileges_grant_and_deny_syntax.svg index 651f74540..156002d3a 100644 --- a/modules/ROOT/images/privileges_grant_and_deny_syntax.svg +++ b/modules/ROOT/images/privileges_grant_and_deny_syntax.svg @@ -1,9 +1 @@ - - - - - - - - - + \ No newline at end of file diff --git a/modules/ROOT/images/privileges_grant_and_deny_syntax_load_privileges.svg b/modules/ROOT/images/privileges_grant_and_deny_syntax_load_privileges.svg new file mode 100644 index 000000000..8cf4a0eb4 --- /dev/null +++ b/modules/ROOT/images/privileges_grant_and_deny_syntax_load_privileges.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/modules/ROOT/images/privileges_on_graph_syntax.svg b/modules/ROOT/images/privileges_on_graph_syntax.svg index 689c5c798..321deeb2b 100644 --- a/modules/ROOT/images/privileges_on_graph_syntax.svg +++ b/modules/ROOT/images/privileges_on_graph_syntax.svg @@ -1,9 +1 @@ - - - - - - - - - + \ No newline at end of file diff --git a/modules/ROOT/images/runtimes_cypher_lifecycle.svg b/modules/ROOT/images/runtimes_cypher_lifecycle.svg new file mode 100644 index 000000000..59e43075f --- /dev/null +++ b/modules/ROOT/images/runtimes_cypher_lifecycle.svg @@ -0,0 +1,41 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/ROOT/images/runtimes_execution_graph1.svg b/modules/ROOT/images/runtimes_execution_graph1.svg new file mode 100644 index 000000000..f98891b76 --- /dev/null +++ b/modules/ROOT/images/runtimes_execution_graph1.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/modules/ROOT/images/runtimes_execution_graph2.svg b/modules/ROOT/images/runtimes_execution_graph2.svg new file mode 100644 index 000000000..bc4e9c20a --- /dev/null +++ b/modules/ROOT/images/runtimes_execution_graph2.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/modules/ROOT/pages/administration/access-control/built-in-roles.adoc b/modules/ROOT/pages/administration/access-control/built-in-roles.adoc deleted file mode 100644 index c3b864362..000000000 --- a/modules/ROOT/pages/administration/access-control/built-in-roles.adoc +++ /dev/null @@ -1,497 +0,0 @@ -:description: The default privileges of the built-in roles in Neo4j and how to recreate them if needed. -[role=enterprise-edition aura-db-enterprise] -[[access-control-built-in-roles]] -= Built-in roles and privileges - -This page explains the default privileges of the built-in roles in Neo4j and how to recreate them if needed. - -All of the commands described in this chapter require that the user executing the commands has the rights to do so. -The privileges listed in the following sections are the default set of privileges for each built-in role: - -* xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-public[The `PUBLIC` role] -* xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-reader[The `reader` role] -* xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-editor[The `editor` role] -* xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-publisher[The `publisher` role] -* xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-architect[The `architect` role] -* xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-admin[The `admin` role] - -[[access-control-built-in-roles-public]] -== The `PUBLIC` role - -All users are granted the `PUBLIC` role, and it can not be revoked or dropped. -By default, it gives access to the default database and allows executing all procedures and user-defined functions. - -[IMPORTANT] -==== -The `PUBLIC` role cannot be dropped or revoked from any user, but the specific privileges for the role can be modified. -In contrast to the `PUBLIC` role, the other built-in roles can be granted, revoked, dropped, and re-created. -==== - -[[access-control-built-in-roles-public-list]] -=== Listing `PUBLIC` role privileges - -[source, cypher, role=noplay] ----- -SHOW ROLE PUBLIC PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ACCESS ON HOME DATABASE TO `PUBLIC`" -|"GRANT EXECUTE FUNCTION * ON DBMS TO `PUBLIC`" -|"GRANT EXECUTE PROCEDURE * ON DBMS TO `PUBLIC`" -a|Rows: 3 -|=== - - -[[access-control-built-in-roles-public-recreate]] -=== Recreating the `PUBLIC` role - -The `PUBLIC` role can not be dropped and thus there is no need to recreate the role itself. -To restore the role to its original capabilities, two steps are needed. - -First, all `GRANT` or `DENY` privileges on this role should be revoked (see output of `SHOW ROLE PUBLIC PRIVILEGES AS REVOKE COMMANDS` on what to revoke). -Secondly, run these queries: - -[source, cypher, role=noplay] ----- -GRANT ACCESS ON HOME DATABASE TO PUBLIC ----- - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURES * ON DBMS TO PUBLIC ----- - -[source, cypher, role=noplay] ----- -GRANT EXECUTE USER DEFINED FUNCTIONS * ON DBMS TO PUBLIC ----- - -The resulting `PUBLIC` role now has the same privileges as the original built-in `PUBLIC` role. - - -[[access-control-built-in-roles-reader]] -== The `reader` role - -The `reader` role can perform read-only queries on all graphs except for the `system` database. - - -[[access-control-built-in-roles-reader-list]] -=== Listing `reader` role privileges - -[source, cypher, role=noplay] ----- -SHOW ROLE reader PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ACCESS ON DATABASE * TO `reader`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `reader`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `reader`" -|"GRANT SHOW CONSTRAINT ON DATABASE * TO `reader`" -|"GRANT SHOW INDEX ON DATABASE * TO `reader`" -a|Rows: 5 -|=== - - -[[access-control-built-in-roles-reader-recreate]] -=== Recreating the `reader` role - -//// -[source, cypher, role=test-setup] ----- -DROP ROLE reader; ----- -//// - -To restore the role to its original capabilities two steps are needed. -First, execute `DROP ROLE reader`. -Secondly, run these queries: - -[source, cypher, role=noplay] ----- -CREATE ROLE reader ----- - -[source, cypher, role=noplay] ----- -GRANT ACCESS ON DATABASE * TO reader ----- - -[source, cypher, role=noplay] ----- -GRANT MATCH {*} ON GRAPH * TO reader ----- - -[source, cypher, role=noplay] ----- -GRANT SHOW CONSTRAINT ON DATABASE * TO reader ----- - -[source, cypher, role=noplay] ----- -GRANT SHOW INDEX ON DATABASE * TO reader ----- - -The resulting `reader` role now has the same privileges as the original built-in `reader` role. - - -[[access-control-built-in-roles-editor]] -== The `editor` role - -The `editor` role can perform read and write operations on all graphs except for the `system` database, but it cannot create new labels, property keys or relationship types. - -[[access-control-built-in-roles-editor-list]] -=== Listing `editor` role privileges - -[source, cypher, role=noplay] ----- -SHOW ROLE editor PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ACCESS ON DATABASE * TO `editor`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `editor`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `editor`" -|"GRANT SHOW CONSTRAINT ON DATABASE * TO `editor`" -|"GRANT SHOW INDEX ON DATABASE * TO `editor`" -|"GRANT WRITE ON GRAPH * TO `editor`" -a|Rows: 6 -|=== - - -[[access-control-built-in-roles-editor-recreate]] -=== Recreating the `editor` role - -//// -[source, cypher, role=test-setup] ----- -DROP ROLE editor; ----- -//// - -To restore the role to its original capabilities two steps are needed. -First, execute `DROP ROLE editor`. -Secondly, run these queries: - -[source, cypher, role=noplay] ----- -CREATE ROLE editor ----- - -[source, cypher, role=noplay] ----- -GRANT ACCESS ON DATABASE * TO editor ----- - -[source, cypher, role=noplay] ----- -GRANT MATCH {*} ON GRAPH * TO editor ----- - -[source, cypher, role=noplay] ----- -GRANT WRITE ON GRAPH * TO editor ----- - -[source, cypher, role=noplay] ----- -GRANT SHOW CONSTRAINT ON DATABASE * TO editor ----- - -[source, cypher, role=noplay] ----- -GRANT SHOW INDEX ON DATABASE * TO editor ----- - -The resulting `editor` role now has the same privileges as the original built-in `editor` role. - - -[[access-control-built-in-roles-publisher]] -== The `publisher` role - -The `publisher` role can do the same as xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-editor[`editor`], as well as create new labels, property keys and relationship types. - - -[[access-control-built-in-roles-publisher-list]] -=== Listing `publisher` role privileges - -[source, cypher, role=noplay] ----- -SHOW ROLE publisher PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ACCESS ON DATABASE * TO `publisher`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `publisher`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `publisher`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `publisher`" -|"GRANT SHOW CONSTRAINT ON DATABASE * TO `publisher`" -|"GRANT SHOW INDEX ON DATABASE * TO `publisher`" -|"GRANT WRITE ON GRAPH * TO `publisher`" -a|Rows: 7 -|=== - - -[[access-control-built-in-roles-publisher-recreate]] -=== Recreating the `publisher` role - -//// -[source, cypher, role=test-setup] ----- -DROP ROLE publisher; ----- -//// - -To restore the role to its original capabilities two steps are needed. -First, execute `DROP ROLE publisher`. -Secondly, run these queries: - -[source, cypher, role=noplay] ----- -CREATE ROLE publisher ----- - -[source, cypher, role=noplay] ----- -GRANT ACCESS ON DATABASE * TO publisher ----- - -[source, cypher, role=noplay] ----- -GRANT MATCH {*} ON GRAPH * TO publisher ----- - -[source, cypher, role=noplay] ----- -GRANT WRITE ON GRAPH * TO publisher ----- - -[source, cypher, role=noplay] ----- -GRANT NAME MANAGEMENT ON DATABASE * TO publisher ----- - -[source, cypher, role=noplay] ----- -GRANT SHOW CONSTRAINT ON DATABASE * TO publisher ----- - -[source, cypher, role=noplay] ----- -GRANT SHOW INDEX ON DATABASE * TO publisher ----- - -The resulting `publisher` role now has the same privileges as the original built-in `publisher` role. - - -[[access-control-built-in-roles-architect]] -== The `architect` role - -The `architect` role can do the same as the xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-publisher[`publisher`], as well as create and manage indexes and constraints. - - -[[access-control-built-in-roles-architect-list]] -=== Listing `architect` role privileges - -[source, cypher, role=noplay] ----- -SHOW ROLE architect PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ACCESS ON DATABASE * TO `architect`" -|"GRANT CONSTRAINT MANAGEMENT ON DATABASE * TO `architect`" -|"GRANT INDEX MANAGEMENT ON DATABASE * TO `architect`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `architect`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `architect`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `architect`" -|"GRANT SHOW CONSTRAINT ON DATABASE * TO `architect`" -|"GRANT SHOW INDEX ON DATABASE * TO `architect`" -|"GRANT WRITE ON GRAPH * TO `architect`" -a|Rows: 9 -|=== - - -[[access-control-built-in-roles-architect-recreate]] -=== Recreating the `architect` role - -//// -[source, cypher, role=test-setup] ----- -DROP ROLE architect; ----- -//// - -To restore the role to its original capabilities two steps are needed. -First, execute `DROP ROLE architect`. -Secondly, run these queries: - -[source, cypher, role=noplay] ----- -CREATE ROLE architect ----- - -[source, cypher, role=noplay] ----- -GRANT ACCESS ON DATABASE * TO architect ----- - -[source, cypher, role=noplay] ----- -GRANT MATCH {*} ON GRAPH * TO architect ----- - -[source, cypher, role=noplay] ----- -GRANT WRITE ON GRAPH * TO architect ----- - -[source, cypher, role=noplay] ----- -GRANT NAME MANAGEMENT ON DATABASE * TO architect ----- - -[source, cypher, role=noplay] ----- -GRANT SHOW CONSTRAINT ON DATABASE * TO architect ----- - -[source, cypher, role=noplay] ----- -GRANT CONSTRAINT MANAGEMENT ON DATABASE * TO architect ----- - -[source, cypher, role=noplay] ----- -GRANT SHOW INDEX ON DATABASE * TO architect ----- - -[source, cypher, role=noplay] ----- -GRANT INDEX MANAGEMENT ON DATABASE * TO architect ----- - -The resulting `architect` role now has the same privileges as the original built-in `architect` role. - - -[[access-control-built-in-roles-admin]] -== The `admin` role - -The `admin` role can do the same as the xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-architect[`architect`], as well as manage databases, aliases, users, roles and privileges. - -The `admin` role has the ability to perform administrative tasks. -These include the rights to perform the following classes of tasks: - -* Manage xref::administration/access-control/database-administration.adoc[database security] to control the rights to perform actions on specific databases: -** Manage access to a database and the right to start and stop a database. -** Manage xref::indexes-for-search-performance.adoc[indexes] and xref::constraints/index.adoc[constraints]. -** Allow the creation of labels, relationship types or property names. -** Manage transactions -* Manage xref::administration/access-control/dbms-administration.adoc[DBMS security] to control the rights to perform actions on the entire system: -** Manage xref::administration/databases.adoc[multiple databases]. -** Manage xref::administration/access-control/manage-users.adoc[users] and xref::administration/access-control/manage-roles.adoc[roles]. -** Change configuration parameters. -** Manage sub-graph privileges. -** Manage procedure security. - -These rights are conferred using privileges that can be managed through the xref::administration/access-control/manage-privileges.adoc#access-control-graph-privileges[`GRANT`, `DENY` and `REVOKE` commands]. - - -[[access-control-built-in-roles-admin-list]] -=== Listing `admin` role privileges - -[source, cypher, role=noplay] ----- -SHOW ROLE admin PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ACCESS ON DATABASE * TO `admin`" -|"GRANT ALL DBMS PRIVILEGES ON DBMS TO `admin`" -|"GRANT CONSTRAINT MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT INDEX MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `admin`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `admin`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT SHOW CONSTRAINT ON DATABASE * TO `admin`" -|"GRANT SHOW INDEX ON DATABASE * TO `admin`" -|"GRANT START ON DATABASE * TO `admin`" -|"GRANT STOP ON DATABASE * TO `admin`" -|"GRANT TRANSACTION MANAGEMENT (*) ON DATABASE * TO `admin`" -|"GRANT WRITE ON GRAPH * TO `admin`" -a|Rows: 13 -|=== - -If the built-in `admin` role has been altered or dropped, and needs to be restored to its original state, see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/password-and-user-recovery[Operations Manual -> Password and user recovery]. - -[[access-control-built-in-roles-admin-recreate]] -=== Recreating the `admin` role - -To restore the role to its original capabilities two steps are needed. -First, execute `DROP ROLE admin`. -Secondly, run these queries: - -// cannot test as it would require deleting the role the test user is logged with -[source, cypher, role=noplay test-skip] ----- -CREATE ROLE admin ----- - -[source, cypher, role=noplay] ----- -GRANT ALL DBMS PRIVILEGES ON DBMS TO admin ----- - -[source, cypher, role=noplay] ----- -GRANT TRANSACTION MANAGEMENT ON DATABASE * TO admin ----- - -[source, cypher, role=noplay] ----- -GRANT START ON DATABASE * TO admin ----- - -[source, cypher, role=noplay] ----- -GRANT STOP ON DATABASE * TO admin ----- - -[source, cypher, role=noplay] ----- -GRANT MATCH {*} ON GRAPH * TO admin ----- - -[source, cypher, role=noplay] ----- -GRANT WRITE ON GRAPH * TO admin ----- - -[source, cypher, role=noplay] ----- -GRANT ALL ON DATABASE * TO admin ----- - -The resulting `admin` role now has the same effective privileges as the original built-in `admin` role. - -Additional information about restoring the `admin` role can be found in the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/password-and-user-recovery#recover-admin-role[Operations Manual -> Recover the admin role]. - diff --git a/modules/ROOT/pages/administration/access-control/database-administration.adoc b/modules/ROOT/pages/administration/access-control/database-administration.adoc deleted file mode 100644 index 7162e971d..000000000 --- a/modules/ROOT/pages/administration/access-control/database-administration.adoc +++ /dev/null @@ -1,982 +0,0 @@ -:description: How to use Cypher to manage Neo4j database administrative privileges. - -//// -[source, cypher, role=test-setup] ----- -CREATE ROLE regularUsers; -CREATE ROLE databaseAdminUsers; -CREATE DATABASE `remote-db`; -CREATE USER jake SET PASSWORD 'abcd1234' CHANGE NOT REQUIRED; ----- -//// - -[role=enterprise-edition aura-db-enterprise] -[[access-control-database-administration]] -= Database administration - -This page explains how to use Cypher to manage Neo4j database administrative privileges. - -Administrators can use the following Cypher commands to manage Neo4j database administrative rights. - -The components of the database privilege commands are: - -* _command_: -** `GRANT` – gives privileges to roles. -** `DENY` – denies privileges to roles. -** `REVOKE` – removes granted or denied privileges from roles. - -* _mutability_: -** `IMMUTABLE` - When used in conjunction with `GRANT` or `DENY`, specifies that a privilege cannot subsequently be removed unless auth is disabled. -Contrastingly, when `IMMUTABLE` is specified in conjunction with a `REVOKE` command, it will act as a filter and only remove matching _immutable_ privileges. -See also xref:administration/access-control/index.adoc#access-control-privileges-immutable[immutable privileges]. - -* _database-privilege_ -** `ACCESS` - allows access to a specific database or remote database alias. -** `START` - allows the specified database to be started. -** `STOP` - allows the specified database to be stopped. -** `CREATE INDEX` - allows indexes to be created on the specified database. -** `DROP INDEX` - allows indexes to be deleted on the specified database. -** `SHOW INDEX` - allows indexes to be listed on the specified database. -** `INDEX [MANAGEMENT]` - allows indexes to be created, deleted, and listed on the specified database. -** `CREATE CONSTRAINT` - allows constraints to be created on the specified database. -** `DROP CONSTRAINT` - allows constraints to be deleted on the specified database. -** `SHOW CONSTRAINT` - allows constraints to be listed on the specified database. -** `CONSTRAINT [MANAGEMENT]` - allows constraints to be created, deleted, and listed on the specified database. -** `CREATE NEW [NODE] LABEL` - allows new node labels to be created. -** `CREATE NEW [RELATIONSHIP] TYPE` - allows new relationship types to be created. -** `CREATE NEW [PROPERTY] NAME` - allows property names to be created, so that nodes and relationships can have properties assigned with these names. -** `NAME [MANAGEMENT]` - allows all of the name management capabilities: node labels, relationship types, and property names. -** `ALL [[DATABASE] PRIVILEGES]` - allows access, index, constraint, and name management for the specified database or remote database alias. -** `SHOW TRANSACTION` - allows listing transactions and queries for the specified users on the specified database. -** `TERMINATE TRANSACTION` - allows ending transactions and queries for the specified users on the specified database. -** `TRANSACTION [MANAGEMENT]` - allows listing and ending transactions and queries for the specified users on the specified database. - -* _name_ -** The database to associate the privilege with. -+ -[NOTE] -==== -If you delete a database and create a new one with the same name, the new one will NOT have the same privileges previously assigned to the deleted one. -==== -** The _name_ component can be `+*+`, which means all databases. -Databases created after this command execution will also be associated with these privileges. -** The `DATABASE[S] _name_` part of the command can be replaced by `HOME DATABASE`. -This refers to the home database configured for a user or, if that user does not have a home database configured, the default database. -If the user's home database changes for any reason after this command execution, the new one will be associated with these privileges. -This can be quite powerful as it allows permissions to be switched from one database to another simply by changing a user's home database. - -* _role[, ...]_ -** The role or roles to associate the privilege with, comma-separated. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.General grant +ON DATABASE+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT ... ON ... TO ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] database-privilege ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } TO role[, ...] ----- - -| Description -| Grants a privilege to one or multiple roles. - -|=== - - -.General deny +ON DATABASE+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +DENY ... ON ... TO ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -DENY [IMMUTABLE] database-privilege ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } TO role[, ...] ----- - -| Description -| Denies a privilege to one or multiple roles. - -|=== - - -.General revoke +ON DATABASE+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +REVOKE GRANT ... ON ... FROM ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -REVOKE [IMMUTABLE] GRANT database-privilege ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } FROM role[, ...] ----- - -| Description -| Revoke a granted privilege from one or multiple roles. - -|=== - - -.General revoke +ON DATABASE+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +REVOKE DENY ... ON ... FROM ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -REVOKE [IMMUTABLE] DENY database-privilege ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } FROM role[, ...] ----- - -| Description -| Revokes a denied privilege from one or multiple roles. - -|=== - - -.General revoke +ON DATABASE+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +REVOKE ... ON ... FROM ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -REVOKE [IMMUTABLE] database-privilege ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } FROM role[, ...] ----- - -| Description -| Revokes a granted or denied privilege from one or multiple roles. - -|=== - - -[NOTE] -==== -`DENY` does *not* erase a granted privilege. -Use `REVOKE` if you want to remove a privilege. -==== - -Common errors, such as misspellings or attempts to revoke privileges that have not been granted or denied, will lead to notifications. -Some of these notifications may be replaced with errors in a future major version of Neo4j. -See link:{neo4j-docs-base-uri}/status-codes/{page-version}/notifications/all-notifications[Status Codes -> Notification codes] for details on notifications. - -The hierarchy between the different database privileges is shown in the image below. - -image::privileges_hierarchy_database.svg[title="Database privileges hierarchy"] - - - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT ACCESS+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] ACCESS - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -a| -Grants the specified roles the privilege to access: - -* The home database. -* Specific database(s) or remote database alias(es). -* All databases and remote database aliases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT { START \| STOP }+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] { START \| STOP } - ON { HOME DATABASE \| DATABASE[S] {* \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to start or stop the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT { CREATE \| DROP \| SHOW } INDEX+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] { CREATE \| DROP \| SHOW } INDEX[ES] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to create, delete, or show indexes on the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT INDEX+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] INDEX[ES] [MANAGEMENT] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to manage indexes on the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT { CREATE \| DROP \| SHOW } CONSTRAINT+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] { CREATE \| DROP \| SHOW } CONSTRAINT[S] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to create, delete, or show constraints on the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT CONSTRAINT+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] CONSTRAINT[S] [MANAGEMENT] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to manage constraints on the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT CREATE NEW LABEL+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] CREATE NEW [NODE] LABEL[S] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to create new node labels in the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT CREATE NEW TYPE+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] CREATE NEW [RELATIONSHIP] TYPE[S] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to create new relationship types in the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT CREATE NEW NAME+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] CREATE NEW [PROPERTY] NAME[S] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to create new property names in the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT NAME+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] NAME [MANAGEMENT] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to manage new labels, relationship types, and property names in the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT ALL+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] ALL [[DATABASE] PRIVILEGES] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles all privileges for the home, a specific, or all databases and remote database aliases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT { SHOW \| TERMINATE } TRANSACTION+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] { SHOW \| TERMINATE } TRANSACTION[S] [( { * \| user[, ...] } )] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to list and end the transactions and queries of all users or a particular user(s) in the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT TRANSACTION+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] TRANSACTION [MANAGEMENT] [( { * \| user[, ...] } )] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Grants the specified roles the privilege to manage the transactions and queries of all users or a particular user(s) in the home database, specific database(s), or all databases. - -|=== - - -image::privileges_grant_and_deny_syntax_database_privileges.svg[title="Syntax of GRANT and DENY Database Privileges"] - - -[[access-control-database-administration-access]] -== The database `ACCESS` privilege - -The `ACCESS` privilege enables users to connect to a database or a remote database alias. -With `ACCESS` you can run calculations, for example, `+RETURN 2 * 5 AS answer+` or call functions `RETURN timestamp() AS time`. - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] ACCESS - ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to access the database `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT ACCESS ON DATABASE neo4j TO regularUsers ----- - -The `ACCESS` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] ACCESS - ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to deny the role `regularUsers` the ability to access to the remote database alias `remote-db`, use: - -[source, cypher, role=noplay] ----- -DENY ACCESS ON DATABASE `remote-db` TO regularUsers ----- - -The privileges granted can be seen using the `SHOW PRIVILEGES` command: - -[source, cypher, role=noplay] ----- -SHOW ROLE regularUsers PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY ACCESS ON DATABASE `remote-db` TO `regularUsers`" -|"GRANT ACCESS ON DATABASE `neo4j` TO `regularUsers`" -a|Rows: 2 -|=== - - -[[access-control-database-administration-startstop]] -== The database `START`/`STOP` privileges - -The `START` privilege can be used to enable the ability to start a database: - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] START - ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to start the database `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT START ON DATABASE neo4j TO regularUsers ----- - -The `START` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] START - ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to deny the role `regularUsers` the ability to start to the database `neo4j`, use: - -[source, cypher, role=noplay] ----- -DENY START ON DATABASE system TO regularUsers ----- - -The `STOP` privilege can be used to enable the ability to stop a database: - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] STOP - ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to stop the database `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT STOP ON DATABASE neo4j TO regularUsers ----- - -The `STOP` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] STOP - ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to deny the role `regularUsers` the ability to stop the database `neo4j`, use: - -[source, cypher, role=noplay] ----- -DENY STOP ON DATABASE system TO regularUsers ----- - -The privileges granted can be seen using the `SHOW PRIVILEGES` command: - -[source, cypher, role=noplay] ----- -SHOW ROLE regularUsers PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY ACCESS ON DATABASE `remote-db` TO `regularUsers`" -|"DENY START ON DATABASE `system` TO `regularUsers`" -|"DENY STOP ON DATABASE `system` TO `regularUsers`" -|"GRANT ACCESS ON DATABASE `neo4j` TO `regularUsers`" -|"GRANT START ON DATABASE `neo4j` TO `regularUsers`" -|"GRANT STOP ON DATABASE `neo4j` TO `regularUsers`" -a|Rows: 6 -|=== - -[NOTE] -==== -Note that `START` and `STOP` privileges are not included in the xref::administration/access-control/database-administration.adoc#access-control-database-administration-all[`ALL DATABASE PRIVILEGES`]. -==== - - -[[access-control-database-administration-index]] -== The `INDEX MANAGEMENT` privileges - -Indexes can be created, deleted, or listed with the `CREATE INDEX`, `DROP INDEX`, and `SHOW INDEXES` commands. -The privilege to do this can be granted with `GRANT CREATE INDEX`, `GRANT DROP INDEX`, and `GRANT SHOW INDEX` commands. -The privilege to do all three can be granted with `GRANT INDEX MANAGEMENT` command. - - - - -.Index management privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT { CREATE \| DROP \| SHOW } INDEX+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] { CREATE \| DROP \| SHOW } INDEX[ES] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to create, delete, or show indexes in the home database, specific database(s), or all databases. - -|=== - - - -.Index management privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT INDEX+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] INDEX[ES] [MANAGEMENT] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to manage indexes in the home database, specific database(s), or all databases. - -|=== - - -For example, to grant the role `regularUsers` the ability to create indexes on the database `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT CREATE INDEX ON DATABASE neo4j TO regularUsers ----- - - -[[access-control-database-administration-constraints]] -== The `CONSTRAINT MANAGEMENT` privileges - -Constraints can be created, deleted, or listed with the `CREATE CONSTRAINT`, `DROP CONSTRAINT` and `SHOW CONSTRAINTS` commands. -The privilege to do this can be granted with `GRANT CREATE CONSTRAINT`, `GRANT DROP CONSTRAINT`, `GRANT SHOW CONSTRAINT` commands. -The privilege to do all three can be granted with `GRANT CONSTRAINT MANAGEMENT` command. - - -.Constraint management privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT { CREATE \| DROP \| SHOW } CONSTRAINT+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] { CREATE \| DROP \| SHOW } CONSTRAINT[S] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to create, delete, or show constraints on the home database, specific database(s), or all databases. - -|=== - - -.Constraint management privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT CONSTRAINT+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] CONSTRAINT[S] [MANAGEMENT] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enable the specified roles to manage constraints on the home database, specific database(s), or all databases. - -|=== - - -For example, to grant the role `regularUsers` the ability to create constraints on the database `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT CREATE CONSTRAINT ON DATABASE neo4j TO regularUsers ----- - - -[[access-control-database-administration-tokens]] -== The `NAME MANAGEMENT` privileges - -The right to create new labels, relationship types, and property names is different from the right to create nodes, relationships, and properties. -The latter is managed using database `WRITE` privileges, while the former is managed using specific `+GRANT/DENY CREATE NEW ...+` commands for each type. - - -.Node label management privileges syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT CREATE NEW LABEL+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] CREATE NEW [NODE] LABEL[S] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to create new node labels in the home database, specific database(s), or all databases. - -|=== - - -.Relationship type management privileges syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT CREATE NEW TYPE+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] CREATE NEW [RELATIONSHIP] TYPE[S] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to create new relationship types in the home database, specific database(s), or all databases. - -|=== - - -.Property name management privileges syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT CREATE NEW NAME+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] CREATE NEW [PROPERTY] NAME[S] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to create new property names in the home database, specific database(s), or all databases. - -|=== - - -.Node label, relationship type, and property name privileges management syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT NAME+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] NAME [MANAGEMENT] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to create new labels, relationship types, and property names in the home database, specific database(s), or all databases. - -|=== - - -For example, to grant the role `regularUsers` the ability to create new properties on nodes or relationships on the database `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT CREATE NEW PROPERTY NAME ON DATABASE neo4j TO regularUsers ----- - - -[[access-control-database-administration-all]] -== Granting `ALL DATABASE PRIVILEGES` - -The right to access a database, create and drop indexes and constraints and create new labels, relationship types or property names can be achieved with a single command: - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] ALL [[DATABASE] PRIVILEGES] - ON { HOME DATABASE | DATABASE[S] { * | name[, ...] } } - TO role[, ...] ----- - -[NOTE] -==== -Note that the privileges for starting and stopping all databases, and transaction management, are not included in the `ALL DATABASE PRIVILEGES` grant. -These privileges are associated with administrators while other database privileges are of use to domain and application developers. -==== - -For example, granting the abilities above on the database `neo4j` to the role `databaseAdminUsers` is done using the following query. - -[source, cypher, role=noplay] ----- -GRANT ALL DATABASE PRIVILEGES ON DATABASE neo4j TO databaseAdminUsers ----- - -The privileges granted can be seen using the `SHOW PRIVILEGES` command: - -[source, cypher, role=noplay] ----- -SHOW ROLE databaseAdminUsers PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ALL DATABASE PRIVILEGES ON DATABASE `neo4j` TO `databaseAdminUsers`" -a|Rows: 1 -|=== - - -[[access-control-database-administration-transaction]] -== Granting `TRANSACTION MANAGEMENT` privileges - -The right to run the commands `SHOW TRANSACTIONS`, `TERMINATE TRANSACTIONS`, and the deprecated procedures `dbms.listTransactions`, `dbms.listQueries`, `dbms.killQuery`, `dbms.killQueries`, `dbms.killTransaction` and `dbms.killTransactions` is now managed through the `SHOW TRANSACTION` and `TERMINATE TRANSACTION` privileges. - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT SHOW TRANSACTION+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] SHOW TRANSACTION[S] [( { * \| user[, ...] } )] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to list transactions and queries for user(s) or all users in the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT TERMINATE TRANSACTION+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] TERMINATE TRANSACTION[S] [( { * \| user[, ...] } )] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to end running transactions and queries for user(s) or all users in the home database, specific database(s), or all databases. - -|=== - - -.Database privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT TRANSACTION+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] TRANSACTION [MANAGEMENT] [( { * \| user[, ...] } )] - ON { HOME DATABASE \| DATABASE[S] { * \| name[, ...] } } - TO role[, ...] ----- - -| Description -| Enables the specified roles to manage transactions and queries for user(s) or all users in the home database, specific database(s), or all databases. - -|=== - - -[NOTE] -==== -Note that the `TRANSACTION MANAGEMENT` privileges are not included in the xref::administration/access-control/database-administration.adoc#access-control-database-administration-all[`ALL DATABASE PRIVILEGES`]. -==== - -For example, to grant the role `regularUsers` the ability to list transactions for user `jake` on the database `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT SHOW TRANSACTION (jake) ON DATABASE neo4j TO regularUsers ----- diff --git a/modules/ROOT/pages/administration/access-control/dbms-administration.adoc b/modules/ROOT/pages/administration/access-control/dbms-administration.adoc deleted file mode 100644 index e1ba106fd..000000000 --- a/modules/ROOT/pages/administration/access-control/dbms-administration.adoc +++ /dev/null @@ -1,2124 +0,0 @@ -:description: How to use Cypher to manage Neo4j DBMS administrative privileges. - -//// -[source, cypher, role=test-setup] ----- -CREATE USER jake SET PASSWORD 'abcd1234' CHANGE NOT REQUIRED; -CREATE ROLE roleAdder IF NOT EXISTS; -CREATE ROLE roleNameModifier IF NOT EXISTS; -CREATE ROLE roleDropper IF NOT EXISTS; -CREATE ROLE roleAssigner IF NOT EXISTS; -CREATE ROLE roleRemover IF NOT EXISTS; -CREATE ROLE roleShower IF NOT EXISTS; -CREATE ROLE roleManager IF NOT EXISTS; -CREATE ROLE userAdder IF NOT EXISTS; -CREATE ROLE userNameModifier IF NOT EXISTS; -CREATE ROLE userModifier IF NOT EXISTS; -CREATE ROLE passwordModifier IF NOT EXISTS; -CREATE ROLE statusModifier IF NOT EXISTS; -CREATE ROLE userDropper IF NOT EXISTS; -CREATE ROLE userShower IF NOT EXISTS; -CREATE ROLE userManager IF NOT EXISTS; -CREATE ROLE userImpersonator IF NOT EXISTS; -CREATE ROLE databaseAdder IF NOT EXISTS; -CREATE ROLE compositeDatabaseAdder IF NOT EXISTS; -CREATE ROLE databaseDropper IF NOT EXISTS; -CREATE ROLE compositeDatabaseDropper IF NOT EXISTS; -CREATE ROLE databaseModifier IF NOT EXISTS; -CREATE ROLE accessModifier IF NOT EXISTS; -CREATE ROLE compositeDatabaseManager IF NOT EXISTS; -CREATE ROLE databaseManager IF NOT EXISTS; -CREATE ROLE aliasAdder IF NOT EXISTS; -CREATE ROLE aliasDropper IF NOT EXISTS; -CREATE ROLE aliasModifier IF NOT EXISTS; -CREATE ROLE aliasLister IF NOT EXISTS; -CREATE ROLE aliasManager IF NOT EXISTS; -CREATE ROLE privilegeShower IF NOT EXISTS; -CREATE ROLE privilegeAssigner IF NOT EXISTS; -CREATE ROLE privilegeRemover IF NOT EXISTS; -CREATE ROLE privilegeManager IF NOT EXISTS; -CREATE ROLE procedureExecutor IF NOT EXISTS; -CREATE ROLE deniedProcedureExecutor IF NOT EXISTS; -CREATE ROLE boostedProcedureExecutor IF NOT EXISTS; -CREATE ROLE deniedBoostedProcedureExecutor1 IF NOT EXISTS; -CREATE ROLE deniedBoostedProcedureExecutor2 IF NOT EXISTS; -CREATE ROLE deniedBoostedProcedureExecutor3 IF NOT EXISTS; -CREATE ROLE deniedBoostedProcedureExecutor4 IF NOT EXISTS; -CREATE ROLE adminProcedureExecutor IF NOT EXISTS; -CREATE ROLE functionExecutor IF NOT EXISTS; -CREATE ROLE deniedFunctionExecutor IF NOT EXISTS; -CREATE ROLE boostedFunctionExecutor IF NOT EXISTS; -CREATE ROLE globbing1 IF NOT EXISTS; -CREATE ROLE globbing2 IF NOT EXISTS; -CREATE ROLE globbing3 IF NOT EXISTS; -CREATE ROLE globbing4 IF NOT EXISTS; -CREATE ROLE globbing5 IF NOT EXISTS; -CREATE ROLE globbing6 IF NOT EXISTS; -CREATE ROLE dbmsManager IF NOT EXISTS; -CREATE ROLE configurationViewer IF NOT EXISTS; -CREATE ROLE deniedConfigurationViewer IF NOT EXISTS; ----- -//// - -[role=enterprise-edition aura-db-enterprise] -[[access-control-dbms-administration]] -= DBMS administration - -This page explains how to use Cypher to manage Neo4j DBMS administrative privileges. - -All DBMS privileges are relevant system-wide. -Like user management, they do not belong to one specific database or graph. -For more details on the differences between graphs, databases and the DBMS, refer to xref::introduction/cypher_neo4j.adoc[]. - -image::privileges_grant_and_deny_syntax_dbms_privileges.svg[title="Syntax of GRANT and DENY DBMS Privileges"] - -image::privileges_hierarchy_dbms.svg[title="DBMS privileges hierarchy"] - -The xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-admin[`admin` role] has a number of built-in privileges. -These include: - -* Create, delete, and modify databases and aliases. -* Change configuration parameters. -* Manage transactions. -* Manage users and roles. -* Manage sub-graph privileges. -* Manage procedure security. - -To enable a user to perform these tasks, you can grant them the `admin` role, but it is also possible to make a custom role with a subset of these privileges. -All privileges are also assignable using Cypher commands. -For more details, see the following sections: - -* xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[Role management] -* xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[User management] -* xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-impersonation[Impersonation privileges management] -* xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[Database management] -* xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[Alias management] -* xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[Privilege management] -* xref::administration/access-control/database-administration.adoc#access-control-database-administration-transaction[Transaction management] -* xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-execute[Procedure and user-defined function security] - -[[access-control-dbms-administration-custom]] -== Using a custom role to manage DBMS privileges - -In order to have an administrator role with a subset of privileges that includes all DBMS privileges, but not all database privileges, you can copy the `admin` role and revoke or deny the unwanted privileges. -A second option is to build a custom administrator from scratch by granting the wanted privileges instead. - -As an example, an administrator role can be created to only manage users and roles by using the second option: - -. First, create the new role: -+ -[source, cypher, role=noplay] ----- -CREATE ROLE usermanager ----- -. Then grant the privilege to manage users: -+ -[source, cypher, role=noplay] ----- -GRANT USER MANAGEMENT ON DBMS TO usermanager ----- -. And to manage roles: -+ -[source, cypher, role=noplay] ----- -GRANT ROLE MANAGEMENT ON DBMS TO usermanager ----- - -The resulting role has privileges that only allow user and role management. -To list all privileges for the role `usermanager` as commands, run this query: - -[source, cypher, role=noplay] ----- -SHOW ROLE usermanager PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ROLE MANAGEMENT ON DBMS TO `usermanager`" -|"GRANT USER MANAGEMENT ON DBMS TO `usermanager`" -a|Rows: 2 -|=== - -Note that this role does not allow all DBMS capabilities. -For example, the role is missing privileges for management, creation and drop of databases as well as execution of `admin` procedures. -To create a more powerful administrator, you can grant a different set of privileges. - -In the following example, a new administrator role is created to perform almost all DBMS capabilities, excluding database management. -However, the role still has some limited database capabilities, such as managing transactions: - -. Again, start by creating a new role: -+ -[source, cypher, role=noplay] ----- -CREATE ROLE customAdministrator ----- -. Then grant the privilege for all DBMS capabilities: -+ -[source, cypher, role=noplay] ----- -GRANT ALL DBMS PRIVILEGES ON DBMS TO customAdministrator ----- -. And explicitly deny the privilege to manage databases and aliases: -+ -[source, cypher, role=noplay] ----- -DENY DATABASE MANAGEMENT ON DBMS TO customAdministrator ----- -. Next, grant the transaction management privilege: -+ -[source, cypher, role=noplay] ----- -GRANT TRANSACTION MANAGEMENT (*) ON DATABASE * TO customAdministrator ----- - -The resulting role has privileges that include all DBMS privileges except creating, dropping, and modifying databases and aliases, as well as managing transactions. -Use the following query to list all privileges for the role `customAdministrator` as commands: - -[source, cypher, role=noplay] ----- -SHOW ROLE customAdministrator PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY DATABASE MANAGEMENT ON DBMS TO `customAdministrator`" -|"GRANT ALL DBMS PRIVILEGES ON DBMS TO `customAdministrator`" -|"GRANT TRANSACTION MANAGEMENT (*) ON DATABASE * TO `customAdministrator`" -a|Rows: 3 -|=== - - -[[access-control-dbms-administration-role-management]] -== The DBMS `ROLE MANAGEMENT` privileges - -The DBMS privileges for role management are assignable using Cypher administrative commands. -They can be granted, denied and revoked like other privileges. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Role management privileges command syntax -[options="header", width="100%", cols="3a,2"] -|=== -| Command | Description - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] CREATE ROLE - ON DBMS - TO role[, ...] -| Enables the specified roles to create new roles. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] RENAME ROLE - ON DBMS - TO role[, ...] -| Enables the specified roles to change the name of roles. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] DROP ROLE - ON DBMS - TO role[, ...] -| Enables the specified roles to delete roles. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] ASSIGN ROLE - ON DBMS - TO role[, ...] -| Enables the specified roles to assign roles to users. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] REMOVE ROLE - ON DBMS - TO role[, ...] -| Enables the specified roles to remove roles from users. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] SHOW ROLE - ON DBMS - TO role[, ...] -| Enables the specified roles to list roles. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] ROLE MANAGEMENT - ON DBMS - TO role[, ...] -| Enables the specified roles to create, delete, assign, remove, and list roles. - -|=== - -The ability to add roles can be granted via the `CREATE ROLE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT CREATE ROLE ON DBMS TO roleAdder ----- - -The resulting role has privileges that only allow adding roles. -List all privileges for the role `roleAdder` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE roleAdder PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT CREATE ROLE ON DBMS TO `roleAdder`" -a|Rows: 1 -|=== - -The ability to rename roles can be granted via the `RENAME ROLE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT RENAME ROLE ON DBMS TO roleNameModifier ----- - -The resulting role has privileges that only allow renaming roles. -List all privileges for the role `roleNameModifier` using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE roleNameModifier PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT RENAME ROLE ON DBMS TO `roleNameModifier`" -a|Rows: 1 -|=== - -The ability to delete roles can be granted via the `DROP ROLE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT DROP ROLE ON DBMS TO roleDropper ----- - -The resulting role has privileges that only allow deleting roles. -List all privileges for the role `roleDropper` by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE roleDropper PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT DROP ROLE ON DBMS TO `roleDropper`" -a|Rows: 1 -|=== - -The ability to assign roles to users can be granted via the `ASSIGN ROLE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT ASSIGN ROLE ON DBMS TO roleAssigner ----- - -The resulting role has privileges that only allow assigning/granting roles. -List all privileges for the role `roleAssigner` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE roleAssigner PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ASSIGN ROLE ON DBMS TO `roleAssigner`" -a|Rows: 1 -|=== - -The ability to remove roles from users can be granted via the `REMOVE ROLE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT REMOVE ROLE ON DBMS TO roleRemover ----- - -The resulting role has privileges that only allow removing/revoking roles. -List all privileges for the role `roleRemover` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE roleRemover PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT REMOVE ROLE ON DBMS TO `roleRemover`" -a|Rows: 1 -|=== - -The ability to show roles can be granted via the `SHOW ROLE` privilege. -A role with this privilege is allowed to execute the `SHOW ROLES` and `SHOW POPULATED ROLES` administration commands. -For the `SHOW ROLES WITH USERS` and `SHOW POPULATED ROLES WITH USERS` administration commands, both this privilege and the `SHOW USER` privilege are required. -The following query shows an example of how to grant the `SHOW ROLE` privilege: - -In order to use `SHOW ROLES WITH USERS` and `SHOW POPULATED ROLES WITH USERS` administration commands, both the `SHOW ROLE` and the `SHOW USER` privileges are required. -See an example of how to grant the `SHOW ROLE` privilege: - -[source, cypher, role=noplay] ----- -GRANT SHOW ROLE ON DBMS TO roleShower ----- - -The resulting role has privileges that only allow showing roles. -List all privileges for the role `roleShower` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE roleShower PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SHOW ROLE ON DBMS TO `roleShower`" -a|Rows: 1 -|=== - -The privileges to create, rename, delete, assign, remove, and list roles can be granted via the `ROLE MANAGEMENT` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT ROLE MANAGEMENT ON DBMS TO roleManager ----- - -The resulting role has all privileges to manage roles. -List all privileges for the role `roleManager` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE roleManager PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ROLE MANAGEMENT ON DBMS TO `roleManager`" -a|Rows: 1 -|=== - - -[[access-control-dbms-administration-user-management]] -== The DBMS `USER MANAGEMENT` privileges - -The DBMS privileges for user management can be assigned using Cypher administrative commands. -They can be granted, denied and revoked like other privileges. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.User management privileges command syntax -[options="header", width="100%", cols="3a,2"] -|=== -| Command | Description - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] CREATE USER - ON DBMS - TO role[, ...] -| Enables the specified roles to create new users. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] RENAME USER - ON DBMS - TO role[, ...] -| Enables the specified roles to change the name of users. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] ALTER USER - ON DBMS - TO role[, ...] -| Enables the specified roles to modify users. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] SET PASSWORD[S] - ON DBMS - TO role[, ...] -| Enables the specified roles to modify users' passwords and whether those passwords must be changed upon first login. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] SET USER HOME DATABASE - ON DBMS - TO role[, ...] -| Enables the specified roles to modify users' home database. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] SET USER STATUS - ON DBMS - TO role[, ...] -| Enables the specified roles to modify the account status of users. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] DROP USER - ON DBMS - TO role[, ...] -| Enables the specified roles to delete users. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] SHOW USER - ON DBMS - TO role[, ...] -| Enables the specified roles to list users. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] USER MANAGEMENT - ON DBMS - TO role[, ...] -| Enables the specified roles to create, delete, modify, and list users. - -|=== - -The ability to add users can be granted via the `CREATE USER` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT CREATE USER ON DBMS TO userAdder ----- - -The resulting role has privileges that only allow adding users. -List all privileges for the role `userAdder` as commands by using this query: - -[source, cypher, role=noplay] ----- -SHOW ROLE userAdder PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT CREATE USER ON DBMS TO `userAdder`" -a|Rows: 1 -|=== - -The ability to rename users can be granted via the `RENAME USER` privilege. -The following query shows an example of this: - -[source, cypher, role=noplay] ----- -GRANT RENAME USER ON DBMS TO userNameModifier ----- - -The resulting role has privileges that only allow renaming users: - -[source, cypher, role=noplay] ----- -SHOW ROLE userNameModifier PRIVILEGES AS COMMANDS ----- - -Lists all privileges for role `userNameModifier`: - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT RENAME USER ON DBMS TO `userNameModifier`" -a|Rows: 1 -|=== - -The ability to modify users can be granted via the `ALTER USER` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT ALTER USER ON DBMS TO userModifier ----- - -The resulting role has privileges that only allow modifying users. -List all privileges for the role `userModifier` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE userModifier PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ALTER USER ON DBMS TO `userModifier`" -a|Rows: 1 -|=== - -A user that is granted the `ALTER USER` privilege is allowed to run the `ALTER USER` administration command with one or several of the `SET PASSWORD`, `SET PASSWORD CHANGE [NOT] REQUIRED` and `SET STATUS` parts: - -[source, cypher, role=noplay] ----- -ALTER USER jake SET PASSWORD 'verysecret' SET STATUS SUSPENDED ----- - -The ability to modify users' passwords and whether those passwords must be changed upon first login can be granted via the `SET PASSWORDS` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT SET PASSWORDS ON DBMS TO passwordModifier ----- - -The resulting role has privileges that only allow modifying users' passwords and whether those passwords must be changed upon first login. -List all privileges for the role `passwordModifier` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE passwordModifier PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SET PASSWORD ON DBMS TO `passwordModifier`" -a|Rows: 1 -|=== - -A user that is granted the `SET PASSWORDS` privilege is allowed to run the `ALTER USER` administration command with one or both of the `SET PASSWORD` and `SET PASSWORD CHANGE [NOT] REQUIRED` parts: - -[source, cypher, role=noplay] ----- -ALTER USER jake SET PASSWORD 'abcd5678' CHANGE NOT REQUIRED ----- - -The ability to modify the account status of users can be granted via the `SET USER STATUS` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT SET USER STATUS ON DBMS TO statusModifier ----- - -The resulting role has privileges that only allow modifying the account status of users. -List all privileges for the role `statusModifier` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE statusModifier PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SET USER STATUS ON DBMS TO `statusModifier`" -a|Rows: 1 -|=== - -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: - -[source, cypher, role=noplay] ----- -ALTER USER jake SET STATUS ACTIVE ----- - -In order to be able to modify the home database of users, grant the `SET USER HOME DATABASE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT SET USER HOME DATABASE ON DBMS TO statusModifier ----- - -The resulting role has privileges that only allow modifying the home database of users. -List all privileges for the role `statusModifier` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE statusModifier PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SET USER HOME DATABASE ON DBMS TO `statusModifier`" -|"GRANT SET USER STATUS ON DBMS TO `statusModifier`" -a|Rows: 2 -|=== - -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: - -[source, cypher, role=noplay] ----- -ALTER USER jake SET HOME DATABASE otherDb ----- - -[source, cypher, role=noplay] ----- -ALTER USER jake REMOVE HOME DATABASE ----- - -[NOTE] -==== -Note that the combination of the `SET PASSWORDS`, `SET USER STATUS`, and the `SET USER HOME DATABASE` privilege actions is equivalent to the `ALTER USER` privilege action. -==== - -The ability to delete users can be granted via the `DROP USER` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT DROP USER ON DBMS TO userDropper ----- - -The resulting role has privileges that only allow deleting users. -List all privileges for the role `userDropper` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE userDropper PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT DROP USER ON DBMS TO `userDropper`" -a|Rows: 1 -|=== - -The ability to show users can be granted via the `SHOW USER` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT SHOW USER ON DBMS TO userShower ----- - -The resulting role has privileges that only allow showing users. -List all privileges for the role `userShower` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE userShower PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SHOW USER ON DBMS TO `userShower`" -a|Rows: 1 -|=== - -The privileges to create, rename, modify, delete, and list users can be granted via the `USER MANAGEMENT` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT USER MANAGEMENT ON DBMS TO userManager ----- - -The resulting role has all privileges to manage users. -List all privileges for the role `userManager` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE userManager PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SHOW USER ON DBMS TO `userManager`" -a|Rows: 1 -|=== - -[[access-control-dbms-administration-impersonation]] -== The DBMS `IMPERSONATE` privileges - -The DBMS privileges for impersonation can be assigned through Cypher administrative commands. -They can be granted, denied, and revoked like other privileges. - -Impersonation is the ability of a user to assume another user's roles (and therefore privileges), with the restriction of not being able to execute updating `admin` commands as the impersonated user (i.e. they would still be able to use `SHOW` commands). - -The ability to impersonate users can be granted via the `IMPERSONATE` privilege. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Impersonation privileges command syntax -[options="header", width="100%", cols="3a,2"] -|=== -| Command | Description - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] IMPERSONATE [(*)] - ON DBMS - TO role[, ...] -| Enables the specified roles to impersonate any user. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] IMPERSONATE (user[, ...]) - ON DBMS - TO role[, ...] -| Enables the specified roles to impersonate the specified users. - -|=== - -The following query shows an example of this. -Note that `userImpersonator` must be an existing role in order to make this query work: - -.Query -[source, cypher, role=noplay] ----- -GRANT IMPERSONATE (*) ON DBMS TO userImpersonator ----- - -The resulting role has privileges that allow impersonating all users: - -.Query -[source, cypher, role=noplay] ----- -SHOW ROLE userImpersonator PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -| command -| "GRANT IMPERSONATE (*) ON DBMS TO `userImpersonator`" -a|Rows: 1 -|=== - -It is also possible to deny and revoke that privilege. -See an example which shows of how the `userImpersonator` user would be able to impersonate all users, except `alice`: - -.Query -[source, cypher, role=noplay] ----- -DENY IMPERSONATE (alice) ON DBMS TO userImpersonator ----- - -To grant (or revoke) the permissions to impersonate a specific user or a subset of users, you can first list them with this query: - -.Query -[source, cypher, role=noplay] ----- -GRANT IMPERSONATE (alice, bob) ON DBMS TO userImpersonator ----- - - -[[access-control-dbms-administration-database-management]] -== The DBMS `DATABASE MANAGEMENT` privileges - -The DBMS privileges for database management can be assigned by using Cypher administrative commands. -They can be granted, denied and revoked like other privileges. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Database management privileges command syntax -[options="header", width="100%", cols="3a,2"] -|=== -| Command | Description - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] CREATE DATABASE - ON DBMS - TO role[, ...] -| Enables the specified roles to create new standard databases and aliases. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] DROP DATABASE - ON DBMS - TO role[, ...] -| Enables the specified roles to delete standard databases and aliases. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] ALTER DATABASE - ON DBMS - TO role[, ...] -| Enables the specified roles to modify standard databases and aliases. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] SET DATABASE ACCESS - ON DBMS - TO role[, ...] -| Enables the specified roles to modify access to standard databases. - -| [source, syntax, role=noheader] -GRANT CREATE COMPOSITE DATABASE - ON DBMS - TO role[, ...] -| Enables the specified roles to create new composite databases. - -| [source, syntax, role=noheader] -GRANT DROP COMPOSITE DATABASE - ON DBMS - TO role[, ...] -| Enables the specified roles to delete composite databases. - -| [source, syntax, role=noheader] -GRANT COMPOSITE DATABASE MANAGEMENT - ON DBMS - TO role[, ...] -| Enables the specified roles to create and delete composite databases. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] DATABASE MANAGEMENT - ON DBMS - TO role[, ...] -| Enables the specified roles to create, delete, and modify databases and aliases. - -|=== - - -The ability to create standard databases and aliases can be granted via the `CREATE DATABASE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT CREATE DATABASE ON DBMS TO databaseAdder ----- - -The resulting role has privileges that only allow creating standard databases and aliases. -List all privileges for the role `databaseAdder` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE databaseAdder PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT CREATE DATABASE ON DBMS TO `databaseAdder`" -a|Rows: 1 -|=== - -The ability to create composite databases can be granted via the `CREATE COMPOSITE DATABASE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT CREATE COMPOSITE DATABASE ON DBMS TO compositeDatabaseAdder ----- - -The resulting role has privileges that only allow creating composite databases. -List all privileges for the role `compositeDatabaseAdder` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE compositeDatabaseAdder PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT CREATE COMPOSITE DATABASE ON DBMS TO `compositeDatabaseAdder`" -a|Rows: 1 -|=== - -The ability to delete standard databases and aliases can be granted via the `DROP DATABASE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT DROP DATABASE ON DBMS TO databaseDropper ----- - -The resulting role has privileges that only allow deleting standard databases and aliases. -List all privileges for the role `databaseDropper` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE databaseDropper PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT DROP DATABASE ON DBMS TO `databaseDropper`" -a|Rows: 1 -|=== - -The ability to delete composite databases can be granted via the `DROP COMPOSITE DATABASE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT DROP COMPOSITE DATABASE ON DBMS TO compositeDatabaseDropper ----- - -The resulting role has privileges that only allow deleting composite databases. -List all privileges for the role `compositeDatabaseDropper` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE compositeDatabaseDropper PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT DROP COMPOSITE DATABASE ON DBMS TO `compositeDatabaseDropper`" -a|Rows: 1 -|=== - -The ability to modify standard databases and aliases can be granted via the `ALTER DATABASE` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT ALTER DATABASE ON DBMS TO databaseModifier ----- - -The resulting role has privileges that only allow modifying standard databases and aliases. -List all privileges for the role `databaseModifier` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE databaseModifier PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ALTER DATABASE ON DBMS TO `databaseModifier`" -a|Rows: 1 -|=== - -The ability to modify access to standard databases can be granted via the `SET DATABASE ACCESS` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT SET DATABASE ACCESS ON DBMS TO accessModifier ----- - -The resulting role has privileges that only allow modifying access to standard databases. -List all privileges for the role `accessModifier` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE accessModifier PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SET DATABASE ACCESS ON DBMS TO `accessModifier`" -a|Rows: 1 -|=== - -The ability to create and delete composite databases can be granted via the `COMPOSITE DATABASE MANAGEMENT` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT COMPOSITE DATABASE MANAGEMENT ON DBMS TO compositeDatabaseManager ----- - -The resulting role has all privileges to manage composite databases. -List all privileges for the role `compositeDatabaseManager` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE compositeDatabaseManager PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT COMPOSITE DATABASE MANAGEMENT ON DBMS TO `compositeDatabaseManager`" -a|Rows: 1 -|=== - -The ability to create, delete, and modify databases and aliases can be granted via the `DATABASE MANAGEMENT` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT DATABASE MANAGEMENT ON DBMS TO databaseManager ----- - -The resulting role has all privileges to manage standard and composite databases as well as aliases. -List all privileges for the role `databaseManager` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE databaseManager PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT DATABASE MANAGEMENT ON DBMS TO `databaseManager`" -a|Rows: 1 -|=== - -[[access-control-dbms-administration-alias-management]] -== The DBMS `ALIAS MANAGEMENT` privileges - -The DBMS privileges for alias management can be assigned by using Cypher administrative commands and can be applied to both local and remote aliases. -They can be granted, denied and revoked like other privileges. -It is also possible to manage aliases with xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[database management commands]. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Alias management privileges command syntax -[options="header", width="100%", cols="3a,2"] -|=== -| Command | Description - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] CREATE ALIAS -ON DBMS -TO role[, ...] -| Enables the specified roles to create new aliases. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] DROP ALIAS -ON DBMS -TO role[, ...] -| Enables the specified roles to delete aliases. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] ALTER ALIAS -ON DBMS -TO role[, ...] -| Enables the specified roles to modify aliases. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] SHOW ALIAS -ON DBMS -TO role[, ...] -| Enables the specified roles to list aliases. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] ALIAS MANAGEMENT -ON DBMS -TO role[, ...] -| Enables the specified roles to list, create, delete, and modify aliases. - -|=== - -The ability to create aliases can be granted via the `CREATE ALIAS` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT CREATE ALIAS ON DBMS TO aliasAdder ----- - -The resulting role has privileges that only allow creating aliases. -List all privileges for the role `aliasAdder` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE aliasAdder PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT CREATE ALIAS ON DBMS TO `aliasAdder`" -a|Rows: 1 -|=== - -The ability to delete aliases can be granted via the `DROP ALIAS` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT DROP ALIAS ON DBMS TO aliasDropper ----- - -The resulting role has privileges that only allow deleting aliases. -See all privileges for the role `aliasDropper` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE aliasDropper PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT DROP ALIAS ON DBMS TO `aliasDropper`" -a|Rows: 1 -|=== - -The ability to modify aliases can be granted via the `ALTER ALIAS` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT ALTER ALIAS ON DBMS TO aliasModifier ----- - -The resulting role has privileges that only allow modifying aliases. -List all privileges for the role `aliasModifier` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE aliasModifier PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ALTER ALIAS ON DBMS TO `aliasModifier`" -a|Rows: 1 -|=== - -The ability to list aliases can be granted via the `SHOW ALIAS` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT SHOW ALIAS ON DBMS TO aliasLister ----- - -The resulting role has privileges that only allow modifying aliases. -List all privileges for the role `aliasLister` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE aliasLister PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SHOW ALIAS ON DBMS TO `aliasLister`" -a|Rows: 1 -|=== - -The privileges to list, create, delete, and modify aliases can be granted via the `ALIAS MANAGEMENT` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT ALIAS MANAGEMENT ON DBMS TO aliasManager ----- - -The resulting role has all privileges to manage aliases. -List all privileges for the role `aliasManager` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE aliasManager PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ALIAS MANAGEMENT ON DBMS TO `aliasManager`" -a|Rows: 1 -|=== - -[[access-control-dbms-administration-server-management]] -== The DBMS `SERVER MANAGEMENT` privileges - -The DBMS privileges for server management can be assigned using Cypher administrative commands. -They can be granted, denied, and revoked like other privileges. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Server management privileges command syntax -[options="header", width="100%", cols="3a,2"] -|=== -| Command | Description - -| [source, syntax, role=noheader] -GRANT SERVER MANAGEMENT - ON DBMS - TO role[, ...] -| Enables the specified roles to show, enable, rename, alter, reallocate, deallocate, and drop servers. - -| [source, syntax, role=noheader] -GRANT SHOW SERVERS - ON DBMS - TO role[, ...] -| Enables the specified roles to show servers. -|=== - - -[[access-control-dbms-administration-privilege-management]] -== The DBMS `PRIVILEGE MANAGEMENT` privileges - -The DBMS privileges for privilege management can be assigned by using Cypher administrative commands. -They can be granted, denied and revoked like other privileges. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Privilege management privileges command syntax -[options="header", width="100%", cols="3a,2"] -|=== -| Command | Description - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] SHOW PRIVILEGE - ON DBMS - TO role[, ...] -| Enables the specified roles to list privileges. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] ASSIGN PRIVILEGE - ON DBMS - TO role[, ...] -| Enables the specified roles to assign privileges using the `GRANT` and `DENY` commands. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] REMOVE PRIVILEGE - ON DBMS - TO role[, ...] -| Enables the specified roles to remove privileges using the `REVOKE` command. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] PRIVILEGE MANAGEMENT - ON DBMS - TO role[, ...] -| Enables the specified roles to list, assign, and remove privileges. -|=== - -The ability to list privileges can be granted via the `SHOW PRIVILEGE` privilege. - -A user with this privilege is allowed to execute the `SHOW PRIVILEGES` and `SHOW ROLE roleName PRIVILEGES` administration commands. -To execute the `SHOW USER username PRIVILEGES` administration command, both this privilege and the `SHOW USER` privilege are required. -The following query shows an example of how to grant the `SHOW PRIVILEGE` privilege: - -[source, cypher, role=noplay] ----- -GRANT SHOW PRIVILEGE ON DBMS TO privilegeShower ----- - -The resulting role has privileges that only allow showing privileges. -List all privileges for the role `privilegeShower` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE privilegeShower PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SHOW PRIVILEGE ON DBMS TO `privilegeShower`" -a|Rows: 1 -|=== - -[NOTE] -==== -Note that no specific privileges are required for showing the current user's privileges through the `SHOW USER _username_ PRIVILEGES` or `SHOW USER PRIVILEGES` commands. - -In addition, note that if a non-native auth provider like LDAP is in use, `SHOW USER PRIVILEGES` will only work with a limited capacity by making it only possible for a user to show their own privileges. -Other users' privileges cannot be listed when using a non-native auth provider. -==== - -The ability to assign privileges to roles can be granted via the `ASSIGN PRIVILEGE` privilege. -A user with this privilege is allowed to execute `GRANT` and `DENY` administration commands. -See an example of how to grant this privilege: - -[source, cypher, role=noplay] ----- -GRANT ASSIGN PRIVILEGE ON DBMS TO privilegeAssigner ----- - -The resulting role has privileges that only allow assigning privileges. -List all privileges for the role `privilegeAssigner` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE privilegeAssigner PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ASSIGN PRIVILEGE ON DBMS TO `privilegeAssigner`" -a|Rows: 1 -|=== - -The ability to remove privileges from roles can be granted via the `REMOVE PRIVILEGE` privilege. - -A user with this privilege is allowed to execute `REVOKE` administration commands. -See an example of how to grant this privilege: - -[source, cypher, role=noplay] ----- -GRANT REMOVE PRIVILEGE ON DBMS TO privilegeRemover ----- - -The resulting role has privileges that only allow removing privileges. -List all privileges for the role `privilegeRemover` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE privilegeRemover PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT REMOVE PRIVILEGE ON DBMS TO `privilegeRemover`" -a|Rows: 1 -|=== - -The privileges to list, assign, and remove privileges can be granted via the `PRIVILEGE MANAGEMENT` privilege. -See an example: - -[source, cypher, role=noplay] ----- -GRANT PRIVILEGE MANAGEMENT ON DBMS TO privilegeManager ----- - -The resulting role has all privileges to manage privileges. -List all privileges for the role `privilegeManager` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE privilegeManager PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT PRIVILEGE MANAGEMENT ON DBMS TO `privilegeManager`" -a|Rows: 1 -|=== - - -[[access-control-dbms-administration-execute]] -== The DBMS `EXECUTE` privileges - -The DBMS privileges for procedure and user-defined function execution can be assigned by using Cypher administrative commands. -They can be granted, denied and revoked like other privileges. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Execute privileges command syntax -[options="header", width="100%", cols="3a,2"] -|=== -| Command -| Description - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] EXECUTE PROCEDURE[S] name-globbing[, ...] - ON DBMS - TO role[, ...] -| Enables the specified roles to execute the given procedures. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] EXECUTE BOOSTED PROCEDURE[S] name-globbing[, ...] - ON DBMS - TO role[, ...] -| Enables the specified roles to use elevated privileges when executing the given procedures. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] EXECUTE ADMIN[ISTRATOR] PROCEDURES - ON DBMS - TO role[, ...] -| Enables the specified roles to execute procedures annotated with `@Admin`. The procedures are executed with elevated privileges. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] EXECUTE [USER [DEFINED]] FUNCTION[S] name-globbing[, ...] - ON DBMS - TO role[, ...] -| Enables the specified roles to execute the given user-defined functions. - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] EXECUTE BOOSTED [USER [DEFINED]] FUNCTION[S] name-globbing[, ...] - ON DBMS - TO role[, ...] -| Enables the specified roles to use elevated privileges when executing the given user-defined functions. -|=== - -[[access-control-execute-procedure]] -=== The `EXECUTE PROCEDURE` privilege - -The ability to execute a procedure can be granted via the `EXECUTE PROCEDURE` privilege. -A role with this privilege is allowed to execute the procedures matched by the xref::administration/access-control/dbms-administration.adoc#access-control-name-globbing[name-globbing]. -The following query shows an example of how to grant this privilege: - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE db.schema.* ON DBMS TO procedureExecutor ----- - -Users with the role `procedureExecutor` can then run any procedure in the `db.schema` namespace. -The procedure is run using the user's own privileges. - -The resulting role has privileges that only allow executing procedures in the `db.schema` namespace. -List all privileges for the role `procedureExecutor` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE procedureExecutor PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT EXECUTE PROCEDURE db.schema.* ON DBMS TO `procedureExecutor`" -a|Rows: 1 -|=== - -In order to allow the execution of all but only a few procedures, you can grant `EXECUTE PROCEDURES *` and deny the unwanted procedures. -For example, the following queries allow the execution of all procedures, except those starting with `dbms.cluster`: - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE * ON DBMS TO deniedProcedureExecutor ----- - -[source, cypher, role=noplay] ----- -DENY EXECUTE PROCEDURE dbms.cluster* ON DBMS TO deniedProcedureExecutor ----- - -The resulting role has privileges that allow executing all procedures except those starting with `dbms.cluster`. -List all privileges for the role `deniedProcedureExecutor` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE deniedProcedureExecutor PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY EXECUTE PROCEDURE dbms.cluster* ON DBMS TO `deniedProcedureExecutor`" -|"GRANT EXECUTE PROCEDURE * ON DBMS TO `deniedProcedureExecutor`" -a|Rows: 2 -|=== - -The `dbms.cluster.checkConnectivity`, `dbms.cluster.cordonServer`, `dbms.cluster.protocols`, `dbms.cluster.readReplicaToggle`, `dbms.cluster.routing.getRoutingTable`, `dbms.cluster.secondaryReplicationDisable`, `dbms.cluster.setAutomaticallyEnableFreeServers`, and `dbms.cluster.uncordonServer` procedures are blocked, as well as any others starting with `dbms.cluster`. - -[[access-control-execute-boosted-procedure]] -=== The `EXECUTE BOOSTED PROCEDURE` privilege - -The ability to use elevated privileges when executing a procedure can be granted via the `EXECUTE BOOSTED PROCEDURE` privilege. -A user with this privilege will not be restricted to their other privileges when executing the procedures matched by the xref::administration/access-control/dbms-administration.adoc#access-control-name-globbing[name-globbing]. -The `EXECUTE BOOSTED PROCEDURE` privilege only affects the elevation, and not the execution of the procedure. -Therefore, it is needed to grant `EXECUTE PROCEDURE` privilege for the procedures as well. - -[NOTE] --- -Since Neo4j 5.0, both `EXECUTE PROCEDURE` and `EXECUTE BOOSTED PROCEDURE` are needed to execute a procedure with elevated privileges. -This differs from Neo4j 4.x, when only the `EXECUTE BOOSTED PROCEDURE` was required. --- - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE * ON DBMS TO boostedProcedureExecutor; -GRANT EXECUTE BOOSTED PROCEDURE db.labels, db.relationshipTypes ON DBMS TO boostedProcedureExecutor ----- - -Users with the role `boostedProcedureExecutor` can thus run the `db.labels` and the `db.relationshipTypes` procedures with full privileges, seeing everything in the graph and not just the labels and types that the user has `TRAVERSE` privilege on. -Without the `EXECUTE PROCEDURE`, no procedures could be executed at all. - -The resulting role has privileges that allow executing the procedures `db.labels` and `db.relationshipTypes` with elevated privileges, and all other procedures with the user's own privileges: - -[source, cypher, role=noplay] ----- -SHOW ROLE boostedProcedureExecutor PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT EXECUTE PROCEDURE * ON DBMS TO `boostedProcedureExecutor`" -|"GRANT EXECUTE BOOSTED PROCEDURE db.labels ON DBMS TO `boostedProcedureExecutor`" -|"GRANT EXECUTE BOOSTED PROCEDURE db.relationshipTypes ON DBMS TO `boostedProcedureExecutor`" -a|Rows: 3 -|=== - -As with grant, denying `EXECUTE BOOSTED PROCEDURE` on its own only affects the elevation and not the execution of the procedure. -This can be seen in the following examples: - -.Grant `EXECUTE PROCEDURE` and deny `EXECUTE BOOSTED PROCEDURE` -[example] -==== -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE * ON DBMS TO deniedBoostedProcedureExecutor1 ----- - -[source, cypher, role=noplay] ----- -DENY EXECUTE BOOSTED PROCEDURE db.labels ON DBMS TO deniedBoostedProcedureExecutor1 ----- - -The resulting role has privileges that allow the execution of all procedures using the user's own privileges. -It also prevents the `db.labels` procedure from being elevated. -Still, the denied `EXECUTE BOOSTED PROCEDURE` does not block execution of `db.labels`. - -To list all privileges for role `deniedBoostedProcedureExecutor1` as commands, use the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE deniedBoostedProcedureExecutor1 PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY EXECUTE BOOSTED PROCEDURE db.labels ON DBMS TO `deniedBoostedProcedureExecutor1`" -|"GRANT EXECUTE PROCEDURE * ON DBMS TO `deniedBoostedProcedureExecutor1`" -a|Rows: 2 -|=== -==== - -.Grant `EXECUTE BOOSTED PROCEDURE` and deny `EXECUTE PROCEDURE` -[example] -==== -[source, cypher, role=noplay] ----- -GRANT EXECUTE BOOSTED PROCEDURE * ON DBMS TO deniedBoostedProcedureExecutor2 ----- - -[source, cypher, role=noplay] ----- -DENY EXECUTE PROCEDURE db.labels ON DBMS TO deniedBoostedProcedureExecutor2 ----- - -The resulting role has privileges that allow elevating the privileges for all procedures, but cannot execute any due to missing or denied `EXECUTE PROCEDURE` privileges. -List all privileges for the role `deniedBoostedProcedureExecutor2` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE deniedBoostedProcedureExecutor2 PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY EXECUTE PROCEDURE db.labels ON DBMS TO `deniedBoostedProcedureExecutor2`" -|"GRANT EXECUTE BOOSTED PROCEDURE * ON DBMS TO `deniedBoostedProcedureExecutor2`" -a|Rows: 2 -|=== -==== - -.Grant `EXECUTE BOOSTED PROCEDURE` and deny `EXECUTE BOOSTED PROCEDURE` -[example] -==== -[source, cypher, role=noplay] ----- -GRANT EXECUTE BOOSTED PROCEDURE * ON DBMS TO deniedBoostedProcedureExecutor3 ----- - -[source, cypher, role=noplay] ----- -DENY EXECUTE BOOSTED PROCEDURE db.labels ON DBMS TO deniedBoostedProcedureExecutor3 ----- - -The resulting role has privileges that allow elevating the privileges for all procedures except `db.labels`, however no procedures can be executed due to missing `EXECUTE PROCEDURE` privilege. -List all privileges for the role `deniedBoostedProcedureExecutor3` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE deniedBoostedProcedureExecutor3 PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY EXECUTE BOOSTED PROCEDURE db.labels ON DBMS TO `deniedBoostedProcedureExecutor3`" -|"GRANT EXECUTE BOOSTED PROCEDURE * ON DBMS TO `deniedBoostedProcedureExecutor3`" -a|Rows: 2 -|=== -==== - -.How would the privileges from examples 1 to 3 affect the output of a procedure? -[example] -==== -Assume there is a procedure called `myProc`. - -This procedure gives the result `A` and `B` for a user with `EXECUTE PROCEDURE` privilege and `A`, `B` and `C` for a user with `EXECUTE BOOSTED PROCEDURE` privilege. - -Now, adapt the privileges from examples 1 to 3 to be applied to this procedure and show what is returned. -With the privileges from example 1, granted `EXECUTE PROCEDURE *` and denied `EXECUTE BOOSTED PROCEDURE myProc`, the `myProc` procedure returns the result `A` and `B`. - -With the privileges from example 2, granted `EXECUTE BOOSTED PROCEDURE *` and denied `EXECUTE PROCEDURE myProc`, execution of the `myProc` procedure is not allowed. - -With the privileges from example 3, granted `EXECUTE BOOSTED PROCEDURE *` and denied `EXECUTE BOOSTED PROCEDURE myProc`, execution of the `myProc` procedure is not allowed. - -For comparison, when granted: - -* `EXECUTE PROCEDURE myProc`: the `myProc` procedure returns the result `A` and `B`. -* `EXECUTE BOOSTED PROCEDURE myProc`: execution of the `myProc` procedure is not allowed. -* `EXECUTE PROCEDURE myProc` and `EXECUTE BOOSTED PROCEDURE myProc`: the `myProc` procedure returns the result `A`, `B`, and `C`. -==== - -[[access-control-admin-procedure]] -=== The `EXECUTE ADMIN PROCEDURE` privilege - -The ability to execute admin procedures (annotated with `@Admin`) can be granted via the `EXECUTE ADMIN PROCEDURES` privilege. -This privilege is equivalent with granting the xref::administration/access-control/dbms-administration.adoc#access-control-execute-procedure[`EXECUTE PROCEDURE`] and xref::administration/access-control/dbms-administration.adoc#access-control-execute-boosted-procedure[`EXECUTE BOOSTED PROCEDURE`] privileges on each of the admin procedures. -Any newly added `admin` procedure is automatically included in this privilege. -The following query shows an example of how to grant this privilege: - -[source, cypher, role=noplay] ----- -GRANT EXECUTE ADMIN PROCEDURES ON DBMS TO adminProcedureExecutor ----- - -Users with the role `adminProcedureExecutor` can then run any `admin` procedure with elevated privileges. -The resulting role has privileges that allow executing all admin procedures. - -List all privileges for the role `adminProcedureExecutor` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE adminProcedureExecutor PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT EXECUTE ADMIN PROCEDURES ON DBMS TO `adminProcedureExecutor`" -a|Rows: 1 -|=== - -In order to compare this with the `EXECUTE PROCEDURE` and `EXECUTE BOOSTED PROCEDURE` privileges, revisit the `myProc` procedure, but this time as an `admin` procedure, which will give the result `A`, `B` and `C` when allowed to execute. - -By starting with a user only granted the `EXECUTE PROCEDURE myProc` or the `EXECUTE BOOSTED PROCEDURE myProc` privilege, execution of the `myProc` procedure is not allowed. - -However, for a user granted the `EXECUTE ADMIN PROCEDURES` or both `EXECUTE PROCEDURE myProc` and `EXECUTE BOOSTED PROCEDURE myProc`, the `myProc` procedure returns the result `A`, `B` and `C`. - -Any denied `EXECUTE` privilege results in the procedure not being allowed to be executed. -In this case, it does not matter whether `EXECUTE PROCEDURE`, `EXECUTE BOOSTED PROCEDURE` or `EXECUTE ADMIN PROCEDURES` is being denied. - -[[access-control-execute-user-defined-function]] -=== The `EXECUTE USER DEFINED FUNCTION` privilege - -//EXECUTE [USER [DEFINED]] FUNCTION[S] -The ability to execute a user-defined function (UDF) can be granted via the `EXECUTE USER DEFINED FUNCTION` privilege. -A role with this privilege is allowed to execute the UDFs matched by the xref::administration/access-control/dbms-administration.adoc#access-control-name-globbing[name-globbing]. - -[IMPORTANT] -==== -The `EXECUTE USER DEFINED FUNCTION` privilege does not apply to built-in functions, which are always executable. -==== - -.Execute user-defined function -====== -The following query shows an example of how to grant this privilege: - -[source,cypher,role=noplay] ----- -GRANT EXECUTE USER DEFINED FUNCTION apoc.coll.* ON DBMS TO functionExecutor ----- - -Or in short form: - -[source,cypher,role=noplay] ----- -GRANT EXECUTE FUNCTION apoc.coll.* ON DBMS TO functionExecutor ----- - -Users with the role `functionExecutor` can thus run any UDF in the `apoc.coll` namespace. -The function here is run using the user's own privileges. - -The resulting role has privileges that only allow executing UDFs in the `apoc.coll` namespace. -List all privileges for the role `functionExecutor` as commands by using the following query: - -[source,cypher,role=noplay] ----- -SHOW ROLE functionExecutor PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT EXECUTE FUNCTION apoc.coll.* ON DBMS TO `functionExecutor`" -a|Rows: 1 -|=== -====== - -To allow the execution of all but a few UDFs, you can grant `+EXECUTE USER DEFINED FUNCTIONS *+` and deny the unwanted functions. - -.Execute user-defined functions -====== -The following queries allow the execution of all UDFs except those starting with `apoc.any.prop`: - -[source, cypher, role=noplay] ----- -GRANT EXECUTE USER DEFINED FUNCTIONS * ON DBMS TO deniedFunctionExecutor ----- - -[source, cypher, role=noplay] ----- -DENY EXECUTE USER DEFINED FUNCTION apoc.any.prop* ON DBMS TO deniedFunctionExecutor ----- - -Or in short form: - -[source, cypher, role=noplay] ----- -GRANT EXECUTE FUNCTIONS * ON DBMS TO deniedFunctionExecutor ----- - -[source, cypher, role=noplay] ----- -DENY EXECUTE FUNCTION apoc.any.prop* ON DBMS TO deniedFunctionExecutor ----- - -The resulting role has privileges that only allow the execution of all procedures except those starting with `apoc.any.prop`. -List all privileges for the role `deniedFunctionExecutor` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE deniedFunctionExecutor PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY EXECUTE FUNCTION apoc.any.prop* ON DBMS TO `deniedFunctionExecutor`" -|"GRANT EXECUTE FUNCTION * ON DBMS TO `deniedFunctionExecutor`" -a|Rows: 2 -|=== - -The `apoc.any.property` and `apoc.any.properties` are blocked, as well as any other procedures starting with `apoc.any.prop`. -====== - -[[access-control-execute-boosted-user-defined-function]] -=== The `EXECUTE BOOSTED USER DEFINED FUNCTION` privilege - -//EXECUTE BOOSTED [USER [DEFINED]] FUNCTION[S] -The ability to use elevated privileges when executing a user-defined function (UDF) can be granted via the `EXECUTE BOOSTED USER DEFINED FUNCTION` privilege. -A user with this privilege will not be restricted to their other privileges when executing the UDFs matched by the xref::administration/access-control/dbms-administration.adoc#access-control-name-globbing[name-globbing]. -The `EXECUTE BOOSTED USER DEFINED FUNCTION` privilege only affects the elevation and not the execution of the function. -Therefore, it is needed to grant `EXECUTE USER DEFINED FUNCTION` privilege for the functions as well. - -[NOTE] --- -Since Neo4j 5.0, both `EXECUTE USER DEFINED FUNCTION` and `EXECUTE BOOSTED USER DEFINED FUNCTION` are needed to execute a function with elevated privileges. -This differs from Neo4j 4.x, when only the `EXECUTE BOOSTED USER DEFINED FUNCTION` was required. --- - -[IMPORTANT] -==== -The `EXECUTE BOOSTED USER DEFINED FUNCTION` privilege does not apply to built-in functions, as they have no concept of elevated privileges. -==== - -.Execute boosted user-defined function -====== -The following query shows an example of how to grant the `EXECUTE BOOSTED USER DEFINED FUNCTION` privilege: - -[source,cypher,role=noplay] ----- -GRANT EXECUTE USER DEFINED FUNCTION * ON DBMS TO boostedFunctionExecutor -GRANT EXECUTE BOOSTED USER DEFINED FUNCTION apoc.any.properties ON DBMS TO boostedFunctionExecutor ----- - -Or in short form: - -[source,cypher,role=noplay] ----- -GRANT EXECUTE FUNCTION * ON DBMS TO boostedFunctionExecutor -GRANT EXECUTE BOOSTED FUNCTION apoc.any.properties ON DBMS TO boostedFunctionExecutor ----- - -Users with the role `boostedFunctionExecutor` can thus run `apoc.any.properties` with full privileges and see every property on the node/relationship, not just the properties that the user has `READ` privilege on. -Without the `EXECUTE USER DEFINED FUNCTION` no UDFs could be executed at all. - -The resulting role has privileges that allow executing the UDF `apoc.any.properties` with elevated privileges, and all other UDFs with the users own privileges. -List all privileges for the role `boostedFunctionExecutor` as commands by using the following query: - -[source,cypher,role=noplay] ----- -SHOW ROLE boostedFunctionExecutor PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer",width="100%",cols="m"] -|=== -|command -|"GRANT EXECUTE FUNCTION * ON DBMS TO `boostedFunctionExecutor`" -|"GRANT EXECUTE BOOSTED FUNCTION apoc.any.properties ON DBMS TO `boostedFunctionExecutor`" -a|Rows: 2 -|=== -====== - - -[[access-control-dbms-administration-setting]] -== The DBMS `SETTING` privileges - -_This feature was introduced in Neo4j 5.6._ - -The ability to show configuration settings can be granted via the `SHOW SETTING` privilege. -A role with this privilege is allowed to query the configuration settings matched by the xref::administration/access-control/dbms-administration.adoc#access-control-name-globbing[name-globbing]. - - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Setting privileges command syntax -[options="header", width="100%", cols="3a,2"] -|=== -| Command -| Description - -| [source, syntax, role=noheader] -GRANT [IMMUTABLE] SHOW SETTING[S] name-globbing[, ...] - ON DBMS - TO role[, ...] -| Enables the specified roles to query given configuration settings. -|=== - -The following query shows an example of how to grant this privilege: - -[source, cypher, role=noplay] ----- -GRANT SHOW SETTING server.bolt.* ON DBMS TO configurationViewer ----- - -Users with the role `configurationViewer` can then query any setting in the `server.bolt` namespace. - -The updated role `configurationViewer` has privileges that only allow querying settings in the `server.bolt` namespace. -List all privileges for the role `configurationViewer` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE configurationViewer PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT SHOW SETTING server.bolt.* ON DBMS TO `configurationViewer`" -a|Rows: 1 -|=== - -To deny a specific setting from a role, first grant `SHOW SETTINGS *`, and then deny the unwanted setting. -For example, the following queries allow the querying of all settings, except those starting with `dbms.security`: - -[source, cypher, role=noplay] ----- -GRANT SHOW SETTINGS * ON DBMS TO deniedConfigurationViewer ----- - -[source, cypher, role=noplay] ----- -DENY SHOW SETTING dbms.security* ON DBMS TO deniedConfigurationViewer ----- - -The resulting role has privileges that allow querying all settings except those starting with `dbms.security`. -List all privileges for the role `deniedConfigurationViewer` as commands by using the following query: - -[source, cypher, role=noplay] ----- -SHOW ROLE deniedConfigurationViewer PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY SHOW SETTING dbms.security* ON DBMS TO `deniedConfigurationViewer`" -|"GRANT SHOW SETTING * ON DBMS TO `deniedConfigurationViewer`" -a|Rows: 2 -|=== - -As the query result shows, access to any setting starting with `dbms.security` are blocked, but the rest can still be queried. - - -[[access-control-dbms-administration-all]] -== Granting `ALL DBMS PRIVILEGES` - -The right to perform the following privileges can be achieved with a single command: - -* Create, drop, assign, remove, and show roles. -* Create, alter, drop, show, and impersonate users. -* Create, alter, and drop databases and aliases. -* Enable, alter, rename, reallocate, deallocate, and drop servers -* Show, assign, and remove privileges. -* Execute all procedures with elevated privileges. -* Execute all user-defined functions with elevated privileges. -* Show all configuration settings. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -[source, syntax, role=noheader] ----- -GRANT [IMMUTABLE] ALL [[DBMS] PRIVILEGES] - ON DBMS - TO role[, ...] ----- - -For example, to grant the role `dbmsManager` the abilities above, use the following query: - -[source, cypher, role=noplay] ----- -GRANT ALL DBMS PRIVILEGES ON DBMS TO dbmsManager ----- - -The privileges granted can be seen using the `SHOW PRIVILEGES` command: - -[source, cypher, role=noplay] ----- -SHOW ROLE dbmsManager PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ALL DBMS PRIVILEGES ON DBMS TO `dbmsManager`" -a|Rows: 1 -|=== - -[[access-control-name-globbing]] -== Name-globbing for procedures, user-defined functions, and settings - -The name-globbing for procedure, user-defined function, and setting names is a simplified version of globbing for filename expansions. -It only allows two wildcard characters: `+*+` and `?`, which are used for multiple and single character matches. -In this case, `+*+` means 0 or more characters and `?` matches exactly one character. - -[NOTE] -==== -The name-globbing is subject to the xref::syntax/naming.adoc[standard Cypher restrictions on valid identifiers], -with the exception that it may include dots, stars, and question marks without the need for escaping using backticks. - -Each part of the name-globbing separated by dots may be individually escaped. -For example, `++mine.`procedureWith%`++` is allowed, but not `++mine.procedure`With%`++`. -Also, note that wildcard characters behave as wildcards even when escaped. -For example, using `++`*`++` is equivalent to using `+*+`, and thus allows executing all functions or procedures and not only the procedure or function named `+*+`. -==== - -Given the following list of procedures: - -* `mine.public.exampleProcedure` -* `mine.public.exampleProcedure1` -* `mine.public.exampleProcedure2` -* `mine.public.with#Special§Characters` -* `mine.private.exampleProcedure` -* `mine.private.exampleProcedure1` -* `mine.private.exampleProcedure2` -* `mine.private.with#Special§Characters` -* `your.exampleProcedure` - -The following examples demonstrate how name-globbing patterns can be used in controlling access to procedures. -Note that the same rules apply to user-defined functions and settings. - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE * ON DBMS TO globbing1 ----- - -Users with the role `globbing1` can run all the procedures. - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE mine.*.exampleProcedure ON DBMS TO globbing2 ----- - -Users with the role `globbing2` can run procedures `mine.public.exampleProcedure` and `mine.private.exampleProcedure`, but no other procedures. - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE mine.*.exampleProcedure? ON DBMS TO globbing3 ----- - -Users with the role `globbing3` can run procedures `mine.public.exampleProcedure1`, `mine.private.exampleProcedure1`, and `mine.private.exampleProcedure2`, but no other procedures. - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE *.exampleProcedure ON DBMS TO globbing4 ----- - -Users with the role `globbing4` can run procedures `your.exampleProcedure`, `mine.public.exampleProcedure`, and `mine.private.exampleProcedure`, but no other procedures. - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE mine.public.exampleProcedure* ON DBMS TO globbing5 ----- - -Users with the role `globbing5` can run procedures `mine.public.exampleProcedure`, `mine.public.exampleProcedure1` and `mine.public.exampleProcedure42`, but no other procedures. - -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE `mine.public.with#*§Characters`, mine.private.`with#Spec???§Characters` ON DBMS TO globbing6 ----- - -Users with the role `globbing6` can run procedures `mine.public.with#Special§Characters`, and `mine.private.with#Special§Characters`, but no other procedures. - -[NOTE] -==== -The name-globbing may be fully or partially escaped. -Both `+*+` and `+?+` are interpreted as wildcards in both cases. -==== - diff --git a/modules/ROOT/pages/administration/access-control/index.adoc b/modules/ROOT/pages/administration/access-control/index.adoc deleted file mode 100644 index 5506d1f1c..000000000 --- a/modules/ROOT/pages/administration/access-control/index.adoc +++ /dev/null @@ -1,37 +0,0 @@ -:description: Neo4j role-based access control and fine-grained security. - -[[access-control]] -= Access control - -== Overview - -Neo4j has a complex security model stored in the system graph, which is maintained on a special database called the `system` database. -All administrative commands need to be executed against the `system` database. -When connected to the DBMS over link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/connectors[Bolt], administrative commands are automatically routed to the `system` database. -For more information on how to manage multiple databases, refer to the section on xref::administration/databases.adoc[administering databases]. - -_Role-based access control_ was introduced in Neo4j 3.1. -Since then, it has been possible to create users and assign them to roles to control whether users can read, write and administer the database. -In Neo4j 4.0 this model was enhanced significantly with the addition of _privileges_, which are the underlying access-control rules by which the users rights are defined. - -The original built-in roles still exist with almost the exact same access rights, but they are no-longer statically defined (see xref::administration/access-control/built-in-roles.adoc[Built-in roles]). -Instead, they are defined in terms of their underlying _privileges_, and they can be modified by adding or removing these access rights. - -In addition, any newly created roles can be assigned to any combination of _privileges_, so that you may set specific access controls for them. -Another new major capability is the _sub-graph_ access control, through which read access to the graph can be limited to specific combinations of labels, relationship types, and properties. - -== Categories of access control - -More details about specific categories of access control can be found in the following sections: - -* xref:administration/access-control/manage-users.adoc[] -* xref:administration/access-control/manage-roles.adoc[] -* xref:administration/access-control/manage-privileges.adoc[] -* xref:administration/access-control/built-in-roles.adoc[] -* xref:administration/access-control/privileges-reads.adoc[] -* xref:administration/access-control/privileges-writes.adoc[] -* xref:administration/access-control/database-administration.adoc[] -* xref:administration/access-control/dbms-administration.adoc[] -* xref:administration/access-control/limitations.adoc[] -* xref:administration/access-control/privileges-immutable.adoc[] - diff --git a/modules/ROOT/pages/administration/access-control/limitations.adoc b/modules/ROOT/pages/administration/access-control/limitations.adoc deleted file mode 100644 index 8aea171ee..000000000 --- a/modules/ROOT/pages/administration/access-control/limitations.adoc +++ /dev/null @@ -1,334 +0,0 @@ -:description: Known limitations and implications of Neo4js role-based access control security. - -//// -[source, cypher, role=test-setup] ----- -CREATE ROLE users; -CREATE ROLE custom; -CREATE ROLE restricted; -CREATE ROLE free; ----- -//// - -[role=enterprise-edition aura-db-enterprise] -[[access-control-limitations]] -= Limitations - -This page lists the known limitations and implications of Neo4j's role-based access control security. - -[[access-control-limitations-indexes]] -== Security and Indexes - -As described in xref::indexes-for-search-performance.adoc[Indexes for search performance], Neo4j {neo4j-version} supports the creation and use of indexes to improve the performance of Cypher queries. - -Note that the Neo4j security model impacts the results of queries, regardless if the indexes are used or not. -When using non full-text Neo4j indexes, a Cypher query will always return the same results it would have if no index existed. -This means that, if the security model causes fewer results to be returned due to restricted read access in xref::administration/access-control/manage-privileges.adoc[Graph and sub-graph access control], -the index will also return the same fewer results. - -However, this rule is not fully obeyed by xref::indexes-for-full-text-search.adoc[Indexes for full-text search]. -These specific indexes are backed by _Lucene_ internally. -It is therefore not possible to know for certain whether a security violation has affected each specific entry returned from the index. -In face of this, Neo4j will return zero results from full-text indexes in case it is determined that any result might be violating the security privileges active for that query. - -Since full-text indexes are not automatically used by Cypher, they do not lead to the case where the same Cypher query would return different results simply because such an index was created. -Users need to explicitly call procedures to use these indexes. -The problem is only that, if this behavior is not known by the user, they might expect the full-text index to return the same results that a different, but semantically similar, Cypher query does. - -=== Example with denied properties - -Consider the following example. -The database has nodes with labels `:User` and `:Person`, and they have properties `name` and `surname`. -There are indexes on both properties: - -[source, cypher] ----- -CREATE INDEX singleProp FOR (n:User) ON (n.name); -CREATE INDEX composite FOR (n:User) ON (n.name, n.surname); -CREATE FULLTEXT INDEX userNames FOR (n:User|Person) ON EACH [n.name, n.surname]; ----- - -[NOTE] -==== -Full-text indexes support multiple labels. -See xref::indexes-for-full-text-search.adoc[Indexes for full-text search] for more details on creating and using full-text indexes. -==== - -After creating these indexes, it would appear that the latter two indexes accomplish the same thing. -However, this is not completely accurate. -The composite and full-text indexes behave in different ways and are focused on different use cases. -A key difference is that full-text indexes are backed by _Lucene_, and will use the _Lucene_ syntax for querying. - -This has consequences for users restricted on the labels or properties involved in the indexes. -Ideally, if the labels and properties in the index are denied, they can correctly return zero results from both native indexes and full-text indexes. -However, there are borderline cases where this is not as simple. - -Imagine the following nodes were added to the database: - -[source, cypher] ----- -CREATE (:User {name: 'Sandy'}); -CREATE (:User {name: 'Mark', surname: 'Andy'}); -CREATE (:User {name: 'Andy', surname: 'Anderson'}); -CREATE (:User:Person {name: 'Mandy', surname: 'Smith'}); -CREATE (:User:Person {name: 'Joe', surname: 'Andy'}); ----- - -Consider denying the label `:Person`: - -[source, cypher] ----- -DENY TRAVERSE ON GRAPH * NODES Person TO users ----- - -If the user runs a query that uses the native single property index on `name`: - -[source, cypher] ----- -MATCH (n:User) WHERE n.name CONTAINS 'ndy' RETURN n.name ----- - -This query performs several checks: - -* Scans the index to create a stream of results of nodes with the `name` property, which leads to five results. -* Filters the results to include only nodes where `n.name CONTAINS 'ndy'`, filtering out `Mark` and `Joe`, which leads to three results. -* Filters the results to exclude nodes that also have the denied label `:Person`, filtering out `Mandy`, which leads to two results. - -Two results will be returned from this dataset and only one of them has the `surname` property. - -In order to use the native composite index on `name` and `surname`, the query needs to include a predicate on the `surname` property as well: - -[source, cypher] ----- -MATCH (n:User) -WHERE n.name CONTAINS 'ndy' AND n.surname IS NOT NULL -RETURN n.name ----- - -This query performs several checks, which are almost identical to the single property index query: - -* Scans the index to create a stream of results of nodes with the `name` and `surname` property, which leads to four results. -* Filters the results to include only nodes where `n.name CONTAINS 'ndy'`, filtering out `Mark` and `Joe`, which leads to two results. -* Filters the results to exclude nodes that also have the denied label `:Person`, filtering out `Mandy`, which leads to only one result. - -Only one result was returned from the above dataset. -What if this query with the full-text index was used instead: - -[source, cypher] ----- -CALL db.index.fulltext.queryNodes("userNames", "ndy") YIELD node, score -RETURN node.name ----- - -The problem now is that it is not certain whether the results provided by the index were achieved due to a match to the `name` or the `surname` property. -The steps taken by the query engine would be: - -* Run a _Lucene_ query on the full-text index to produce results containing `ndy` in either property, leading to five results. -* Filter the results to exclude nodes that also have the label `:Person`, filtering out `Mandy` and `Joe`, leading to three results. - -This difference in results is caused by the `OR` relationship between the two properties in the index creation. - -=== Denying properties - -Now consider denying access on properties, like the `surname` property: - -[source, cypher] ----- -DENY READ {surname} ON GRAPH * TO users ----- - -For that, run the same queries again: - -[source, cypher] ----- -MATCH (n:User) -WHERE n.name CONTAINS 'ndy' -RETURN n.name ----- - -This query operates exactly as before, returning the same two results, because nothing in it relates to the denied property. - -However, this is not the same for the query targeting the composite index: - -[source, cypher] ----- -MATCH (n:User) -WHERE n.name CONTAINS 'ndy' AND n.surname IS NOT NULL -RETURN n.name ----- - -Since the `surname` property is denied, it will appear to always be `null` and the composite index empty. Therefore, the query returns no result. - -Now consider the full-text index query: - -[source, cypher] ----- -CALL db.index.fulltext.queryNodes("userNames", "ndy") YIELD node, score -RETURN node.name ----- - -The problem remains, since it is not certain whether the results provided by the index were returned due to a match on the `name` or the `surname` property. -Results from the `surname` property now need to be excluded by the security rules, because they require that the user is unable to see any `surname` properties. -However, the security model is not able to introspect the _Lucene_ query in order to know what it will actually do, whether it works only on the allowed `name` property, or also on the disallowed `surname` property. -What is known is that the earlier query returned a match for `Joe Andy` which should now be filtered out. -Therefore, in order to never return results the user should not be able to see, all results need to be blocked. -The steps taken by the query engine would be: - -* Determine if the full-text index includes denied properties. -* If yes, return an empty results stream. -Otherwise, it will process as described before. - -In this case, the query will return zero results rather than simply returning the results `Andy` and `Sandy`, which might have been expected. - - -[[access-control-limitations-labels]] -== Security and labels - -=== Traversing the graph with multi-labeled nodes - -The general influence of access control privileges on graph traversal is described in detail in xref::administration/access-control/manage-privileges.adoc[Graph and sub-graph access control]. -The following section will only focus on nodes due to their ability to have multiple labels. -Relationships can only have one type of label and thus they do not exhibit the behavior this section aims to clarify. -While this section will not mention relationships further, the general function of the traverse privilege also applies to them. - -For any node that is traversable, due to `GRANT TRAVERSE` or `GRANT MATCH`, -the user can get information about the attached labels by calling the built-in `labels()` function. -In the case of nodes with multiple labels, they can be returned to users that weren't directly granted access to. - -To give an illustrative example, imagine a graph with three nodes: one labeled `:A`, another labeled `:B` and one with the labels `:A` and `:B`. -In this case, there is a user with the role `custom` defined by: - -[source, cypher] ----- -GRANT TRAVERSE ON GRAPH * NODES A TO custom ----- - -If that user were to execute - -[source, cypher] ----- -MATCH (n:A) -RETURN n, labels(n) ----- - -They would get a result with two nodes: the node that was labeled with `:A` and the node with labels `:A :B`. - -In contrast, executing - -[source, cypher] ----- -MATCH (n:B) -RETURN n, labels(n) ----- - -This will return only the one node that has both labels: `:A` and `:B`. -Even though `:B` did not have access to traversals, there is one node with that label accessible in the dataset due to the allow-listed label `:A` that is attached to the same node. - -If a user is denied to traverse on a label they will never get results from any node that has this label attached to it. -Thus, the label name will never show up for them. -As an example, this can be done by executing: - -[source, cypher] ----- -DENY TRAVERSE ON GRAPH * NODES B TO custom ----- - -The query - -[source, cypher] ----- -MATCH (n:A) -RETURN n, labels(n) ----- - -will now return the node only labeled with `:A`, while the query - -[source, cypher] ----- -MATCH (n:B) -RETURN n, labels(n) ----- - -will now return no nodes. - -=== The db.labels() procedure - -In contrast to the normal graph traversal described in the previous section, the built-in `db.labels()` procedure is not processing the data graph itself, but the security rules defined on the system graph. -That means: - -* If a label is explicitly whitelisted (granted), it will be returned by this procedure. -* If a label is denied or isn't explicitly allowed, it will not be returned by this procedure. - -Reusing the previous example, imagine a graph with three nodes: one labeled `:A`, another labeled `:B` and one with the labels `:A` and `:B`. -In this case, there is a user with the role `custom` defined by: - -[source, cypher] ----- -GRANT TRAVERSE ON GRAPH * NODES A TO custom ----- - -This means that only label `:A` is explicitly allow-listed. -Thus, executing - -[source, cypher] ----- -CALL db.labels() ----- - -will only return label `:A`, because that is the only label for which traversal was granted. - - -[[access-control-limitations-db-operations]] -== Security and count store operations - -The rules of a security model may impact some of the database operations. -This means extra security checks are necessary to incur additional data accesses, especially in the case of count store operations. -These are, however, usually very fast lookups and the difference might be noticeable. - -See the following security rules that use a `restricted` and a `free` role as an example: - -[source, cypher] ----- -GRANT TRAVERSE ON GRAPH * NODES Person TO restricted; -DENY TRAVERSE ON GRAPH * NODES Customer TO restricted; -GRANT TRAVERSE ON GRAPH * ELEMENTS * TO free; ----- - -Now, let's look at what the database needs to do in order to execute the following query: - -[source, cypher] ----- -MATCH (n:Person) -RETURN count(n) ----- - -For both roles the execution plan will look like this: - ----- -+--------------------------+ -| Operator | -+--------------------------+ -| +ProduceResults | -| | + -| +NodeCountFromCountStore | -+--------------------------+ ----- - -Internally, however, very different operations need to be executed. -The following table illustrates the difference: - -[%header,cols=2*] -|=== -|User with `free` role -|User with `restricted` role - -|The database can access the count store and retrieve the total number of nodes with the label `:Person`. - -This is a very quick operation. - -|The database cannot access the count store because it must make sure that only traversable nodes with the desired label `:Person` are counted. -Due to this, each node with the `:Person` label needs to be accessed and examined to make sure that they do not have a deny-listed label, such as `:Customer`. - -Due to the additional data accesses that the security checks need to do, this operation will be slower compared to executing the query as an unrestricted user. - -|=== diff --git a/modules/ROOT/pages/administration/access-control/manage-privileges.adoc b/modules/ROOT/pages/administration/access-control/manage-privileges.adoc deleted file mode 100644 index d87d0fa65..000000000 --- a/modules/ROOT/pages/administration/access-control/manage-privileges.adoc +++ /dev/null @@ -1,1598 +0,0 @@ -:description: This section explains how to use Cypher to manage privileges for Neo4j role-based access control and fine-grained security. -[role=enterprise-edition aura-db-enterprise] -[[access-control-manage-privileges]] - -= Managing privileges - -This page explains how to use Cypher to manage privileges for Neo4j role-based access control and fine-grained security. - -Privileges control the access rights to graph elements using a combined allowlist/denylist mechanism. -It is possible to grant or deny access, or use a combination of the two. -The user will be able to access the resource if they have a `GRANT` (allowlist) and do not have a `DENY` (denylist) relevant to that resource. -All other combinations of `GRANT` and `DENY` will result in the matching path being inaccessible. -What this means in practice depends on whether we are talking about a xref::administration/access-control/privileges-reads.adoc[read privilege] or a xref::administration/access-control/privileges-writes.adoc[write privilege]: - -* If an entity is not accessible due to xref::administration/access-control/privileges-reads.adoc[read privileges], the data will become invisible. -It will appear to the user as if they had a smaller database (smaller graph). -* If an entity is not accessible due to xref::administration/access-control/privileges-writes.adoc[write privileges], an error will occur on any attempt to write that data. - -[NOTE] -==== -In this document we will often use the terms _'allows'_ and _'enables'_ in seemingly identical ways. However, there is a subtle difference. -We will use _'enables'_ to refer to the consequences of xref::administration/access-control/privileges-reads.adoc[read privileges] where a restriction will not cause an error, only a reduction in the apparent graph size. -We will use _'allows'_ to refer to the consequence of xref::administration/access-control/privileges-writes.adoc[write privileges] where a restriction can result in an error. -==== - -[NOTE] -==== -If a user was not also provided with the database `ACCESS` privilege, then access to the entire database will be denied. -Information about the database access privilege can be found in xref::administration/access-control/database-administration.adoc#access-control-database-administration-access[The ACCESS privilege]. -==== - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -[[access-control-graph-privileges]] -== Graph privilege commands (`GRANT`, `DENY` and `REVOKE`) - -Administrators can use Cypher commands to manage Neo4j graph administrative rights. -The components of the graph privilege commands are: - -* _the command_: -** `GRANT` – gives privileges to roles. -** `DENY` – denies privileges to roles. -** `REVOKE` – removes granted or denied privileges from roles. - -* _mutability_: -** `IMMUTABLE` can optionally be specified when performing a `GRANT` or `DENY` to indicate that the privilege cannot be subsequently removed unless auth is disabled. Auth must also be disabled in order to `GRANT` or `DENY` an immutable privilege. Contrastingly, when `IMMUTABLE` is specified in conjunction with a `REVOKE` command, it will act as a filter and only remove matching _immutable_ privileges. See also xref:administration/access-control/index.adoc#access-control-privileges-immutable[immutable privileges]. - -* _graph-privilege_: -** Can be either a xref::administration/access-control/privileges-reads.adoc[read privilege] or xref::administration/access-control/privileges-writes.adoc[write privilege]. - -* _name_: -** The graph or graphs to associate the privilege with. -Because in Neo4j {neo4j-version} you can have only one graph per database, this command uses the database name or alias to refer to that graph. -When using an alias, the command will be executed on the resolved graph. -+ -[NOTE] -==== -If you delete a database and create a new one with the same name, the new one will _NOT_ have the privileges previously assigned to the deleted graph. -==== -** It can be `+*+`, which means all graphs. -Graphs created after this command execution will also be associated with these privileges. - -** `HOME GRAPH` refers to the graph associated with the home database for that user. -The default database will be used as home database if a user does not have one configured. -If the user's home database changes for any reason after privileges have been created, then these privileges will be associated with the graph attached to the new database. -This can be quite powerful as it allows permissions to be switched from one graph to another simply by changing a user's home database. - -* _entity_ -** The graph elements this privilege applies to: -*** `NODES` label (nodes with the specified label(s)). -*** `RELATIONSHIPS` type (relationships of the specific type(s)). -*** `ELEMENTS` label (both nodes and relationships). -** The label or type can be referred with `+*+`, which means all labels or types. -** Multiple labels or types can be specified, comma-separated. -** Defaults to `ELEMENTS` `+*+` if omitted. -** Some of the commands for write privileges do not allow an _entity_ part. -See xref::administration/access-control/privileges-writes.adoc[Write privileges] for details. -* _role[, ...]_ -** The role or roles to associate the privilege with, comma-separated. - -.General grant +ON GRAPH+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +GRANT ... ON ... TO ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -GRANT [IMMUTABLE] graph-privilege ON { HOME GRAPH \| GRAPH[S] { * \| name[, ...] } } [entity] TO role[, ...] ----- - -| Description -a| Grants a privilege to one or multiple roles. - -|=== - -.General deny +ON GRAPH+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +DENY ... ON ... TO ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -DENY [IMMUTABLE] graph-privilege ON { HOME GRAPH \| GRAPH[S] { * \| name[, ...] } } [entity] TO role[, ...] ----- - -| Description -a| Denies a privilege to one or multiple roles. - -|=== - -.General revoke +ON GRAPH+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +REVOKE GRANT ... ON ... FROM ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -REVOKE [IMMUTABLE] GRANT graph-privilege ON { HOME GRAPH \| GRAPH[S] { * \| name[, ...] } } [entity] FROM role[, ...] ----- -| Description -a| Revokes a granted privilege from one or multiple roles. - -|=== - -.General revoke +ON GRAPH+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +REVOKE DENY ... ON ... FROM ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -REVOKE [IMMUTABLE] DENY graph-privilege ON { HOME GRAPH \| GRAPH[S] {* \| name[, ...] } } [entity] FROM role[, ...] ----- - -| Description -a| Revokes a denied privilege from one or multiple roles. - -|=== - -.General revoke +ON GRAPH+ privilege syntax -[cols="<15s,<85"] -|=== - -| Command -m| +REVOKE ... ON ... FROM ...+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -REVOKE [IMMUTABLE] graph-privilege ON { HOME GRAPH \| GRAPH[S] { * \| name[, ...] } } [entity] FROM role[, ...] ----- - -| Description -| Revokes a granted or denied privilege from one or multiple roles. -|=== - -[NOTE] -==== -`DENY` does NOT erase a granted privilege; they both exist. -Use `REVOKE` if you want to remove a privilege. -==== - -Common errors, such as misspellings or attempts to revoke privileges that have not been granted or denied, will result in notifications. -Some of these notifications may be replaced with errors in a future major version of Neo4j. -See link:{neo4j-docs-base-uri}/status-codes/{page-version}/notifications/all-notifications[Status Codes -> Notification codes] for details on notifications. - -The general `GRANT` and `DENY` syntaxes are illustrated in the following image: - -image::privileges_grant_and_deny_syntax.svg[title="GRANT and DENY Syntax"] - -A more detailed syntax illustration for graph privileges would be the following: - -image::privileges_on_graph_syntax.svg[title="Syntax of GRANT and DENY Graph Privileges. The `{` and `}` are part of the syntax and not used for grouping."] - -The following image shows the hierarchy between different graph privileges: - -image::privileges_hierarchy.svg[title="Graph privileges hierarchy"] - -[[access-control-list-supported-privileges]] -== Listing supported privileges - -_This feature was introduced in Neo4j 5.9._ - -Supported privileges can be displayed using the `SHOW SUPPORTED PRIVILEGES` command. -This lists the privileges that are possible to grant or deny on a server, together with the structure of the privilege. - -.Show supported privileges command syntax -[cols="<15s,<85"] -|=== - -| Command -m| +SHOW SUPPORTED PRIVILEGES+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -SHOW SUPPORTED PRIVILEGE[S] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- -| Description -| List all privileges supported by the server. - -|=== - -When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. - -Results will include multiple columns describing the privileges: - -[options="header", width="100%", cols="4m,6a,2m"] -|=== -| Column | Description | Type - -| action -| The privilege action. -| STRING - -| qualifier -| Qualifier to further limit the target of the privilege (`function`, `label`, `procedure`, `property`, `setting`, `username`) or null if not applicable. -| STRING - -| target -| Target of the privilege: `dbms`, `database`, or `graph`. -| STRING - -| scope -| List of possible scopes for the privilege (`elements`, `nodes`, `relationships`) or null if not applicable. -| LIST - -| description -| A short description of the privilege. -| STRING - -|=== - -If a privilege lists a qualifier, it has to be used in the command by either an identifier or `*` if it should affect all identifiers. -The below table demonstrates how qualifiers are used: - -[options="header", width="100%", cols="2m,6m"] -|=== -| qualifier | example -| function | \... EXECUTE FUNCTION `abc*` ON ... -| label | \... SET LABEL `A` ON ... -| procedure | \... EXECUTE BOOSTED PROCEDURE `apoc.*` ON ... -| property | \... READ {`property`} ON ... -| setting | \... SHOW SETTINGS `dbms.*` ON ... -| username | \... IMPERSONATE (`username`) ON ... - -|=== - -It is optional to specify the scope of a privilege. -If it is not specified, the default scope will be `ELEMENT *`. -Note that not all privileges have a scope. - - -[[access-control-list-supported-privileges-example]] -=== Examples for listing supported privileges - -[source, cypher, role=noplay] ----- -SHOW SUPPORTED PRIVILEGES YIELD * ORDER BY action DESC LIMIT 10 RETURN action, qualifier, target, scope, description ----- - -Lists 10 supported privileges: - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m"] -|=== -|action -|qualifier -|target -|scope -|description - -| "write" -| NULL -| "graph" -| NULL -| "allows all WRITE operations on an entire graph" - -| "user management" -| NULL -| "dbms" -| NULL -| "enables the specified roles to create, delete, modify, and list users" - -| "traverse" -| NULL -| "graph" -| ["elements", "nodes", "relationships"] -| "enables the specified entities to be found" - -| "transaction management" -| "username" -| "database" -| NULL -| "allows listing and ending transactions and queries for the specified users on the specified database" - -| "terminate transactions" -| "username" -| "database" -| NULL -| "allows ending transactions and queries for the specified users on the specified database" - -| "stop" -| NULL -| "database" -| NULL -| "allows the specified database to be stopped" - -| "start" -| NULL -| "database" -| NULL -| "allows the specified database to be started" - -| "show user" -| NULL -| "dbms" -| NULL -| "enables the specified roles to list users" - -| "show transactions" -| "username" -| "database" -| NULL -| "allows listing transactions and queries for the specified users on the specified database" - -| "show settings" -| "setting" -| "dbms" -| NULL -| "enables the specified roles to query given configuration settings" - -5+a|Rows: 10 -|=== - -[[access-control-list-privileges]] -== Listing assigned privileges - -Privileges that have been granted or denied to roles can be displayed using the following `SHOW PRIVILEGE[S]` commands. - -.Show privileges command syntax -[cols="<15s,<85"] -|=== - -| Command -m| +SHOW PRIVILEGE+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -SHOW [ALL] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- -| Description -| List all granted or denied privileges. - -|=== - -.Show role privileges syntax -[cols="<15s,<85"] -|=== - -| Command -m| +SHOW ROLE ... PRIVILEGE+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| Description -| List privileges granted or denied to a specific role. - -|=== - -.Show user privileges syntax -[cols="<15s,<85"] -|=== - -| Command -m| +SHOW USER ... PRIVILEGE+ - -| Syntax -a| -[source, syntax, role="noheader", indent=0] ----- -SHOW USER[S] [name[, ...]] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| Description -| List privileges for a specific user, or the current user. - -[NOTE] -==== -Please note that it is only possible for a user to show their own privileges. -Therefore, if a non-native auth provider like LDAP is in use, `SHOW USER PRIVILEGES` will only work in a limited capacity. - -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. - -When omitting the `AS COMMANDS` clause, results will include multiple columns describing privileges: - -[options="header", width="100%", cols="4m,6a,2m"] -|=== -| Column | Description | Type - -| access -| Whether the privilege is granted or denied. -| STRING - -| action -| The type of the privilege. -E.g., traverse, read, index management, or role management. -| STRING - -| resource -| The scope of the privilege. -E.g., the entire DBMS, a specific database, a graph, or sub-graph access. -| STRING - -| graph -| The specific database or graph the privilege applies to. -| STRING - -| segment -| The labels, relationship types, procedures, functions, transactions or settings the privilege applies to (if applicable). -| STRING - -| role -| The role the privilege is granted to. -| STRING - -| immutable -| Whether or not the privilege is immutable. - -This column is also available for the `AS COMMAND` variant using `YIELD`. -| BOOLEAN - -| user -| The user the privilege belongs to. - -Note that this is only returned for `SHOW USER [username] PRIVILEGES`. -| STRING - -|=== - -[[access-control-list-all-privileges]] -=== Examples for listing all privileges - -Assigned privileges can be displayed using the different `SHOW PRIVILEGE[S]` commands. - -[source, syntax] ----- -SHOW [ALL] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - [WHERE expression] - -SHOW [ALL] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -[source, cypher, role=noplay] ----- -SHOW PRIVILEGES ----- - -Lists all privileges for all roles: - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m,m,m"] -|=== -|access -|action -|resource -|graph -|segment -|role -|immutable - -|"GRANTED" -|"execute" -|"database" -|"*" -|"FUNCTION(*)" -|"PUBLIC" -|false - -|"GRANTED" -|"execute" -|"database" -|"*" -|"PROCEDURE(*)" -|"PUBLIC" -|false - -|"GRANTED" -|"access" -|"database" -|"DEFAULT" -|"database" -|"PUBLIC" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"NODE(*)" -|"admin" -|false - -|"GRANTED" -|"write" -|"graph" -|"*" -|"NODE(*)" -|"admin" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"RELATIONSHIP(*)" -|"admin" -|false - -|"GRANTED" -|"write" -|"graph" -|"*" -|"RELATIONSHIP(*)" -|"admin" -|false - -|"GRANTED" -|"transaction_management" -|"database" -|"*" -|"USER(*)" -|"admin" -|false - -|"GRANTED" -|"access" -|"database" -|"*" -|"database" -|"admin" -|false - -|"GRANTED" -|"constraint" -|"database" -|"*" -|"database" -|"admin" -|false - -|"GRANTED" -|"dbms_actions" -|"database" -|"*" -|"database" -|"admin" -|false - -|"GRANTED" -|"index" -|"database" -|"*" -|"database" -|"admin" -|false - -|"GRANTED" -|"start_database" -|"database" -|"*" -|"database" -|"admin" -|false - -|"GRANTED" -|"stop_database" -|"database" -|"*" -|"database" -|"admin" -|false - -|"GRANTED" -|"token" -|"database" -|"*" -|"database" -|"admin" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"NODE(*)" -|"architect" -|false - -|"GRANTED" -|"write" -|"graph" -|"*" -|"NODE(*)" -|"architect" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"RELATIONSHIP(*)" -|"architect" -|false - -|"GRANTED" -|"write" -|"graph" -|"*" -|"RELATIONSHIP(*)" -|"architect" -|false - -|"GRANTED" -|"access" -|"database" -|"*" -|"database" -|"architect" -|false - -|"GRANTED" -|"constraint" -|"database" -|"*" -|"database" -|"architect" -|false - -|"GRANTED" -|"index" -|"database" -|"*" -|"database" -|"architect" -|false - -|"GRANTED" -|"token" -|"database" -|"*" -|"database" -|"architect" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"NODE(*)" -|"editor" -|false - -|"GRANTED" -|"write" -|"graph" -|"*" -|"NODE(*)" -|"editor" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"RELATIONSHIP(*)" -|"editor" -|false - -|"GRANTED" -|"write" -|"graph" -|"*" -|"RELATIONSHIP(*)" -|"editor" -|false - -|"GRANTED" -|"access" -|"database" -|"*" -|"database" -|"editor" -|false - -|"DENIED" -|"access" -|"database" -|"neo4j" -|"database" -|"noAccessUsers" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"NODE(*)" -|"publisher" -|false - -|"GRANTED" -|"write" -|"graph" -|"*" -|"NODE(*)" -|"publisher" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"RELATIONSHIP(*)" -|"publisher" -|false - -|"GRANTED" -|"write" -|"graph" -|"*" -|"RELATIONSHIP(*)" -|"publisher" -|false - -|"GRANTED" -|"access" -|"database" -|"*" -|"database" -|"publisher" -|false - -|"GRANTED" -|"token" -|"database" -|"*" -|"database" -|"publisher" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"NODE(*)" -|"reader" -|false - -|"GRANTED" -|"match" -|"all_properties" -|"*" -|"RELATIONSHIP(*)" -|"reader" -|false - -|"GRANTED" -|"access" -|"database" -|"*" -|"database" -|"reader" -|false - -|"GRANTED" -|"access" -|"database" -|"neo4j" -|"database" -|"regularUsers" -|false - -7+a|Rows: 39 -|=== - -It is also possible to filter and sort the results by using `YIELD`, `ORDER BY` and `WHERE`: - -[source, cypher, role=noplay] ----- -SHOW PRIVILEGES YIELD role, access, action, segment -ORDER BY action -WHERE role = 'admin' ----- - -In this example: - -* The number of columns returned has been reduced with the `YIELD` clause. -* The order of the returned columns has been changed. -* The results have been filtered to only return the `admin` role using a `WHERE` clause. -* The results are ordered by the `action` column using `ORDER BY`. - -`SKIP` and `LIMIT` can also be used to paginate the results. - -.Result -[options="header,footer", width="100%", cols="m,m,m,m"] -|=== -|role -|access -|action -|segment - -|"admin" -|"GRANTED" -|"access" -|"database" - -|"admin" -|"GRANTED" -|"constraint" -|"database" - -|"admin" -|"GRANTED" -|"dbms_actions" -|"database" - -|"admin" -|"GRANTED" -|"index" -|"database" - -|"admin" -|"GRANTED" -|"match" -|"NODE(*)" - -|"admin" -|"GRANTED" -|"match" -|"RELATIONSHIP(*)" - -|"admin" -|"GRANTED" -|"start_database" -|"database" - -|"admin" -|"GRANTED" -|"stop_database" -|"database" - -|"admin" -|"GRANTED" -|"token" -|"database" - -|"admin" -|"GRANTED" -|"transaction_management" -|"USER(*)" - -|"admin" -|"GRANTED" -|"write" -|"NODE(*)" - -|"admin" -|"GRANTED" -|"write" -|"RELATIONSHIP(*)" - -4+a|Rows: 12 -|=== - -`WHERE` can also be used without `YIELD`: - -[source, cypher, role=noplay] ----- -SHOW PRIVILEGES -WHERE graph <> '*' ----- - -In this example, the `WHERE` clause is used to filter privileges down to those that target specific graphs only. - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m,m"] -|=== -|access -|action -|graph -|resource -|role -|segment - -|"GRANTED" -|"access" -|"DEFAULT" -|"database" -|"PUBLIC" -|"database" - -|"DENIED" -|"access" -|"neo4j" -|"database" -|"noAccessUsers" -|"database" - -|"GRANTED" -|"access" -|"neo4j" -|"database" -|"regularUsers" -|"database" - -6+a|Rows: 3 -|=== - -Aggregations in the `RETURN` clause can be used to group privileges. -In this case, by user and `GRANTED` or `DENIED`: - -[source, cypher, role=noplay] ----- -SHOW PRIVILEGES YIELD * RETURN role, access, collect([graph, resource, segment, action]) AS privileges ----- - -.Result -[options="header,footer", width="100%", cols="1m,1m,3m"] -|=== -|role -|access -|privileges - -|"PUBLIC" -|"GRANTED" -|[["\*","database","FUNCTION(*)","execute"],["\*","database","PROCEDURE(*)","execute"],["DEFAULT","database","database","access"]] - -|"admin" -|"GRANTED" -|[["\*","all_properties","NODE(*)","match"],["\*","graph","NODE(*)","write"],["\*","all_properties","RELATIONSHIP(*)","match"],["\*","graph","RELATIONSHIP(*)","write"],["\*","database","USER(*)","transaction_management"],["\*","database","database","access"],["*","database","database","constraint"],["\*","database","database","dbms_actions"],["*","database","database","index"],["\*","database","database","start_database"],["*","database","database","stop_database"],["*","database","database","token"]] - -|"architect" -|"GRANTED" -|[["\*","all_properties","NODE(*)","match"],["\*","graph","NODE(*)","write"],["\*","all_properties","RELATIONSHIP(*)","match"],["\*","graph","RELATIONSHIP(*)","write"],["\*","database","database","access"],["*","database","database","constraint"],["\*","database","database","index"],["*","database","database","token"]] - -|"editor" -|"GRANTED" -|[["\*","all_properties","NODE(*)","match"],["\*","graph","NODE(*)","write"],["\*","all_properties","RELATIONSHIP(*)","match"],["\*","graph","RELATIONSHIP(*)","write"],["*","database","database","access"]] - -|"noAccessUsers" -|"DENIED" -|[["neo4j","database","database","access"]] - -|"publisher" -|"GRANTED" -|[["\*","all_properties","NODE(*)","match"],["\*","graph","NODE(*)","write"],["\*","all_properties","RELATIONSHIP(*)","match"],["\*","graph","RELATIONSHIP(*)","write"],["\*","database","database","access"],["*","database","database","token"]] - -|"reader" -|"GRANTED" -|[["\*","all_properties","NODE(*)","match"],["\*","all_properties","RELATIONSHIP(*)","match"],["*","database","database","access"]] - -|"regularUsers" -|"GRANTED" -|[["neo4j","database","database","access"]] - -3+a|Rows: 8 -|=== - -The `RETURN` clause can also be used to order and paginate the results, which is useful when combined with `YIELD` and `WHERE`. -In this example the query returns privileges for display five-per-page, and skips the first five to display the second page. - -[source, cypher, role=noplay] ----- -SHOW PRIVILEGES YIELD * RETURN * ORDER BY role SKIP 5 LIMIT 5 ----- - -.Result -[options="header,footer", width="100%", cols="2m,2m,1m,2m,1m,2m,1m"] -|=== -|access -|action -|graph -|resource -|role -|segment -|immutable - -|"GRANTED" -|"match" -|"*" -|"all_properties" -|"admin" -|"RELATIONSHIP(*)" -|false - -|"GRANTED" -|"write" -|"*" -|"graph" -|"admin" -|"RELATIONSHIP(*)" -|false - -|"GRANTED" -|"transaction_management" -|"*" -|"database" -|"admin" -|"USER(*)" -|false - -|"GRANTED" -|"access" -|"*" -|"database" -|"admin" -|"database" -|false - -|"GRANTED" -|"constraint" -|"*" -|"database" -|"admin" -|"database" -|false - -7+a|Rows: 5 -|=== - -Available privileges can also be displayed as Cypher commands by adding `AS COMMAND[S]`: - -[source, cypher, role=noplay] ----- -SHOW PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"DENY ACCESS ON DATABASE `neo4j` TO `noAccessUsers`" -|"GRANT ACCESS ON DATABASE * TO `admin`" -|"GRANT ACCESS ON DATABASE * TO `architect`" -|"GRANT ACCESS ON DATABASE * TO `editor`" -|"GRANT ACCESS ON DATABASE * TO `publisher`" -|"GRANT ACCESS ON DATABASE * TO `reader`" -|"GRANT ACCESS ON DATABASE `neo4j` TO `regularUsers`" -|"GRANT ACCESS ON HOME DATABASE TO `PUBLIC`" -|"GRANT ALL DBMS PRIVILEGES ON DBMS TO `admin`" -|"GRANT CONSTRAINT MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT CONSTRAINT MANAGEMENT ON DATABASE * TO `architect`" -|"GRANT EXECUTE FUNCTION * ON DBMS TO `PUBLIC`" -|"GRANT EXECUTE PROCEDURE * ON DBMS TO `PUBLIC`" -|"GRANT INDEX MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT INDEX MANAGEMENT ON DATABASE * TO `architect`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `admin`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `architect`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `editor`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `publisher`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `reader`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `admin`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `architect`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `editor`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `publisher`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `reader`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `architect`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `publisher`" -|"GRANT START ON DATABASE * TO `admin`" -|"GRANT STOP ON DATABASE * TO `admin`" -|"GRANT TRANSACTION MANAGEMENT (*) ON DATABASE * TO `admin`" -|"GRANT WRITE ON GRAPH * TO `admin`" -|"GRANT WRITE ON GRAPH * TO `architect`" -|"GRANT WRITE ON GRAPH * TO `editor`" -|"GRANT WRITE ON GRAPH * TO `publisher`" -a|Rows: 35 -|=== - -Like other `SHOW` commands, the output can also be processed using `YIELD` / `WHERE` / `RETURN`: - -[source, cypher, role=noplay] ----- -SHOW PRIVILEGES AS COMMANDS -WHERE command CONTAINS 'MANAGEMENT' ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT CONSTRAINT MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT CONSTRAINT MANAGEMENT ON DATABASE * TO `architect`" -|"GRANT INDEX MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT INDEX MANAGEMENT ON DATABASE * TO `architect`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `architect`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `publisher`" -|"GRANT TRANSACTION MANAGEMENT (*) ON DATABASE * TO `admin`" -a|Rows: 8 -|=== - -It is also possible to get the privileges listed as revoking commands instead of granting or denying: - -[source, cypher, role=noplay] ----- -SHOW PRIVILEGES AS REVOKE COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"REVOKE DENY ACCESS ON DATABASE `neo4j` FROM `noAccessUsers`" -|"REVOKE GRANT ACCESS ON DATABASE * FROM `admin`" -|"REVOKE GRANT ACCESS ON DATABASE * FROM `architect`" -|"REVOKE GRANT ACCESS ON DATABASE * FROM `editor`" -|"REVOKE GRANT ACCESS ON DATABASE * FROM `publisher`" -|"REVOKE GRANT ACCESS ON DATABASE * FROM `reader`" -|"REVOKE GRANT ACCESS ON DATABASE `neo4j` FROM `regularUsers`" -|"REVOKE GRANT ACCESS ON HOME DATABASE FROM `PUBLIC`" -|"REVOKE GRANT ALL DBMS PRIVILEGES ON DBMS FROM `admin`" -|"REVOKE GRANT CONSTRAINT MANAGEMENT ON DATABASE * FROM `admin`" -|"REVOKE GRANT CONSTRAINT MANAGEMENT ON DATABASE * FROM `architect`" -|"REVOKE GRANT EXECUTE FUNCTION * ON DBMS FROM `PUBLIC`" -|"REVOKE GRANT EXECUTE PROCEDURE * ON DBMS FROM `PUBLIC`" -|"REVOKE GRANT INDEX MANAGEMENT ON DATABASE * FROM `admin`" -|"REVOKE GRANT INDEX MANAGEMENT ON DATABASE * FROM `architect`" -|"REVOKE GRANT MATCH {*} ON GRAPH * NODE * FROM `admin`" -|"REVOKE GRANT MATCH {*} ON GRAPH * NODE * FROM `architect`" -|"REVOKE GRANT MATCH {*} ON GRAPH * NODE * FROM `editor`" -|"REVOKE GRANT MATCH {*} ON GRAPH * NODE * FROM `publisher`" -|"REVOKE GRANT MATCH {*} ON GRAPH * NODE * FROM `reader`" -|"REVOKE GRANT MATCH {*} ON GRAPH * RELATIONSHIP * FROM `admin`" -|"REVOKE GRANT MATCH {*} ON GRAPH * RELATIONSHIP * FROM `architect`" -|"REVOKE GRANT MATCH {*} ON GRAPH * RELATIONSHIP * FROM `editor`" -|"REVOKE GRANT MATCH {*} ON GRAPH * RELATIONSHIP * FROM `publisher`" -|"REVOKE GRANT MATCH {*} ON GRAPH * RELATIONSHIP * FROM `reader`" -|"REVOKE GRANT NAME MANAGEMENT ON DATABASE * FROM `admin`" -|"REVOKE GRANT NAME MANAGEMENT ON DATABASE * FROM `architect`" -|"REVOKE GRANT NAME MANAGEMENT ON DATABASE * FROM `publisher`" -|"REVOKE GRANT START ON DATABASE * FROM `admin`" -|"REVOKE GRANT STOP ON DATABASE * FROM `admin`" -|"REVOKE GRANT TRANSACTION MANAGEMENT (*) ON DATABASE * FROM `admin`" -|"REVOKE GRANT WRITE ON GRAPH * FROM `admin`" -|"REVOKE GRANT WRITE ON GRAPH * FROM `architect`" -|"REVOKE GRANT WRITE ON GRAPH * FROM `editor`" -|"REVOKE GRANT WRITE ON GRAPH * FROM `publisher`" -a|Rows: 35 -|=== - -For more info about revoking privileges, please see xref::administration/access-control/manage-privileges.adoc#access-control-revoke-privileges[The REVOKE command]. - -[[access-control-list-privileges-role]] -=== Examples for listing privileges for specific roles - -Available privileges for specific roles can be displayed using `SHOW ROLE name PRIVILEGE[S]`: - -[source, syntax] ----- -SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - [WHERE expression] - -SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -[source, cypher, role=noplay] ----- -SHOW ROLE regularUsers PRIVILEGES ----- - -Lists all privileges for role `regularUsers`. - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m,m,m"] -|=== -|access -|action -|graph -|resource -|role -|segment -|immutable - -|"GRANTED" -|"access" -|"database" -|"neo4j" -|"database" -|"regularUsers" -|false - -7+a|Rows: 1 -|=== - -[source, cypher, role=noplay] ----- -SHOW ROLES regularUsers, noAccessUsers PRIVILEGES ----- - -Lists all privileges for roles `regularUsers` and `noAccessUsers`. - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m,m,m"] -|=== -|access -|action -|graph -|resource -|role -|segment -|immutable - -|"DENIED" -|"access" -|"database" -|"neo4j" -|"database" -|"noAccessUsers" -|false - -|"GRANTED" -|"access" -|"database" -|"neo4j" -|"database" -|"regularUsers" -|false - -7+a|Rows: 2 -|=== - -Similar to the other `SHOW PRIVILEGES` commands, the available privileges for roles can also be listed as Cypher commands with the optional `AS COMMAND[S]`. - -[source, cypher, role=noplay] ----- -SHOW ROLES regularUsers, noAccessUsers PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ACCESS ON DATABASE * TO `admin`" -|"GRANT ALL DBMS PRIVILEGES ON DBMS TO `admin`" -|"GRANT CONSTRAINT MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT INDEX MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT MATCH {*} ON GRAPH * NODE * TO `admin`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `admin`" -|"GRANT NAME MANAGEMENT ON DATABASE * TO `admin`" -|"GRANT START ON DATABASE * TO `admin`" -|"GRANT STOP ON DATABASE * TO `admin`" -|"GRANT TRANSACTION MANAGEMENT (*) ON DATABASE * TO `admin`" -|"GRANT WRITE ON GRAPH * TO `admin`" -a|Rows: 11 -|=== - -The output can be processed using `YIELD` / `WHERE` / `RETURN` here as well: - -[source, cypher, role=noplay] ----- -SHOW ROLE architect PRIVILEGES AS COMMANDS WHERE command CONTAINS 'MATCH' ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT MATCH {*} ON GRAPH * NODE * TO `architect`" -|"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `architect`" -|Rows: 2 -|=== - -Again, it is possible to get the privileges listed as revoking commands instead of granting or denying. -For more info about revoking privileges, please see xref::administration/access-control/manage-privileges.adoc#access-control-revoke-privileges[The REVOKE command]. - -[source, cypher, role=noplay] ----- -SHOW ROLE reader PRIVILEGES AS REVOKE COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"REVOKE GRANT ACCESS ON DATABASE * FROM `reader`" -|"REVOKE GRANT MATCH {*} ON GRAPH * NODE * FROM `reader`" -|"REVOKE GRANT MATCH {*} ON GRAPH * RELATIONSHIP * FROM `reader`" -a|Rows: 3 -|=== - -[[access-control-list-privileges-user]] -=== Examples for listing privileges for specific users - -Available privileges for specific users can be displayed using `SHOW USER name PRIVILEGES`. - -[NOTE] -==== -Note that if a non-native auth provider like LDAP is in use, `SHOW USER PRIVILEGES` will only work with a limited capacity as it is only possible for a user to show their own privileges. -Other users' privileges cannot be listed when using a non-native auth provider. -==== - -[source, syntax] ----- -SHOW USER[S] [name[, ...]] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - [WHERE expression] - -SHOW USER[S] [name[, ...]] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -[source, cypher, role=noplay] ----- -SHOW USER jake PRIVILEGES ----- - -Lists all privileges for user `jake`. - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m,m,m,m"] -|=== -|access -|action -|resource -|graph -|resource -|role -|segment -|immutable - -|"GRANTED" -|"execute" -|"database" -|"*" -|"FUNCTION(*)" -|"PUBLIC" -|"jake" -|false - -|"GRANTED" -|"execute" -|"database" -|"*" -|"PROCEDURE(*)" -|"PUBLIC" -|"jake" -|false - -|"GRANTED" -|"access" -|"database" -|"DEFAULT" -|"database" -|"PUBLIC" -|"jake" -|false - -|"GRANTED" -|"access" -|"database" -|"neo4j" -|"database" -|"regularUsers" -|"jake" -|false - -8+a|Rows: 4 -|=== - -[source, cypher, role=noplay] ----- -SHOW USERS jake, joe PRIVILEGES ----- - -Lists all privileges for users `jake` and `joe`. - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m,m,m,m"] -|=== -|access -|action -|resource -|graph -|resource -|role -|segment -|immutable - -|"GRANTED" -|"execute" -|"database" -|"*" -|"FUNCTION(*)" -|"PUBLIC" -|"jake" -|false - -|"GRANTED" -|"execute" -|"database" -|"*" -|"PROCEDURE(*)" -|"PUBLIC" -|"jake" -|false - -|"GRANTED" -|"access" -|"database" -|"DEFAULT" -|"database" -|"PUBLIC" -|"jake" -|false - -|"GRANTED" -|"access" -|"database" -|"neo4j" -|"database" -|"regularUsers" -|"jake" -|false - -|"GRANTED" -|"execute" -|"database" -|"*" -|"FUNCTION(*)" -|"PUBLIC" -|"joe" -|false - -|"GRANTED" -|"execute" -|"database" -|"*" -|"PROCEDURE(*)" -|"PUBLIC" -|"joe" -|false - -|"GRANTED" -|"access" -|"database" -|"DEFAULT" -|"database" -|"PUBLIC" -|"joe" -|false - -|"DENIED" -|"access" -|"database" -|"neo4j" -|"database" -|"noAccessUsers" -|"joe" -|false - -8+a|Rows: 8 -|=== - -The same command can be used at all times to review available privileges for the current user. -For this purpose, there is a shorter form of the command: `SHOW USER PRIVILEGES`: - -[source, cypher, role=noplay] ----- -SHOW USER PRIVILEGES ----- - -As for the other privilege commands, available privileges for users can also be listed as Cypher commands with the optional `AS COMMAND[S]`. - -[NOTE] -==== -When showing user privileges as commands, the roles in the Cypher commands are replaced with a parameter. -This can be used to quickly create new roles based on the privileges of specific users. -==== - -[source, cypher, role=noplay] ----- -SHOW USER jake PRIVILEGES AS COMMANDS ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"GRANT ACCESS ON DATABASE `neo4j` TO $role" -|"GRANT ACCESS ON HOME DATABASE TO $role" -|"GRANT EXECUTE FUNCTION * ON DBMS TO $role" -|"GRANT EXECUTE PROCEDURE * ON DBMS TO $role" -a|Rows: 4 -|=== - -Like other `SHOW` commands, the output can also be processed using `YIELD` / `WHERE` / `RETURN`. -Additionally, similar to the other show privilege commands, it is also possible to show the commands for revoking the privileges. - -[source, cypher, role=noplay] ----- -SHOW USER jake PRIVILEGES AS REVOKE COMMANDS -WHERE command CONTAINS 'EXECUTE' ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|command -|"REVOKE GRANT EXECUTE FUNCTION * ON DBMS FROM $role" -|"REVOKE GRANT EXECUTE PROCEDURE * ON DBMS FROM $role" -a|Rows: 2 -|=== - -[[access-control-revoke-privileges]] -== Revoking privileges - -Privileges that were granted or denied earlier can be revoked using the `REVOKE` command: - -[source, syntax] ----- -REVOKE - [ IMMUTABLE ] - [ GRANT | DENY ] graph-privilege - FROM role[, ...] ----- - -An example usage of the `REVOKE` command is given here: - -[source, cypher, role=noplay] ----- -REVOKE GRANT TRAVERSE ON HOME GRAPH NODES Post FROM regularUsers ----- - -While it can be explicitly specified that `REVOKE` should remove a `GRANT` or `DENY`, it is also possible to `REVOKE` both by not specifying them at all, as the next example demonstrates. -Because of this, if there happens to be a `GRANT` and a `DENY` for the same privilege, it would remove both. - -[source, cypher, role=noplay] ----- -REVOKE TRAVERSE ON HOME GRAPH NODES Payments FROM regularUsers ----- - -Adding `IMMUTABLE` explicitly specifies that only immutable privileges should be removed. Omitting it specifies that both immutable and regular privileges should be removed. diff --git a/modules/ROOT/pages/administration/access-control/manage-roles.adoc b/modules/ROOT/pages/administration/access-control/manage-roles.adoc deleted file mode 100644 index 1dd434cf1..000000000 --- a/modules/ROOT/pages/administration/access-control/manage-roles.adoc +++ /dev/null @@ -1,819 +0,0 @@ -:description: This section explains how to use Cypher to manage roles in Neo4j. - -[role=enterprise-edition aura-db-enterprise] -[[access-control-manage-roles]] -= Managing roles - -//// -[source, cypher, role=test-setup] ----- -CREATE USER bob SET PASSWORD 'abcd1234' CHANGE NOT REQUIRED; -CREATE USER user1 SET PASSWORD 'abcd1234' CHANGE NOT REQUIRED; -CREATE USER user2 SET PASSWORD 'abcd1234' CHANGE NOT REQUIRED; -CREATE USER user3 SET PASSWORD 'abcd1234' CHANGE NOT REQUIRED; -CREATE ROLE myrole IF NOT EXISTS; -CREATE ROLE role1 IF NOT EXISTS; -CREATE ROLE role2 IF NOT EXISTS; ----- -//// - -This page explains how to use Cypher to manage roles in Neo4j. - -Roles can be created and managed using a set of Cypher administration commands executed against the `system` database. - -When connected to the DBMS over `bolt`, administration commands are automatically routed to the `system` database. - - -[[access-control-role-syntax]] -== Role management command syntax - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -[cols="<15s,<85"] -|=== - -| Command -m| SHOW ROLES - -| Syntax -a| -[source, syntax, role="noheader"] ----- -SHOW [ALL\|POPULATED] ROLE[S] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| Description -a| -Lists roles. - -When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. - -For more information, see xref::administration/access-control/manage-roles.adoc#access-control-list-roles[Listing roles]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT SHOW ROLE ----- - - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]). -|=== - - -[cols="<15s,<85"] -|=== - -| Command -m| SHOW ROLES WITH USERS - -| Syntax -a| -[source, syntax, role="noheader"] ----- -SHOW [ALL\|POPULATED] ROLE[S] WITH USER[S] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| Description -a| -Lists roles and users assigned to them. - -When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. - -For more information, see xref::administration/access-control/manage-roles.adoc#access-control-list-roles[Listing roles]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT SHOW ROLE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - - -[source, privilege, role="noheader"] ----- -GRANT SHOW USER ----- - - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) - -|=== - - -[cols="<15s,<85"] -|=== - -| Command -m| SHOW ROLE PRIVILEGES - -| Syntax -a| -[source, syntax, role="noheader"] ----- -SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| Description -a| -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::administration/access-control/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT SHOW PRIVILEGE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges]) - -|=== - - -[cols="<15s,<85"] -|=== - - -| Command -m| CREATE ROLE - -| Syntax -a| -[source, syntax, role="noheader"] ----- -CREATE ROLE name [IF NOT EXISTS] [AS COPY OF otherName] ----- - -| Description -a| -Creates a new role. - -For more information, see xref::administration/access-control/manage-roles.adoc#access-control-create-roles[Creating roles]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT CREATE ROLE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - -|=== - -[cols="<15s,<85"] -|=== -| Command -m| CREATE OR REPLACE ROLE - -| Syntax -a| -[source, syntax, role="noheader"] ----- -CREATE OR REPLACE ROLE name [AS COPY OF otherName] ----- - -| Description -a| -Creates a new role, or if a role with the same name exists, replace it. - -For more information, see xref::administration/access-control/manage-roles.adoc#access-control-create-roles[Creating roles]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT CREATE ROLE ----- - -[source, privilege, role="noheader"] ----- -GRANT DROP ROLE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - -|=== - - -[cols="<15s,<85"] -|=== - -| Command -m| RENAME ROLE - -| Syntax -a| -[source, syntax, role="noheader"] ----- -RENAME ROLE name [IF EXISTS] TO otherName ----- - -| Description -a| -Changes the name of a role. - -For more information, see xref::administration/access-control/manage-roles.adoc#access-control-rename-roles[Renaming roles]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT RENAME ROLE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - -|=== - - -[cols="<15s,<85"] -|=== - -| Command -m| DROP ROLE - -| Syntax -a| -[source, syntax, role="noheader"] ----- -DROP ROLE name [IF EXISTS] ----- - -| Description -a| -Removes a role. - -For more information, see xref::administration/access-control/manage-roles.adoc#access-control-drop-roles[Deleting roles]. - -| Required privilege -[source, privilege, role="noheader"] ----- -GRANT DROP ROLE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - -|=== - - -[cols="<15s,<85"] -|=== - -| Command -m| GRANT ROLE TO - -| Syntax -a| -[source, syntax, role="noheader"] ----- -GRANT ROLE[S] name[, ...] TO user[, ...] ----- - -| Description -a| -Assigns roles to users. - -For more information, see xref::administration/access-control/manage-roles.adoc#access-control-assign-roles[Assigning roles to users]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT ASSIGN ROLE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - -|=== - - -[cols="<15s,<85"] -|=== - -| Command -m| REVOKE ROLE - -| Syntax -a| -[source, syntax, role="noheader"] ----- -REVOKE ROLE[S] name[, ...] FROM user[, ...] ----- - -| Description -a| -Removes roles from users. - -For more information, see xref::administration/access-control/manage-roles.adoc#access-control-revoke-roles[Revoking roles from users]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT REMOVE ROLE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - -|=== - - -[[access-control-list-roles]] -== Listing roles - - -Available roles can be seen using `SHOW ROLES`. -This returns a single column `role` of type `STRING`, containing the role name. - -[source, cypher, role=noplay] ----- -SHOW ROLES ----- - -This is the same command as `SHOW ALL ROLES`. - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|role - -|"PUBLIC" -|"admin" -|"architect" -|"editor" -|"publisher" -|"reader" - -1+a|Rows: 6 -|=== - -When first starting a Neo4j DBMS, there are a number of built-in roles: - -* `PUBLIC` - a role that all users have granted. -By default it gives access to the home database and to execute privileges for procedures and functions. -* `reader` - can perform traverse and read operations in all databases except `system`. -* `editor` - can perform traverse, read, and write operations in all databases except `system`, but cannot create new labels or relationship types. -* `publisher` - can do the same as `editor`, but also create new labels and relationship types. -* `architect` - can do the same as `publisher` as well as create and manage indexes and constraints. -* `admin` - can do the same as all the above, as well as manage databases, aliases, users, roles, and privileges. - -More information about the built-in roles can be found in link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/built-in-roles[Operations Manual -> Built-in roles] - -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. -Since this gives a result with one row for each user, if a role is assigned to two users it will show up twice. - -[source, cypher, role=noplay] ----- -SHOW POPULATED ROLES WITH USERS ----- - -The table of results will show information about the role and what database it belongs to: - -.Result -[options="header,footer", width="100%", cols="m,m"] -|=== -|role -|member - -|"PUBLIC" -|"neo4j" - -|"PUBLIC" -|"bob" - -|"PUBLIC" -|"user1" - -|"PUBLIC" -|"user2" - -|"PUBLIC" -|"user3" - -|"admin" -|"neo4j" - -2+a|Rows: 6 -|=== - -It is also possible to filter and sort the results by using `YIELD`, `ORDER BY` and `WHERE`: - -[source, cypher, role=noplay] ----- -SHOW ROLES YIELD role -ORDER BY role -WHERE role ENDS WITH 'r' ----- - -In this example: - -* The results have been filtered to only return the roles ending in 'r'. -* The results are ordered by the `action` column using `ORDER BY`. - -It is also possible to use `SKIP` and `LIMIT` to paginate the results. - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|role - -|"editor" -|"publisher" -|"reader" - -1+a|Rows: 3 -|=== - -[NOTE] -==== -The `SHOW ROLE name PRIVILEGES` command is found in xref::administration/access-control/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. -==== - - -[[access-control-create-roles]] -== Creating roles - -Roles can be created using `CREATE ROLE`: - -[source, syntax] ----- -CREATE ROLE name [IF NOT EXISTS] [AS COPY OF otherName] ----- - -Roles can be created or replaced by using `CREATE OR REPLACE ROLE`: - -[source, syntax] ----- -CREATE OR REPLACE ROLE name [AS COPY OF otherName] ----- - -[NOTE] -==== -The following naming rules apply: - -* The first character must be an ASCII alphabetic character. -* Subsequent characters can be ASCII alphabetic, numeric characters, and underscore. -* Role names are case sensitive. -==== - -A role can be copied, keeping its privileges, using `CREATE ROLE name AS COPY OF otherName`. - -.Copy a role -====== -[source, cypher, role=noplay] ----- -CREATE ROLE mysecondrole AS COPY OF myrole ----- -====== - -Created roles will appear on the list provided by `SHOW ROLES`. - -.List roles -====== -[source, cypher, role=noplay] ----- -SHOW ROLES ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|role - -|"PUBLIC" -|"admin" -|"architect" -|"editor" -|"myrole" -|"mysecondrole" -|"publisher" -|"reader" - -1+a|Rows: 8 -|=== -====== - -The `CREATE ROLE` command is optionally idempotent, with the default behavior to throw an exception if the role already exists. -Adding `IF NOT EXISTS` to the `CREATE ROLE` command will ensure that no exception is thrown and nothing happens should the role already exist. - -.Create role if not exists -====== - -[source, cypher, role=noplay] ----- -CREATE ROLE myrole IF NOT EXISTS ----- - -====== - - -The `CREATE OR REPLACE ROLE` command will result in any existing role being deleted and a new one created. - - -.Create or replace role -====== - -[source, cypher, role=noplay] ----- -CREATE OR REPLACE ROLE myrole ----- - -This is equivalent to running `DROP ROLE myrole IF EXISTS` followed by `CREATE ROLE myrole`. - -====== - - -[NOTE] -==== -* The `CREATE OR REPLACE ROLE` command does not allow you to use the `IF NOT EXISTS`. -==== - - -[[access-control-rename-roles]] -== Renaming roles - -Roles can be renamed using `RENAME ROLE` command: - -[source, cypher, role=noplay] ----- -RENAME ROLE mysecondrole TO mythirdrole ----- - -[source, cypher, role=noplay] ----- -SHOW ROLES ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|role - -|"PUBLIC" -|"admin" -|"architect" -|"editor" -|"myrole" -|"mythirdrole" -|"publisher" -|"reader" - -1+a|Rows: 8 -|=== - -[NOTE] -==== -The `RENAME ROLE` command is only available when using native authentication and authorization. -==== - - -[[access-control-assign-roles]] -== Assigning roles to users - -Users can be given access rights by assigning them roles using `GRANT ROLE`: - -[source, cypher, role=noplay] ----- -GRANT ROLE myrole TO bob ----- - -The roles assigned to each user can be seen on the list provided by `SHOW USERS`: - -[source, cypher, role=noplay] ----- -SHOW USERS ----- - -.Result -[options="header,footer", width="100%", cols="2m,3m,3m,2m,2m"] -|=== -|user -|roles -|passwordChangeRequired -|suspended -|home - -|"bob" -|["myrole","PUBLIC"] -|false -|false -| - -|"neo4j" -|["admin","PUBLIC"] -|true -|false -| - -|"user1" -|["PUBLIC"] -|true -|false -| - -|"user2" -|["PUBLIC"] -|true -|false -| - -|"user3" -|["PUBLIC"] -|true -|false -| - -5+a|Rows: 5 -|=== - -It is possible to assign multiple roles to multiple users in one command: - -[source, cypher, role=noplay] ----- -GRANT ROLES role1, role2 TO user1, user2, user3 ----- - -[source, cypher, role=noplay] ----- -SHOW USERS ----- - -.Result -[options="header,footer", width="100%", cols="2m,3m,3m,2m,2m"] -|=== -|user -|roles -|passwordChangeRequired -|suspended -|home - -|"bob" -|["myrole","PUBLIC"] -|false -|false -| - -|"neo4j" -|["admin","PUBLIC"] -|true -|false -| - -|"user1" -|["role1","role2","PUBLIC"] -|true -|false -| - -|"user2" -|["role1","role2","PUBLIC"] -|true -|false -| - -|"user3" -|["role1","role2","PUBLIC"] -|true -|false -| - -5+a|Rows: 5 -|=== - -Common errors, such as attempts to grant roles to users who have already been granted those roles, will lead to notifications. -Some of these notifications may be replaced with errors in a future major version of Neo4j. -See link:{neo4j-docs-base-uri}/status-codes/{page-version}/notifications/all-notifications[Status Codes -> Notification codes] for details on notifications. - -[[access-control-revoke-roles]] -== Revoking roles from users - -Users can lose access rights by revoking their role using `REVOKE ROLE`: - -[source, cypher, role=noplay] ----- -REVOKE ROLE myrole FROM bob ----- - -The roles revoked from users can no longer be seen on the list provided by `SHOW USERS`: - -[source, cypher, role=noplay] ----- -SHOW USERS ----- - -.Result -[options="header,footer", width="100%", cols="2m,3m,3m,2m,2m"] -|=== -|user -|roles -|passwordChangeRequired -|suspended -|home - -|"bob" -|["PUBLIC"] -|false -|false -| - -|"neo4j" -|["admin","PUBLIC"] -|true -|false -| - -|"user1" -|["role1","role2","PUBLIC"] -|true -|false -| - -|"user2" -|["role1","role2","PUBLIC"] -|true -|false -| - -|"user3" -|["role1","role2","PUBLIC"] -|true -|false -| - -5+a|Rows: 5 -|=== - -It is possible to revoke multiple roles from multiple users in one command: - -[source, cypher, role=noplay] ----- -REVOKE ROLES role1, role2 FROM user1, user2, user3 ----- - -Common errors, such as misspellings or attempts to revoke roles from users who have not been granted those roles, will lead to notifications. -Some of these notifications may be replaced with errors in a future major version of Neo4j. -See link:{neo4j-docs-base-uri}/status-codes/{page-version}/notifications/all-notifications[Status Codes -> Notification codes] for details on notifications. - -[[access-control-drop-roles]] -== Deleting roles - -Roles can be deleted using `DROP ROLE` command: - -[source, cypher, role=noplay] ----- -DROP ROLE mythirdrole ----- - -When a role has been deleted, it will no longer appear on the list provided by `SHOW ROLES`: - -[source, cypher, role=noplay] ----- -SHOW ROLES ----- - -.Result -[options="header,footer", width="100%", cols="m"] -|=== -|role - -|"PUBLIC" -|"admin" -|"architect" -|"editor" -|"myrole" -|"publisher" -|"reader" - -1+a|Rows: 8 -|=== - -This command is optionally idempotent, with the default behavior to throw an exception if the role does not exist. -Adding `IF EXISTS` to the command will ensure that no exception is thrown and nothing happens should the role not exist: - -[source, cypher, role=noplay] ----- -DROP ROLE mythirdrole IF EXISTS ----- diff --git a/modules/ROOT/pages/administration/access-control/manage-users.adoc b/modules/ROOT/pages/administration/access-control/manage-users.adoc deleted file mode 100644 index f53f432c8..000000000 --- a/modules/ROOT/pages/administration/access-control/manage-users.adoc +++ /dev/null @@ -1,865 +0,0 @@ -:description: This section explains how to use Cypher to manage users in Neo4j. - -[[access-control-manage-users]] -= Managing users - -This page explains how to use Cypher to manage users in Neo4j. - -Users can be created and managed using a set of Cypher administration commands executed against the `system` database. -When connected to the DBMS over `bolt`, administration commands are automatically routed to the `system` database. - -[[access-control-user-syntax]] -== User management command syntax - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -[cols="<15s,<85"] -|=== - -| Command -m| SHOW CURRENT USER - -| Syntax -a| -[source, syntax, role="noheader"] ----- -SHOW CURRENT USER - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| Description -a| -Lists the current user. - -When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. - -For more information, see xref::administration/access-control/manage-users.adoc#access-control-current-users[Listing current user]. - -| Required privilege -a| None - -|=== - - -[cols="<15s,<85"] -|=== - -| Command -m| SHOW USERS - -| Syntax -a| -[source, syntax, role="noheader"] ----- -SHOW USER[S] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| Description -a| -Lists all users. - -When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. - -For more information, see xref::administration/access-control/manage-users.adoc#access-control-list-users[Listing users]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT SHOW USER ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) - -|=== - - -[cols="<15s,<85"] -|=== -| Command -m| SHOW USER PRIVILEGES - -| Syntax -a| -[source, syntax, role="noheader"] ----- -SHOW USER[S] [name[, ...]] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| Description -a| -Lists the privileges granted to the specified users or the current user if no user is specified. - -When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. - -For more information, see xref::administration/access-control/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT SHOW PRIVILEGE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges]) - -[source, privilege, role="noheader"] ----- -GRANT SHOW USER ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) -|=== - - -[cols="<15s,<85"] -|=== -| Command -m| CREATE USER - -| Syntax -a| -[source, syntax, role="noheader"] ----- -CREATE USER name [IF NOT EXISTS] - SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE \| SUSPENDED}] - [SET HOME DATABASE name] ----- - -| Description -a| -Creates a new user. - -For more information, see xref::administration/access-control/manage-users.adoc#access-control-create-users[Creating users]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT CREATE USER ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) - -|=== - -[cols="<15s,<85"] -|=== -| Command -m| CREATE OR REPLACE USER - -| Syntax -a| -[source, syntax, role="noheader"] ----- -CREATE OR REPLACE USER name - SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password' - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE \| SUSPENDED}] - [SET HOME DATABASE name] ----- - -| Description -a| -Creates a new user, or if a user with the same name exists, replace it. - -For more information, see xref::administration/access-control/manage-users.adoc#access-control-create-users[Creating users]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT CREATE USER ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) - - -[source, privilege, role="noheader"] ----- -GRANT DROP USER ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) - -|=== - -[cols="<15s,<85"] -|=== -| Command -m| RENAME USER - -| Syntax -a| -[source, syntax, role="noheader"] ----- -RENAME USER name [IF EXISTS] TO otherName ----- - -| Description -a| -Changes the name of a user. - -For more information, see xref::administration/access-control/manage-users.adoc#access-control-rename-users[Renaming users]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT RENAME USER ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) - -|=== - -[cols="<15s,<85"] -|=== -| Command -m| ALTER USER - -| Syntax -a| -[source, syntax, role="noheader"] ----- -ALTER USER name [IF EXISTS] - [SET [PLAINTEXT \| ENCRYPTED] PASSWORD 'password'] - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE \| SUSPENDED} ] - [SET HOME DATABASE name] - [REMOVE HOME DATABASE] ----- - -| Description -a| -Modifies the settings for an existing user. -At least one `SET` or `REMOVE` clause is required. -`SET` and `REMOVE` clauses cannot be combined in the same command. - -For more information, see xref::administration/access-control/manage-users.adoc#access-control-alter-users[Modifying users]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT SET PASSWORD ----- - -[source, privilege, role="noheader" ----- -GRANT SET USER STATUS ----- - -[source, privilege, role="noheader"] ----- -GRANT SET USER HOME DATABASE ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) - -|=== - - -[cols="<15s,<85"] -|=== - -| Command -m| ALTER CURRENT USER SET PASSWORD - -| Syntax -a| -[source, syntax, role="noheader"] ----- -ALTER CURRENT USER SET PASSWORD FROM 'oldPassword' TO 'newPassword' ----- - -| Description -a| -Changes the current user's password. - -This command auto-commits even when executed inside an explicit transaction. label:new[Introduced in 5.11] - -For more information, see xref::administration/access-control/manage-users.adoc#access-control-alter-password[Changing the current user's password]. - -| Required privilege -a| None - -|=== - - -[cols="<15s,<85"] -|=== - -| Command -m| DROP USER - -| Syntax -a| -[source, syntax, role="noheader"] ----- -DROP USER name [IF EXISTS] ----- - -| Description -a| -Removes an existing user. - -For more information, see xref::administration/access-control/manage-users.adoc#access-control-drop-users[Delete users]. - -| Required privilege -a| -[source, privilege, role="noheader"] ----- -GRANT DROP USER ----- - -(see xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) - -|=== - - -[NOTE] -==== -The `SHOW USER[S] PRIVILEGES` command is only available in Neo4j Enterprise Edition. label:enterprise-edition[] -==== - - -[[access-control-current-users]] -== Listing current user - -The currently logged-in user can be seen using `SHOW CURRENT USER`, which will produce a table with the following columns: - -[options="header", width="100%", cols="2a,4,2m,^.^,^.^"] -|=== -| Column -| Description -| Type -| Community Edition -| Enterprise Edition - -| user -| User name -| STRING -| {check-mark} -| {check-mark} - -| roles -| Roles granted to the user. - -Will return `null` in community edition. -| LIST -| {cross-mark} -| {check-mark} - -| passwordChangeRequired -| If `true`, the user must change their password at the next login. -| BOOLEAN -| {check-mark} -| {check-mark} - -| suspended -| If `true`, the user is currently suspended (cannot log in). - -Will return `null` in community edition. -| BOOLEAN -| {cross-mark} -| {check-mark} - -| home -| The home database configured by the user, or `null` if no home database has been configured. -If this database is unavailable and the user does not specify a database to use, they will not be able to log in. - -Will return `null` in community edition. -| STRING -| {cross-mark} -| {check-mark} -|=== - -[source, cypher, role=noplay] ----- -SHOW CURRENT USER ----- - -.Result -[options="header,footer", width="100%", cols="2m,2m,3m,2m,2m"] -|=== -|user -|roles -|passwordChangeRequired -|suspended -|home - -|"jake" -|["PUBLIC"] -|false -|false -| - -5+a|Rows: 1 -|=== - -[NOTE] -==== -This command is only supported for a logged-in user and will return an empty result if authorization has been disabled. -==== - - -[[access-control-list-users]] -== Listing users - -Available users can be seen using `SHOW USERS`, which will produce a table of users with the following columns: - -[options="header", width="100%", cols="2a,4,2m,^.^,^.^"] -|=== -| Column -| Description -| Type -| Community Edition -| Enterprise Edition - -| user -| User name -| STRING -| {check-mark} -| {check-mark} - -| roles -| Roles granted to the user. - -Will return `null` in community edition. -| LIST -| {cross-mark} -| {check-mark} - -| passwordChangeRequired -| If `true`, the user must change their password at the next login. -| BOOLEAN -| {check-mark} -| {check-mark} - -| suspended -| If `true`, the user is currently suspended (cannot log in). - -Will return `null` in community edition. -| BOOLEAN -| {cross-mark} -| {check-mark} - -| home -| The home database configured by the user, or `null` if no home database has been configured. -A home database will be resolved if it is either pointing to a database or a database alias. -If this database is unavailable and the user does not specify a database to use, they will not be able to log in. - -Will return `null` in community edition. -| STRING -| {cross-mark} -| {check-mark} -|=== - -[source, cypher, role=noplay] ----- -SHOW USERS ----- - -.Result -[role="queryresult" options="header,footer", width="100%", cols="2m,3m,3m,2m,2m"] -|=== -|user -|roles -|passwordChangeRequired -|suspended -|home - -|"neo4j" -|["admin","PUBLIC"] -|false -|false -| - -5+a|Rows: 1 -|=== - -When first starting a Neo4j DBMS, there is always a single default user `neo4j` with administrative privileges. -It is possible to set the initial password using link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/set-initial-password[`neo4j-admin dbms set-initial-password `], otherwise it is necessary to change the password after the first login. - -.Show user -====== -This example shows how to: - -* Reorder the columns using a `YIELD` clause. -* Filter the results using a `WHERE` clause. - -[source, cypher, role=noplay] ----- -SHOW USER YIELD user, suspended, passwordChangeRequired, roles, home -WHERE user = 'jake' ----- -====== - -.Show user -====== -It is possible to add a `RETURN` clause to further manipulate the results after filtering. -In this example, the `RETURN` clause is used to filter out the `roles` column and rename the `user` column to `adminUser`. - -[source,cypher,role=noplay] ----- -SHOW USERS YIELD roles, user -WHERE 'admin' IN roles -RETURN user AS adminUser ----- -====== - -[NOTE] -==== -The `SHOW USER name PRIVILEGES` command is described in xref::administration/access-control/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. -==== - - -[[access-control-create-users]] -== Creating users - -Users can be created using `CREATE USER`. - -[source, syntax, role="noheader"] ----- -CREATE USER name [IF NOT EXISTS] - SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password' - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE | SUSPENDED}] - [SET HOME DATABASE name] ----- - -Users can be created or replaced using `CREATE OR REPLACE USER`. - -[source, syntax, role="noheader"] ----- -CREATE OR REPLACE USER name - SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password' - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE | SUSPENDED}] - [SET HOME DATABASE name] ----- - -* For `SET PASSWORD`: -** The `password` can either be a string value or a string parameter. -** The default Neo4j password length is at least 8 characters. -** All passwords are encrypted (hashed) when stored in the Neo4j `system` database. -`PLAINTEXT` and `ENCRYPTED` just refer to the format of the password in the Cypher command, i.e. whether Neo4j needs to hash it or it has already been hashed. -Consequently, it is never possible to get the plaintext of a password back out of the database. -A password can be set in either fashion at any time. -** The optional `PLAINTEXT` in `SET PLAINTEXT PASSWORD` has the same behavior as `SET PASSWORD`. -** The optional `ENCRYPTED` is used to recreate an existing user when the plaintext password is unknown, but the encrypted password is available in the _data/scripts/databasename/restore_metadata.cypher_ file of a database backup. -See link:{neo4j-docs-base-uri}/operations-manual/{page-version}/backup-restore/restore-backup#restore-backup-example[Operations Manual -> Restore a database backup -> Example]. + -With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: -*** `0` is the first version and refers to the `SHA-256` cryptographic hash function with iterations `1`. -*** `1` is the second version and refers to the `SHA-256` cryptographic hash function with iterations `1024`. -* If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted, the default is `CHANGE REQUIRED`. -The `SET PASSWORD` part is only optional if it directly follows the `SET PASSWORD` clause. -* The default for `SET STATUS` is `ACTIVE`. -* `SET HOME DATABASE` can be used to configure a home database for a user. -A home database will be resolved if it is either pointing to a database or a database alias. -If no home database is set, the DBMS default database is used as the home database for the user. -* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, and `SET HOME DATABASE` clauses can be applied in any order. - -[NOTE] -==== -User names are case sensitive. -The created user will appear on the list provided by `SHOW USERS`. - -* In Neo4j Community Edition there are no roles, but all users have implied administrator privileges. -* In Neo4j Enterprise Edition all users are automatically assigned the xref::administration/access-control/built-in-roles.adoc#access-control-built-in-roles-public[`PUBLIC` role], giving them a base set of privileges. -==== - - -.Create user -====== -For example, you can create the user `jake` in a suspended state, with the home database `anotherDb`, and the requirement to change the password by using the command: - -[source,cypher,role=noplay] ----- -CREATE USER jake -SET PASSWORD 'abcd1234' CHANGE REQUIRED -SET STATUS SUSPENDED -SET HOME DATABASE anotherDb ----- - -====== - - -.Create user -====== -Or you can create the user `Jake` in an active state, with an encrypted password (taken from the _data/scripts/databasename/restore_metadata.cypher_ of a database backup), and the requirement to not change the password by running: - -[source,cypher,role=noplay] ----- -CREATE USER Jake -SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff2a55c5b825,190ae47c661e0668a0c8be8a21ff78a4a34cdf918cae3c407e907b73932bd16c' CHANGE NOT REQUIRED -SET STATUS ACTIVE ----- - -====== - -[NOTE] -==== -The `SET STATUS {ACTIVE | SUSPENDED}` and `SET HOME DATABASE` parts of the commands are only available in Neo4j Enterprise Edition. label:enterprise-edition[] -==== - -The `CREATE USER` command is optionally idempotent, with the default behavior to throw an exception if the user already exists. -Appending `IF NOT EXISTS` to the `CREATE USER` command will ensure that no exception is thrown and nothing happens should the user already exist. - - -.Create user if not exists -====== -[source,cypher,role=noplay] ----- -CREATE USER jake IF NOT EXISTS -SET PLAINTEXT PASSWORD 'abcd1234' ----- - -====== - -The `CREATE OR REPLACE USER` command will result in any existing user being deleted and a new one created. - - -.Create or replace user -====== -[source,cypher,role=noplay] ----- -CREATE OR REPLACE USER jake -SET PLAINTEXT PASSWORD 'abcd1234' ----- - -This is equivalent to running `DROP USER jake IF EXISTS` followed by `CREATE USER jake SET PASSWORD 'abcd1234'`. - -====== - -[NOTE] -==== -The `CREATE OR REPLACE USER` command does not allow the use of `IF NOT EXISTS`. -==== - - -[[access-control-rename-users]] -== Renaming users - -Users can be renamed with the `RENAME USER` command. - -[source, cypher, role=noplay] ----- -RENAME USER jake TO bob ----- - -[source, cypher, role=noplay] ----- -SHOW USERS ----- - -.Result -[options="header,footer", width="100%", cols="2m,3m,3m,2m,2m"] -|=== -|user |roles |passwordChangeRequired |suspended |home - -|"bob" -|["PUBLIC"] -|true -|false -| - -|"neo4j" -|["admin","PUBLIC"] -|true -|false -| - -5+a|Rows: 2 - -|=== - -[NOTE] -==== -The `RENAME USER` command is only available when using native authentication and authorization. -==== - - -[[access-control-alter-users]] -== Modifying users - -Users can be modified with `ALTER USER`. - -[source, syntax, role="noheader"] ----- -ALTER USER name [IF EXISTS] - [SET [PLAINTEXT | ENCRYPTED] PASSWORD 'password'] - [[SET PASSWORD] CHANGE [NOT] REQUIRED] - [SET STATUS {ACTIVE | SUSPENDED}] - [SET HOME DATABASE name] - [REMOVE HOME DATABASE name] ----- - -* At least one `SET` or `REMOVE` clause is required for the command. -* `SET` and `REMOVE` clauses cannot be combined in the same command. -* The `SET PASSWORD CHANGE [NOT] REQUIRED`, `SET STATUS`, and `SET HOME DATABASE` clauses can be applied in any order. -The `SET PASSWORD` clause must come first, if used. -* For `SET PASSWORD`: -** The `password` can either be a string value or a string parameter. -** All passwords are encrypted (hashed) when stored in the Neo4j `system` database. -`PLAINTEXT` and `ENCRYPTED` just refer to the format of the password in the Cypher command, i.e. whether Neo4j needs to hash it or it has already been hashed. -Consequently, it is never possible to get the plaintext of a password back out of the database. -A password can be set in either fashion at any time. -** The optional `PLAINTEXT` in `SET PLAINTEXT PASSWORD` has the same behavior as `SET PASSWORD`. -** The optional `ENCRYPTED` is used to update an existing user's password when the plaintext password is unknown, but the encrypted password is available in the _data/scripts/databasename/restore_metadata.cypher_ file of a database backup. -See link:{neo4j-docs-base-uri}/operations-manual/{page-version}/backup-restore/restore-backup#restore-backup-example[Operations Manual -> Restore a database backup -> Example]. + -With `ENCRYPTED`, the password string is expected to be in the format of `,,`, where, for example: -*** `0` is the first version and refers to the `SHA-256` cryptographic hash function with iterations `1`. -*** `1` is the second version and refers to the `SHA-256` cryptographic hash function with iterations `1024`. -* If the optional `SET PASSWORD CHANGE [NOT] REQUIRED` is omitted, the default is `CHANGE REQUIRED`. -The `SET PASSWORD` part is only optional if it directly follows the `SET PASSWORD` clause. -* For `SET PASSWORD CHANGE [NOT] REQUIRED`, the `SET PASSWORD` is only optional if it directly follows the `SET PASSWORD` clause. -* `SET HOME DATABASE` can be used to configure a home database for a user. -A home database will be resolved if it is either pointing to a database or a database alias. -If no home database is set, the DBMS default database is used as the home database for the user. -* `REMOVE HOME DATABASE` is used to unset the home database for a user. -This results in the DBMS default database being used as the home database for the user. - -For example, you can modify the user `bob` with a new password and active status, and remove the requirement to change his password: - -[source, cypher, role=noplay] ----- -ALTER USER bob -SET PASSWORD 'abcd5678' CHANGE NOT REQUIRED -SET STATUS ACTIVE ----- - -Or you may decide to assign the user `bob` a different home database: - -[source, cypher, role=noplay] ----- -ALTER USER bob -SET HOME DATABASE anotherDbOrAlias ----- - -Or remove the home database from the user `bob`: - -[source, cypher, role=noplay] ----- -ALTER USER bob -REMOVE HOME DATABASE ----- - -[NOTE] -==== -When altering a user, it is only necessary to specify the changes required. -For example, leaving out the `CHANGE [NOT] REQUIRED` part of the query will leave that unchanged. -==== - -[NOTE] -==== -The `SET STATUS {ACTIVE | SUSPENDED}`, `SET HOME DATABASE`, and `REMOVE HOME DATABASE` parts of the command are only available in Neo4j Enterprise Edition. label:enterprise-edition[] -==== - -The changes to the user will appear on the list provided by `SHOW USERS`: - -[source, cypher, role=noplay] ----- -SHOW USERS ----- - -.Result -[options="header,footer", width="100%", cols="2m,3m,3m,2m,2m"] -|=== -|user |roles |passwordChangeRequired |suspended |home - -|"bob" -|["PUBLIC"] -|false -|false -| - -|"neo4j" -|["admin","PUBLIC"] -|true -|false -| - -5+a|Rows: 2 - -|=== - -The default behavior of this command is to throw an exception if the user does not exist. -Adding an optional parameter `IF EXISTS` to the command makes it idempotent and ensures that no exception is thrown. -Nothing happens should the user not exist. - -[source, cypher, role=noplay] ----- -ALTER USER nonExistingUser IF EXISTS SET PASSWORD 'abcd1234' ----- - - -[[access-control-alter-password]] -== Changing the current user's password - -Users can change their password using `ALTER CURRENT USER SET PASSWORD`. -The old password is required in addition to the new one, and either or both can be a string value or a string parameter. -When a user executes this command it will change their password as well as set the `CHANGE NOT REQUIRED` flag. - -// can't test, don't want to hardcode test user password -[source, cypher, role=test-skip] ----- -ALTER CURRENT USER -SET PASSWORD FROM 'password1' TO 'password2' ----- - -As of Neo4j 5.11, this command auto-commits even when executed inside an explicit transaction. - -[NOTE] -==== -This command works only for a logged-in user and cannot be run with auth disabled. -==== - - -[[access-control-drop-users]] -== Delete users - -Users can be deleted with `DROP USER`. - -[source, cypher, role=noplay] ----- -DROP USER bob ----- - -Deleting a user will not automatically terminate associated connections, sessions, transactions, or queries. - -However, when a user has been deleted, it will no longer appear on the list provided by `SHOW USERS`: - -[source, cypher, role=noplay] ----- -SHOW USERS ----- - -.Result -[options="header,footer", width="100%", cols="2m,3m,3m,2m,2m"] -|=== -|user |roles |passwordChangeRequired |suspended |home - -|"neo4j" -|["admin","PUBLIC"] -|true -|false -| - -5+a|Rows: 1 - -|=== diff --git a/modules/ROOT/pages/administration/access-control/privileges-immutable.adoc b/modules/ROOT/pages/administration/access-control/privileges-immutable.adoc deleted file mode 100644 index 6ab3965af..000000000 --- a/modules/ROOT/pages/administration/access-control/privileges-immutable.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[role=enterprise-edition not-on-aura] -[[access-control-privileges-immutable]] -= Immutable privileges -:description: This section explains how to use Cypher to manage immutable privileges. - -Unlike regular privileges, having xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[privilege management] privileges is not sufficient to enable immutable privileges to be added or removed. They can only be administered when auth is disabled -- that is, when the configuration setting <> is set to `false`. - -[[access-control-privileges-immutable-usecase]] -== When to use immutable privileges - -Immutable privileges are useful for restricting the actions of users who themselves are able to xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[administer privileges]. - -For example, you may want to prevent all users from performing Database Management, even the `admin` user (who are themselves able to add or remove privileges). -To do so, you could run: - -[source, cypher] ----- -DENY DATABASE MANAGEMENT ON DBMS TO PUBLIC ----- - -However, this would not be adequate. -In case the `admin` user subsequently runs this: - -[source, cypher] ----- -REVOKE DENY DATABASE MANAGEMENT ON DBMS FROM PUBLIC ----- - -They would effectively regain Database Management privileges. -Instead, run the following query to prevent this scenario: - -[source, cypher, role=test-skip] ----- -DENY IMMUTABLE DATABASE MANAGEMENT ON DBMS TO PUBLIC ----- - - -[[access-control-privileges-immutable-admin]] -== How to administer immutable privileges - -Immutable privileges can only be administered when auth is disabled -- that is, when the configuration setting <> is set to `false`, for example. -Under these conditions, immutable privileges can be added and removed in a similar manner to regular privileges, using the `IMMUTABLE` keyword. - -See the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/tutorial/tutorial-immutable-privileges[Immutable privileges tutorial] for examples of how to administer immutable privileges. - -See xref:administration/access-control/manage-privileges.adoc[Managing Privileges] for more detail on syntax. diff --git a/modules/ROOT/pages/administration/access-control/privileges-reads.adoc b/modules/ROOT/pages/administration/access-control/privileges-reads.adoc deleted file mode 100644 index c8eb731a8..000000000 --- a/modules/ROOT/pages/administration/access-control/privileges-reads.adoc +++ /dev/null @@ -1,187 +0,0 @@ -:description: How to use Cypher to manage read privileges on graphs. - -//// -[source, cypher, role=test-setup] ----- -CREATE ROLE regularUsers; ----- -//// - -[role=enterprise-edition aura-db-enterprise] -[[access-control-privileges-reads]] -= Read privileges - - -This page explains how to use Cypher to manage read privileges on graphs. - -There are three separate read privileges: - -* xref::administration/access-control/privileges-reads.adoc#access-control-privileges-reads-traverse[`TRAVERSE`] - enables the specified entities to be found. -* xref::administration/access-control/privileges-reads.adoc#access-control-privileges-reads-read[`READ`] - enables the specified properties of the found entities to be read. -* xref::administration/access-control/privileges-reads.adoc#access-control-privileges-reads-match[`MATCH`] - combines both `TRAVERSE` and `READ`, enabling an entity to be found and its properties read. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -[[access-control-privileges-reads-traverse]] -== The `TRAVERSE` privilege - -Users can be granted the right to find nodes and relationships using the `GRANT TRAVERSE` privilege. - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] TRAVERSE - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, we can enable users with the role `regularUsers` to find all nodes with the label `Post` in the database `neo4j`: - -[source, cypher, role=noplay] ----- -GRANT TRAVERSE ON GRAPH neo4j NODES Post TO regularUsers ----- - -The `TRAVERSE` privilege can also be denied. - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] TRAVERSE - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, we can disable users with the role `regularUsers` from finding all nodes with the label `Payments`: - -[source, cypher, role=noplay] ----- -DENY TRAVERSE ON HOME GRAPH NODES Payments TO regularUsers ----- - - -[[access-control-privileges-reads-read]] -== The `READ` privilege - -Users can be granted the right to do property reads on nodes and relationships using the `GRANT READ` privilege. -It is very important to note that users can only read properties on entities that they are enabled to find in the first place. - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] READ "{" { * | property[, ...] } "}" - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, we can enable user with the role `regularUsers` to read all properties on nodes with the label `Post` in the database `neo4j`. -The `+*+` implies that the ability to read all properties also extends to properties that might be added in the future. - -[source, cypher, role=noplay] ----- -GRANT READ { * } ON GRAPH neo4j NODES Post TO regularUsers ----- - -[NOTE] -==== -Granting property `READ` access does not imply that the entities with that property can be found. -For example, if there is also a `DENY TRAVERSE` present on the same entity as a `GRANT READ`, the entity will not be found by a Cypher `MATCH` statement. -==== - -The `READ` privilege can also be denied. - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] READ "{" { * | property[, ...] } "}" - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -Although we just granted the role `regularUsers` the right to read all properties, we may want to hide the `secret` property. -The following example shows how to do that: - -[source, cypher, role=noplay] ----- -DENY READ { secret } ON GRAPH neo4j NODES Post TO regularUsers ----- - - -[[access-control-privileges-reads-match]] -== The `MATCH` privilege - -Users can be granted the right to find and do property reads on nodes and relationships using the `GRANT MATCH` privilege. -This is semantically the same as having both `TRAVERSE` and `READ` privileges. - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] MATCH "{" { * | property[, ...] } "}" - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example if you want to grant the ability to read the properties `language` and `length` for nodes with the label `Message`, as well as the ability to find these nodes to the role `regularUsers`, you can use the following `GRANT MATCH` query: - -[source, cypher, role=noplay] ----- -GRANT MATCH { language, length } ON GRAPH neo4j NODES Message TO regularUsers ----- - -Like all other privileges, the `MATCH` privilege can also be denied. - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] MATCH "{" { * | property[, ...] } "}" - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -Please note that the effect of denying a `MATCH` privilege depends on whether concrete property keys are specified or are `+*+`. -If you specify concrete property keys, then `DENY MATCH` will only deny reading those properties. -Finding the elements to traverse would still be enabled. -If you specify `+*+` instead, then both traversal of the element and all property reads will be disabled. -The following queries will show examples for this. - -Denying to read the property `content` on nodes with the label `Message` for the role `regularUsers` would look like the following query. -Although not being able to read this specific property, nodes with that label can still be traversed (and, depending on other grants, other properties on it could still be read). - -[source, cypher, role=noplay] ----- -DENY MATCH { content } ON GRAPH neo4j NODES Message TO regularUsers ----- - -The following query exemplifies how it would look if you wanted to deny both reading all properties and traversing nodes labeled with `Account` in the database `neo4j`: - -[source, cypher, role=noplay] ----- -DENY MATCH { * } ON GRAPH neo4j NODES Account TO regularUsers ----- diff --git a/modules/ROOT/pages/administration/access-control/privileges-writes.adoc b/modules/ROOT/pages/administration/access-control/privileges-writes.adoc deleted file mode 100644 index aef0fb916..000000000 --- a/modules/ROOT/pages/administration/access-control/privileges-writes.adoc +++ /dev/null @@ -1,404 +0,0 @@ -:description: How to use Cypher to manage write privileges on graphs. - -//// -[source, cypher, role=test-setup] ----- -CREATE ROLE regularUsers; ----- -//// - -[role=enterprise-edition aura-db-enterprise] -[[access-control-privileges-writes]] -= Write privileges - -This page explains how to use Cypher to manage write privileges on graphs. - -Write privileges are defined for different parts of the graph: - -* xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-create[`CREATE`] - allows creating nodes and relationships. -* xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-delete[`DELETE`] - allows deleting nodes and relationships. -* xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-set-label[`SET LABEL`] - allows setting the specified node labels using the `SET` clause. -* xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-remove-label[`REMOVE LABEL`] - allows removing the specified node labels using the `REMOVE` clause. -* xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-set-property[`SET PROPERTY`] - allows setting properties on nodes and relationships. - -There are also compound privileges which combine the above specific privileges: - -* xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-merge[`MERGE`] - allows `MATCH`, `CREATE` and `SET PROPERTY` to apply the `MERGE` command. -* xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-write[`WRITE`] - allows all `WRITE` operations on an entire graph. -* xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-all[`ALL GRAPH PRIVILEGES`] - allows all `READ` and `WRITE` operations on an entire graph. - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -[[access-control-privileges-writes-create]] -== The `CREATE` privilege - -The `CREATE` privilege allows a user to create new node and relationship elements on a graph. -See the Cypher xref::clauses/create.adoc[CREATE] clause. - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] CREATE - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to `CREATE` elements on the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT CREATE ON GRAPH neo4j ELEMENTS * TO regularUsers ----- - -The `CREATE` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] CREATE - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, to deny the role `regularUsers` the ability to `CREATE` nodes with the label `foo` on all graphs, use: - -[source, cypher, role=noplay] ----- -DENY CREATE ON GRAPH * NODES foo TO regularUsers ----- - -[NOTE] -==== -If the user attempts to create nodes with a label that does not already exist on the database, then the user must also possess the xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW LABEL] privilege. -The same applies to new relationships: the xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW RELATIONSHIP TYPE] privilege is required. -==== - - -[[access-control-privileges-writes-delete]] -== The `DELETE` privilege - -The `DELETE` privilege allows a user to delete node and relationship elements on a graph. -See the Cypher xref::clauses/delete.adoc[DELETE] clause. - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] DELETE - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to `DELETE` elements on the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT DELETE ON GRAPH neo4j ELEMENTS * TO regularUsers ----- - -The `DELETE` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] DELETE - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, to deny the role `regularUsers` the ability to `DELETE` relationships with the relationship type `bar` on all graphs, use: - -[source, cypher, role=noplay] ----- -DENY DELETE ON GRAPH * RELATIONSHIPS bar TO regularUsers ----- - -[NOTE] -==== -Users with `DELETE` privilege, but restricted `TRAVERSE` privileges, will not be able to do `DETACH DELETE` in all cases. -See link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/access-control#detach-delete-restricted-user[Operations Manual -> Fine-grained access control] for more info. -==== - - -[[access-control-privileges-writes-set-label]] -== The `SET LABEL` privilege - -The `SET LABEL` privilege allows you to set labels on a node using the xref::clauses/set.adoc#set-set-a-label-on-a-node[SET clause]: - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] SET LABEL { * | label[, ...] } - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to `SET` any label on nodes of the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT SET LABEL * ON GRAPH neo4j TO regularUsers ----- - -[NOTE] -==== -Unlike many of the other `READ` and `WRITE` privileges, it is not possible to restrict the `SET LABEL` privilege to specific +ELEMENTS+, +NODES+ or +RELATIONSHIPS+. -==== - -The `SET LABEL` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] SET LABEL { * | label[, ...] } - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to deny the role `regularUsers` the ability to `SET` the label `foo` on nodes of all graphs, use: - -[source, cypher, role=noplay] ----- -DENY SET LABEL foo ON GRAPH * TO regularUsers ----- - -[NOTE] -==== -If no instances of this label exist on the database, then the xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW LABEL] privilege is also required. -==== - - -[[access-control-privileges-writes-remove-label]] -== The `REMOVE LABEL` privilege - -The `REMOVE LABEL` privilege allows you to remove labels from a node by using the xref::clauses/remove.adoc#remove-remove-a-label-from-a-node[REMOVE clause]: - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] REMOVE LABEL { * | label[, ...] } - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to `REMOVE` any label from nodes of the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT REMOVE LABEL * ON GRAPH neo4j TO regularUsers ----- - -[NOTE] -==== -Unlike many of the other `READ` and `WRITE` privileges, it is not possible to restrict the `REMOVE LABEL` privilege to specific +ELEMENTS+, +NODES+ or +RELATIONSHIPS+. -==== - -The `REMOVE LABEL` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] REMOVE LABEL { * | label[, ...] } - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, denying the role `regularUsers` the ability to remove the label `foo` from nodes of all graphs, use: - -[source, cypher, role=noplay] ----- -DENY REMOVE LABEL foo ON GRAPH * TO regularUsers ----- - - -[[access-control-privileges-writes-set-property]] -== The `SET PROPERTY` privilege - -The `SET PROPERTY` privilege allows a user to set a property on a node or relationship element in a graph by using the xref::clauses/set.adoc#set-set-a-property[SET clause]: - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] SET PROPERTY "{" { * | property[, ...] } "}" - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to `SET` any property on all elements of the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT SET PROPERTY {*} ON HOME GRAPH ELEMENTS * TO regularUsers ----- - -The `SET PROPERTY` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] SET PROPERTY "{" { * | property[, ...] } "}" - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, to deny the role `regularUsers` the ability to `SET` the property `foo` on nodes with the label `bar` on all graphs, use: - -[source, cypher, role=noplay] ----- -DENY SET PROPERTY { foo } ON GRAPH * NODES bar TO regularUsers ----- - -[NOTE] -==== -If the user attempts to set a property with a property name that does not already exist on the database, the user must also possess the xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW PROPERTY NAME] privilege. -==== - - -[[access-control-privileges-writes-merge]] -== The `MERGE` privilege - -The `MERGE` privilege is a compound privilege that combines `TRAVERSE` and `READ` (i.e. `MATCH`) with `CREATE` and `SET PROPERTY`. -This is intended to enable the use of xref::clauses/merge.adoc[the MERGE command], but it is also applicable to all reads and writes that require these privileges. - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] MERGE "{" { * | property[, ...] } "}" - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - [ - ELEMENT[S] { * | label-or-rel-type[, ...] } - | NODE[S] { * | label[, ...] } - | RELATIONSHIP[S] { * | rel-type[, ...] } - ] - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to `MERGE` on all elements of the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT MERGE {*} ON GRAPH neo4j ELEMENTS * TO regularUsers ----- - -It is not possible to deny the `MERGE` privilege. -If you wish to prevent a user from creating elements and setting properties: use xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-create[DENY CREATE] or xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-set-property[DENY SET PROPERTY]. - -[NOTE] -==== -If the user attempts to create nodes with a label that does not already exist on the database, the user must also possess the -xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW LABEL] privilege. -The same applies to new relationships and properties - the -xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW RELATIONSHIP TYPE] or -xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW PROPERTY NAME] privileges are required. -==== - - -[[access-control-privileges-writes-write]] -== The `WRITE` privilege - -The `WRITE` privilege allows the user to execute any `WRITE` command on a graph. - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] WRITE - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to grant the role `regularUsers` the ability to `WRITE` on the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT WRITE ON GRAPH neo4j TO regularUsers ----- - -[NOTE] -==== -Unlike the more specific `WRITE` commands, it is not possible to restrict `WRITE` privileges to specific +ELEMENTS+, +NODES+ or +RELATIONSHIPS+. -If you wish to prevent a user from writing to a subset of database objects, a `GRANT WRITE` can be combined with more specific `DENY` commands to target these elements. -==== - -The `WRITE` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] WRITE - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to deny the role `regularUsers` the ability to `WRITE` on the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -DENY WRITE ON GRAPH neo4j TO regularUsers ----- - -[NOTE] -==== -Users with `WRITE` privilege but restricted `TRAVERSE` privileges will not be able to do `DETACH DELETE` in all cases. -See link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/access-control#detach-delete-restricted-user[Operations Manual -> Fine-grained access control] for more info. -==== - - -[[access-control-privileges-writes-all]] -== The `ALL GRAPH PRIVILEGES` privilege - -The `ALL GRAPH PRIVILEGES` privilege allows the user to execute any command on a graph: - -[source, syntax, role="noheader"] ----- -GRANT [IMMUTABLE] ALL [ [ GRAPH ] PRIVILEGES ] - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to grant the role `regularUsers` `ALL GRAPH PRIVILEGES` on the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -GRANT ALL GRAPH PRIVILEGES ON GRAPH neo4j TO regularUsers ----- - -[NOTE] -==== -Unlike the more specific `READ` and `WRITE` commands, it is not possible to restrict `ALL GRAPH PRIVILEGES` to specific +ELEMENTS, +NODES+ or +RELATIONSHIPS+. -If you wish to prevent a user from reading or writing to a subset of database objects, a `GRANT ALL GRAPH PRIVILEGES` can be combined with more specific `DENY` commands to target these elements. -==== - -The `ALL GRAPH PRIVILEGES` privilege can also be denied: - -[source, syntax, role="noheader"] ----- -DENY [IMMUTABLE] ALL [ [ GRAPH ] PRIVILEGES ] - ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } } - TO role[, ...] ----- - -For example, to deny the role `regularUsers` all graph privileges on the graph `neo4j`, use: - -[source, cypher, role=noplay] ----- -DENY ALL GRAPH PRIVILEGES ON GRAPH neo4j TO regularUsers ----- diff --git a/modules/ROOT/pages/administration/aliases.adoc b/modules/ROOT/pages/administration/aliases.adoc deleted file mode 100644 index e4176e6c2..000000000 --- a/modules/ROOT/pages/administration/aliases.adoc +++ /dev/null @@ -1,1544 +0,0 @@ -:description: How to use Cypher to manage database aliases in Neo4j. -[role=enterprise-edition aura-db-enterprise] -[[alias-management]] -= Database alias management - -This page explains how to use Cypher to manage database aliases in Neo4j. - -There are two kinds of database aliases: local and remote. -A local database alias can only target a database within the same DBMS. -A remote database alias may target a database from another Neo4j DBMS. -When a query is run against a database alias, it will be redirected to the target database. -The home database for users can be set to an alias, which will be resolved to the target database on use. -Both local and remote database aliases can be created as part of a xref::administration/databases.adoc#administration-databases-create-composite-database[composite database]. - -A local database alias can be used in all other Cypher commands in place of the target database. -Please note that the local database alias will be resolved while executing the command. -Privileges are defined on the database, and not the local database alias. - -A remote database alias can be used for connecting to a database of a remote Neo4j DBMS, use clauses, setting a user's home database and defining the access privileges to the remote database. -Remote database aliases require configuration to safely connect to the remote target, which is described in link:{neo4j-docs-base-uri}/operations-manual/{page-version}/manage-databases/remote-alias[Connecting remote databases]. -It is not possible to impersonate a user on the remote database or to execute an administration command on the remote database via a remote database alias. - -Database aliases can be created and managed using a set of Cypher administration commands executed against the `system` database. -The required privileges are described xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[here]. -When connected to the DBMS over Bolt, administration commands are automatically routed to the `system` database. - -The syntax of the database alias management commands is as follows: - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Alias management command syntax -[options="header", width="100%", cols="1,5a"] -|=== -| Command | Syntax -| Show Database Alias -| -[source, syntax, role=noheader] ------ -SHOW ALIAS[ES] [name] FOR DATABASE[S] -[WHERE expression] ------ -[source, syntax, role=noheader] ------ -SHOW ALIAS[ES] [name] FOR DATABASE[S] -YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n] -[WHERE expression] -[RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ------ -Lists both local and remote database aliases, optionally filtered on the alias name. - -| Create Local Alias -| -[source, syntax, role=noheader] ------ -CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName -[PROPERTIES "{" key: value[, ...] "}"] ------ -[source, syntax, role=noheader] ------ -CREATE OR REPLACE ALIAS name FOR DATABASE targetName -[PROPERTIES "{" key: value[, ...] "}"] ------ - -| Create Remote Alias -| -[source, syntax, role=noheader] ------ -CREATE ALIAS name [IF NOT EXISTS] FOR DATABASE targetName -AT 'url' USER username PASSWORD 'password' -[DRIVER "{" setting: value[, ...] "}"] -[PROPERTIES "{" key: value[, ...] "}"] ------ -[source, syntax, role=noheader] ------ -CREATE OR REPLACE ALIAS name FOR DATABASE targetName -AT 'url' USER username PASSWORD 'password' -[DRIVER "{" setting: value[, ...] "}"] -[PROPERTIES "{" key: value[, ...] "}"] ------ - -| Alter Local Alias -| -[source, syntax, role=noheader] ------ -ALTER ALIAS name [IF EXISTS] SET DATABASE -[TARGET targetName] -[PROPERTIES "{" key: value[, ...] "}"] ------ - -| Alter Remote Alias -| -[source, syntax, role=noheader] ------ -ALTER ALIAS name [IF EXISTS] SET DATABASE -[TARGET targetName AT 'url'] -[USER username] -[PASSWORD 'password'] -[DRIVER "{" setting: value[, ...] "}"] -[PROPERTIES "{" key: value[, ...] "}"] ------ - -| Drop Alias -| -[source, syntax, role=noheader] ------ -DROP ALIAS name [IF EXISTS] FOR DATABASE ------ -Drop either a local or remote database alias. - -|=== - -This is the list of the allowed driver settings for remote database aliases. - -[[remote-alias-driver-settings]] -.ssl_enforced -[width="100%", cols="1s, 4a"] -|=== -| Description -| -SSL for remote database alias drivers is configured through the target url scheme. -If `ssl_enforced` is set to true, a secure url scheme is enforced. -This will be validated when the command is executed. - -| Valid values -| Boolean - -| Default value -| true - -|=== - -.connection_timeout -[width="100%", cols="1s, 4a"] -|=== - -| Description -| -Socket connection timeout. -A timeout of zero is treated as an infinite timeout and will be bound by the timeout configured on the operating system level. - -| Valid values -| Duration - -| Default value -| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.routing.driver.connection.connect_timeout[dbms.routing.driver.connection.connect_timeout] - -|=== - -.connection_max_lifetime -[width="100%", cols="1s, 4a"] -|=== - -| Description -| -Pooled connections older than this threshold will be closed and removed from the pool. -Setting this option to a low value will cause a high connection churn and might result in a performance hit. -It is recommended to set maximum lifetime to a slightly smaller value than the one configured in network equipment (load balancer, proxy, firewall, etc. can also limit maximum connection lifetime). - -| Valid values -| Duration. - -Zero and negative values result in lifetime not being checked. - -| Default value -| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.routing.driver.connection.max_lifetime[dbms.routing.driver.connection.max_lifetime] - -|=== - -.connection_pool_acquisition_timeout -[width="100%", cols="1s, 4a"] -|=== -| Description -| -Maximum amount of time spent attempting to acquire a connection from the connection pool. -This timeout only kicks in when all existing connections are being used and no new connections can be created because maximum connection pool size has been reached. -Error is raised when connection can’t be acquired within configured time. - -| Valid values -| Duration. - -Negative values are allowed and result in unlimited acquisition timeout. -Value of `0` is allowed and results in no timeout and immediate failure when connection is unavailable. - -| Default value -| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.routing.driver.connection.pool.acquisition_timeout[dbms.routing.driver.connection.pool.acquisition_timeout] - -|=== - -.connection_pool_max_size -[width="100%", cols="1s, 4a"] -|=== - -| Description -| -Maximum total number of connections to be managed by a connection pool. -The limit is enforced for a combination of a host and user. - -| Valid values -| Integer. - -Negative values are allowed and result in unlimited pool. -Value of `0` is not allowed. - -| Default value -| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.routing.driver.connection.pool.max_size[dbms.routing.driver.connection.pool.max_size] - -|=== - -.logging_level -[width="100%", cols="1s, 4a"] -|=== - -| Description -| Sets level for driver internal logging. - -| Valid values -| org.neo4j.logging.Level. - -One of `DEBUG`, `INFO`, `WARN`, `ERROR`, or `NONE`. - -| Default value -| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.routing.driver.logging.level[dbms.routing.driver.logging.level] - -|=== - - -[NOTE] -==== -If transaction modifies a database alias, other transactions concurrently executing against that alias may be aborted and rolled back for safety. -This prevents issues such as a transaction executing against multiple target databases for the same alias. -==== - - -[[alias-management-show-alias]] -== Listing database aliases - -//// -[source, cypher, role=test-setup] ----- -CREATE DATABASE `movies`; -CREATE ALIAS `films` FOR DATABASE `movies`; -CREATE ALIAS `motion pictures` FOR DATABASE `movies` PROPERTIES { nameContainsSpace: true }; -CREATE DATABASE `northwind-graph-2020`; -CREATE DATABASE `northwind-graph-2021`; -CREATE DATABASE `northwind-graph-2022`; -CREATE DATABASE `sci-fi-books`; -CREATE COMPOSITE DATABASE `library`; -CREATE ALIAS `library`.`sci-fi` FOR DATABASE `sci-fi-books`; -CREATE COMPOSITE DATABASE garden; -CREATE DATABASE `perennial-flowers`; -CREATE ALIAS `library`.`romance` FOR DATABASE `romance-books` AT 'neo4j+s://location:7687' USER alice PASSWORD 'password'; -CREATE ALIAS `movie scripts` FOR DATABASE `scripts` AT "neo4j+s://location:7687" USER alice PASSWORD "password" -DRIVER { - ssl_enforced: true, - connection_timeout: duration({seconds: 5}), - connection_max_lifetime: duration({hours: 1}), - connection_pool_acquisition_timeout: duration({minutes: 1}), - connection_pool_idle_test: duration({minutes: 2}), - connection_pool_max_size: 10, - logging_level: 'info' -}; ----- -//// - -Available database aliases can be seen using `SHOW ALIASES FOR DATABASE`. -The required privileges are described xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[here]. - -`SHOW ALIASES FOR DATABASE` will produce a table of database aliases with the following columns: - -[options="header" cols="2m,4a,2m"] -|=== -| Column | Description | Type - -| name -| The fully qualified name of the database alias. label:default-output[] -| STRING - -| composite -| The name of the composite database this alias belongs to, or `null` if the alias does not belong to a composite database. label:default-output[] -| STRING - -| database -| The name of the target database. label:default-output[] - -This column is filtered according to the `ACCESS` privileges of the user. -However, some privileges enable users to see additional databases regardless of their `ACCESS` privileges: - -* Users with the `CREATE DATABASE`, `DROP DATABASE`, `ALTER DATABASE`, or `SET DATABASE ACCESS` privileges can see all standard databases. -* Users with the `CREATE COMPOSITE DATABASE`, `DROP COMPOSITE DATABASE`, or `COMPOSITE DATABASE MANAGEMENT` privileges can see all composite databases. -* Users with the `DATABASE MANAGEMENT` privilege can see all databases. -* Users can always see the `system` database. - -If a user has not been granted the `ACCESS` privilege to the target database and none of the above special cases apply, then it is not visible to the user -and this column will be `null`. - -| STRING - -| location -| The location of the database, either `local` or `remote`. label:default-output[] -| STRING - -| url -| Target location or `null` if the target is local. label:default-output[] -| STRING - -| user -| User connecting to the remote database or `null` if the target database is local. label:default-output[] -| STRING - -| driver -| -The driver options for connection to the remote database or `null` if the target database is local or if no driver settings are added. -List of xref::administration/aliases.adoc#remote-alias-driver-settings[driver settings] allowed for remote database aliases. -| MAP - -| properties -| Any properties set on the database alias. -| MAP - -|=== - -The detailed information for a particular database alias can be displayed using the command `SHOW ALIASES FOR DATABASE YIELD *`. -When a `YIELD *` clause is provided, the full set of columns is returned. - -.+Show all aliases for a database+ -====== - -A summary of all available database aliases can be displayed using the command `SHOW ALIASES FOR DATABASE`. - -.Query -[source, cypher] ----- -SHOW ALIASES FOR DATABASE ----- - -.Result -[role="queryresult",options="header,footer",cols="6*+ | ++ -| +"library.romance"+ | +"library"+ | +"romance-books""+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ -| +"library.sci-fi"+ | +"library"+ | +"sci-fi-books"+ | +"local"+ | ++ | ++ -| +"motion pictures"+ | +null+ | +"movies"+ | +"local"+ | ++ | ++ -| +"movie scripts"+ | +null+ | +"scripts"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ -6+d|Rows: 5 - -|=== - -====== - -.+Show specific aliases for databases+ -====== - -To list just one database alias, the `SHOW ALIASES` command takes an alias name; - -.Query -[source, cypher] ----- -SHOW ALIAS films FOR DATABASES ----- - -.Result -[role="queryresult",options="header,footer",cols="6*+ | ++ - -6+d|Rows: 1 - -|=== - -.Query -[source, cypher] ----- -SHOW ALIAS library.romance FOR DATABASES ----- - -.Result -[role="queryresult",options="header,footer",cols="6*+ | ++ | ++ | +{}+ -| +"library.romance"+ | +"library"+ | +"romance-books"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ | +{}+ | +{}+ -| +"library.sci-fi"+ | +"library"+ | +"sci-fi-books"+ | +"local"+ | ++ | ++ | ++ | +{}+ -| +"motion pictures"+ | +null+ | +"movies"+ | +"local"+ | ++ | ++ | ++ | +{"namecontainsspace":true}+ -| +"movie scripts"+ | +null+ | +"scripts"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ | +{"connection_pool_idle_test":PT2M,"connection_pool_max_size":10,"loggi"connection_pool_idle_test":PT2M,"connection_pool_max_size":10,"logging_level":"INFO","ssl_enforced":true,"connection_pool_acquisition_timeout":PT1M,"connection_timeout":PT5S,"connection_max_lifetime":PT1H} | +{}+ - -8+d|Rows: 5 - -|=== - -====== - - -.+Show count of aliases for a database+ -====== - -The number of database aliases can be seen using a `count()` aggregation with `YIELD` and `RETURN`. - - -.Query -[source, cypher] ----- -SHOW ALIASES FOR DATABASE YIELD * -RETURN count(*) as count ----- - -.Result -[role="queryresult",options="header,footer",cols="1*+ | +"movies"+ -| +"library.romance"+ | +"neo4j+s://location:7687"+ | +"romance-books"+ -| +"movie scripts"+ | +"neo4j+s://location:7687"+ | +"scripts"+ -3+d|Rows: 3 -|=== - -====== - -[[alias-management-create-database-alias]] -== Creating database aliases - -Database aliases can be created using `CREATE ALIAS`. - -The required privileges are described xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[here]. - -.Create alias command syntax -[options="header", width="100%", cols="5a,2"] -|=== -| Syntax | Comment -| -[source, syntax, role=noheader] ------ -CREATE [OR REPLACE] ALIAS [compositeDatabaseName.]aliasName [IF NOT EXISTS] FOR DATABASE targetName -[PROPERTIES "{" key: value[, ...] "}"] ------ -| Create a local alias. - -| -[source, syntax, role=noheader] ------ -CREATE [OR REPLACE] ALIAS [compositeDatabaseName.]aliasName [IF NOT EXISTS] FOR DATABASE targetName -AT 'url' USER username PASSWORD 'password' -[DRIVER "{" setting: value[, ...] "}"] -[PROPERTIES "{" key: value[, ...] "}"] ------ -| Create a remote database alias. - -|=== - - -This command is optionally idempotent, with the default behavior to fail with an error if the database alias already exists. -Inserting `IF NOT EXISTS` after the alias name ensures that no error is returned and nothing happens should a database alias with that name already exist. -Adding `OR REPLACE` to the command will result in any existing database alias being deleted and a new one created. -`CREATE OR REPLACE ALIAS` will fail if there is an existing database with the same name. - -[NOTE] -==== -The `IF NOT EXISTS` and `OR REPLACE` parts of this command cannot be used together. -==== - -[NOTE] -==== -Database alias names are subject to the rules specified in the xref:administration/alias-management-escaping[Alias names and escaping] section. -==== - -[[database-management-create-local-database-alias]] -=== Creating local database aliases - -Local aliases are created with a target database. - -.+Creating aliases for local databases+ -====== - -.Query -[source, cypher] ----- -CREATE ALIAS `northwind` FOR DATABASE `northwind-graph-2021` ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -When a local database alias has been created, it will show up in the `aliases` column provided by the command `SHOW DATABASES` and in the `SHOW ALIASES FOR DATABASE` command. - - -.Query -[source, cypher] ----- -SHOW DATABASE `northwind` ----- - -.Result -[role="queryresult",options="header,footer",cols="13*+ | ++ -6+d|Rows: 1 - -|=== - -====== - -.+Setting properties for local database aliases+ -====== - -Local database aliases can also be given properties. -These properties can then be used in queries with the xref::functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName()` function]. - -.Query -[source, cypher] ----- -CREATE ALIAS `northwind-2022` -FOR DATABASE `northwind-graph-2022` -PROPERTIES { newestNorthwind: true, index: 3 } ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -The properties are then shown in the `SHOW ALIASES FOR DATABASE YIELD ...` command. - -.Query -[source, cypher] ----- -SHOW ALIAS `northwind-2022` FOR DATABASE YIELD name, properties ----- - -.Result -[role="queryresult",options="header,footer",cols="2* 10, connection_timeout -> PT1M}+ | +{}+ -8+d|Rows: 1 - -|=== - -====== - -.+Setting properties for remote database aliases+ -====== -Just as the local database aliases, the remote database aliases can be given properties. -These properties can then be used in queries with the xref::functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName()` function]. - -.Query -[source, cypher] ----- -CREATE ALIAS `remote-northwind-2021` FOR DATABASE `northwind-graph-2021` AT 'neo4j+s://location:7687' -USER alice PASSWORD 'password' -PROPERTIES { newestNorthwind: false, index: 6 } ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -The properties are then shown in the `SHOW ALIASES FOR DATABASE YIELD ...` command. - -.Query -[source, cypher] ----- -SHOW ALIAS `remote-northwind-2021` FOR DATABASE YIELD name, properties ----- - -.Result -[role="queryresult",options="header,footer",cols="2*+ | ++ -| +"garden.trees"+ | +"garden"+ | +"trees"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ -6+d|Rows: 1 - -|=== -====== - - -.+Aliases pointing to composite databases+ -====== -Database aliases cannot point to a composite database. - -.Query -[source, cypher, role=test-fail] ----- -CREATE ALIAS yard FOR DATABASE garden ----- - -.Error message -[source, output, role="noheader"] ----- -Failed to create the specified database alias 'yard': Database 'garden' is composite. ----- - -====== - -[[alias-management-alter-database-alias]] -== Altering database aliases - -//// -CREATE ALIAS garden.flowers FOR DATABASE `perennial-flowers`; -CREATE ALIAS `northwind` FOR DATABASE `northwind-graph-2020`; // created in the replace alias example -CREATE ALIAS `remote-northwind` FOR DATABASE `northwind-graph-2020` AT "neo4j+s://location:7687" USER alice PASSWORD 'password'; -CREATE ALIAS `remote-with-driver-settings` FOR DATABASE `northwind-graph-2020` AT "neo4j+s://location:7687" USER alice PASSWORD 'password' -DRIVER { - connection_timeout: duration({ minutes: 1 }), - connection_pool_max_size: 10 - }; -CREATE ALIAS garden.trees FOR DATABASE trees AT 'neo4j+s://location:7687' USER alice PASSWORD 'password' -//// - -Database aliases can be altered using `ALTER ALIAS` to change its database target, properties, url, user credentials, or driver settings. -The required privileges are described xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[here]. -Only the clauses used will be altered. - -[NOTE] -==== -Local database aliases cannot be altered to remote aliases, or vice versa. -==== - -.Alter alias command syntax -[options="header", width="100%", cols="5a,2"] -|=== -| Syntax | Comment -| -[source, source, role=noheader] ------ -ALTER ALIAS [compositeDatabaseName.]aliasName [IF EXISTS] SET DATABASE -[TARGET targetName] -[PROPERTIES "{" key: value[, ...] "}"] ------ -| Modify database target of a local alias. - -The clauses can be applied in any order, while at least one clause needs to be set. - -| -[source, source, role=noheader] ------ -ALTER ALIAS [compositeDatabaseName.]aliasName [IF EXISTS] SET DATABASE -[TARGET targetName AT 'url'] -[USER username] -[PASSWORD 'password'] -[DRIVER "{" setting: value[, ...] "}"] -[PROPERTIES "{" key: value[, ...] "}"] ------ -| Modify a remote alias. - -The clauses can be applied in any order, while at least one clause needs to be set. - -|=== - -.+Altering local database aliases+ -====== - -Example of altering a local database alias target. - - -.Query -[source, cypher] ----- -ALTER ALIAS `northwind` -SET DATABASE TARGET `northwind-graph-2021` ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -When a local database alias has been altered, it will show up in the `aliases` column for the target database provided by the command `SHOW DATABASES`. - -.Query -[source, cypher] ----- -SHOW DATABASE `northwind-graph-2021` ----- - -.Result -[role="queryresult",options="header,footer",cols="13*+ | ++ | ++ | +{"perennial":true}+ -| +"garden.trees"+ | +"garden"+ | +"updatedtrees"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ | +{}+ | +{"treeversion":2}+ -| +"motion pictures"+ | +null+ | +"movies"+ | +"local"+ | ++ | ++ | ++ | +{"namecontainsspace":true,"moreinfo":"no, not really"}+ -| +"movie scripts"+ | +null+ | +"scripts"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ | +{connection_pool_idle_test: PT2M, connection_pool_max_size: 10, logging_level: "INFO", ssl_enforced: TRUE, connection_pool_acquisition_timeout: PT1M, connection_timeout: PT5S, connection_max_lifetime: PT1H}+ | +{"namecontainsspace":true}+ -| +"northwind"+ | +null+ | +"northwind-graph-2021"+ | +"local"+ | ++ | ++ | ++ |+[]+ -| +"remote-northwind"+ | +null+ | +"northwind-graph-2020"+ | +"remote"+ | +"neo4j+s://other-location:7687"+ | +"alice"+ | +{}+ | +{}+ -| +"remote-with-driver-settings"+ | +null+ | +"northwind-graph-2020"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"bob"+ | +{logging_level -> "DEBUG", connection_timeout -> PT1M}+ |+[]+ -8+d|Rows: 7 - -|=== - - -.+Using IF EXISTS when altering database aliases+ -====== - -The `ALTER ALIAS` command is optionally idempotent, with the default behavior to fail with an error if the database alias does not exist. -Appending `IF EXISTS` to the command ensures that no error is returned and nothing happens should the alias not exist. - - - -.Query -[source, cypher] ----- -ALTER ALIAS `no-alias` IF EXISTS SET DATABASE TARGET `northwind-graph-2021` ----- - -[source, result, role="noheader"] ----- -(no changes, no records) ----- - -====== - -[[alias-management-drop-database-alias]] -== Deleting database aliases - -//// -CREATE ALIAS garden.flowers FOR DATABASE `perennial-flowers` PROPERTIES { perennial: true }; -CREATE ALIAS `northwind-2022` FOR DATABASE `northwind-graph-2022` PROPERTIES { newestNorthwind: true, index: 3 }; -CREATE ALIAS `northwind` FOR DATABASE `northwind-graph-2021`; -CREATE ALIAS `remote-northwind-2021` -FOR DATABASE `northwind-graph-2021` AT 'neo4j+s://location:7687' USER alice PASSWORD 'password' -PROPERTIES { newestNorthwind: false, index: 6 }; -CREATE ALIAS `remote-northwind` FOR DATABASE `northwind-graph-2020` AT "neo4j+s://other-location:7687" USER alice PASSWORD 'password'; -CREATE ALIAS `remote-with-driver-settings` FOR DATABASE `northwind-graph-2020` AT "neo4j+s://location:7687" USER bob PASSWORD 'newPassword' -DRIVER { - connection_timeout: duration({ minutes: 1 }), - logging_level: "debug" - }; -CREATE ALIAS garden.trees FOR DATABASE updatedTrees AT 'neo4j+s://location:7687' -USER alice PASSWORD 'password' -PROPERTIES { treeVersion: 2 } -//// - - -Both local and remote database aliases can be deleted using the `DROP ALIAS` command. -The required privileges are described xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[here]. - - -.+Deleting local database aliases+ -====== - -Delete a local database alias. - - -.Query -[source, cypher] ----- -DROP ALIAS `northwind` FOR DATABASE ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -When a database alias has been deleted, it will no longer show up in the `aliases` column provided by the command `SHOW DATABASES`. - -.Query -[source, cypher] ----- -SHOW DATABASE `northwind-graph-2021` ----- - -.Result -[role="queryresult",options="header,footer",cols="13*+ | ++ -| +"garden.trees"+ | +"garden"+ | +"updatedtrees"+ | +"local"+ | +"neo4j+s://location:7687"+ | +"alice"+ -| +"library.romance"+ | +"library"+ | +"romance-books"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ -| +"library.sci-fi"+ | +"library"+ | +"sci-fi-books"+ | +"local"+ | ++ | ++ -| +"motion pictures"+ | +null+ | +"movies"+ | +"local"+ | ++ | ++ -| +"movie scripts"+ | +null+ | +"scripts"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ -| +"northwind-2022"+ | +null+ | +"northwind-graph-2022"+ | +"local"+ | ++ | ++ -| +"remote-northwind"+ | +null+ | +"northwind-graph-2020"+ | +"remote"+ | +"neo4j+s://other-location:7687"+ | +"alice"+ -| +"remote-northwind-2021"+ | +null+ | +"northwind-graph-2021"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"alice"+ -| +"remote-with-driver-settings"+ | +null+ | +"northwind-graph-2020"+ | +"remote"+ | +"neo4j+s://location:7687"+ | +"bob"+ -6+d|Rows: 9 - -|=== - -.+Using IF EXISTS when deleting database aliases+ -====== - -The `DROP ALIAS` command is optionally idempotent, with the default behavior to fail with an error if the database alias does not exist. -Inserting `IF EXISTS` after the alias name ensures that no error is returned and nothing happens should the alias not exist. - -.Query -[source, cypher] ----- -DROP ALIAS `northwind` IF EXISTS FOR DATABASE ----- - -[source, result, role="noheader"] ----- -(no changes, no records) ----- - -====== - -[[alias-management-escaping]] -== Alias names and escaping -//// -[source, cypher, role=test-setup] ----- -CREATE DATABASE `northwind-graph`; -CREATE COMPOSITE DATABASE `my-composite-database-with-dashes`; -CREATE COMPOSITE DATABASE `my.composite.database.with.dots`; -CREATE COMPOSITE DATABASE mySimpleCompositeDatabase; -CREATE COMPOSITE DATABASE `myCompositeDatabase.withDot`; ----- -//// - -Database alias names are subject to the xref::syntax/naming.adoc[standard Cypher restrictions on valid identifiers]. - -The following naming rules apply: - -* A name is a valid identifier. -* Name length can be up to 65534 characters. -* Names cannot end with dots. -* Unescaped dots signify that the database alias belongs to a composite database, separating the composite database name and the alias name. -* Names that begin with an underscore or with the prefix `system` are reserved for internal use. -* Non-alphabetic characters, including numbers, symbols, dots, and whitespace characters, can be used in names, but must be escaped using backticks. - -The name restrictions and escaping rules apply to all the different database alias commands. - -[NOTE] -==== -Having dots (`.`) in the database alias names is not recommended. -This is due to the difficulty of determining if a dot is part of the database alias name or a delimiter for a database alias in a composite database. -==== - -When it comes to escaping names using backticks, there are some additional things to consider around database aliases in composite databases: - -.+Escaping database alias and composite database names+ -====== - -The composite database name and the database alias name need to be escaped individually. -The following example creates a database alias named `my alias with spaces` as a constituent in the composite database named `my-composite-database-with-dashes`: - -.Query -[source, cypher] ----- -CREATE ALIAS `my-composite-database-with-dashes`.`my alias with spaces` FOR DATABASE `northwind-graph` ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -When not escaped individually, a database alias with the full name `my alias with.dots and spaces` gets created instead: - -.Query -[source, cypher] ----- -CREATE ALIAS `my alias with.dots and spaces` FOR DATABASE `northwind-graph` ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -====== - -.+Handling multiple dots+ -====== - -//Examples where dots are not separators between composite name and alias name are impossible to test, because the right escaping cannot be inferred automatically. - -Database alias names may also include dots. -Though these always need to be escaped in order to avoid ambiguity with the composite database and database alias split character. - -.Query -[source, cypher, role=test-skip] ----- -CREATE ALIAS `my.alias.with.dots` FOR DATABASE `northwind-graph` ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -.Query -[source, cypher, role=test-skip] ----- -CREATE ALIAS `my.composite.database.with.dots`.`my.other.alias.with.dots` FOR DATABASE `northwind-graph` ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -====== - -.+Single dots and local database aliases+ label:deprecated[] -====== -There is a special case for local database aliases with a single dot without any existing composite database. -If a composite database `some` exists, the query below will create a database alias named `alias` within the composite database `some`. -If no such database exists, however, the same query will instead create a database alias named `some.alias`: - -.Query -[source, cypher] ----- -CREATE ALIAS some.alias FOR DATABASE `northwind-graph` ----- - -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -====== - -.+Handling parameters+ -====== - -When using parameters, names cannot be escaped. -When the given parameter includes dots, the first dot will be considered the divider for the composite database. - -Consider the query with parameter: - -.Parameters -[source, javascript] ----- -{ - "aliasname": "mySimpleCompositeDatabase.myAlias" -} ----- - -.Query -[source, cypher] ----- -CREATE ALIAS $aliasname FOR DATABASE `northwind-graph` ----- - -If the composite database `mysimplecompositedatabase` exists, then a database alias `myalias` will be created in that composite database. -If no such composite database exists, then a database alias `mysimplecompositedatabase.myalias` will be created. - -On the contrary, a database alias `myalias` cannot be created in composite `mycompositedatabase.withdot` using parameters. -Consider the same query but with the following parameter: - -.Parameters -[source, javascript] ----- -{ - "aliasname": "myCompositeDatabase.withDot.myAlias" -} ----- - -Since the first dot will be used as a divider, the command will attempt to create the database alias `withdot.myalias` in the composite database `mycompositedatabase`. -If `mycompositedatabase` doesn't exist, the command will create a database alias with the name `mycompositedatabase.withdot.myalias`, which is not part of any composite database. - -In these cases, it is recommended to avoid parameters and explicitly escape the composite database name and alias name separately to avoid ambiguity. - -====== - -.+Handling parameters+ -====== - -Further special handling with parameters is needed for database aliases and similarly named composite databases. - -Consider the set-up: - -.Query -[source, cypher, role="noheader test-skip"] ----- -CREATE COMPOSITE DATABASE foo -CREATE ALIAS `foo.bar` FOR DATABASE `northwind-graph` ----- - -The alias `foo.bar` does not belong to the composite database `foo`. - -Dropping this alias using parameters fails with an error about a missing alias: - -.Parameters -[source, javascript] ----- -{ - "aliasname": "foo.bar" -} ----- - -.Query -[source, cypher, role=test-fail] ----- -DROP ALIAS $aliasname FOR DATABASE ----- - -.Error message -[source, output, role="noheader"] ----- -Failed to delete the specified database alias 'foo.bar': Database alias does not exist. ----- - -Had the composite database `foo` not existed, the database alias `foo.bar` would have been dropped. - -In these cases, it is recommended to avoid parameters and explicitly escape the composite database name and alias name separately to avoid ambiguity. - -====== diff --git a/modules/ROOT/pages/administration/databases.adoc b/modules/ROOT/pages/administration/databases.adoc deleted file mode 100644 index 3df9319c2..000000000 --- a/modules/ROOT/pages/administration/databases.adoc +++ /dev/null @@ -1,1182 +0,0 @@ -//// -[source, cypher, role=test-setup] ----- -CREATE DATABASE `movies`; -CREATE ALIAS `films` FOR DATABASE `movies`; -CREATE ALIAS `motion pictures` FOR DATABASE `movies`; ----- -//// - -[[administration-databases]] -= Database management -:description: How to use Cypher to manage databases in Neo4j DBMS: creating, modifying, deleting, starting, and stopping individual databases within a single server. -:page-aliases: databases.adoc - -This section explains how to use Cypher to manage databases in Neo4j DBMS. -It describes how to create, modify, delete, start, and stop individual databases within a single server. - -Neo4j supports the management of multiple databases within the same DBMS. -The metadata for these databases, including the associated security model, is maintained in a special database called the `system` database. -All multi-database administrative commands must be run against the `system` database. -These administrative commands are automatically routed to the `system` database when connected to the DBMS over Bolt. - -The syntax of the database management commands is as follows: - -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - -.Database management command syntax -[options="header", width="100%", cols="1m,5a"] -|=== -| Command | Syntax - -| SHOW DATABASE -| -[source, syntax, role="noheader"] ----- -SHOW { DATABASE[S] name \| DATABASE[S] \| DEFAULT DATABASE \| HOME DATABASE } -[WHERE expression] ----- - -[source, syntax, role="noheader"] ----- -SHOW { DATABASE[S] name \| DATABASE[S] \| DEFAULT DATABASE \| HOME DATABASE } -YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n] -[WHERE expression] -[RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| CREATE DATABASE -| -[source, syntax, role="noheader"] ----- -CREATE DATABASE name [IF NOT EXISTS] -[TOPOLOGY n PRIMAR{Y\|IES} [m SECONDAR{Y\|IES}]] -[OPTIONS "{" option: value[, ...] "}"] -[WAIT [n [SEC[OND[S]]]]\|NOWAIT] ----- - -[source, syntax, role="noheader"] ----- -CREATE OR REPLACE DATABASE name -[TOPOLOGY n PRIMAR{Y\|IES} [m SECONDAR{Y\|IES}]] -[OPTIONS "{" option: value[, ...] "}"] -[WAIT [n [SEC[OND[S]]]]\|NOWAIT] ----- - -| CREATE COMPOSITE DATABASE -| -[source, syntax, role="noheader"] ----- -CREATE COMPOSITE DATABASE name [IF NOT EXISTS] -[OPTIONS "{" "}"] -[WAIT [n [SEC[OND[S]]]]\|NOWAIT] ----- - -[source, syntax, role="noheader"] ----- -CREATE OR REPLACE COMPOSITE DATABASE name -[OPTIONS "{" "}"] -[WAIT [n [SEC[OND[S]]]]\|NOWAIT] ----- - -| ALTER DATABASE -| -[source, syntax, role="noheader"] ----- -ALTER DATABASE name [IF EXISTS] -{ -SET ACCESS {READ ONLY \| READ WRITE} \| -SET TOPOLOGY n PRIMAR{Y\|IES} [m SECONDAR{Y\|IES}] -} -[WAIT [n [SEC[OND[S]]]]\|NOWAIT] ----- - -| STOP DATABASE -| -[source, syntax, role="noheader"] ----- -STOP DATABASE name [WAIT [n [SEC[OND[S]]]]\|NOWAIT] ----- - -| START DATABASE -| -[source, syntax, role="noheader"] ----- -START DATABASE name [WAIT [n [SEC[OND[S]]]]\|NOWAIT] ----- - -| DROP DATABASE -| -[source, syntax, role="noheader"] ----- -DROP [COMPOSITE] DATABASE name [IF EXISTS] [{DUMP\|DESTROY} [DATA]] [WAIT [n [SEC[OND[S]]]]\|NOWAIT] ----- - -|=== - -[[administration-databases-show-databases]] -== Listing databases - -There are four different commands for listing databases: - -* Listing all databases. -* Listing a particular database. -* Listing the default database. -* Listing the home database. - -These commands return the following columns: - -.Listing databases output -[options="header", width="100%", cols="4m,6a,2m"] -|=== -| Column | Description | Type - -| name -| The name of the database. label:default-output[] -| STRING - -| type -| The type of the database: `system`, `standard`, or `composite`. label:default-output[] -| STRING - -| aliases -| The names of any aliases the database may have. label:default-output[] -| LIST - -| access -| The database access mode, either `read-write` or `read-only`. label:default-output[] - -[NOTE] -==== -A database may be described as read-only when using `ALTER DATABASE ... SET ACCESS READ ONLY`. -==== -| STRING - -| databaseID -| The database unique ID. -| STRING - -| serverID -| The server instance ID. -| STRING - -| address -| -Instance address in a clustered DBMS. -The default for a standalone database is `neo4j://localhost:7687`. label:default-output[] -| STRING - -| role -| The current role of the database (`primary`, `secondary`, `unknown`). label:default-output[] -| STRING - -| writer -|`true` for the instance that accepts writes for this database (this instance is the leader for this database in a cluster or this is a standalone instance). label:default-output[] -| BOOLEAN - -| requestedStatus -| The expected status of the database. -The value can be either `online` or `offline`. label:default-output[] -| STRING - -| currentStatus -| The actual status of the database. label:default-output[] - -The value can be one of the following: - -* `online` - the database is running -* `offline` - the database is not running -* `starting` - the database is not running, but is about to. -* `stopping` - the database is not running anymore, but still has not stopped completely. -Offline operations (e.g. `load`/`dump`) cannot be performed yet. -* `store copying` - the database is currently being updated from another instance of Neo4j -* For other states please refer to the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/manage-databases/errors/#database-management-states[operation manual]. - -| STRING - -| statusMessage -| A message explaining the status of the database, often explaining why it is not in the correct state. label:default-output[] -| STRING - -| default -| -Show if this is the default database for the DBMS. label:default-output[] - -[NOTE] -==== -Not returned by `SHOW HOME DATABASE` or `SHOW DEFAULT DATABASE`. -==== -| BOOLEAN - -| home -| -Shown if this is the home database for the current user. label:default-output[] - -[NOTE] -==== -Not returned by `SHOW HOME DATABASE` or `SHOW DEFAULT DATABASE`. -==== -| BOOLEAN - -| `currentPrimariesCount` -| Number of primaries for this database reported as running currently. -It is the same as the number of rows where `role=primary` and `name=this database`. -| INTEGER - -| `currentSecondariesCount` -| Number of secondaries for this database reported as running currently. -It is the same as the number of rows where `role=secondary` and `name=this database`. -| INTEGER - -| `requestedPrimariesCount` -| The requested number of primaries for this database. -May be lower than current if the DBMS is currently reducing the number of copies of the database, or higher if it is currently increasing the number of copies. -| INTEGER - -| `requestedSecondariesCount` -| The requested number of secondaries for this database. -May be lower than current if the DBMS is currently reducing the number of copies of the database, or higher if it is currently increasing the number of copies. -| INTEGER - -| creationTime -| The date and time at which the database was created. -| DATETIME - -| lastStartTime -| The date and time at which the database was last started. -| DATETIME - -| lastStopTime -| The date and time at which the database was last stopped. -| DATETIME - -| store -a| -Information about the storage engine and the store format. - -The value is a string formatted as: - -[source, syntax, role="noheader"] ----- -{storage engine}-{store format}-{major version}.{minor version} ----- -| STRING - -| lastCommittedTxn -| The ID of the last transaction received. -| INTEGER - -| replicationLag -| -Number of transactions the current database is behind compared to the database on the primary instance. -The lag is expressed in negative integers. In standalone environments, the value is always `0`. -| INTEGER - -|constituents -|The names of any constituents the database may have. label:default-output[] -| LIST - -|=== - - -.+SHOW DATABASES+ -====== - -A summary of all available databases can be displayed using the command `SHOW DATABASES`. - -.Query -[source, cypher] ----- -SHOW DATABASES ----- - -.Result -[role="queryresult",options="header,footer",cols="13* Composite database introduction]. - -Composite databases can be created using `CREATE COMPOSITE DATABASE`. - -Composite database names are subject to the same rules as xref:administration-databases-create-database[standard databases]. -One difference is however that the deprecated syntax using dots without enclosing the name in backticks is not available. -Both dots and dashes need to be enclosed within backticks when using composite databases. - -[NOTE] -==== -Having dots (`.`) in the composite database names is not recommended. -This is due to the difficulty of determining if a dot is part of the composite database name or a delimiter for a database alias in a composite database. -==== - -.Query -[source, cypher] ----- -CREATE COMPOSITE DATABASE inventory ----- - -[role="statsonlyqueryresult"] -0 rows, System updates: 1 - -When a composite database has been created, it will show up in the listing provided by the command `SHOW DATABASES`. - - -.Query -[source, cypher] ----- -SHOW DATABASES YIELD name, type, access, role, writer, constituents ----- - -.Result -[role="queryresult",options="header,footer",cols="6*+ | +false+ | +[]+ -| +"library"+ | +"composite"+ | +"read-only"+ | ++ | +false+ | +["library.sci-fi","library.romance"]+ -| +"movies"+ | +"standard"+ | +"read-write"+ | +"primary"+ | +true+ | +[]+ -| +"neo4j"+ | +"standard"+ | +"read-write"+ | +"primary"+ | +true+ | +[]+ -| +"romance"+ | +"standard"+ | +"read-write"+ | +"primary"+ | +true+ | +[]+ -| +"sci-fi"+ | +"standard"+ | +"read-write"+ | +"primary"+ | +true+ | +[]+ -| +"system"+ | +"system"+ | +"read-write"+ | +"primary"+ | +true+ | +[]+ -| +"topology-example"+ | +"standard"+ | +"read-write"+ | +"primary"+ | +true+ | +[]+ -6+d|Rows: 8 -|=== - -In order to create database aliases in the composite database, give the composite database as namespace for the alias. -For information about creating aliases in composite databases, see xref:administration/aliases.adoc#alias-management-create-composite-database-alias[here]. - - -[role=enterprise-edition not-on-aura] -[[administration-databases-create-database-existing]] -=== Handling Existing Databases - -These commands are optionally idempotent, with the default behavior to fail with an error if the database already exists. -Appending `IF NOT EXISTS` to the command ensures that no error is returned and nothing happens should the database already exist. -Adding `OR REPLACE` to the command will result in any existing database being deleted and a new one created. - -These behavior flags apply to both standard and composite databases (e.g. a composite database may replace a standard one or another composite.) - - -.+CREATE DATABASE+ -====== - -.Query -[source, cypher] ----- -CREATE COMPOSITE DATABASE customers IF NOT EXISTS ----- - - -====== - - -.+CREATE OR REPLACE DATABASE+ -====== - -.Query -[source, cypher] ----- -CREATE OR REPLACE DATABASE customers ----- - -This is equivalent to running `DROP DATABASE customers IF EXISTS` followed by `CREATE DATABASE customers`. - -[NOTE] -==== -The `IF NOT EXISTS` and `OR REPLACE` parts of these commands cannot be used together. -==== - -====== - - -[role=enterprise-edition not-on-aura] -[[administration-databases-create-database-options]] -=== Options - -The `CREATE DATABASE` command can have a map of options, e.g. `OPTIONS {key: 'value'}`. - -[NOTE] -==== -There are no available `OPTIONS` values for composite databases. -==== - - -[options="header"] -|=== - -| Key | Value | Description - -| `existingData` -| `use` -| -Controls how the system handles existing data on disk when creating the database. -Currently this is only supported with `existingDataSeedInstance` and must be set to `use` which indicates the existing data files should be used for the new database. - -| `existingDataSeedInstance` -| ID of the cluster server -| -Defines which server is used for seeding the data of the created database. -The server ID can be found in the `serverId` column after running `SHOW SERVERS`. - -| `seedURI` -| URI to a backup or a dump from an existing database. -| -Defines an identical seed from an external source which will be used to seed all servers. - -| `seedConfig` -| comma separated list of configuration values. -| -Defines additional configuration specified by comma separated `name=value` pairs that might be required by certain seed providers. - -| `seedCredentials` -| credentials -| -Defines credentials that needs to be passed into certain seed providers. - -|=== - - -[NOTE] -==== -The `existingData`, `existingDataSeedInstance`, `seedURI`, `seedConfig` and `seedCredentials` options cannot be combined with the `OR REPLACE` part of this command. -For details about the use of these seeding options, see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/clustering/databases/#cluster-seed[Operations Manual -> Seed a cluster]. -==== - - -[role=enterprise-edition not-on-aura] -[[administration-databases-alter-database]] -== Altering databases - -Standard databases can be modified using the command `ALTER DATABASE`. - -[role=enterprise-edition not-on-aura] -[[administration-databases-alter-database-access]] -=== Access - -By default, a database has read-write access mode on creation. -The database can be limited to read-only mode on creation using the configuration parameters `dbms.databases.default_to_read_only`, `dbms.databases.read_only`, and `dbms.database.writable`. -For details, see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/manage-databases/configuration#manage_database_parameters[Configuration parameters]. - -A database that was created with read-write access mode can be changed to read-only. -To change it to read-only, you can use the `ALTER DATABASE` command with the sub-clause `SET ACCESS READ ONLY`. -Subsequently, the database access mode can be switched back to read-write using the sub-clause `SET ACCESS READ WRITE`. -Altering the database access mode is allowed at all times, whether a database is online or offline. - -If conflicting modes are set by the `ALTER DATABASE` command and the configuration parameters, i.e. one says read-write and the other read-only, the database will be read-only and prevent write queries. - -[NOTE] -==== -Modifying access mode is only available to standard databases and not composite databases. -==== - - -.+ALTER DATABASE+ -====== - -.Query -[source, cypher] ----- -ALTER DATABASE customers SET ACCESS READ ONLY ----- - -.Result -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -====== - - -.+SHOW DATABASES+ -====== - -The database access mode can be seen in the `access` output column of the command `SHOW DATABASES`. - -.Query -[source, cypher] ----- -SHOW DATABASES yield name, access ----- - -.Result -[role="queryresult",options="header,footer",cols="2* Alter topology] for more information. -==== - - -.+SHOW DATABASE+ -====== - -.Query -[source, cypher] ----- -SHOW DATABASES yield name, currentPrimariesCount, currentSecondariesCount, requestedPrimariesCount, requestedSecondariesCount ----- - -====== - -For more details on primary and secondary server roles, see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/clustering/introduction#clustering-introduction-operational[Operations Manual -> Clustering overview]. - -[NOTE] -==== -Modifying database topology is only available to standard databases and not composite databases. -==== - -`ALTER DATABASE` commands are optionally idempotent, with the default behavior to fail with an error if the database does not exist. -Appending `IF EXISTS` to the command ensures that no error is returned and nothing happens should the database not exist. - -.Query -[source, cypher] ----- -ALTER DATABASE nonExisting IF EXISTS SET TOPOLOGY 1 PRIMARY 0 SECONDARY ----- - -[role="statsonlyqueryresult"] -0 rows - - -[role=enterprise-edition not-on-aura] -[[administration-databases-stop-database]] -== Stopping databases - -Databases can be stopped using the command `STOP DATABASE`. - - -.+STOP DATABASE+ -====== - -.Query -[source, cypher] ----- -STOP DATABASE customers ----- - -.Result -[source, result, role="noheader"] ----- -System updates: 1 -Rows: 0 ----- - -[NOTE] -==== -Both standard databases and composite databases can be stopped using this command. -==== - -====== - - -.+SHOW DATABASE+ -====== - -The status of the stopped database can be seen using the command `SHOW DATABASE name`. - -.Query -[source, cypher] ----- -SHOW DATABASE customers YIELD name, requestedStatus, currentStatus ----- - -.Result -[role="queryresult",options="header,footer",cols="3*/data/dumps`). -This can be achieved by appending `DUMP DATA` to the command (or `DESTROY DATA` to explicitly request the default behavior). -These dumps are equivalent to those produced by `neo4j-admin dump` and can be similarly restored using `neo4j-admin load`. - -.Query -[source, cypher] ----- -DROP DATABASE `topology-example` DUMP DATA ----- - -The options `IF EXISTS` and `DUMP DATA`/ `DESTROY DATA` can also be combined. -An example could look like this: - -.Query -[source, cypher] ----- -DROP DATABASE customers IF EXISTS DUMP DATA ----- - -====== - -It is also possible to ensure that only composite databases are dropped. A `DROP COMPOSITE` request would then fail if the targeted database is a standard database. - -.+DROP COMPOSITE DATABASE+ -====== - -.Query -[source, cypher] ----- -DROP COMPOSITE DATABASE inventory ----- - -[role="statsonlyqueryresult"] -0 rows, System updates: 1 - -To ensure the database to be dropped is standard and not composite, the user first needs to check the `type` column of `SHOW DATABASES` manually. - -====== - - -[role=enterprise-edition not-on-aura] -[[administration-wait-nowait]] -== Wait options - -_The_ `WAIT` _subclause was added as an option to the_ `ALTER DATABASE` _command in Neo4j 5.7._ - -Aside from `SHOW DATABASES`, all database management commands accept an optional `WAIT`/`NOWAIT` clause. -The `WAIT`/`NOWAIT` clause allows you to specify a time limit in which the command must complete and return. - -The options are: - -* `WAIT n SECONDS` - Return once completed or when the specified time limit of `n` seconds is up. -* `WAIT` - Return once completed or when the default time limit of 300 seconds is up. -* `NOWAIT` - Return immediately. - -A command using a `WAIT` clause will automatically commit the current transaction when it executes successfully, as the command needs to run immediately for it to be possible to `WAIT` for it to complete. -Any subsequent commands executed will therefore be performed in a new transaction. -This is different to the usual transactional behavior, and for this reason it is recommended that these commands be run in their own transaction. -The default behavior is `NOWAIT`, so if no clause is specified the transaction will behave normally and the action is performed in the background post-commit. - -[NOTE] -==== -A command with a `WAIT` clause may be interrupted whilst it is waiting to complete. -In this event the command will continue to execute in the background and will not be aborted. -==== - - -.+CREATE DATABASE+ -====== - -.Query -[source, cypher] ----- -CREATE DATABASE slow WAIT 5 SECONDS ----- - -.Result -[role="queryresult",options="header,footer",cols="4*>. - -| Required privilege -a| `GRANT SERVER MANAGEMENT` - -(see xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-server-management[SERVER MANAGEMENT privileges]) -|=== - -[cols="<15s,<85"] -|=== -| Command -m| ALTER SERVER - -| Syntax -a| -[source, syntax, role=noheader] ----- -ALTER SERVER 'name' SET OPTIONS "{" option: value[,...] "}" ----- - -| Description -a| Changes the constraints for a server. -For more information see <>. - -| Required privilege -a| `GRANT SERVER MANAGEMENT` - -(see xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-server-management[SERVER MANAGEMENT privileges]) -|=== - -[cols="<15s,<85"] -|=== -| Command -m| RENAME SERVER - -| Syntax -a| -[source, syntax, role=noheader] ----- -RENAME SERVER 'name' TO 'newName' ----- - -| Description -a| Changes the name of a server. -For more information see <>. - -| Required privilege -a| `GRANT SERVER MANAGEMENT` - -(see xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-server-management[SERVER MANAGEMENT privileges]) -|=== - -[cols="<15s,<85"] -|=== -| Command -m| REALLOCATE DATABASES - -| Syntax -a| -[source, syntax, role=noheader] ----- -[DRYRUN] REALLOCATE DATABASE[S] ----- - -| Description -a| Re-balances databases among the servers in the cluster. -For more information see <>. - -| Required privilege -a| `GRANT SERVER MANAGEMENT` - -(see xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-server-management[SERVER MANAGEMENT privileges]) -|=== - -[cols="<15s,<85"] -|=== -| Command -m| DEALLOCATE DATABASES - -| Syntax -a| -[source, syntax, role=noheader] ----- -[DRYRUN] DEALLOCATE DATABASE[S] FROM SERVER[S] 'name'[, ...] ----- - -| Description -a| Removes all databases from the given servers. -For more information see <>. - -| Required privilege -a| `GRANT SERVER MANAGEMENT` - -(see xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-server-management[SERVER MANAGEMENT privileges]) -|=== - -[cols="<15s,<85"] -|=== -| Command -m| DROP SERVER - -| Syntax -a| -[source, syntax, role=noheader] ----- -DROP SERVER 'name' ----- - -| Description -a| Removes a server not hosting any databases from the cluster. -For more information see <>. - -| Required privilege -a| `GRANT SERVER MANAGEMENT` - -(see xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-server-management[SERVER MANAGEMENT privileges]) -|=== - -[cols="<15s,<85"] -|=== -| Command -m| SHOW SERVERS - -| Syntax -a| -[source, syntax, role=noheader] ----- -SHOW SERVER[S] - [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] - [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ----- - -| Description -a| Lists all servers visible to the cluster. -For more information see <>. - -| Required privilege -a| `GRANT SHOW SERVERS` - -(see xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-server-management[SERVER MANAGEMENT privileges]) -|=== - -[[server-management-show-servers]] -== Listing servers - -`SHOW SERVERS` displays all servers running in the cluster, including servers that have yet to be enabled as well as dropped servers. - -The table of results shows information about the servers: - -[options="header", width="100%", cols="2a,4,2m,1,1"] -|=== -| Column -| Description -| Type -| Default output -| Full output - -| name -| Name of the server. -| STRING -| {check-mark} -| {check-mark} - -| serverId -| Id of the server. -| STRING -| -| {check-mark} - -| address -| Bolt address of the server (if enabled). -| STRING -| {check-mark} -| {check-mark} - -| httpAddress -| Http address of the server (if enabled). -| STRING -| -| {check-mark} - -| httpsAddress -| Https address of the server (if enabled). -| STRING -| -| {check-mark} - -| state -| Information of the state of the server: `free`, `enabled`, `deallocating`, or `dropped`. -| STRING -| {check-mark} -| {check-mark} - -| health -| The availability of the server: `available` or `unavailable`. -| STRING -| {check-mark} -| {check-mark} - -| hosting -| A list of databases currently hosted on the server. -| LIST -| {check-mark} -| {check-mark} - -| requestedHosting -| A list of databases that should be hosted on the server. -Composite databases do not currently appear in this list, though they do appear in `hosting` for all servers. -| LIST -| -| {check-mark} - -| tags -| Tags are user provided strings that can be used while allocating databases. -| LIST -| -| {check-mark} - -| allowedDatabases -| A list of databases allowed to be hosted on the server. -| LIST -| -| {check-mark} - -| deniedDatabases -| A list of databases not allowed to be hosted on the server. -| LIST -| -| {check-mark} - -| modeConstraint -| Constraint for the allocator to allocate only databases in this mode on the server. -| STRING -| -| {check-mark} - -| version -| Neo4j version the server is running. -| STRING -| -| {check-mark} -|=== - -A summary of all servers can be displayed using the command `SHOW SERVERS`. - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m"] -|=== -|name|address|state|health|hosting - -| "server1" | "localhost:20000" | "Enabled" | "Available" | ["system","neo4j"] -| "server2" | "localhost:20007" | "Enabled" | "Available" | ["system","neo4j"] -| "server3" | "localhost:20014" | "Enabled" | "Available" | ["system","neo4j"] -| "0c030000-267b-49a8-801f-78bd0b5c6445" | "localhost:20021" | "Free" | "Available" | ["system"] -|=== - -[role=not-on-aura] -[[server-management-enable-server]] -== Enabling servers - -A server can be added to the cluster with the `ENABLE SERVER 'name'` command. -The servers initial name is its id. -The server must be in the `free` state to be added to the cluster. -If the server is already `enabled` and the command is executed with the same options specified nothing is changed. -In any other case trying to enable a server fails. - -The possible options allowed when enabling a server are: - -[options="header", width="100%", cols="2a,2,^.^"] -|=== -| Option -| Allowed values -| Description - -| modeConstraint -| `PRIMARY`, `SECONDARY`, `NONE` -| Databases may only be hosted on the server in the mode specified by the constraint. -`None` means there is no constraint and any mode is allowed. - -| allowedDatabases -| list of database names, e.g. `["db1", "db2"]` -| Only databases matching the specified names may be hosted on the server. -This may not be specified in combination with `deniedDatabases`. - -| deniedDatabases -| list of database names, e.g. `["db1", "db2"]` -| Only databases **not** matching the specified names may be hosted on the server. -This may not be specified in combination with `allowedDatabases`. - -| tags -| list of server tags, e.g. `["tag1", "tag2"]` -| List of server tags used during database allocation and for load balancing and routing policies. -label:new[Introduced in 5.6] -|=== - -[NOTE] -==== -Composite databases are ignored by both `allowedDatabases` and `deniedDatabases`. -The composite databases are available everywhere and hold no data on their own. -==== - -[NOTE] -==== -When a server is enabled, if `tags` are not provided in `OPTIONS`, the default server tags are taken from the setting `initial.server.tags`. -==== - -[role=not-on-aura] -[[server-management-alter-server]] -== Modifying servers - -The constraints on a server can be changed with `ALTER SERVER 'name' SET OPTIONS { option: value }`. -Either the name or the id of the server can be used. - -The possible options allowed when altering a server are: - -[options="header", width="100%", cols="2a,2,^.^"] -|=== -| Option -| Allowed values -| Description - -| modeConstraint -| `PRIMARY`, `SECONDARY`, `NONE` -| Databases may only be hosted on the server in the mode specified by the constraint. -`None` means there is no constraint and any mode is allowed. - -| allowedDatabases -| list of database names, e.g. `["db1", "db2"]` -| Only databases matching the specified names may be hosted on the server. -This may not be specified in combination with `deniedDatabases`. - -| deniedDatabases -| list of database names, e.g. `["db1", "db2"]` -| Only databases **not** matching the specified names may be hosted on the server. -This may not be specified in combination with `allowedDatabases`. - -| tags -| list of server tags, e.g. `["tag1", "tag2"]` -| List of server tags used during database allocation and for load balancing and routing policies. -label:new[Introduced in 5.6] -|=== - -[NOTE] -==== -Composite databases are ignored by both `allowedDatabases` and `deniedDatabases`. -The composite databases are available everywhere and hold no data on their own. -==== - -[NOTE] -==== -Input provided to `SET OPTIONS {...}` replaces **all** existing options, rather than being combined with them. -For instance, if `SET OPTIONS {modeConstraint:'SECONDARY'}` is run followed by `SET OPTIONS {allowedDatabases:['foo']}`, the second `ALTER` removes the mode constraint. -==== - -[[server-management-rename-server]] -== Renaming servers - -The name of a server can be altered with `RENAME SERVER 'name' TO 'newName'`. -Either the id or current name of the server can be used to identify the server. -The new name of the server must be unique. - -[[server-management-reallocate]] -== Reallocate databases - -_The_ `DRYRUN` _feature was introduced in Neo4j 5.2._ - -After enabling a server, `REALLOCATE DATABASES` can be used to make the cluster re-balance databases across all servers that are part of the cluster. -Using `DRYRUN REALLOCATE DATABASE` returns a view of how the databases would have been re-balanced if the command was executed without `DRYRUN`: - - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m,m"] -|=== -|database|fromServerName|fromServerId|toServerName|toServerId|mode - -| "db1" | "server-1" | "00000000-94ff-4ede-87be-3d741b795480" | "server-4" | "00000002-25a9-4984-9ad2-dc39024c9238" | "primary" -| "db3" | "server-1" | "00000000-94ff-4ede-87be-3d741b795480" | "server-5" | "00000003-0df7-4057-81fd-1cf43c9ef5f7" | "primary" -|=== - - -[role=not-on-aura] -[[server-management-deallocate]] -== Deallocate databases - -A server can be set to not host any databases with `DEALLOCATE DATABASES FROM SERVER 'name'`, in preparation for removing the server from the cluster. -Either the id or name of the server can be used. -All databases that the server is hosting are moved to other servers. -The server changes state to `deallocating`. -A deallocated server cannot readily be enabled again. - -Multiple servers can be deallocated at the same time, `DEALLOCATE DATABASES FROM SERVER 'server-1', 'server-2'`. -The command fails if there aren't enough servers available to move the databases to. - -Using `DRYRUN DEALLOCATE DATABASES FROM 'server-1', 'server-2'` returns a view of how the databases would have been re-balanced if the command was executed without `DRYRUN`: - -.Result -[options="header,footer", width="100%", cols="m,m,m,m,m,m"] -|=== -|database|fromServerName|fromServerId|toServerName|toServerId|mode -| "db1" | "server-1" | "00000001-8c04-4731-a2fd-7b0289c511ce" | "server-4" | "00000002-5b91-43c1-8b25-5289f674563e" | "primary" -| "db1" | "server-2" | "00000000-7e53-427c-a987-24634c4745f3" | "server-5" | "00000003-0e98-44c8-9844-f0a4eb95b0d8" | "primary" -|=== - -[role=not-on-aura] -[[server-management-drop-server]] -== Drop server - -When a server has been deallocated and is no longer hosting any databases it can be removed from the cluster with `DROP SERVER 'name'`. -Either the id or name of the server can be used. -As long as the server is running, it is listed when showing servers with the state `dropped`. diff --git a/modules/ROOT/pages/query-tuning/advanced-example.adoc b/modules/ROOT/pages/appendix/tutorials/advanced-query-tuning.adoc similarity index 99% rename from modules/ROOT/pages/query-tuning/advanced-example.adoc rename to modules/ROOT/pages/appendix/tutorials/advanced-query-tuning.adoc index 2f70ef8a3..c3b7fa647 100644 --- a/modules/ROOT/pages/query-tuning/advanced-example.adoc +++ b/modules/ROOT/pages/appendix/tutorials/advanced-query-tuning.adoc @@ -1,13 +1,11 @@ :description: Example of some more subtle optimizations based on native index capabilities. - - [[advanced-query-tuning-example]] = Advanced query tuning example This page describes advanced query optimizations based on native index capabilities. One of the most important and useful ways of optimizing Cypher queries involves creating appropriate indexes. -This is described in more detail in xref::indexes-for-search-performance.adoc[], and demonstrated in xref::query-tuning/basic-example.adoc[]. +This is described in more detail in xref::indexes-for-search-performance.adoc[], and demonstrated in xref::appendix/tutorials/basic-query-tuning.adoc[]. In summary, an index will be based on the combination of a `Label` and a `property`. Any Cypher query that searches for nodes with a specific label and some predicate on the property (equality, range or existence) will be planned to use the index if the cost planner deems that to be the most efficient solution. diff --git a/modules/ROOT/pages/query-tuning/basic-example.adoc b/modules/ROOT/pages/appendix/tutorials/basic-query-tuning.adoc similarity index 97% rename from modules/ROOT/pages/query-tuning/basic-example.adoc rename to modules/ROOT/pages/appendix/tutorials/basic-query-tuning.adoc index c7b2478f9..a5ed3db92 100644 --- a/modules/ROOT/pages/query-tuning/basic-example.adoc +++ b/modules/ROOT/pages/appendix/tutorials/basic-query-tuning.adoc @@ -607,7 +607,7 @@ RETURN p This query will find the *'Tom Hanks'* node but as the number of nodes in the database increase it will become slower and slower. We can profile the query to find out why that is. -You can learn more about the options for profiling queries in xref::query-tuning/query-options.adoc[] but in this case you are going to prefix our query with `PROFILE`: +You can learn more about the options for profiling queries in xref::planning-and-tuning/query-tuning/query-options.adoc[] but in this case you are going to prefix our query with `PROFILE`: [source, cypher] ---- @@ -646,9 +646,9 @@ ready to start consuming query after 17 ms, results consumed after another 10 ms The first thing to keep in mind when reading execution plans is that you need to read from the bottom up. In that vein, starting from the last row, the first thing you notice is that the value in the `Rows` column seems high given there is only one node with the name property *'Tom Hanks'* in the database. -If you look across to the `Operator` column, you will see that xref::execution-plans/operators.adoc#query-plan-all-nodes-scan[AllNodesScan] has been used which means that the query planner scanned through all the nodes in the database. +If you look across to the `Operator` column, you will see that xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[AllNodesScan] has been used which means that the query planner scanned through all the nodes in the database. -The xref::execution-plans/operators.adoc#query-plan-filter[Filter] operator which will check the `name` property on each of the nodes passed through by `AllNodesScan`. +The xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-filter[Filter] operator which will check the `name` property on each of the nodes passed through by `AllNodesScan`. This seems like an inefficient way of finding *'Tom Hanks'* given that you are looking at many nodes that are not even people and therefore are not what you are looking for. @@ -700,7 +700,7 @@ Total database accesses: 379, total allocated memory: 184 ---- This time the `Rows` value on the last row has reduced so you are not scanning some nodes that you were before which is a good start. -The xref::execution-plans/operators.adoc#query-plan-node-by-label-scan[NodeByLabelScan] operator indicates that you achieved this by first doing a linear scan of all the `Person` nodes in the database. +The xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-by-label-scan[NodeByLabelScan] operator indicates that you achieved this by first doing a linear scan of all the `Person` nodes in the database. Once you have done that, you can again scan through all those nodes using the `Filter` operator, comparing the name property of each one. @@ -764,5 +764,5 @@ Total database accesses: 5, total allocated memory: 184 1 row ---- -Our execution plan is down to a single row and uses the xref::execution-plans/operators.adoc#query-plan-node-index-seek[Node Index Seek] operator which does an index seek (see xref::indexes-for-search-performance.adoc[]) to find the appropriate node. +Our execution plan is down to a single row and uses the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-index-seek[Node Index Seek] operator which does an index seek (see xref::indexes-for-search-performance.adoc[]) to find the appropriate node. diff --git a/modules/ROOT/pages/appendix/tutorials/index.adoc b/modules/ROOT/pages/appendix/tutorials/index.adoc new file mode 100644 index 000000000..a575df029 --- /dev/null +++ b/modules/ROOT/pages/appendix/tutorials/index.adoc @@ -0,0 +1,6 @@ +:description: List of available tutorials in the Cypher Manual. += Tutorials and extended examples + +* xref:appendix/tutorials/basic-query-tuning.adoc[] +* xref:appendix/tutorials/advanced-query-tuning.adoc[] +* xref:appendix/tutorials/shortestpath-planning.adoc[] - information about how to plan queries using the xref:patterns/concepts.adoc#shortest-path[`shortestPath()` function]. \ No newline at end of file diff --git a/modules/ROOT/pages/execution-plans/shortestpath-planning.adoc b/modules/ROOT/pages/appendix/tutorials/shortestpath-planning.adoc similarity index 99% rename from modules/ROOT/pages/execution-plans/shortestpath-planning.adoc rename to modules/ROOT/pages/appendix/tutorials/shortestpath-planning.adoc index 1f32b3095..ce5ce9703 100644 --- a/modules/ROOT/pages/execution-plans/shortestpath-planning.adoc +++ b/modules/ROOT/pages/appendix/tutorials/shortestpath-planning.adoc @@ -26,7 +26,7 @@ Therefore, in these cases, it is recommended to set `cypher.forbid_exhaustive_sh == Shortest path -- fast algorithm -.Query evaluated with the fast algorithm +.Query evaluated with the fast algorith ====== //// diff --git a/modules/ROOT/pages/clauses/call.adoc b/modules/ROOT/pages/clauses/call.adoc index a74bfe054..f2cf65652 100644 --- a/modules/ROOT/pages/clauses/call.adoc +++ b/modules/ROOT/pages/clauses/call.adoc @@ -135,7 +135,7 @@ The result shows that: [role="queryresult",options="header,footer",cols="1* Database administration] +* link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/[Operations Manual -> Authentication and authorization] +* link:{neo4j-docs-base-uri}/operations-manual/{page-version}/clustering/[Operations Manual -> Clustering] diff --git a/modules/ROOT/pages/clauses/listing-functions.adoc b/modules/ROOT/pages/clauses/listing-functions.adoc index 7c419a99d..0530a6b7c 100644 --- a/modules/ROOT/pages/clauses/listing-functions.adoc +++ b/modules/ROOT/pages/clauses/listing-functions.adoc @@ -55,13 +55,13 @@ m| BOOLEAN m| rolesExecution a| List of roles permitted to execute this function. -Is `null` without the xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. +Is `null` without the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. m| LIST m| rolesBoostedExecution a| List of roles permitted to use boosted mode when executing this function. -Is `null` without the xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. +Is `null` without the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. m| LIST m| isDeprecated @@ -119,7 +119,7 @@ SHOW [ALL|BUILT IN|USER DEFINED] FUNCTION[S] EXECUTABLE BY username [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ---- -Required privilege xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[`SHOW USER`]. +Required privilege link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration#access-control-dbms-administration-user-management[`SHOW USER`]. This command cannot be used for LDAP users. [NOTE] @@ -358,7 +358,7 @@ SHOW FUNCTIONS EXECUTABLE BY CURRENT USER YIELD * 6+d|Rows: 10 |=== -Notice that the two `roles` columns are empty due to missing the xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. +Notice that the two `roles` columns are empty due to missing the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. Also note that the following columns are not present in the table: * `signature` diff --git a/modules/ROOT/pages/clauses/listing-procedures.adoc b/modules/ROOT/pages/clauses/listing-procedures.adoc index bc490e350..be9d2b470 100644 --- a/modules/ROOT/pages/clauses/listing-procedures.adoc +++ b/modules/ROOT/pages/clauses/listing-procedures.adoc @@ -53,13 +53,13 @@ m| BOOLEAN m| rolesExecution a| List of roles permitted to execute this procedure. -Is `null` without the xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. +Is `null` without the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. m| LIST m| rolesBoostedExecution a| List of roles permitted to use boosted mode when executing this procedure. -Is `null` without the xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. +Is `null` without the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. m| LIST m| isDeprecated @@ -122,7 +122,7 @@ SHOW PROCEDURE[S] EXECUTABLE BY username [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ---- -Requires the privilege xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[`SHOW USER`]. +Requires the privilege link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration#access-control-dbms-administration-user-management[`SHOW USER`]. This command cannot be used for LDAP users. [NOTE] @@ -147,6 +147,21 @@ SHOW PROCEDURES |=== | name | description | mode | worksOnSystem +| "cdc.current" +| "Returns the current change identifier that can be used to stream changes from." +| "READ" +| false + +| "cdc.earliest" +| "Returns the earliest change identifier that can be used to stream changes from." +| "READ" +| false + +| "cdc.query" +| "Query changes observed by the provided change identifier." +| "READ" +| false + | "db.awaitIndex" | "Wait for an index to come online (for example: CALL db.awaitIndex("MyIndex", 300))." | "READ" @@ -381,7 +396,7 @@ SHOW PROCEDURES EXECUTABLE BY CURRENT USER YIELD * |=== The above table only displays the first 15 results of the query. -Note that the two `roles` columns are empty due to missing the xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. +Note that the two `roles` columns are empty due to missing the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration#access-control-dbms-administration-role-management[`SHOW ROLE`] privilege. Also note that the following columns are not present in the table: * `mode` @@ -395,7 +410,7 @@ Also note that the following columns are not present in the table: The second option for using the `EXECUTABLE` clause is to filter the list to only contain procedures executable by a specific user. The below example shows the procedures available to the user `jake`, who has been granted the `EXECUTE PROCEDURE dbms.*` privilege by the `admin` of the database. -(More information about `DBMS EXECUTE` privilege administration can be found xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-execute[here]). +(More information about `DBMS EXECUTE` privilege administration can be found in the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration/#access-control-dbms-administration-execute[Operations Manual -> The `DBMS EXECUTE` privileges]). .Query [source, cypher, role=test-result-skip] diff --git a/modules/ROOT/pages/clauses/load-csv.adoc b/modules/ROOT/pages/clauses/load-csv.adoc index b341c2950..526a9ca73 100644 --- a/modules/ROOT/pages/clauses/load-csv.adoc +++ b/modules/ROOT/pages/clauses/load-csv.adoc @@ -18,7 +18,7 @@ * `LOAD CSV` supports resources compressed with _gzip_ and _Deflate_. Additionally `LOAD CSV` supports locally stored CSV files compressed with _ZIP_. * `LOAD CSV` will follow _HTTP_ redirects but for security reasons it will not follow redirects that changes the protocol, for example if the redirect is going from _HTTPS_ to _HTTP_. * `LOAD CSV` is often used in conjunction with the subquery xref:subqueries/subqueries-in-transactions.adoc[`CALL { ... } IN TRANSACTIONS`]. - +* `LOAD CSV` is regulated by the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/load-privileges/[load privileges]. .Configuration settings for file URLs link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.security.allow_csv_import_from_file_urls[dbms.security.allow_csv_import_from_file_urls]:: @@ -220,7 +220,7 @@ This reduces the memory overhead of the transaction state. [NOTE] ==== The query clause `CALL { ... } IN TRANSACTIONS` is only allowed in xref::introduction/cypher_neo4j.adoc#cypher-neo4j-transactions[implicit (auto-commit or `:auto`) transactions]. -For more information, see xref:subqueries/subqueries-in-transactions[Subqueries in transactions]. +For more information, see xref:subqueries/subqueries-in-transactions.adoc[Subqueries in transactions]. ==== .+artists.csv+ diff --git a/modules/ROOT/pages/clauses/match.adoc b/modules/ROOT/pages/clauses/match.adoc index 4195ac4bd..2c4113488 100644 --- a/modules/ROOT/pages/clauses/match.adoc +++ b/modules/ROOT/pages/clauses/match.adoc @@ -24,7 +24,7 @@ Cypher is declarative, and so usually the query itself does not specify the algo Neo4j will automatically work out the best approach to finding start nodes and matching patterns. Predicates in `WHERE` parts can be evaluated before pattern matching, during pattern matching, or after finding matches. However, there are cases where you can influence the decisions taken by the query compiler. -Read more about indexes in xref::indexes-for-search-performance.adoc[], and more about specifying hints to force Neo4j to solve a query in a specific way in xref::query-tuning/using.adoc[Planner hints and the USING keyword]. +Read more about indexes in xref::indexes-for-search-performance.adoc[], and more about specifying hints to force Neo4j to solve a query in a specific way in xref::planning-and-tuning/query-tuning/using.adoc[Planner hints and the USING keyword]. [[match-example-graph]] diff --git a/modules/ROOT/pages/clauses/order-by.adoc b/modules/ROOT/pages/clauses/order-by.adoc index 94bf8597e..973659b66 100644 --- a/modules/ROOT/pages/clauses/order-by.adoc +++ b/modules/ROOT/pages/clauses/order-by.adoc @@ -19,7 +19,7 @@ This last rule is to make sure that `ORDER BY` does not change the results, only The performance of Cypher queries using `ORDER BY` on node properties can be influenced by the existence and use of an index for finding the nodes. If the index can provide the nodes in the order requested in the query, Cypher can avoid the use of an expensive `Sort` operation. -Read more about this capability in xref::query-tuning/advanced-example.adoc#advanced-query-tuning-example-index-backed-order-by[Index-backed ORDER BY]. +Read more about this capability in xref::appendix/tutorials/advanced-query-tuning.adoc#advanced-query-tuning-example-index-backed-order-by[Index-backed ORDER BY]. The following graph is used for the examples below: diff --git a/modules/ROOT/pages/clauses/transaction-clauses.adoc b/modules/ROOT/pages/clauses/transaction-clauses.adoc index 41a6734b1..966ad7709 100644 --- a/modules/ROOT/pages/clauses/transaction-clauses.adoc +++ b/modules/ROOT/pages/clauses/transaction-clauses.adoc @@ -82,11 +82,11 @@ m| MAP m| planner a| The name of the Cypher planner used to plan the query currently executing in this transaction, or an empty string if no query is currently executing. -For details, see xref::query-tuning/index.adoc#cypher-planner[Cypher planner]. +For details, see xref::planning-and-tuning/query-tuning/index.adoc#cypher-planner[Cypher planner]. m| STRING m| runtime -a| The name of the Cypher runtime used by the query currently executing in this transaction, or an empty string if no query is currently executing. For details, see xref::query-tuning/index.adoc#cypher-runtime[Cypher runtime]. +a| The name of the Cypher runtime used by the query currently executing in this transaction, or an empty string if no query is currently executing. For details, see xref::planning-and-tuning/runtimes/index.adoc[Cypher runtime]. m| STRING m| indexes @@ -229,7 +229,7 @@ Transaction IDs must be supplied as one or more comma-separated quoted strings o When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. ==== -A user with the xref::administration/access-control/database-administration.adoc#access-control-database-administration-transaction[`SHOW TRANSACTION`] privilege can view the currently executing transactions in accordance with the privilege grants. +A user with the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/database-administration/#access-control-database-administration-transaction[`SHOW TRANSACTION`] privilege can view the currently executing transactions in accordance with the privilege grants. All users may view all of their own currently executing transactions. @@ -395,7 +395,7 @@ Transaction IDs must be supplied as one or more comma-separated quoted strings o When using the `WHERE` or `RETURN` clauses, the `YIELD` clause is mandatory and must not be omitted. ==== -A user with the xref::administration/access-control/database-administration.adoc#access-control-database-administration-transaction[`TERMINATE TRANSACTION`] privilege can terminate transactions in accordance with the privilege grants. +A user with the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/database-administration/#access-control-database-administration-transaction[`TERMINATE TRANSACTION`] privilege can terminate transactions in accordance with the privilege grants. All users may terminate their own currently executing transactions. diff --git a/modules/ROOT/pages/clauses/use.adoc b/modules/ROOT/pages/clauses/use.adoc index fcc4ec609..9cff87f1e 100644 --- a/modules/ROOT/pages/clauses/use.adoc +++ b/modules/ROOT/pages/clauses/use.adoc @@ -115,3 +115,16 @@ The argument can be any expression that evaluates to the name of a constituent g USE graph.byName($graphName) MATCH (n) RETURN n ---- + +[[query-use-examples-query-composite-database-by-element-id]] +=== Query a composite database constituent using elementId + +The `graph.byElementId()` function (introduced in Neo4j 5.13), can be used in the `USE` clause to resolve a constituent graph to which a given element id belongs. +In the below example, it is assumed that the DBMS contains a composite database constituent, which contains the element id `4:c0a65d96-4993-4b0c-b036-e7ebd9174905:0`. +If the constituent database is not a standard database in the DBMS an error will be thrown: +.Query +[source, cypher, role=test-skip] +---- +USE graph.byElementId("4:c0a65d96-4993-4b0c-b036-e7ebd9174905:0") +MATCH (n) RETURN n +---- diff --git a/modules/ROOT/pages/constraints/syntax.adoc b/modules/ROOT/pages/constraints/syntax.adoc index 8f51a2674..3ef32f1f6 100644 --- a/modules/ROOT/pages/constraints/syntax.adoc +++ b/modules/ROOT/pages/constraints/syntax.adoc @@ -4,11 +4,6 @@ = Syntax :check-mark: icon:check[] -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - [[constraints-syntax-create]] == Syntax for creating constraints @@ -28,7 +23,7 @@ There is no supported index configuration for range indexes. [NOTE] ==== -Creating a constraint requires the xref::administration/access-control/database-administration.adoc#access-control-database-administration-constraints[`CREATE CONSTRAINT` privilege]. +Creating a constraint requires the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/database-administration/#access-control-database-administration-constraints[`CREATE CONSTRAINT` privilege]. ==== [[constraints-syntax-create-node-unique]] @@ -292,7 +287,7 @@ With the `IF EXISTS` flag, no error is thrown and nothing happens should the con [NOTE] ==== -Dropping a constraint requires the xref::administration/access-control/database-administration.adoc#access-control-database-administration-constraints[`DROP CONSTRAINT` privilege]. +Dropping a constraint requires the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/database-administration/#access-control-database-administration-constraints[`DROP CONSTRAINT` privilege]. ==== @@ -303,7 +298,7 @@ List constraints in the database, either all or filtered on constraint type. [NOTE] ==== -Listing constraints requires the xref::administration/access-control/database-administration.adoc#access-control-database-administration-constraints[`SHOW CONSTRAINTS` privilege]. +Listing constraints requires the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/database-administration/#access-control-database-administration-constraints[`DROP CONSTRAINT` privilege][`SHOW CONSTRAINTS` privilege]. ==== The simple version of the command allows for a `WHERE` clause and will give back the default set of output columns: diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index b7bc4940d..56b245105 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -16,6 +16,135 @@ New features are added to the language continuously, and occasionally, some feat This section lists all of the features that have been removed, deprecated, added, or extended in different Cypher versions. Replacement syntax for deprecated and removed features are also indicated. +[[cypher-deprecations-additions-removals-5.13]] +== Neo4j 5.13 + +=== Updated features + +[cols="2", options="header"] +|=== +| Feature +| Details + +a| +label:functionality[] +label:updated[] +[source, cypher, role="noheader"] +---- +SHOW FUNCTIONS YIELD * +SHOW PROCEDURES YIELD * +---- +a| +Updated the `signatures` column in `SHOW FUNCTIONS` and `SHOW PROCEDURES`. + +Procedure signatures now follow the pattern: +`"procedureName(param1 :: TYPE, param2 :: TYPE, .., paramN :: TYPE) :: (returnParam1 :: TYPE, returnParam2, .., returnParamN :: TYPE)"` + +The signature for procedures with no return columns now follows the pattern: +`"procedureName(param1 :: TYPE, param2 :: TYPE, .., paramN :: TYPE)"` + +Function signatures now follow the pattern: +`"functionName(param1 :: TYPE, param2 :: TYPE, .., paramN :: TYPE) :: TYPE"` + +For all available Cypher types, see the section on xref::values-and-types/property-structural-constructed.adoc#types-synonyms[types and their synonyms]. + +|=== + +=== New features + +[cols="2", options="header"] +|=== +| Feature +| Details + +a| +label:functionality[] +label:new[] +label:beta[] + +[source, cypher, role=noheader] +---- +CALL cdc.current() +CALL cdc.earliest() +CALL cdc.query(from, selectors) +---- + +| Introduction of the Change Data Capture (CDC) feature. +For details, see link:{neo4j-docs-base-uri}/cdc/{page-version}/introduction[Change Data Capture]. + +a| +label:functionality[] +label:new[] + +[source, cypher, role=noheader] +---- +RETURN valueType(expr) +---- + +| Introduction of a xref::functions/scalar.adoc#functions-valueType[valueType()] function. +This function returns a `STRING` representation of the most precise value xref::values-and-types/property-structural-constructed.adoc#types-synonyms[type] that the given expression evaluates to. + +a| +label:functionality[] +label:new[] + +[source, cypher, role=noheader] +---- +RETURN char_length(expr) +---- + +| Introduction of a xref::functions/scalar.adoc#functions-char_length[char_length()] function. +This function returns the number of Unicode characters in a `STRING`. It is an alias of the xref::functions/scalar.adoc#functions-size[`size()`] function. + +a| +label:functionality[] +label:new[] + +[source, cypher, role=noheader] +---- +RETURN character_length(expr) +---- + +| Introduction of a xref::functions/scalar.adoc#functions-character_length[character_length()] function. +This function returns the number of Unicode characters in a `STRING`. It is an alias of the xref::functions/scalar.adoc#functions-size[`size()`] function. + +a| +label:functionality[] +label:new[] + +New privilege: +[source, cypher, role=noheader] +---- +GRANT LOAD ON ALL DATA TO `role` +---- + +| New privilege that controls a user's ability to load data. +Unlike other privileges, these are not granted, denied, or revoked on graphs, databases, or the DBMS, but instead on `ALL DATA`. + +a| +label:functionality[] +label:new[] + +[source, cypher, role=noheader] +---- +USE graph.byElementId(elementId :: STRING) +---- + +| New graph function, xref:functions/graph.adoc#functions-graph-by-elementid[graph.byElementId()], that resolves the constituent graph to which a given element id belongs. + +a| +label:functionality[] +label:new[] + +---- +CYPHER runtime = parallel +---- + +| +Introduction of the xref:planning-and-tuning/runtimes/concepts.adoc#runtimes-parallel-runtime[parallel runtime]. +This runtime is designed for analytical, graph-global read queries run on machines with several available CPUs. +|=== + [[cypher-deprecations-additions-removals-5.12]] == Neo4j 5.12 @@ -294,7 +423,7 @@ New operator: `Repeat(Trail)` a| The `Repeat(Trail)` operator is used to solve xref::patterns/concepts.adoc#quantified-path-patterns[quantified path patterns]. -More information can be found xref::execution-plans/operators.adoc#query-plan-repeat[here]. +More information can be found xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-repeat[here]. a| label:functionality[] @@ -417,7 +546,7 @@ New operator: `AssertSameRelationship` a| The `AssertSameRelationship` operator is used to ensure that no relationship property uniqueness constraints are violated in the slotted and interpreted runtime. -More information can be found xref::execution-plans/operators.adoc#query-plan-assert-same-relationship[here]. +More information can be found xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-assert-same-relationship[here]. |=== @@ -557,7 +686,7 @@ label:new[] `server.tag` a| New functionality to change tags at runtime via `ALTER SERVER`. -More information can be found xref::administration/servers.adoc#server-management-alter-server[here]. +More information can be found in the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/clustering/servers#alter-server-options[Operations Manual -> `ALTER SERVER` options]. a| label:functionality[] @@ -666,7 +795,7 @@ New operator: `IntersectionNodeByLabelsScan` a| The `IntersectionNodeByLabelsScan` operator fetches all nodes that have all of the provided labels from the node label index. -More information can be found xref::execution-plans/operators.adoc#query-plan-intersection-node-by-labels-scan[here]. +More information can be found xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-intersection-node-by-labels-scan[here]. |=== @@ -751,7 +880,7 @@ New operator: `NodeByElementIdSeek` a| The `NodeByElementIdSeek` operator reads one or more nodes by ID from the node store, specified via the function xref::functions/scalar.adoc#functions-elementid[elementId()]. -More information can be found xref::execution-plans/operators.adoc#query-plan-node-by-elementid-seek[here]. +More information can be found xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-by-elementid-seek[here]. |=== @@ -3127,7 +3256,7 @@ label:new[] DEFAULT GRAPH ---- a| -New optional part of the Cypher commands for xref:administration/access-control/database-administration.adoc[database privileges]. +New optional part of the Cypher commands for database privileges. a| @@ -3161,8 +3290,7 @@ EXECUTE ---- a| New Cypher commands for administering privileges for executing procedures and user defined functions. -See xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-execute[The DBMS `EXECUTE` privileges]. - +See link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration/#access-control-dbms-administration-execute[The DBMS `EXECUTE` privileges]. a| label:syntax[] @@ -3430,29 +3558,28 @@ New support for `YIELD` and `WHERE` clauses to allow filtering results. a| label:functionality[] label:new[] + -xref:administration/access-control/database-administration.adoc#access-control-database-administration-transaction[TRANSACTION MANAGEMENT] privileges +link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/database-administration/#access-control-database-administration-transaction[TRANSACTION MANAGEMENT] privileges a| New Cypher commands for administering transaction management. a| label:functionality[] label:new[] + -DBMS xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[USER MANAGEMENT] privileges +DBMS link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration/#access-control-dbms-administration-user-management[USER MANAGEMENT] privileges a| New Cypher commands for administering user management. a| label:functionality[] label:new[] + -DBMS xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[DATABASE MANAGEMENT] privileges +DBMS link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration/#access-control-dbms-administration-database-management[DATABASE MANAGEMENT] privileges a| New Cypher commands for administering database management. - a| label:functionality[] label:new[] + -DBMS xref:administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[PRIVILEGE MANAGEMENT] privileges +DBMS link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/dbms-administration/#access-control-dbms-administration-privilege-management[PRIVILEGE MANAGEMENT] privileges a| New Cypher commands for administering privilege management. @@ -3492,7 +3619,7 @@ label:new[] ON DEFAULT DATABASE ---- a| -New optional part of the Cypher commands for xref:administration/access-control/database-administration.adoc[database privileges]. +New optional part of the Cypher commands for database privileges. |=== @@ -3825,21 +3952,21 @@ This Neo4j Enterprise Edition only feature involves a new runtime that has many a| label:functionality[] label:new[] + -xref:administration/databases.adoc[Multi-database administration] +link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/manage-databases/[Multi-database administration] a| New Cypher commands for administering multiple databases. a| label:functionality[] label:new[] + -xref:administration/access-control/index.adoc[Access control] +link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/[Access control] a| New Cypher commands for administering role-based access control. a| label:functionality[] label:new[] + -xref:administration/access-control/manage-privileges.adoc[Fine-grained security] +link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/manage-privileges/[Fine-grained security] a| New Cypher commands for administering dbms, database, graph and sub-graph access control. diff --git a/modules/ROOT/pages/execution-plans/db-hits.adoc b/modules/ROOT/pages/execution-plans/db-hits.adoc deleted file mode 100644 index c0928e432..000000000 --- a/modules/ROOT/pages/execution-plans/db-hits.adoc +++ /dev/null @@ -1,64 +0,0 @@ -:description: Actions that triggers database hits (DBHits). - -[[execution-plans-dbhits]] -= Database hits - -Each operator will send a request to the storage engine to do work such as retrieving or updating data. -A _database hit_ (DBHits) is an abstract unit of this storage engine work. - -These are all the actions that trigger one or more database hits: - -* **Create actions** -** Create a node. -** Create a relationship. -** Create a new node label. -** Create a new relationship type. -** Create a new ID for property keys with the same name. - -* **Delete actions** -** Delete a node. -** Delete a relationship. - -* **Update actions** -** Set one or more labels on a node. -** Remove one or more labels from a node. - -* **Node-specific actions** -** Get a node by its ID. -** Get the degree of a node. -** Determine whether a node is dense. -** Determine whether a label is set on a node. -** Get the labels of a node. -** Get a property of a node. -** Get an existing node label. -** Get the name of a label by its ID, or its ID by its name. - -* **Relationship-specific actions** -** Get a relationship by its ID. -** Get a property of a relationship. -** Get an existing relationship type. -** Get a relationship type name by its ID, or its ID by its name. - -* **General actions** -** Get the name of a property key by its ID, or its ID by the key name. -** Find a node or relationship through an index seek or index scan. -** Find a path in a variable-length expand. -** Find a shortest path. -** Ask the count store for a value. - -* **Schema actions** -** Add an index. -** Drop an index. -** Get the reference of an index. -** Create a constraint. -** Drop a constraint. - -* Call a procedure. -* Call a user-defined function. - -[NOTE] -==== -The presented value can vary slightly depending on the xref::query-tuning/query-options.adoc#cypher-runtime[Cypher runtime] that was used to execute the query. -In the pipelined runtime the number of _database hits_ will typically be higher since it uses a more accurate way of measuring. -==== - diff --git a/modules/ROOT/pages/execution-plans/index.adoc b/modules/ROOT/pages/execution-plans/index.adoc deleted file mode 100644 index 2c72d57cf..000000000 --- a/modules/ROOT/pages/execution-plans/index.adoc +++ /dev/null @@ -1,91 +0,0 @@ -:description: Characteristics of query execution plans and provides details about each of the operators. - -[[execution-plans]] -= Execution plans - -This page describes the characteristics of query execution plans and provides details about each of the operators. - -[NOTE] -==== -For information on replanning, see xref:query-tuning/query-options.adoc#cypher-replanning[Cypher replanning]. -==== - -[[execution-plan-introduction]] -.Introduction -The task of executing a query is decomposed into _operators_, each of which implements a specific piece of work. -The operators are combined into a tree-like structure called an _execution plan_. -Each operator in the execution plan is represented as a node in the tree. -Each operator takes as input zero or more rows, and produces as output zero or more rows. -This means that the output from one operator becomes the input for the next operator. -Operators that join two branches in the tree combine input from two incoming streams and produce a single output. - -.Evaluation model -Evaluation of the execution plan begins at the leaf nodes of the tree. -Leaf nodes have no input rows and generally comprise operators such as scans and seeks. -These operators obtain the data directly from the storage engine, thus incurring xref::execution-plans/db-hits.adoc[database hits]. -Any rows produced by leaf nodes are then piped into their parent nodes, which in turn pipe their output rows to their parent nodes and so on, all the way up to the root node. -The root node produces the final results of the query. - -[[eagerness-laziness]] -.Eager and lazy evaluation -In general, query evaluation is _lazy_: most operators pipe their output rows to their parent operators as soon as they are produced. -This means that a child operator may not be fully exhausted before the parent operator starts consuming the input rows produced by the child. - -However, some operators, such as those used for aggregation and sorting, need to aggregate all their rows before they can produce output. -Such operators need to complete execution in its entirety before any rows are sent to their parents as input. -These operators are called _eager_ operators, and are denoted as such in xref::execution-plans/operator-summary.adoc[]. -Eagerness can cause high memory usage and may therefore be the cause of query performance issues. - -[[id-column]] -.IDs -Each operator is assigned a unique ID, which is shown in the execution plan. -The IDs can be used to refer unambiguously to operators. -There are no guarantees about the order of IDs, although they will usually start with 0 at the root, and will increase towards the leaves of the tree. - -.Statistics -Each operator is annotated with statistics. - -`Rows`:: -The number of rows that the operator produced. -This is only available if the query was profiled. - -`EstimatedRows`:: -This is the estimated number of rows that is expected to be produced by the operator. -The estimate is an approximate number based on the available statistical information. -The compiler uses this estimate to choose a suitable execution plan. - -`DbHits`:: -Each operator will ask the Neo4j storage engine to do work such as retrieving or updating data. -A _database hit_ is an abstract unit of this storage engine work. -The actions triggering a database hit are listed in xref::execution-plans/db-hits.adoc[]. - -`Page Cache Hits`, `Page Cache Misses`, `Page Cache Hit Ratio`:: -These metrics are only shown for some queries when using Neo4j Enterprise Edition. -The page cache is used to cache data and avoid accessing disk, so having a high number of `hits` and a low number of `misses` will typically make the query run faster. -Whenever several operators are fused together for more efficient execution we can no longer associate this metric with a given operator and then nothing will appear here. - -`Time`:: -`Time` is only shown for some operators when using the `pipelined` runtime. -The number shown is the time in milliseconds it took to execute the given operator. -Whenever several operators are fused together for more efficient execution we can no longer associate a duration with a given operator and then nothing will appear here. - -To produce an efficient plan for a query, the Cypher query planner requires information about the Neo4j database. -This information includes which indexes and constraints are available, as well as various statistics maintained by the database. -The Cypher query planner uses this information to determine which access patterns will produce the best execution plan. - -The statistical information maintained by Neo4j is: - -. The number of nodes having a certain label. -. The number of relationships by type. -. Selectivity per index. -. The number of relationships by type, ending with or starting from a node with a specific label. - -Information about how the statistics are kept up to date, as well as configuration options for managing query replanning and caching, can be found in the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/performance/statistics-execution-plans[Operations Manual -> Statistics and execution plans]. - -xref::query-tuning/index.adoc[] describes how to tune Cypher queries. -In particular, see xref::query-tuning/query-profile.adoc[] for how to view the execution plan for a query and xref::query-tuning/using.adoc[Planner hints and the USING keyword] for how to use _hints_ to influence the decisions of the planner when building an execution plan for a query. - -For a deeper understanding of how each operator works, refer to xref::execution-plans/operator-summary.adoc[] and the linked sections per operator. -Please remember that the statistics of the particular database where the queries run will decide the plan used. -There is no guarantee that a specific query will always be solved with the same plan. - diff --git a/modules/ROOT/pages/execution-plans/operator-summary.adoc b/modules/ROOT/pages/execution-plans/operator-summary.adoc deleted file mode 100644 index 3177fbb9f..000000000 --- a/modules/ROOT/pages/execution-plans/operator-summary.adoc +++ /dev/null @@ -1,731 +0,0 @@ -:description: Exection plan operators at a glance. - -[[execution-plan-operators]] -= Execution plan operators - -This section contains a summary of the execution plan operators. - -The below table comprises all the execution plan operators ordered lexicographically. - -* _Leaf_ operators, in most cases, locate the starting nodes and relationships required in order to execute the query. - -* _Updating_ operators are used in queries that update the graph. - -* _Eager_ operators xref::execution-plans/index.adoc#eagerness-laziness[accumulate all their rows] before piping them to the next operator. - -[cols="35a,35a,6,10,14", options="header"] -|=== -| Name | Description | Leaf? | Updating? | Considerations - -| xref::execution-plans/operators.adoc#query-plan-all-nodes-scan[AllNodesScan] -| Reads all nodes from the node store. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-anti[Anti] -| Tests for the absence of a pattern. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-anti-semi-apply[AntiSemiApply] -a| -Performs a nested loop. -Tests for the absence of a pattern predicate. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-apply[Apply] -| Performs a nested loop. Yields rows from both the left-hand and right-hand side operators. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-argument[Argument] -| Indicates the variable to be used as an argument to the right-hand side of an `Apply` operator. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-assert-same-node[AssertSameNode] -| Ensures that no node property uniqueness constraints are violated. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-assert-same-relationship[AssertSameRelationship] -| Ensures that no relationship property uniqueness constraints are violated. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-asserting-multi-node-index-seek[AssertingMultiNodeIndexSeek] -| Used to ensure that no property uniqueness constraints are violated. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-cache-properties[CacheProperties] -| Reads node or relationship properties and caches them. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-cartesian-product[CartesianProduct] -| Produces a cartesian product of the inputs from the left-hand and right-hand operators. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-create[Create] -| Creates nodes and relationships. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-create-index[CreateIndex] -| Creates an index for either nodes or relationships. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-create-constraint[CreateConstraint] -| Creates a constraint for either nodes or relationships. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-delete[Delete] -| Deletes a node or relationship. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-detach-delete[DetachDelete] -| Deletes a node and its relationships. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-directed-all-relationships-scan[DirectedAllRelationshipsScan] -| Fetches all relationships and their start and end nodes in the database. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-directed-relationship-by-id-seek[DirectedRelationshipByIdSeek] -| Reads one or more relationships by id from the relationship store. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-directed-relationship-index-contains-scan[DirectedRelationshipIndexContainsScan] -| Examines all values stored in an index, searching for entries containing a specific string; for example, in queries including `CONTAINS`. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-directed-relationship-index-ends-with-scan[DirectedRelationshipIndexEndsWithScan] -| Examines all values stored in an index, searching for entries ending in a specific string; for example, in queries containing `ENDS WITH`. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-directed-relationship-index-scan[DirectedRelationshipIndexScan] -| Examines all values stored in an index, returning all relationships and their start and end nodes with a particular relationship type and a specified property. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-directed-relationship-index-seek[DirectedRelationshipIndexSeek] -| Finds relationships and their start and end nodes using an index seek. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-directed-relationship-index-seek-by-range[DirectedRelationshipIndexSeekByRange] -| Finds relationships and their start and end nodes using an index seek where the value of the property matches a given prefix string. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-directed-relationship-type-scan[DirectedRelationshipTypeScan] -| Fetches all relationships and their start and end nodes with a specific type from the relationship type index. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-directed-union-relationship-types-scan[DirectedUnionRelationshipTypesScan] -| Fetches all relationships and their start and end nodes with at least one of the provided types from the relationship type index. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-distinct[Distinct] -| Drops duplicate rows from the incoming stream of rows. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-do-nothing-if-exists-constraint[DoNothingIfExists(CONSTRAINT)] -| Checks if a constraint already exists, if it does then it stops the execution, if not it continues. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-do-nothing-if-exists-index[DoNothingIfExists(INDEX)] -| Checks if an index already exists, if it does then it stops the execution, if not it continues. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-drop-constraint[DropConstraint] -| Drops a constraint using its name. -| label:yes[] -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-drop-index[DropIndex] -| Drops an index using its name. -| label:yes[] -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-eager[Eager] -| For isolation purposes, `Eager` ensures that operations affecting subsequent operations are executed fully for the whole dataset before continuing execution. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-eager-aggregation[EagerAggregation] -| Evaluates a grouping expression. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-empty-result[EmptyResult] -| Eagerly loads all incoming data and discards it. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-empty-row[EmptyRow] -| Returns a single row with no columns. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-exhaustive-limit[ExhaustiveLimit] -a| -The `ExhaustiveLimit` operator is similar to the `Limit` operator, but always exhausts the input. -Used when combining `LIMIT` and updates. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-expand-all[Expand(All)] -| Traverses incoming or outgoing relationships from a given node. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-expand-into[Expand(Into)] -| Finds all relationships between two nodes. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-filter[Filter] -| Filters each row coming from the child operator, only passing through rows that evaluate the predicates to `true`. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-foreach[Foreach] -a| -Performs a nested loop. -Yields rows from the left-hand operator and discards rows from the right-hand operator. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-intersection-node-by-labels-scan[IntersectionNodeByLabelsScan] -| Fetches all nodes that have all of the provided labels from the node label index. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-let-anti-semi-apply[LetAntiSemiApply] -a| -Performs a nested loop. -Tests for the absence of a pattern predicate in queries containing multiple pattern predicates. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-let-select-or-anti-semi-apply[LetSelectOrAntiSemiApply] -a| -Performs a nested loop. -Tests for the absence of a pattern predicate that is combined with other predicates. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-let-select-or-semi-apply[LetSelectOrSemiApply] -a| -Performs a nested loop. -Tests for the presence of a pattern predicate that is combined with other predicates. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-let-semi-apply[LetSemiApply] -a| -Performs a nested loop. -Tests for the presence of a pattern predicate in queries containing multiple pattern predicates. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-limit[Limit] -| Returns the first `+n+` rows from the incoming input. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-load-csv[LoadCSV] -| Loads data from a CSV source into the query. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-locking-merge[LockingMerge] -| Similar to the `Merge` operator but will lock the start and end node when creating a relationship if necessary. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-merge[Merge] -| The `Merge` operator will either read or create nodes and/or relationships. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-multi-node-index-seek[MultiNodeIndexSeek] -| Finds nodes using multiple index seeks. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-by-elementid-seek[NodeByElementIdSeek] -| Reads one or more nodes by ID from the node store, specified via the function xref::functions/scalar.adoc#functions-elementid[elementId()]. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-by-id-seek[NodeByIdSeek] -| Reads one or more nodes by ID from the node store, specified via the function xref::functions/scalar.adoc#functions-id[id()]. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-by-label-scan[NodeByLabelScan] -| Fetches all nodes with a specific label from the node label index. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-count-from-count-store[NodeCountFromCountStore] -| Uses the count store to answer questions about node counts. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-hash-join[NodeHashJoin] -| Executes a hash join on node ID. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-node-index-contains-scan[NodeIndexContainsScan] -| Examines all values stored in an index, searching for entries containing a specific string. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-index-ends-with-scan[NodeIndexEndsWithScan] -| Examines all values stored in an index, searching for entries ending in a specific string. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-index-scan[NodeIndexScan] -| Examines all values stored in an index, returning all nodes with a particular label with a specified property. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-index-seek[NodeIndexSeek] -| Finds nodes using an index seek. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-index-seek-by-range[NodeIndexSeekByRange] -| Finds nodes using an index seek where the value of the property matches the given prefix string. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-left-right-outer-hash-join[NodeLeftOuterHashJoin] -| Executes a left outer hash join. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-node-left-right-outer-hash-join[NodeRightOuterHashJoin] -| Executes a right outer hash join. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-node-unique-index-seek[NodeUniqueIndexSeek] -| Finds nodes using an index seek within a unique index. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-node-unique-index-seek-by-range[NodeUniqueIndexSeekByRange] -| Finds nodes using an index seek within a unique index where the value of the property matches the given prefix string. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-optional[Optional] -| Yields a single row with all columns set to `null` if no data is returned by its source. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-optional-expand-all[OptionalExpand(All)] -| Traverses relationships from a given node, producing a single row with the relationship and end node set to `null` if the predicates are not fulfilled. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-optional-expand-into[OptionalExpand(Into)] -| Traverses all relationships between two nodes, producing a single row with the relationship and end node set to `null` if no matching relationships are found (the start node is the node with the smallest degree). -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-ordered-aggregation[OrderedAggregation] -a| -Like `EagerAggregation` but relies on the ordering of incoming rows. -Is not eager. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-ordered-distinct[OrderedDistinct] -| Like `Distinct` but relies on the ordering of incoming rows. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-partial-sort[PartialSort] -| Sorts a row by multiple columns if there is already an ordering. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-partial-top[PartialTop] -| Returns the first `+n+` rows sorted by multiple columns if there is already an ordering. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-procedure-call[ProcedureCall] -| Calls a procedure. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-produce-results[ProduceResults] -| Prepares the result so that it is consumable by the user. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-project-endpoints[ProjectEndpoints] -| Projects the start and end node of a relationship. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-projection[Projection] -| Evaluates a set of expressions, producing a row with the results thereof. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-relationship-count-from-count-store[RelationshipCountFromCountStore] -| Uses the count store to answer questions about relationship counts. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-repeat[Repeat(Trail)] -| Solves quantified path patterns. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-remove-labels[RemoveLabels] -| Deletes labels from a node. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-roll-up-apply[RollUpApply] -a| -Performs a nested loop. -Executes a pattern expression or pattern comprehension. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-select-or-anti-semi-apply[SelectOrAntiSemiApply] -a| -Performs a nested loop. -Tests for the absence of a pattern predicate if an expression predicate evaluates to `false`. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-select-or-semi-apply[SelectOrSemiApply] -| Performs a nested loop. Tests for the presence of a pattern predicate if an expression predicate evaluates to `false`. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-semi-apply[SemiApply] -| Performs a nested loop. Tests for the presence of a pattern predicate. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-set-labels[SetLabels] -| Sets labels on a node. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-set-node-properties-from-map[SetNodePropertiesFromMap] -| Sets properties from a map on a node. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-set-property[SetProperty] -| Sets a property on a node or relationship. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-set-relationship-properties-from-map[SetRelationshipPropertiesFromMap] -| Sets properties from a map on a relationship. -| -| label:yes[] -| - -| xref::execution-plans/operators.adoc#query-plan-shortest-path[ShortestPath] -| Finds one or all shortest paths between two previously matches node variables. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-show-constraints[ShowConstraints] -| Lists the available constraints. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-show-functions[ShowFunctions] -| Lists the available functions. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-show-indexes[ShowIndexes] -| Lists the available indexes. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-show-procedures[ShowProcedures] -| Lists the available procedures. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-show-settings[ShowSettings] -| Lists the available configuration settings. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-show-transactions[ShowTransactions] -| Lists the available transactions on the current server. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-skip[Skip] -| Skips `+n+` rows from the incoming rows. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-sort[Sort] -| Sorts rows by a provided key. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-terminate-transactions[TerminateTransactions] -| Terminate transactions with the given IDs. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-top[Top] -| Returns the first 'n' rows sorted by a provided key. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-triadic-build[TriadicBuild] -| The `TriadicBuild` operator is used in conjunction with `TriadicFilter` to solve triangular queries. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-triadic-filter[TriadicFilter] -| The `TriadicFilter` operator is used in conjunction with `TriadicBuild` to solve triangular queries. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-triadic-selection[TriadicSelection] -| Solves triangular queries, such as the very common 'find my friend-of-friends that are not already my friend'. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-undirected-all-relationships-scan[UndirectedAllRelationshipsScan] -| Fetches all relationships and their start and end nodes in the database. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-undirected-relationship-by-id-seek[UndirectedRelationshipByIdSeek] -| Reads one or more relationships by ID from the relationship store. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-undirected-relationship-index-contains-scan[UndirectedRelationshipIndexContainsScan] -| Examines all values stored in an index, searching for entries containing a specific string; for example, in queries including `CONTAINS`. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-undirected-relationship-index-ends-with-scan[UndirectedRelationshipIndexEndsWithScan] -| Examines all values stored in an index, searching for entries ending in a specific string; for example, in queries containing `ENDS WITH`. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-undirected-relationship-index-scan[UndirectedRelationshipIndexScan] -| Examines all values stored in an index, returning all relationships and their start and end nodes with a particular relationship type and a specified property. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-undirected-relationship-index-seek[UndirectedRelationshipIndexSeek] -| Finds relationships and their start and end nodes using an index seek. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-undirected-relationship-index-seek-by-range[UndirectedRelationshipIndexSeekByRange] -| Finds relationships and their start and end nodes using an index seek where the value of the property matches a given prefix string. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-undirected-relationship-type-scan[UndirectedRelationshipTypeScan] -| Fetches all relationships and their start and end nodes with a specific type from the relationship type index. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-undirected-union-relationship-types-scan[UndirectedUnionRelationshipTypesScan] -| Fetches all relationships and their start and end nodes with at least one of the provided types from the relationship type index. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-union[Union] -| Concatenates the results from the right-hand operator with the results from the left-hand operator. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-union-node-by-labels-scan[UnionNodeByLabelsScan] -| Fetches all nodes that have at least one of the provided labels from the node label index. -| label:yes[] -| -| - -| xref::execution-plans/operators.adoc#query-plan-unwind[Unwind] -| Returns one row per item in a list. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-value-hash-join[ValueHashJoin] -| Executes a hash join on arbitrary values. -| -| -| label:eager[] - -| xref::execution-plans/operators.adoc#query-plan-varlength-expand-all[VarLengthExpand(All)] -| Traverses variable-length relationships from a given node. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-varlength-expand-into[VarLengthExpand(Into)] -| Finds all variable-length relationships between two nodes. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-varlength-expand-pruning[VarLengthExpand(Pruning)] -| Traverses variable-length relationships from a given node and only returns unique end nodes. -| -| -| - -| xref::execution-plans/operators.adoc#query-plan-varlength-expand-pruning-bfs[VarLengthExpand(Pruning,BFS)] -| Traverses variable-length relationships from a given node and only returns unique end nodes. -| -| -| - -|=== - diff --git a/modules/ROOT/pages/functions/graph.adoc b/modules/ROOT/pages/functions/graph.adoc index a52869f84..1853d3464 100644 --- a/modules/ROOT/pages/functions/graph.adoc +++ b/modules/ROOT/pages/functions/graph.adoc @@ -48,7 +48,7 @@ The names of all graphs on the current composite database are returned. [[functions-graph-propertiesByName]] == graph.propertiesByName() -Returns a map containing the properties associated with the given graph. The properties are set on the <> that adds the graph as a constituent of a composite database. +Returns a map containing the properties associated with the given graph. The properties are set on the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/aliases/manage-aliases-standard-databases/[alias]that adds the graph as a constituent of a composite database. It is only supported on link:{neo4j-docs-base-uri}/operations-manual/{page-version}/composite-databases[composite databases]. .+graph.propertiesByName()+ @@ -132,4 +132,26 @@ RETURN n Returns all nodes from all graphs on the current composite database. -====== \ No newline at end of file +====== + +[[functions-graph-by-elementid]] +== graph.byElementId() + +_This feature was introduced in Neo4j 5.13._ + +The `graph.byElementId()` function is used in the xref:clauses/use.adoc[] clause to resolve a constituent graph to which a given element id belongs. +If the constituent database is not a standard database in the DBMS, an error will be thrown. + +.+graph.byElementId()+ +====== + +In this example, it is assumed that the DBMS contains a composite database constituent, which contains the element id `4:c0a65d96-4993-4b0c-b036-e7ebd9174905:0`. + +.Query +[source, cypher, role=test-skip] +---- +USE graph.byElementId("4:c0a65d96-4993-4b0c-b036-e7ebd9174905:0") +MATCH (n) RETURN n +---- + +====== diff --git a/modules/ROOT/pages/functions/index.adoc b/modules/ROOT/pages/functions/index.adoc index d7c13d46b..5558a3510 100644 --- a/modules/ROOT/pages/functions/index.adoc +++ b/modules/ROOT/pages/functions/index.adoc @@ -52,31 +52,31 @@ These functions return either true or false for the given arguments. | Function | Signature | Description 1.1+| xref::functions/predicate.adoc#functions-all[`all()`] -| `all(variable :: VARIABLE IN list :: LIST OF ANY? WHERE predicate :: ANY?) :: (BOOLEAN?)` +| `all(variable :: VARIABLE IN list :: LIST WHERE predicate :: ANY) :: BOOLEAN` | Returns true if the predicate holds for all elements in the given `LIST`. 1.1+| xref::functions/predicate.adoc#functions-any[`any()`] -| `any(variable :: VARIABLE IN list :: LIST OF ANY? WHERE predicate :: ANY?) :: (BOOLEAN?)` +| `any(variable :: VARIABLE IN list :: LIST WHERE predicate :: ANY) :: BOOLEAN` | Returns true if the predicate holds for at least one element in the given `LIST`. 1.1+| xref::functions/predicate.adoc#functions-exists[`exists()`] -| `exists(input :: ANY?) :: (BOOLEAN?)` +| `exists(input :: ANY) :: BOOLEAN` | Returns `true` if a match for the pattern exists in the graph. 1.3+| xref::functions/predicate.adoc#functions-isempty[`isEmpty()`] -| `isEmpty(input :: LIST? OF ANY?) :: (BOOLEAN?)` +| `isEmpty(input :: LIST) :: BOOLEAN` | Checks whether a `LIST` is empty. -| `isEmpty(input :: MAP?) :: (BOOLEAN?)` +| `isEmpty(input :: MAP) :: BOOLEAN` | Checks whether a `MAP` is empty. -| `isEmpty(input :: STRING?) :: (BOOLEAN?)` +| `isEmpty(input :: STRING) :: BOOLEAN` | Checks whether a `STRING` is empty. 1.1+| xref::functions/predicate.adoc#functions-none[`none()`] -| `none(variable :: VARIABLE IN list :: LIST OF ANY? WHERE predicate :: ANY?) :: (BOOLEAN?)` +| `none(variable :: VARIABLE IN list :: LIST WHERE predicate :: ANY) :: BOOLEAN` | Returns true if the predicate holds for no element in the given `LIST`. 1.1+| xref::functions/predicate.adoc#functions-single[`single()`] -| `single(variable :: VARIABLE IN list :: LIST OF ANY? WHERE predicate :: ANY?) :: (BOOLEAN?)` +| `single(variable :: VARIABLE IN list :: LIST WHERE predicate :: ANY) :: BOOLEAN` | Returns true if the predicate holds for exactly one of the elements in the given `LIST`. |=== @@ -91,92 +91,105 @@ These functions return a single value. |=== | Function | Signature | Description +1.1+| xref::functions/scalar.adoc#functions-char_length[`char_length()`] +| `char_length(input :: STRING) :: INTEGER` +| Returns the number of Unicode characters in a `STRING`. +label:new[Introduced in 5.13] + +1.1+| xref::functions/scalar.adoc#functions-character_length[`character_length()`] +| `character_length(input :: STRING) :: INTEGER` +| Returns the number of Unicode characters in a `STRING`. +label:new[Introduced in 5.13] 1.1+| xref::functions/scalar.adoc#functions-coalesce[`coalesce()`] -| `coalesce(input :: ANY?) :: (ANY?)` +| `coalesce(input :: ANY) :: ANY` | Returns the first non-null value in a list of expressions. 1.1+| xref::functions/scalar.adoc#functions-endnode[`endNode()`] -| `endNode(input :: RELATIONSHIP?) :: (NODE?)` +| `endNode(input :: RELATIONSHIP) :: NODE` | Returns the end `NODE` of a `RELATIONSHIP`. 1.1+| xref::functions/scalar.adoc#functions-head[`head()`] -| `head(list :: LIST? OF ANY?) :: (ANY?)` +| `head(list :: LIST) :: ANY` | Returns the first element in a `LIST`. 1.2+| xref::functions/scalar.adoc#functions-id[`id()`] -| `id(input :: NODE?) :: (INTEGER?)` +| `id(input :: NODE) :: INTEGER` | label:deprecated[] Returns the id of a `NODE`. Replaced by `elementId()` -| `id(input :: RELATIONSHIP?) :: (INTEGER?)` +| `id(input :: RELATIONSHIP) :: INTEGER` | label:deprecated[] Returns the id of a `RELATIONSHIP`. Replaced by `elementId()`. 1.1+| xref::functions/scalar.adoc#functions-last[`last()`] -| `last(list :: LIST? OF ANY?) :: (ANY?)` +| `last(list :: LIST) :: ANY` | Returns the last element in a `LIST`. 1.1+| xref::functions/scalar.adoc#functions-length[`length()`] -| `length(input :: PATH?) :: (INTEGER?)` +| `length(input :: PATH) :: INTEGER` | Returns the length of a `PATH`. 1.3+| xref::functions/scalar.adoc#functions-properties[`properties()`] -| `properties(input :: MAP?) :: (MAP?)` +| `properties(input :: MAP) :: MAP` | Returns a `MAP` containing all the properties of a `MAP`. -| `properties(input :: NODE?) :: (MAP?)` +| `properties(input :: NODE) :: MAP` | Returns a `MAP` containing all the properties of a `NODE`. -| `properties(input :: RELATIONSHIP?) :: (MAP?)` +| `properties(input :: RELATIONSHIP) :: MAP` | Returns a `MAP` containing all the properties of a `RELATIONSHIP`. 1.1+| xref::functions/scalar.adoc#functions-randomuuid[`randomUUID()`] -| `randomUUID() :: (STRING?)` +| `randomUUID() :: STRING` | Generates a random UUID. 1.2+| xref::functions/scalar.adoc#functions-size[`size()`] -| `size(input :: LIST? OF ANY?) :: (INTEGER?)` +| `size(input :: LIST) :: INTEGER` | Returns the number of items in a `LIST`. -| `size(input :: STRING?) :: (INTEGER?)` +| `size(input :: STRING) :: INTEGER` | Returns the number of Unicode characters in a `STRING`. 1.1+| xref::functions/scalar.adoc#functions-startnode[`startNode()`] -| `startNode(input :: RELATIONSHIP?) :: (NODE?)` +| `startNode(input :: RELATIONSHIP) :: NODE` | Returns the start `NODE` of a `RELATIONSHIP`. 1.3+| xref::functions/scalar.adoc#functions-toboolean[`toBoolean()`] -| `toBoolean(input :: STRING?) :: (BOOLEAN?)` +| `toBoolean(input :: STRING) :: BOOLEAN` | Converts a `STRING` value to a `BOOLEAN` value. -| `toBoolean(input :: BOOLEAN?) :: (BOOLEAN?)` +| `toBoolean(input :: BOOLEAN) :: BOOLEAN` | Converts a `BOOLEAN` value to a `BOOLEAN` value. -| `toBoolean(input :: INTEGER?) :: (BOOLEAN?)` +| `toBoolean(input :: INTEGER) :: BOOLEAN` | Converts an `INTEGER` value to a `BOOLEAN` value. 1.1+| xref::functions/scalar.adoc#functions-tobooleanornull[`toBooleanOrNull()`] -| `toBooleanOrNull(input :: ANY?) :: (BOOLEAN?)` +| `toBooleanOrNull(input :: ANY) :: BOOLEAN` | Converts a value to a `BOOLEAN` value, or null if the value cannot be converted. 1.2+| xref::functions/scalar.adoc#functions-tofloat[`toFloat()`] -| `toFloat(input :: NUMBER?) :: (FLOAT?)` +| `toFloat(input :: INTEGER \| FLOAT) :: FLOAT` | Converts an `INTEGER` value to a `FLOAT` value. -| `toFloat(input :: STRING?) :: (FLOAT?)` +| `toFloat(input :: STRING) :: FLOAT` | Converts a `STRING` value to a `FLOAT` value. 1.1+| xref::functions/scalar.adoc#functions-tofloatornull[`toFloatOrNull()`] -| `toFloatOrNull(input :: ANY?) :: (FLOAT?)` +| `toFloatOrNull(input :: ANY) :: FLOAT` | Converts a value to a `FLOAT` value, or null if the value cannot be converted. 1.3+| xref::functions/scalar.adoc#functions-tointeger[`toInteger()`] -| `toInteger(input :: NUMBER?) :: (INTEGER?)` +| `toInteger(input :: INTEGER \| FLOAT) :: INTEGER` | Converts a `FLOAT` value to an `INTEGER` value. -| `toInteger(input :: BOOLEAN?) :: (INTEGER?)` +| `toInteger(input :: BOOLEAN) :: INTEGER` | Converts a `BOOLEAN` value to an `INTEGER` value. -| `toInteger(input :: STRING?) :: (INTEGER?)` +| `toInteger(input :: STRING) :: INTEGER` | Converts a `STRING` value to an `INTEGER` value. 1.1+| xref::functions/scalar.adoc#functions-tointegerornull[`toIntegerOrNull()`] -| `toIntegerOrNull(input :: ANY?) :: (INTEGER?)` +| `toIntegerOrNull(input :: ANY) :: INTEGER` | Converts a value to an `INTEGER` value, or null if the value cannot be converted. 1.1+| xref::functions/scalar.adoc#functions-type[`type()`] -| `type(input :: RELATIONSHIP?) :: (STRING?)` +| `type(input :: RELATIONSHIP) :: STRING` | Returns a `STRING` representation of the `RELATIONSHIP` type. +1.1+| xref::functions/scalar.adoc#functions-valueType[`valueType()`] +| `valueType(input :: ANY?) :: (STRING?)` +| Returns a `STRING` representation of the most precise value type that the given expression evaluates to. + |=== @@ -190,53 +203,53 @@ These functions take multiple values as arguments, and calculate and return an a | Function | Signature | Description 1.3+| xref::functions/aggregating.adoc#functions-avg[`avg()`] -| `avg(input :: DURATION?) :: (DURATION?)` +| `avg(input :: DURATION) :: DURATION` | Returns the average of a set of `DURATION` values. -| `avg(input :: FLOAT?) :: (FLOAT?)` +| `avg(input :: FLOAT) :: FLOAT` | Returns the average of a set of `FLOAT` values. -| `avg(input :: INTEGER?) :: (INTEGER?)` +| `avg(input :: INTEGER) :: INTEGER` | Returns the average of a set of `INTEGER` values. 1.1+| xref::functions/aggregating.adoc#functions-collect[`collect()`] -| `collect(input :: ANY?) :: (LIST? OF ANY?)` +| `collect(input :: ANY) :: LIST` | Returns a list containing the values returned by an expression. 1.1+| xref::functions/aggregating.adoc#functions-count[`count()`] -| `count(input :: ANY?) :: (INTEGER?)` +| `count(input :: ANY) :: INTEGER` | Returns the number of values or rows. 1.1+| xref::functions/aggregating.adoc#functions-max[`max()`] -| `max(input :: ANY?) :: (ANY?)` +| `max(input :: ANY) :: ANY` | Returns the maximum value in a set of values. 1.1+| xref::functions/aggregating.adoc#functions-min[`min()`] -| `min(input :: ANY?) :: (ANY?)` +| `min(input :: ANY) :: ANY` | Returns the minimum value in a set of values. 1.1+| xref::functions/aggregating.adoc#functions-percentilecont[`percentileCont()`] -| `percentileCont(input :: FLOAT?, percentile :: FLOAT?) :: (FLOAT?)` +| `percentileCont(input :: FLOAT, percentile :: FLOAT) :: FLOAT` | Returns the percentile of a value over a group using linear interpolation. 1.2+| xref::functions/aggregating.adoc#functions-percentiledisc[`percentileDisc()`] -| `percentileDisc(input :: FLOAT?, percentile :: FLOAT?) :: (FLOAT?)` +| `percentileDisc(input :: FLOAT, percentile :: FLOAT) :: FLOAT` | Returns the nearest `FLOAT` value to the given percentile over a group using a rounding method. -| `percentileDisc(input :: INTEGER?, percentile :: FLOAT?) :: (INTEGER?)` +| `percentileDisc(input :: INTEGER, percentile :: FLOAT) :: INTEGER` | Returns the nearest `INTEGER` value to the given percentile over a group using a rounding method. 1.1+| xref::functions/aggregating.adoc#functions-stdev[`stdev()`] -| `stdev(input :: FLOAT?) :: (FLOAT?)` +| `stdev(input :: FLOAT) :: FLOAT` | Returns the standard deviation for the given value over a group for a sample of a population. 1.1+| xref::functions/aggregating.adoc#functions-stdevp[`stdevp()`] -| `stdevp(input :: FLOAT?) :: (FLOAT?)` +| `stdevp(input :: FLOAT) :: FLOAT` | Returns the standard deviation for the given value over a group for an entire population. 1.3+| xref::functions/aggregating.adoc#functions-sum[`sum()`] -| `sum(input :: DURATION?) :: (DURATION?)` +| `sum(input :: DURATION) :: DURATION` | Returns the sum of a set of `DURATION` values. -| `sum(input :: FLOAT?) :: (FLOAT?)` +| `sum(input :: FLOAT) :: FLOAT` | Returns the sum of a set of `FLOAT` values. -| `sum(input :: INTEGER?) :: (INTEGER?)` +| `sum(input :: INTEGER) :: INTEGER` | Returns the sum of a set of `INTEGER` values. |=== @@ -254,63 +267,63 @@ Further details and examples of lists may be found in xref::values-and-types/lis | Function | Signature | Description 1.3+| xref::functions/list.adoc#functions-keys[`keys()`] -| `keys(input :: MAP?) :: (LIST? OF STRING?)` +| `keys(input :: MAP) :: LIST` | Returns a `LIST` containing the `STRING` representations for all the property names of a `MAP`. -| `keys(input :: NODE?) :: (LIST? OF STRING?)` +| `keys(input :: NODE) :: LIST` | Returns a `LIST` containing the `STRING` representations for all the property names of a `NODE`. -| `keys(input :: RELATIONSHIP?) :: (LIST? OF STRING?)` +| `keys(input :: RELATIONSHIP) :: LIST` | Returns a `LIST` containing the `STRING` representations for all the property names of a `RELATIONSHIP`. 1.1+| xref::functions/list.adoc#functions-labels[`labels()`] -| `labels(input :: NODE?) :: (LIST? OF STRING?)` +| `labels(input :: NODE) :: LIST` | Returns a `LIST` containing the `STRING` representations for all the labels of a `NODE`. 1.1+| xref::functions/list.adoc#functions-nodes[`nodes()`] -| `nodes(input :: PATH?) :: (LIST? OF NODE?)` +| `nodes(input :: PATH) :: LIST` | Returns a `LIST` containing all the `NODE` values in a `PATH`. 1.2+| xref::functions/list.adoc#functions-range[`range()`] -| `range(start :: INTEGER?, end :: INTEGER?) :: (LIST? OF INTEGER?)` +| `range(start :: INTEGER, end :: INTEGER) :: LIST` | Returns a `LIST` comprising all `INTEGER` values within a specified range. -| `range(start :: INTEGER?, end :: INTEGER?, step :: INTEGER?) :: (LIST? OF INTEGER?)` +| `range(start :: INTEGER, end :: INTEGER, step :: INTEGER) :: LIST` | Returns a `LIST` comprising all `INTEGER` values within a specified range created with step length. 1.1+| xref::functions/list.adoc#functions-reduce[`reduce()`] -| `reduce(accumulator :: VARIABLE = initial :: ANY?, variable :: VARIABLE IN list :: LIST OF ANY? \| expression :: ANY) :: (ANY?)` +| `reduce(accumulator :: VARIABLE = initial :: ANY, variable :: VARIABLE IN list :: LIST \| expression :: ANY) :: ANY` | Runs an expression against individual elements of a `LIST`, storing the result of the expression in an accumulator. 1.1+| xref::functions/list.adoc#functions-relationships[`relationships()`] -| `relationships(input :: PATH?) :: (LIST? OF RELATIONSHIP?)` +| `relationships(input :: PATH) :: LIST` | Returns a `LIST` containing all the `RELATIONSHIP` values in a `PATH`. 1.1+| xref::functions/string.adoc#functions-reverse[`reverse()`] -| `reverse(input :: LIST? OF ANY?) :: (LIST? OF ANY?)` +| `reverse(input :: LIST) :: LIST` | Returns a `LIST` in which the order of all elements in the given `LIST` have been reversed. 1.1+| xref::functions/list.adoc#functions-tail[`tail()`] -| `tail(input :: LIST? OF ANY?) :: (LIST? OF ANY?)` +| `tail(input :: LIST) :: LIST` | Returns all but the first element in a `LIST`. 1.1+| xref::functions/list.adoc#functions-tobooleanlist[`toBooleanList()`] -| `toBooleanList(input :: LIST? OF ANY?) :: (LIST? OF BOOLEAN?)` +| `toBooleanList(input :: LIST) :: LIST` a| Converts a `LIST` of values to a `LIST` values. If any values are not convertible to `BOOLEAN` they will be null in the `LIST` returned. 1.1+| xref::functions/list.adoc#functions-tofloatlist[`toFloatList()`] -| `toFloatList(input :: LIST? OF ANY?) :: (LIST? OF FLOAT?)` +| `toFloatList(input :: LIST) :: LIST` a| Converts a `LIST` to a `LIST` values. If any values are not convertible to `FLOAT` they will be null in the `LIST` returned. 1.1+| xref::functions/list.adoc#functions-tointegerlist[`toIntegerList()`] -| `toIntegerList(input :: LIST? OF ANY?) :: (LIST? OF INTEGER?)` +| `toIntegerList(input :: LIST) :: LIST` a| Converts a `LIST` to a `LIST` values. If any values are not convertible to `INTEGER` they will be null in the `LIST` returned. 1.1+| xref::functions/list.adoc#functions-tostringlist[`toStringList()`] -| `toStringList(input :: LIST? OF ANY?) :: (LIST? OF STRING?)` +| `toStringList(input :: LIST) :: LIST` a| Converts a `LIST` to a `LIST` values. If any values are not convertible to `STRING` they will be null in the `LIST` returned. @@ -328,41 +341,41 @@ These functions all operate on numerical expressions only, and will return an er | Function | Signature | Description 1.2+| xref::functions/mathematical-numeric.adoc#functions-abs[`abs()`] -| `abs(input :: FLOAT?) :: (FLOAT?)` +| `abs(input :: FLOAT) :: FLOAT` | Returns the absolute value of a `FLOAT`. -| `abs(input :: INTEGER?) :: (INTEGER?)` +| `abs(input :: INTEGER) :: INTEGER` | Returns the absolute value of an `INTEGER`. 1.1+| xref::functions/mathematical-numeric.adoc#functions-ceil[`ceil()`] -| `ceil(input :: FLOAT?) :: (FLOAT?)` +| `ceil(input :: FLOAT) :: FLOAT` | Returns the smallest `FLOAT` that is greater than or equal to a number and equal to an `INTEGER`. 1.1+| xref::functions/mathematical-numeric.adoc#functions-floor[`floor()`] -| `floor(input :: FLOAT?) :: (FLOAT?)` +| `floor(input :: FLOAT) :: FLOAT` | Returns the largest `FLOAT` that is less than or equal to a number and equal to an `INTEGER`. 1.2+| xref::functions/mathematical-numeric.adoc#functions-isnan[`isNaN()`] -| `isNaN(input :: FLOAT?) :: (BOOLEAN?)` +| `isNaN(input :: FLOAT) :: BOOLEAN` | Returns `true` if the floating point number is `NaN`. -| `isNaN(input :: INTEGER?) :: (BOOLEAN?)` +| `isNaN(input :: INTEGER) :: BOOLEAN` | Returns `true` if the integer number is `NaN`. 1.1+| xref::functions/mathematical-numeric.adoc#functions-rand[`rand()`] -| `rand() :: (FLOAT?)` +| `rand() :: FLOAT` | Returns a random `FLOAT` in the range from 0 (inclusive) to 1 (exclusive). 1.3+| xref::functions/mathematical-numeric.adoc#functions-round[`round()`] -| `round(input :: FLOAT?) :: (FLOAT?)` +| `round(input :: FLOAT) :: FLOAT` | Returns the value of a number rounded to the nearest `INTEGER`. -| `round(value :: FLOAT?, precision :: NUMBER?) :: (FLOAT?)` +| `round(value :: FLOAT, precision :: INTEGER \| FLOAT) :: FLOAT` | Returns the value of a number rounded to the specified precision using rounding mode HALF_UP. -| `round(value :: FLOAT?, precision :: NUMBER?, mode :: STRING?) :: (FLOAT?)` +| `round(value :: FLOAT, precision :: INTEGER \| FLOAT, mode :: STRING) :: FLOAT` | Returns the value of a number rounded to the specified precision with the specified rounding mode. 1.2+| xref::functions/mathematical-numeric.adoc#functions-sign[`sign()`] -| `sign(input :: FLOAT?) :: (INTEGER?)` +| `sign(input :: FLOAT) :: INTEGER` | Returns the signum of a `FLOAT`: 0 if the number is 0, -1 for any negative number, and 1 for any positive number. -| `sign(input :: INTEGER?) :: (INTEGER?)` +| `sign(input :: INTEGER) :: INTEGER` | Returns the signum of an `INTEGER`: 0 if the number is 0, -1 for any negative number, and 1 for any positive number. |=== @@ -378,23 +391,23 @@ These functions all operate on numerical expressions only, and will return an er | Function | Signature | Description 1.1+| xref::functions/mathematical-logarithmic.adoc#functions-e[`e()`] -| `e() :: (FLOAT?)` +| `e() :: FLOAT` | Returns the base of the natural logarithm, e. 1.1+| xref::functions/mathematical-logarithmic.adoc#functions-exp[`exp()`] -| `exp(input :: FLOAT?) :: (FLOAT?)` +| `exp(input :: FLOAT) :: FLOAT` | Returns e^n^, where e is the base of the natural logarithm, and n is the value of the argument expression. 1.1+| xref::functions/mathematical-logarithmic.adoc#functions-log[`log()`] -| `log(input :: FLOAT?) :: (FLOAT?)` +| `log(input :: FLOAT) :: FLOAT` | Returns the natural logarithm of a `FLOAT`. 1.1+| xref::functions/mathematical-logarithmic.adoc#functions-log10[`log10()`] -| `log10(input :: FLOAT?) :: (FLOAT?)` +| `log10(input :: FLOAT) :: FLOAT` | Returns the common logarithm (base 10) of a `FLOAT`. 1.1+| xref::functions/mathematical-logarithmic.adoc#functions-sqrt[`sqrt()`] -| `sqrt(input :: FLOAT?) :: (FLOAT?)` +| `sqrt(input :: FLOAT) :: FLOAT` | Returns the square root of a `FLOAT`. |=== @@ -412,51 +425,51 @@ All trigonometric functions operate on radians, unless otherwise specified. | Function | Signature | Description 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-acos[`acos()`] -| `acos(input :: FLOAT?) :: (FLOAT?)` +| `acos(input :: FLOAT) :: FLOAT` | Returns the arccosine of a `FLOAT` in radians. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-asin[`asin()`] -| `asin(input :: FLOAT?) :: (FLOAT?)` +| `asin(input :: FLOAT) :: FLOAT` | Returns the arcsine of a `FLOAT` in radians. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-atan[`atan()`] -| `atan(input :: FLOAT?) :: (FLOAT?)` +| `atan(input :: FLOAT) :: FLOAT` | Returns the arctangent of a `FLOAT` in radians. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-atan2[`atan2()`] -| `atan2(y :: FLOAT?, x :: FLOAT?) :: (FLOAT?)` +| `atan2(y :: FLOAT, x :: FLOAT) :: FLOAT` | Returns the arctangent2 of a set of coordinates in radians. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-cos[`cos()`] -| `cos(input :: FLOAT?) :: (FLOAT?)` +| `cos(input :: FLOAT) :: FLOAT` | Returns the cosine of a `FLOAT`. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-cot[`cot()`] -| `cot(input :: FLOAT?) :: (FLOAT?)` +| `cot(input :: FLOAT) :: FLOAT` | Returns the cotangent of a `FLOAT`. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-degrees[`degrees()`] -| `degrees(input :: FLOAT?) :: (FLOAT?)` +| `degrees(input :: FLOAT) :: FLOAT` | Converts radians to degrees. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-haversin[`haversin()`] -| `haversin(input :: FLOAT?) :: (FLOAT?)` +| `haversin(input :: FLOAT) :: FLOAT` | Returns half the versine of a number. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-pi[`pi()`] -| `pi() :: (FLOAT?)` +| `pi() :: FLOAT` | Returns the mathematical constant pi. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-radians[`radians()`] -| `radians(input :: FLOAT?) :: (FLOAT?)` +| `radians(input :: FLOAT) :: FLOAT` | Converts degrees to radians. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-sin[`sin()`] -| `sin(input :: FLOAT?) :: (FLOAT?)` +| `sin(input :: FLOAT) :: FLOAT` | Returns the sine of a `FLOAT`. 1.1+| xref::functions/mathematical-trigonometric.adoc#functions-tan[`tan()`] -| `tan(input :: FLOAT?) :: (FLOAT?)` +| `tan(input :: FLOAT) :: FLOAT` | Returns the tangent of a `FLOAT`. |=== @@ -472,59 +485,59 @@ These functions are used to manipulate strings or to create a string representat | Function | Signature | Description 1.1+| xref::functions/string.adoc#functions-left[`left()`] -| `left(original :: STRING?, length :: INTEGER?) :: (STRING?)` +| `left(original :: STRING, length :: INTEGER) :: STRING` | Returns a `STRING` containing the specified number (`INTEGER`) of leftmost characters in the given `STRING`. 1.1+| xref::functions/string.adoc#functions-ltrim[`ltrim()`] -| `ltrim(input :: STRING?) :: (STRING?)` +| `ltrim(input :: STRING) :: STRING` | Returns the given `STRING` with leading whitespace removed. 1.1+| xref::functions/string.adoc#functions-replace[`replace()`] -| `replace(original :: STRING?, search :: STRING?, replace :: STRING?) :: (STRING?)` +| `replace(original :: STRING, search :: STRING, replace :: STRING) :: STRING` | Returns a `STRING` in which all occurrences of a specified search `STRING` in the given `STRING` have been replaced by another (specified) replacement `STRING`. 1.1+| xref::functions/string.adoc#functions-reverse[`reverse()`] -| `reverse(input :: STRING?) :: (STRING?)` +| `reverse(input :: STRING) :: STRING` | Returns a `STRING` in which the order of all characters in the given `STRING` have been reversed. 1.1+| xref::functions/string.adoc#functions-right[`right()`] -| `right(original :: STRING?, length :: INTEGER?) :: (STRING?)` +| `right(original :: STRING, length :: INTEGER) :: STRING` | Returns a `STRING` containing the specified number of rightmost characters in the given `STRING`. 1.1+| xref::functions/string.adoc#functions-rtrim[`rtrim()`] -| `rtrim(input :: STRING?) :: (STRING?)` +| `rtrim(input :: STRING) :: STRING` | Returns the given `STRING` with trailing whitespace removed. 1.2+| xref::functions/string.adoc#functions-split[`split()`] -| `split(original :: STRING?, splitDelimiter :: STRING?) :: (LIST? OF STRING?)` +| `split(original :: STRING, splitDelimiter :: STRING) :: LIST` | Returns a `LIST` resulting from the splitting of the given `STRING` around matches of the given delimiter. -| `split(original :: STRING?, splitDelimiters :: LIST? OF STRING?) :: (LIST? OF STRING?)` +| `split(original :: STRING, splitDelimiters :: LIST) :: LIST` | Returns a `LIST` resulting from the splitting of the given `STRING` around matches of any of the given delimiters. 1.2+| xref::functions/string.adoc#functions-substring[`substring()`] -| `substring(original :: STRING?, start :: INTEGER?) :: (STRING?)` +| `substring(original :: STRING, start :: INTEGER) :: STRING` | Returns a substring of the given `STRING`, beginning with a 0-based index start. -| `substring(original :: STRING?, start :: INTEGER?, length :: INTEGER?) :: (STRING?)` +| `substring(original :: STRING, start :: INTEGER, length :: INTEGER) :: STRING` | Returns a substring of a given `length` from the given `STRING`, beginning with a 0-based index start. 1.1+| xref::functions/string.adoc#functions-tolower[`toLower()`] -| `toLower(input :: STRING?) :: (STRING?)` +| `toLower(input :: STRING) :: STRING` | Returns the given `STRING` in lowercase. 1.1+| xref::functions/string.adoc#functions-tostring[`toString()`] -| `toString(input :: ANY?) :: (STRING?)` +| `toString(input :: ANY) :: STRING` | Converts an `INTEGER`, `FLOAT`, `BOOLEAN`, `POINT` or temporal type (i.e. `DATE`, `ZONED TIME`, `LOCAL TIME`, `ZONED DATETIME`, `LOCAL DATETIME` or `DURATION`) value to a `STRING`. 1.1+| xref::functions/string.adoc#functions-tostringornull[`toStringOrNull()`] -| `toStringOrNull(input :: ANY?) :: (STRING?)` +| `toStringOrNull(input :: ANY) :: STRING` | Converts an `INTEGER`, `FLOAT`, `BOOLEAN`, `POINT` or temporal type (i.e. `DATE`, `ZONED TIME`, `LOCAL TIME`, `ZONED DATETIME`, `LOCAL DATETIME` or `DURATION`) value to a `STRING`, or null if the value cannot be converted. 1.1+| xref::functions/string.adoc#functions-toupper[`toUpper()`] -| `toUpper(input :: STRING?) :: (STRING?)` +| `toUpper(input :: STRING) :: STRING` | Returns the given `STRING` in uppercase. 1.1+| xref::functions/string.adoc#functions-trim[`trim()`] -| `trim(input :: STRING?) :: (STRING?)` +| `trim(input :: STRING) :: STRING` | Returns the given `STRING` with leading and trailing whitespace removed. |=== @@ -540,111 +553,111 @@ Values of the xref::values-and-types/temporal.adoc[temporal types] -- `DATE`, `Z | Function | Signature | Description 1.1+| xref::functions/temporal/index.adoc#functions-date[`date()`] -| `date(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATE?)` +| `date(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: DATE` | Creates a `DATE` instant. 1.1+| xref::functions/temporal/index.adoc#functions-date-realtime[`date.realtime()`] -| `date.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATE?)` +| `date.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: DATE` | Returns the current `DATE` instant using the realtime clock. 1.1+| xref::functions/temporal/index.adoc#functions-date-statement[`date.statement()`] -| `date.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATE?)` +| `date.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: DATE` | Returns the current `DATE` instant using the statement clock. 1.1+| xref::functions/temporal/index.adoc#functions-date-transaction[`date.transaction()`] -| `date.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATE?)` +| `date.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: DATE` | Returns the current `DATE` instant using the transaction clock. 1.1+| xref::functions/temporal/index.adoc#functions-date-truncate[`date.truncate()`] -| `date.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (DATE?)` +| `date.truncate(unit :: STRING, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY, fields = null :: MAP) :: DATE` | Truncates the given temporal value to a `DATE` instant using the specified unit. 1.1+| xref::functions/temporal/index.adoc#functions-datetime[`datetime()`] -| `datetime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATETIME?)` +| `datetime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: ZONED DATETIME` | Creates a `ZONED DATETIME` instant. 1.1+| xref::functions/temporal/index.adoc#functions-datetime-timestamp[`datetime.fromepoch()`] -| `datetime.fromepoch(seconds :: NUMBER?, nanoseconds :: NUMBER?) :: (DATETIME?)` +| `datetime.fromepoch(seconds :: INTEGER \| FLOAT, nanoseconds :: INTEGER \| FLOAT) :: ZONED DATETIME` | Creates a `ZONED DATETIME` given the seconds and nanoseconds since the start of the epoch. 1.1+| xref::functions/temporal/index.adoc#functions-datetime-timestamp[`datetime.fromepochmillis()`] -| `datetime.fromepochmillis(milliseconds :: NUMBER?) :: (DATETIME?)` +| `datetime.fromepochmillis(milliseconds :: INTEGER \| FLOAT) :: ZONED DATETIME` | Creates a `ZONED DATETIME` given the milliseconds since the start of the epoch. 1.1+| xref::functions/temporal/index.adoc#functions-datetime-realtime[`datetime.realtime()`] -| `datetime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATETIME?)` +| `datetime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: ZONED DATETIME` | Returns the current `ZONED DATETIME` instant using the realtime clock. 1.1+| xref::functions/temporal/index.adoc#functions-datetime-statement[`datetime.statement()`] -| `datetime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATETIME?)` +| `datetime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: ZONED DATETIME` | Returns the current `ZONED DATETIME` instant using the statement clock. 1.1+| xref::functions/temporal/index.adoc#functions-datetime-transaction[`datetime.transaction()`] -| `datetime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (DATETIME?)` +| `datetime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: ZONED DATETIME` | Returns the current `ZONED DATETIME` instant using the transaction clock. 1.1+| xref::functions/temporal/index.adoc#functions-datetime-truncate[`datetime.truncate()`] -| `datetime.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (DATETIME?)` +| `datetime.truncate(unit :: STRING, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY, fields = null :: MAP) :: ZONED DATETIME` | Truncates the given temporal value to a `ZONED DATETIME` instant using the specified unit. 1.1+| xref::functions/temporal/index.adoc#functions-localdatetime[`localdatetime()`] -| `localdatetime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALDATETIME?)` +| `localdatetime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL DATETIME` | Creates a `LOCAL DATETIME` instant. 1.1+| xref::functions/temporal/index.adoc#functions-localdatetime-realtime[`localdatetime.realtime()`] -| `localdatetime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALDATETIME?)` +| `localdatetime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL DATETIME` | Returns the current `LOCAL DATETIME` instant using the realtime clock. 1.1+| xref::functions/temporal/index.adoc#functions-localdatetime-statement[`localdatetime.statement()`] -| `localdatetime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALDATETIME?)` +| `localdatetime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL DATETIME` | Returns the current `LOCAL DATETIME` instant using the statement clock. 1.1+| xref::functions/temporal/index.adoc#functions-localdatetime-transaction[`localdatetime.transaction()`] -| `localdatetime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALDATETIME?)` +| `localdatetime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL DATETIME` | Returns the current `LOCAL DATETIME` instant using the transaction clock. 1.1+| xref::functions/temporal/index.adoc#functions-localdatetime-truncate[`localdatetime.truncate()`] -| `localdatetime.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (LOCALDATETIME?)` +| `localdatetime.truncate(unit :: STRING, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY, fields = null :: MAP) :: LOCAL DATETIME` | Truncates the given temporal value to a `LOCAL DATETIME` instant using the specified unit. 1.1+| xref::functions/temporal/index.adoc#functions-localtime[`localtime()`] -| `localtime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALTIME?)` +| `localtime(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL TIME` | Creates a `LOCAL TIME` instant. 1.1+| xref::functions/temporal/index.adoc#functions-localtime-realtime[`localtime.realtime()`] -| `localtime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALTIME?)` +| `localtime.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL TIME` | Returns the current `LOCAL TIME` instant using the realtime clock. 1.1+| xref::functions/temporal/index.adoc#functions-localtime-statement[`localtime.statement()`] -| `localtime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALTIME?)` +| `localtime.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL TIME` | Returns the current `LOCAL TIME` instant using the statement clock. 1.1+| xref::functions/temporal/index.adoc#functions-localtime-transaction[`localtime.transaction()`] -| `localtime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (LOCALTIME?)` +| `localtime.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: LOCAL TIME` | Returns the current `LOCAL TIME` instant using the transaction clock. 1.1+| xref::functions/temporal/index.adoc#functions-localtime-truncate[`localtime.truncate()`] -| `localtime.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (LOCALTIME?)` +| `localtime.truncate(unit :: STRING, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY, fields = null :: MAP) :: LOCAL TIME` | Truncates the given temporal value to a `LOCAL TIME` instant using the specified unit. 1.1+| xref::functions/temporal/index.adoc#functions-time[`time()`] -| `time(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (TIME?)` +| `time(input = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: ZONED TIME` | Creates a `ZONED TIME` instant. 1.1+| xref::functions/temporal/index.adoc#functions-time-realtime[`time.realtime()`] -| `time.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (TIME?)` +| `time.realtime(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: ZONED TIME` | Returns the current `ZONED TIME` instant using the realtime clock. 1.1+| xref::functions/temporal/index.adoc#functions-time-statement[`time.statement()`] -| `time.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (TIME?)` +| `time.statement(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: ZONED TIME` | Returns the current `ZONED TIME` instant using the statement clock. 1.1+| xref::functions/temporal/index.adoc#functions-time-transaction[`time.transaction()`] -| `time.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY?) :: (TIME?)` +| `time.transaction(timezone = DEFAULT_TEMPORAL_ARGUMENT :: ANY) :: ZONED TIME` | Returns the current `ZONED TIME` instant using the transaction clock. 1.1+| xref::functions/temporal/index.adoc#functions-time-truncate[`time.truncate()`] -| `time.truncate(unit :: STRING?, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY?, fields = null :: MAP?) :: (TIME?)` +| `time.truncate(unit :: STRING, input = DEFAULT_TEMPORAL_ARGUMENT :: ANY, fields = null :: MAP) :: ZONED TIME` | Truncates the given temporal value to a `ZONED TIME` instant using the specified unit. |=== @@ -660,23 +673,23 @@ Values of the xref::values-and-types/temporal.adoc[temporal types] -- `DATE`, `Z | Function | Signature | Description 1.1+| xref::functions/temporal/duration.adoc#functions-duration[`duration()`] -| `duration(input :: ANY?) :: (DURATION?)` +| `duration(input :: ANY) :: DURATION` | Constructs a `DURATION` value. 1.1+| xref::functions/temporal/duration.adoc#functions-duration-between[`duration.between()`] -| `duration.between(from :: ANY?, to :: ANY?) :: (DURATION?)` +| `duration.between(from :: ANY, to :: ANY) :: DURATION` | Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in logical units. 1.1+| xref::functions/temporal/duration.adoc#functions-duration-indays[`duration.inDays()`] -| `duration.inDays(from :: ANY?, to :: ANY?) :: (DURATION?)` +| `duration.inDays(from :: ANY, to :: ANY) :: DURATION` | Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in days. 1.1+| xref::functions/temporal/duration.adoc#functions-duration-inmonths[`duration.inMonths()`] -| `duration.inMonths(from :: ANY?, to :: ANY?) :: (DURATION?)` +| `duration.inMonths(from :: ANY, to :: ANY) :: DURATION` | Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in months. 1.1+| xref::functions/temporal/duration.adoc#functions-duration-inseconds[`duration.inSeconds()`] -| `duration.inSeconds(from :: ANY?, to :: ANY?) :: (DURATION?)` +| `duration.inSeconds(from :: ANY, to :: ANY) :: DURATION` | Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in seconds. |=== @@ -692,27 +705,27 @@ These functions are used to specify 2D or 3D points in a geographic or cartesian | Function | Signature | Description 1.1+| xref::functions/spatial.adoc#functions-distance[`point.distance()`] -| `point.distance(from :: POINT?, to :: POINT?) :: (FLOAT?)` +| `point.distance(from :: POINT, to :: POINT) :: FLOAT` | Returns a `FLOAT` representing the geodesic distance between any two points in the same CRS. 1.1+| xref::functions/spatial.adoc#functions-point-cartesian-2d[`point()` - Cartesian 2D] -| `point(input :: MAP?) :: (POINT?)` +| `point(input :: MAP) :: POINT` | Returns a 2D point object, given two coordinate values in the Cartesian coordinate system. 1.1+| xref::functions/spatial.adoc#functions-point-cartesian-3d[`point()` - Cartesian 3D] -| `point(input :: MAP?) :: (POINT?)` +| `point(input :: MAP) :: POINT` | Returns a 3D point object, given three coordinate values in the Cartesian coordinate system. 1.1+| xref::functions/spatial.adoc#functions-point-wgs84-2d[`point()` - WGS 84 2D] -| `point(input :: MAP?) :: (POINT?)` +| `point(input :: MAP) :: POINT` | Returns a 2D point object, given two coordinate values in the WGS 84 geographic coordinate system. 1.1+| xref::functions/spatial.adoc#functions-point-wgs84-3d[`point()` - WGS 84 3D] -| `point(input :: MAP?) :: (POINT?)` +| `point(input :: MAP) :: POINT` | Returns a 3D point object, given three coordinate values in the WGS 84 geographic coordinate system. 1.1+| xref::functions/spatial.adoc#functions-withinBBox[`point.withinBBox()`] -| `point.withinBBox(point :: POINT?, lowerLeft :: POINT?, upperRight :: POINT?) :: (BOOLEAN?)` +| `point.withinBBox(point :: POINT, lowerLeft :: POINT, upperRight :: POINT) :: BOOLEAN` | Returns `true` if the provided point is within the bounding box defined by the two provided points, `lowerLeft` and `upperRight`. |=== @@ -728,11 +741,11 @@ LOAD CSV functions can be used to get information about the file that is process | Function | Signature | Description 1.1+| xref::functions/load-csv.adoc#functions-file[`file()`] -| `file() :: (STRING?)` +| `file() :: STRING` | Returns the absolute path of the file that LOAD CSV is using. 1.1+| xref::functions/load-csv.adoc#functions-linenumber[`linenumber()`] -| `linenumber() :: (INTEGER?)` +| `linenumber() :: INTEGER` | Returns the line number that LOAD CSV is currently using. |=== @@ -746,9 +759,11 @@ Graph functions provide information about the constituent graphs in composite da [options="header"] |=== | Function | Signature | Description -1.1+| xref:functions/graph.adoc#functions-graph-names[`graph.names()`] | `graph.names() :: (LIST? OF STRING?)` | Returns a list containing the names of all graphs in the current composite database. -1.1+| xref:functions/graph.adoc#functions-graph-names[`graph.propertiesByName()`] | `graph.propertiesByName(name :: STRING?) :: (MAP?)` | Returns a map containing the properties associated with the given graph. -1.1+| xref:functions/graph.adoc#functions-graph-byname[`graph.byName()`] | `USE graph.byName(name :: STRING?)` | Resolves a constituent graph by name. +1.1+| xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId()`] | `USE graph.byElementId(elementId :: STRING)` | Resolves the constituent graph to which a given element id belongs. +label:new[Introduced in Neo4j 5.13] +1.1+| xref:functions/graph.adoc#functions-graph-byname[`graph.byName()`] | `USE graph.byName(name :: STRING)` | Resolves a constituent graph by name. +1.1+| xref:functions/graph.adoc#functions-graph-names[`graph.names()`] | `graph.names() :: LIST` | Returns a list containing the names of all graphs in the current composite database. +1.1+| xref:functions/graph.adoc#functions-graph-names[`graph.propertiesByName()`] | `graph.propertiesByName(name :: STRING) :: MAP` | Returns a map containing the properties associated with the given graph. |=== [[header-query-functions-database]] @@ -759,7 +774,8 @@ Database functions provide information about databases. [options="header"] |=== | Function | Signature | Description -1.1+| xref:functions/database.adoc#functions-database-nameFromElementId[`db.nameFromElementId()`] | `db.nameFromElementId(name :: STRING?) :: (STRING?)` | Resolves the database name from the given element id. +1.1+| xref:functions/database.adoc#functions-database-nameFromElementId[`db.nameFromElementId()`] | `db.nameFromElementId(name :: STRING) :: STRING` | Resolves the database name from the given element id. +label:new[Introduced in 5.12] |=== [[header-query-functions-user-defined]] diff --git a/modules/ROOT/pages/functions/scalar.adoc b/modules/ROOT/pages/functions/scalar.adoc index c31023988..f00158120 100644 --- a/modules/ROOT/pages/functions/scalar.adoc +++ b/modules/ROOT/pages/functions/scalar.adoc @@ -34,6 +34,136 @@ CREATE //// +[[functions-char_length]] +== char_length() + +_This feature was introduced in Neo4j 5.13._ + +The function `char_length()` returns the number of Unicode characters in a `STRING`. +This function is an alias of the xref::functions/scalar.adoc#functions-size[`size()`] function. + +*Syntax:* + +[source, syntax, role="noheader"] +---- +char_length(string) +---- + +*Returns:* + +|=== + +| `INTEGER` + +|=== + +*Arguments:* + +[options="header"] +|=== +| Name | Description + +| `string` +| An expression that returns a `STRING`. + +|=== + +*Considerations:* +|=== + +| `char_length(null)` returns `null`. + +|=== + + +.+char_length()+ +====== + +.Query +[source, cypher, indent=0] +---- +RETURN char_length('Alice') +---- + +.Result +[role="queryresult",options="header,footer",cols="1*` (ordered by the inner type) +** `PATH` +* Dynamic union types +** `INNER_TYPE_1 \| INNER_TYPE_2...` (ordered by specific rules for closed dynamic union type) +** `ANY` + +This should be taken into account when relying on the output of the `valueType()` function. + +See the xref::values-and-types/type-predicate.adoc[type predicate expression] for an alternative way of testing type values. + + +.+valueType()+ +====== + +.Query +[source, cypher, indent=0] +---- +UNWIND ["abc", 1, 2.0, true, [date()]] AS value +RETURN valueType(value) AS result +---- + +.Result +[role="queryresult",options="header,footer",cols="1* NOT NULL"+ +1+d|Rows: 5 + +|=== + +====== + diff --git a/modules/ROOT/pages/indexes-for-search-performance.adoc b/modules/ROOT/pages/indexes-for-search-performance.adoc index c07d604df..da76aced4 100644 --- a/modules/ROOT/pages/indexes-for-search-performance.adoc +++ b/modules/ROOT/pages/indexes-for-search-performance.adoc @@ -6,8 +6,8 @@ This page explains how to manage indexes used for search performance. For query performance purposes, it is important to also understand how the indexes are used by the Cypher planner. -Refer to xref::query-tuning/index.adoc[] for examples and in-depth discussions on how query plans result from different index and query scenarios. -See specifically xref::query-tuning/indexes.adoc[The use of indexes] for examples of how various index scenarios result in different query plans. +Refer to xref::planning-and-tuning/query-tuning/index.adoc[] for examples and in-depth discussions on how query plans result from different index and query scenarios. +See specifically xref::planning-and-tuning/query-tuning/indexes.adoc[The use of indexes] for examples of how various index scenarios result in different query plans. For information on index configuration and limitations, refer to link:{neo4j-docs-base-uri}/operations-manual/{page-version}/performance/index-configuration[Operations Manual -> Index configuration]. @@ -71,7 +71,7 @@ The `+CREATE INDEX+` command is optionally idempotent. This mean that its defaul With `IF NOT EXISTS`, no error is thrown and nothing happens should an index with the same name or same schema and index type already exist. It may still throw an error if conflicting constraints exist, such as constraints with the same name or schema and backing index type. -Creating an index requires xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[the `CREATE INDEX` privilege]. +Creating an index requires link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/manage-databases/#manage-databases-stop/authentication-authorization/database-administration/#access-control-database-administration-index[the `CREATE INDEX` privilege]. [NOTE] ==== @@ -103,8 +103,6 @@ ON (r.propertyName_1[, r.propertyName_n]) ---- -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. - Range indexes have only one index provider available, `range-1.0`, and no supported index configuration. [discrete] @@ -207,8 +205,6 @@ ON (r.propertyName) [OPTIONS "{" option: value[, ...] "}"] ---- -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. - As of Neo4j 5.1, text indexes have two index providers available, `text-2.0` (default) and `text-1.0` (deprecated), and no supported index configuration. @@ -304,8 +300,6 @@ ON (r.propertyName) [OPTIONS "{" option: value[, ...] "}"] ---- -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. - Point indexes have supported index configuration, see the last examples, but only one index provider available, `point-1.0`. [NOTE] @@ -417,8 +411,6 @@ FOR ()-"["r"]"-() ON [EACH] type(r) ---- -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. - Token lookup indexes have only one index provider available, `token-lookup-1.0`, and no supported index configuration. [discrete] @@ -611,8 +603,6 @@ SHOW [ALL \| FULLTEXT \| LOOKUP \| POINT \| RANGE \| TEXT] INDEX[ES] [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ---- -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. - This command will produce a table with the following columns: .List indexes output @@ -667,7 +657,7 @@ This command will produce a table with the following columns: Returns `null` if the index has not been read since `trackedSince`, or if the statistics are not tracked. label:default-output[] label:new[Introduced in 5.8] -| `DATETIME` +| `ZONED DATETIME` // New in 5.8 | `readCount` @@ -679,7 +669,7 @@ label:new[Introduced in 5.8] | `trackedSince` | The time when usage statistics tracking started for this index, or `null` if the statistics are not tracked. label:new[Introduced in 5.8] -| `DATETIME` +| `ZONED DATETIME` | `options` | The options passed to `CREATE` command. @@ -704,7 +694,7 @@ Full output: `+SHOW INDEXES YIELD *+`. Listing indexes also allows for `WHERE` and `YIELD` clauses to filter the returned rows and columns. -Listing indexes require xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[the `SHOW INDEX` privilege]. +Listing indexes require link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/manage-databases/#manage-databases-stop/authentication-authorization/database-administration/#access-control-database-administration-index[the `SHOW INDEX` privilege]. [discrete] === Examples @@ -816,13 +806,11 @@ The name of the index can be found using the xref::indexes-for-search-performanc DROP INDEX index_name [IF EXISTS] ---- -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. - The `DROP INDEX` command is optionally idempotent. This means that its default behavior is to throw an error if an attempt is made to drop the same index twice. With `IF EXISTS`, no error is thrown and nothing happens should the index not exist. -Dropping an index requires xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[the `DROP INDEX` privilege]. +Dropping an index requires link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/manage-databases/#manage-databases-stop/authentication-authorization/database-administration/#access-control-database-administration-index[the `DROP INDEX` privilege]. [discrete] === Examples @@ -884,12 +872,6 @@ With `IF NOT EXISTS`, no error is thrown and nothing happens should an index wit It may still throw an error if conflicting constraints exist, such as constraints with the same name or schema and backing index type. ==== -[NOTE] -==== -More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. -==== - - .+Create a range index on nodes+ [options="noheader", width="100%", cols="2, 8a"] |=== @@ -1131,11 +1113,11 @@ SHOW [ALL \| FULLTEXT \| LOOKUP \| POINT \| RANGE \| TEXT] INDEX[ES] |=== -Creating an index requires xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[the `CREATE INDEX` privilege], -while dropping an index requires xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[the `DROP INDEX` privilege] and -listing indexes require xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[the `SHOW INDEX` privilege]. +Creating an index requires link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/manage-databases/#manage-databases-stop/authentication-authorization/database-administration/#access-control-database-administration-index[the `CREATE INDEX` privilege], +while dropping an index requires link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/manage-databases/#manage-databases-stop/authentication-authorization/database-administration/#access-control-database-administration-index[the `DROP INDEX` privilege] and +listing indexes require link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/standard-databases/manage-databases/#manage-databases-stop/authentication-authorization/database-administration/#access-control-database-administration-index[the `SHOW INDEX` privilege]. -xref:query-tuning/using.adoc[Planner hints and the USING keyword] describes how to make the Cypher planner use specific indexes (especially in cases where the planner would not necessarily have used them). +xref:planning-and-tuning/query-tuning/using.adoc[Planner hints and the USING keyword] describes how to make the Cypher planner use specific indexes (especially in cases where the planner would not necessarily have used them). [[indexes-single-vs-composite-index]] diff --git a/modules/ROOT/pages/indexes-for-vector-search.adoc b/modules/ROOT/pages/indexes-for-vector-search.adoc index 18dcb4884..440f65da3 100644 --- a/modules/ROOT/pages/indexes-for-vector-search.adoc +++ b/modules/ROOT/pages/indexes-for-vector-search.adoc @@ -10,11 +10,10 @@ :l2-norm: image:l2.svg["l2"]-norm -[role=beta] [[indexes-vector]] = Vector search index -_Vector search indexes were released as a public beta in Neo4j 5.11._ +_Vector search indexes were released as a public beta in Neo4j 5.11 and general availability in Neo4j 5.13._ This chapter describes how to use vector indexes to perform an approximate nearest neighbor search. @@ -64,9 +63,13 @@ Returns the requested number of approximate nearest neighbor nodes and their sim | `SHOW INDEXES WHERE type = "VECTOR"` | Lists all vector indexes, see the xref:indexes-for-search-performance.adoc#indexes-list-indexes[`SHOW INDEXES`] command for details. There is no vector index filter built into `SHOW INDEXES`. +| Set vector property. +| {link-procedures-reference}#procedure_db_create_setNodeVectorProperty[`db.create.setNodeVectorProperty`] +| label:beta[] label:new[Introduced in 5.13] Update a given node property with the given vector in a more space-efficient way than directly using xref:clauses/set.adoc#set-set-a-property[`SET`]. Replaces {link-procedures-reference}#procedure_db_create_setVectorProperty[`db.create.setVectorProperty`]. + | Set vector property. | {link-procedures-reference}#procedure_db_create_setVectorProperty[`db.create.setVectorProperty`] -| Update a given node property with the given vector in a more space-efficient way than directly using xref:clauses/set.adoc#set-set-a-property[`SET`]. +| label:beta[] label:deprecated[] It is replaced by {link-procedures-reference}#procedure_db_create_setNodeVectorProperty[`db.create.setNodeVectorProperty`] |=== @@ -88,7 +91,7 @@ For details, see xref:#indexes-vector-similarity[]. .Signature for `db.index.vector.createNodeIndex` to create a vector node index [source,syntax,role="noheader",indent=0] ---- -db.index.vector.createNodeIndex(indexName :: STRING?, label :: STRING?, propertyKey :: STRING?, vectorDimension :: INTEGER?, vectorSimilarityFunction :: STRING?) :: VOID +db.index.vector.createNodeIndex(indexName :: STRING, label :: STRING, propertyKey :: STRING, vectorDimension :: INTEGER, vectorSimilarityFunction :: STRING) ---- [NOTE] @@ -166,7 +169,7 @@ You can query a vector index using the procedure {link-procedures-reference}#pro .Signature for `db.index.vector.queryNodes` to query a vector index [source,syntax,role="noheader",indent=0] ---- -db.index.vector.queryNodes(indexName :: STRING?, numberOfNearestNeighbours :: INTEGER?, query :: LIST? OF FLOAT?) :: (node :: NODE?, score :: FLOAT?) +db.index.vector.queryNodes(indexName :: STRING, numberOfNearestNeighbours :: INTEGER, query :: LIST) :: (node :: NODE, score :: FLOAT) ---- * The `indexName` (a `STRING`) refers to the unique name of the vector index to query. @@ -267,46 +270,57 @@ Removed 1 index. ====== +[role=beta] [[indexes-vector-set]] == Set a vector property on a node Valid vectors for use in the index must have components finitely representable in {ieee-754} _single_ precision. -They are represented as properties on nodes with type `LIST`. -The recommended way of setting a vector property is using the link:{link-procedures-reference}#procedure_db_create_setVectorProperty[`db.create.setVectorProperty`] procedure. -This procedure validates the input and sets the property as an array of {ieee-754} single precision values. +They are represented as properties on nodes with the type `LIST`. +As of Neo4j 5.13, you can set a vector property using the {link-procedures-reference}#procedure_db_create_setNodeVectorProperty[`db.create.setNodeVectorProperty`] procedure. +It validates the input and sets the property as an array of {ieee-754} single precision values. +This beta procedure replaces {link-procedures-reference}#procedure_db_create_setVectorProperty[`db.create.setVectorProperty`]. + +.Signature for `db.create.setNodeVectorProperty` +[source,syntax] +---- +db.create.setNodeVectorProperty(node :: NODE, key :: STRING, vector :: LIST) +---- -.Signature for `db.create.setVectorProperty` +.Signature for `db.create.setVectorProperty` label:deprecated[] [source,syntax] ---- -db.create.setVectorProperty(node :: NODE?, key :: STRING?, vector :: LIST? OF FLOAT?) :: (node :: NODE?) +db.create.setVectorProperty(node :: NODE, key :: STRING, vector :: LIST) :: (node :: NODE) ---- -Usually you want to define your embeddings as Cypher parameters and call `db.create.setVectorProperty` as in the following example: +The following example shows how to define embeddings as Cypher parameters by matching a node and setting its vector properties using `db.create.setNodeVectorProperty`: .Set a vector via `db.create.setVectorProperty` [source,cypher] ---- MATCH (n:Node {id: $id}) -CALL db.create.setVectorProperty(n, 'propertyKey', $vector) -YIELD node RETURN node; +CALL db.create.setNodeVectorProperty(n, 'propertyKey', $vector) +RETURN node ---- -The example above matches one node and updates its embedding, but it's also possible to use a list parameter containing several MATCH criterias and embeddings, to update multiple nodes in an `UNWIND` clause. +Furthermore, you can also use a list parameter containing several `MATCH` criteria and embeddings to update multiple nodes in an `UNWIND` clause. This is ideal for creating and setting new vector properties in the graph. -You can also set a vector property on a node using the xref:clauses/set.adoc#set-set-a-property[`SET`] command: +You can also set a vector property on a node using the xref:clauses/set.adoc#set-set-a-property[`SET`] command as in the following example: .Set a vector property via `SET` [source,cypher] ---- MATCH (node:Node {id: $id}) SET node.propertyKey = $vector -RETURN node; +RETURN node ---- -However, Cypher stores the provided `LIST` as a primitive array of {ieee-754} _double_ precision values. -As a result, it takes up approximately twice as much space and it's not recommended for properties that are used in a vector index. -Existing properties can be re-set using `db.create.setVectorProperty` to minimize store size, but there is a cost in the transaction log size until they are rotated away. +However, Cypher stores the provided `LIST` as a primitive array of {ieee-754} _double_ precision values. +This takes up almost twice as much space compared to the alternative method, where you use the `db.create.setNodeVectorProperty` procedure. +As a result, using `SET` for a vector index is not recommended. + +To reduce the storage space, you can reset the existing properties using `db.create.setNodeVectorProperty`. +However, this comes with the cost of an increase in the transaction log size until they are rotated away. [[indexes-vector-similarity]] == Supported similarity functions @@ -391,13 +405,24 @@ For example, you cannot have one xref:indexes-vector-similarity-euclidean[Euclid [[index-vector-issues]] == Known issues -The vector search index is a beta feature. -The below table lists the known issues in its current implementation. +As of Neo4j 5.13, the vector search index is no longer a beta feature. +The following table lists the known issues and the version in which they were fixed: [%header,cols="5a,d"] |=== | Known issues | Fixed in +| Querying for a _single_ approximate nearest neighbor from an index would fail a validation check. Passing a `null` value would also provide an unhelpful exception. +| Neo4j 5.13 + +| Vector index queries throw an exception if the transaction state contains changes. This means that writes may only take place *after* the last vector index query in a transaction. + +[TIP] +==== +To work around this issue if you need to run multiple vector index queries and make changes based on the results, you can run the queries in a `+CALL { ... } IN TRANSACTIONS+` clause to isolate them from the outer transaction's state. +==== +| Neo4j 5.13 + | xref:clauses/listing-procedures.adoc[`SHOW PROCEDURES`] does not show the vector index procedures: * {link-procedures-reference}#procedure_db_create_setVectorProperty[`db.create.setVectorProperty`] diff --git a/modules/ROOT/pages/introduction/cypher_neo4j.adoc b/modules/ROOT/pages/introduction/cypher_neo4j.adoc index 24c528183..11c70a69e 100644 --- a/modules/ROOT/pages/introduction/cypher_neo4j.adoc +++ b/modules/ROOT/pages/introduction/cypher_neo4j.adoc @@ -16,7 +16,7 @@ Cypher works almost identically between the two editions, but there are key area |=== | Feature | Enterprise Edition | Community Edition -| xref::administration/databases.adoc[Multi-database] +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/[Multi-database] a| Any number of user databases. a| @@ -24,9 +24,9 @@ Only `system` and one user database. | Role-based security a| -User, role, and privilege management for flexible xref::administration/access-control/index.adoc[access control] and xref::administration/access-control/manage-privileges.adoc[sub-graph access control]. +User, role, and privilege management for flexible link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/manage-privileges/[access control] and link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/manage-privileges/[sub-graph access control]. a| -xref::administration/access-control/manage-users.adoc[Multi-user management]. +link:{neo4j-docs-base-uri}/operations-manual/{page-version}authentication-authorization/manage-users[Multi-user management]. All users have full access rights. | Constraints @@ -74,12 +74,12 @@ A fresh installation of Neo4j includes two databases: * `system` - the system database described above, containing meta-data on the DBMS and security configuration. * `neo4j` - the default database, named using the config option `dbms.default_database=neo4j`. -For more information about the _system_ database, see the sections on xref::administration/databases.adoc[Database management] and xref::administration/access-control/index.adoc[Access control]. +For more information about the _system_ database, see the sections on link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/[Database management] and link:{neo4j-docs-base-uri}/operations-manual/{page-version}/authentication-authorization/[Access control]. === Query considerations Most of the time Cypher queries are reading or updating queries, which are run against a graph. -There are also xref:administration/index.adoc[administrative commands] that apply to a database, or to the entire DBMS. +There are also link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/syntax[administrative commands] that apply to a database, or to the entire DBMS. Administrative commands cannot be run in a session connected to a normal user database, but instead need to be run within a session connected to the `system` database. Administrative commands execute on the `system` database. If an administrative command is submitted to a user database, it is rerouted to the system database. diff --git a/modules/ROOT/pages/keyword-glossary.adoc b/modules/ROOT/pages/keyword-glossary.adoc deleted file mode 100644 index d24a14794..000000000 --- a/modules/ROOT/pages/keyword-glossary.adoc +++ /dev/null @@ -1,1560 +0,0 @@ -:description: Glossary of all the keywords -- grouped by category and thence ordered lexicographically -- in the Cypher query language. - -[[cypher-glossary]] -= Glossary of keywords - -This page contains a glossary of all the keywords -- grouped by category and thence ordered lexicographically -- in the Cypher query language. - - -[[glossary-clauses]] -== xref::clauses/index.adoc[Clauses] - -[options="header"] -|=== -| Clause | Category | Description - -| xref::clauses/call.adoc[CALL [...YIELD\]] -| Reading/Writing -| Invoke a procedure deployed in the database. - -| xref::subqueries/call-subquery.adoc[+CALL {...}+] -| Reading/Writing -| Evaluates a subquery, typically used for post-union processing or aggregations. - -| xref::subqueries/subqueries-in-transactions.adoc[+CALL { ... } IN TRANSACTIONS+] -| Reading/Writing -a| -Evaluates a subquery in separate transactions. -Typically used when modifying or importing large amounts of data. - -| xref::clauses/create.adoc[CREATE] -| Writing -| Create nodes and relationships. - -| xref::constraints/syntax.adoc#constraints-syntax-create-node-exists[CREATE CONSTRAINT [existence\] [IF NOT EXISTS\] FOR (n:Label) REQUIRE n.property IS NOT NULL [OPTIONS {}\]] -| Schema -| Create a constraint ensuring that all nodes with a particular label have a certain property. - -| xref::constraints/syntax.adoc#constraints-syntax-create-rel-exists[CREATE CONSTRAINT [existence\] [IF NOT EXISTS\] FOR ()-"["r:REL_TYPE"\]"-() REQUIRE r.property IS NOT NULL [OPTIONS {}\]] -| Schema -| Create a constraint ensuring that all relationships with a particular relationship type have a certain property. - -| xref::constraints/syntax.adoc#constraints-syntax-create-node-key[CREATE CONSTRAINT [node_key\] [IF NOT EXISTS\] FOR (n:Label) REQUIRE (n.prop1[, ..., n.propN\]) IS [NODE\] KEY [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a constraint ensuring that all nodes with a particular label have all the specified properties and that the combination of property values is unique; i.e. ensures existence and uniqueness. - -| xref::constraints/syntax.adoc#constraints-syntax-create-rel-key[CREATE CONSTRAINT [rel_key\] [IF NOT EXISTS\] FOR ()-"["r:REL_TYPE"\]"-() REQUIRE (r.prop1[, ..., r.propN\]) IS [REL[ATIONSHIP\]\] KEY [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a constraint ensuring that all relationships with a particular relationship type have all the specified properties and that the combination of property values is unique; i.e. ensures existence and uniqueness. - -| xref::constraints/syntax.adoc#constraints-syntax-create-node-prop-type[CREATE CONSTRAINT [property_type\] [IF NOT EXISTS\] FOR (n:Label) REQUIRE n.property IS :: type [OPTIONS {}\]] -| Schema -| Create a constraint ensuring that the property has the required property type (given by `type`) for all nodes with a particular label. - -| xref::constraints/syntax.adoc#constraints-syntax-create-rel-prop-type[CREATE CONSTRAINT [property_type\] [IF NOT EXISTS\] FOR ()-"["r:REL_TYPE"\]"-() REQUIRE r.property IS :: type [OPTIONS {}\]] -| Schema -| Create a constraint ensuring that the property has the required property type (given by `type`) for all relationships with a particular relationship type. - -| xref::constraints/syntax.adoc#constraints-syntax-create-node-unique[CREATE CONSTRAINT [uniqueness\] [IF NOT EXISTS\] FOR (n:Label) REQUIRE (n.prop1[, ..., n.propN\]) IS [NODE\] UNIQUE [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a constraint ensuring the uniqueness of the combination of node label and property values for a particular property key combination across all nodes. - -| xref::constraints/syntax.adoc#constraints-syntax-create-rel-unique[CREATE CONSTRAINT [uniqueness\] [IF NOT EXISTS\] FOR ()-"["r:REL_TYPE"\]"-() REQUIRE (r.prop1[, ..., r.propN\]) IS [REL[ATIONSHIP\]\] UNIQUE [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a constraint ensuring the uniqueness of the combination of relationship type and property values for a particular property key combination across all relationships. - -| xref::indexes-for-full-text-search.adoc[CREATE FULLTEXT INDEX [name\] [IF NOT EXISTS\] FOR (n:Label["\|" ... "\|" LabelN\]) ON EACH "[" n.property[, ..., n.propertyN\] "\]" [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a fulltext index on nodes. - -| xref::indexes-for-full-text-search.adoc[CREATE FULLTEXT INDEX [name\] [IF NOT EXISTS\] FOR ()-"["r:TYPE["\|" ... "\|" TYPE_N\]"\]"-() ON EACH "[" r.property[, ..., r.propertyN\] "\]" [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a fulltext index on relationships. - -| xref::indexes-for-search-performance.adoc#indexes-syntax[CREATE LOOKUP INDEX [name\] [IF NOT EXISTS\] FOR (n) ON EACH labels(n) [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create an index on all nodes with any label. - -| xref::indexes-for-search-performance.adoc#indexes-syntax[CREATE LOOKUP INDEX [name\] [IF NOT EXISTS\] FOR ()-"["r"\]"-() ON [EACH\] type(r) [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create an index on all relationships with any relationship type. - -| xref::indexes-for-search-performance.adoc#indexes-syntax[CREATE POINT INDEX [name\] [IF NOT EXISTS\] FOR (n:Label) ON (n.property) [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a point index on nodes. - -| xref::indexes-for-search-performance.adoc#indexes-syntax[CREATE POINT INDEX [name\] [IF NOT EXISTS\] FOR ()-"["r:TYPE"\]"-() ON (r.property) [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a point index on relationships. - -| xref::indexes-for-search-performance.adoc#indexes-syntax[CREATE [RANGE\] INDEX [name\] [IF NOT EXISTS\] FOR (n:Label) ON (n.property[, ..., n.propertyN\]) [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a range index on nodes. - -| xref::indexes-for-search-performance.adoc#indexes-syntax[CREATE [RANGE\] INDEX [name\] [IF NOT EXISTS\] FOR ()-"["r:TYPE"\]"-() ON (r.property[, ..., r.propertyN\]) [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a range index on relationships. - -| xref::indexes-for-search-performance.adoc#indexes-syntax[CREATE TEXT INDEX [name\] [IF NOT EXISTS\] FOR (n:Label) ON (n.property) [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a text index on nodes. - -| xref::indexes-for-search-performance.adoc#indexes-syntax[CREATE TEXT INDEX [name\] [IF NOT EXISTS\] FOR ()-"["r:TYPE"\]"-() ON (r.property) [OPTIONS {optionKey: optionValue[, ...\]}\]] -| Schema -| Create a text index on relationships. - -| xref::clauses/delete.adoc[DELETE] -| Writing -| -Delete nodes, relationships or paths. -Any node to be deleted must also have all associated relationships explicitly deleted. - -| xref::clauses/delete.adoc[DETACH DELETE] -| Writing -| -Delete a node or set of nodes. -All associated relationships will automatically be deleted. - -| xref::constraints/syntax.adoc[DROP CONSTRAINT name [IF EXISTS\]] -| Schema -| Drop a constraint using the name. - -| xref::indexes-for-search-performance.adoc#indexes-syntax[DROP INDEX name [IF EXISTS\]] -| Schema -| Drop an index using the name. - -| xref::clauses/foreach.adoc[FOREACH] -| Writing -| Update data within a list, whether components of a path, or the result of aggregation. - -| xref::clauses/limit.adoc[LIMIT] -| Reading sub-clause -| A sub-clause used to constrain the number of rows in the output. - -| xref::clauses/load-csv.adoc[LOAD CSV] -| Importing data -| Use when importing data from CSV files. - -| xref::clauses/match.adoc[MATCH] -| Reading -| Specify the patterns to search for in the database. - -| xref::clauses/merge.adoc[MERGE] -| Reading/Writing -| -Ensures that a pattern exists in the graph. -Either the pattern already exists, or it needs to be created. - -| xref::clauses/merge.adoc#query-merge-on-create-on-match[ON CREATE] -| Reading/Writing -| Used in conjunction with `MERGE`, specifying the actions to take if the pattern needs to be created. - -| xref::clauses/merge.adoc#query-merge-on-create-on-match[ON MATCH] -| Reading/Writing -| Used in conjunction with `MERGE`, specifying the actions to take if the pattern already exists. - -| xref::clauses/optional-match.adoc[OPTIONAL MATCH] -| Reading -| Specify the patterns to search for in the database while using `nulls` for missing parts of the pattern. - -| xref::clauses/order-by.adoc[ORDER BY [ASC[ENDING\] \| DESC[ENDING\]\]] -| Reading sub-clause -| A sub-clause following `RETURN` or `WITH`, specifying that the output should be sorted in either ascending (the default) or descending order. - -| xref::clauses/remove.adoc[REMOVE] -| Writing -| Remove properties and labels from nodes and relationships. - -| xref::clauses/return.adoc[RETURN ... [AS\]] -| Projecting -| Defines what to include in the query result set. - -| xref::clauses/set.adoc[SET] -| Writing -| Update labels on nodes and properties on nodes and relationships. - -| xref::constraints/syntax.adoc#constraints-syntax-list[SHOW [...\] CONSTRAINT[S\]] -| Schema -| -List constraints in the database, either all or filtered on type. -Also allows `WHERE` and `YIELD` clauses. - -| xref::indexes-for-search-performance.adoc#indexes-list-indexes[SHOW [ALL\|FULLTEXT\|LOOKUP\|POINT\|RANGE\|TEXT\] INDEX[ES\]] -| Schema -| -List indexes in the database, either all or filtered on fulltext, lookup, point, range, or text indexes. -Also allows `WHERE` and `YIELD` clauses. - -| xref::clauses/listing-functions.adoc[SHOW [ALL\|BUILT IN\|USER DEFINED\] FUNCTION[S\] [EXECUTABLE [BY {CURRENT USER\|username}\]\]] -| DBMS -| -List functions, either all or filtered. -Available filters are executable by a user or function type (built-in or user-defined). -Also allows `WHERE` and `YIELD` clauses. - -| xref::clauses/listing-procedures.adoc[SHOW PROCEDURE[S\] [EXECUTABLE [BY {CURRENT USER\|username}\]\]] -| DBMS -| -List procedures, either all or filtered on executable by a user. -Also allows `WHERE` and `YIELD` clauses. - -| xref:clauses/listing-settings.adoc[SHOW SETTINGS[S\] [setting-name[, ...\]\]] -| DBMS -| -List configuration settings, either all or filtered on setting name(s). -Also allows `WHERE` and `YIELD` clauses. - -|xref:clauses/transaction-clauses.adoc#query-listing-transactions[SHOW TRANSACTION[S\] [transaction-id[, ...\]\]] -| DBMS -| -List transactions, either all or filtered on ID. -Also allows `WHERE` and `YIELD` clauses. - -| xref::clauses/skip.adoc[SKIP] -| Reading/Writing -| A sub-clause defining from which row to start including the rows in the output. - -| xref:clauses/transaction-clauses.adoc#query-terminate-transactions[TERMINATE TRANSACTION[S\] transaction-id[, ...\]] -| DBMS -| Terminate transactions with the given IDs. - -| xref::clauses/union.adoc[UNION] -| Set operations -| -Combines the result of multiple queries. -Duplicates are removed. - -| xref::clauses/union.adoc[UNION ALL] -| Set operations -| -Combines the result of multiple queries. -Duplicates are retained. - -| xref::clauses/unwind.adoc[UNWIND ... [AS\]] -| Projecting -| Expands a list into a sequence of rows. - -| xref::clauses/use.adoc[USE] -| Multiple graphs -| Determines which graph a query, or query part, is executed against. - -| xref::query-tuning/using.adoc#query-using-index-hint[USING INDEX variable:Label(property)] -| Hint -| Index hints are used to specify which index, if any, the planner should use as a starting point. - -| xref::query-tuning/using.adoc#query-using-index-hint[USING INDEX SEEK variable:Label(property)] -| Hint -| Index seek hint instructs the planner to use an index seek for this clause. - -| xref::query-tuning/using.adoc#query-using-join-hint[USING JOIN ON variable] -| Hint -| Join hints are used to enforce a join operation at specified points. - -| xref::query-tuning/using.adoc#query-using-scan-hint[USING SCAN variable:Label] -| Hint -| Scan hints are used to force the planner to do a label scan (followed by a filtering operation) instead of using an index. - -| xref::clauses/with.adoc[WITH ... [AS\]] -| Projecting -| Allows query parts to be chained together, piping the results from one to be used as starting points or criteria in the next. - -| xref::clauses/where.adoc[WHERE] -| Reading sub-clause -| A sub-clause used to add constraints to the patterns in a `MATCH` or `OPTIONAL MATCH` clause, or to filter the results of a `WITH` clause. - -|=== - - -[[glossary-operators]] -== xref::syntax/operators.adoc[Operators] - -[options="header"] -|=== -|Operator | Category | Description - -| xref::syntax/operators.adoc#query-operators-mathematical[%] -| Mathematical -| Modulo division. - -| xref::syntax/operators.adoc#query-operators-mathematical[*] -| Mathematical -| Multiplication. - -| xref::syntax/operators.adoc#query-operators-temporal[*] -| Temporal -| Multiplying a duration with a number. - -| xref::syntax/operators.adoc#query-operators-mathematical[+] -| Mathematical -| Addition. - -| xref::syntax/operators.adoc#query-operators-string[+] -| String -| Concatenation. - -| xref::syntax/operators.adoc#query-operators-property[+=] -| Property -| Property mutation. - -| xref::syntax/operators.adoc#query-operators-list[+] -| List -| Concatenation - -| xref::syntax/operators.adoc#query-operators-temporal[+] -| Temporal -| Adding two durations, or a duration and a temporal instant. - -| xref::syntax/operators.adoc#query-operators-mathematical[-] -| Mathematical -| Subtraction or unary minus. - -| xref::syntax/operators.adoc#query-operators-temporal[-] -| Temporal -| Subtracting a duration from a temporal instant or from another duration. - -| xref::syntax/operators.adoc#query-operators-map[.] -| Map -| Static value access by key. - -| xref::syntax/operators.adoc#query-operators-property[.] -| Property -| Static property access. - -| xref::syntax/operators.adoc#query-operators-mathematical[/] -| Mathematical -| Division. - -| xref::syntax/operators.adoc#query-operators-temporal[/] -| Temporal -| Dividing a duration by a number. - -| xref::syntax/operators.adoc#query-operators-comparison[<] -| Comparison -| Less than. - -| xref::syntax/operators.adoc#query-operators-comparison[<=] -| Comparison -| Less than or equal to. - -| xref::syntax/operators.adoc#query-operators-comparison[<>] -| Comparison -| Inequality. - -| xref::syntax/operators.adoc#query-operators-comparison[=] -| Comparison -| Equality. - -| xref::syntax/operators.adoc#query-operators-property[=] -| Property -| Property replacement. - -| xref::syntax/operators.adoc#query-operators-string[=~] -| String -| Regular expression match. - -| xref::syntax/operators.adoc#query-operators-comparison[>] -| Comparison -| Greater than. - -| xref::syntax/operators.adoc#query-operators-comparison[>=] -| Comparison -| Greater than or equal to. - -| xref::syntax/operators.adoc#query-operators-boolean[AND] -| Boolean -| Conjunction. - -| xref::syntax/operators.adoc#query-operator-comparison-string-specific[CONTAINS] -| String comparison -| Case-sensitive inclusion search. - -| xref::syntax/operators.adoc#query-operators-aggregation[DISTINCT] -| Aggregation -| Duplicate removal. - -| xref::syntax/operators.adoc#query-operator-comparison-string-specific[ENDS WITH] -| String comparison -| Case-sensitive suffix search. - -| xref::syntax/operators.adoc#query-operators-list[IN] -| List -| List element existence check. - -| xref::syntax/operators.adoc#query-operators-comparison[IS NOT NULL] -| Comparison -| Non-`null` check. - -| xref::syntax/operators.adoc#query-operators-comparison[IS NULL] -| Comparison -| `null` check. - -| xref::syntax/operators.adoc#query-operators-boolean[NOT] -| Boolean -| Negation. - -| xref::syntax/operators.adoc#query-operators-boolean[OR] -| Boolean -| Disjunction. - -| xref::syntax/operators.adoc#query-operator-comparison-string-specific[STARTS WITH] -| String comparison -| Case-sensitive prefix search. - -| xref::syntax/operators.adoc#query-operators-boolean[XOR] -| Boolean -| Exclusive disjunction. - -| xref::syntax/operators.adoc#query-operators-map[[\]] -| Map -| Subscript (dynamic value access by key). - -| xref::syntax/operators.adoc#query-operators-property[[\]] -| Property -| Subscript (dynamic property access). - -| xref::syntax/operators.adoc#query-operators-list[[\]] -| List -| Subscript (accessing element(s) in a list). - -| xref::syntax/operators.adoc#query-operators-mathematical[^] -| Mathematical -| Exponentiation. - -|=== - - -[[glossary-functions]] -== xref::functions/index.adoc[Functions] - -[options="header"] -|=== -| Function | Category | Description - -| xref::functions/mathematical-numeric.adoc#functions-abs[abs()] -| Numeric -| Returns the absolute value of a `FLOAT`. - -| xref::functions/mathematical-trigonometric.adoc#functions-acos[acos()] -| Trigonometric -| Returns the arccosine of a `FLOAT` in radians. - -| xref::functions/predicate.adoc#functions-all[all()] -| Predicate -| Returns true if the predicate holds for all elements in the given `LIST`. - -| xref::functions/predicate.adoc#functions-any[any()] -| Predicate -| Returns true if the predicate holds for at least one element in the given `LIST`. - -| xref::functions/mathematical-trigonometric.adoc#functions-asin[asin()] -| Trigonometric -| Returns the arcsine of a `FLOAT` in radians. - -| xref::functions/mathematical-trigonometric.adoc#functions-atan[atan()] -| Trigonometric -| Returns the arctangent of a `FLOAT` in radians. - -| xref::functions/mathematical-trigonometric.adoc#functions-atan2[atan2()] -| Trigonometric -| Returns the arctangent2 of a set of coordinates in radians. - -| xref::functions/aggregating.adoc#functions-avg[avg()] -| Aggregating -| Returns the average of a set of values. - -| xref::functions/mathematical-numeric.adoc#functions-ceil[ceil()] -| Numeric -| Returns the smallest `FLOAT` that is greater than or equal to a number and equal to an `INTEGER`. - -| xref::functions/scalar.adoc#functions-coalesce[coalesce()] -| Scalar -| Returns the first non-`null` value in a list of expressions. - -| xref::functions/aggregating.adoc#functions-collect[collect()] -| Aggregating -| Returns a list containing the values returned by an expression. - -| xref::functions/mathematical-trigonometric.adoc#functions-cos[cos()] -| Trigonometric -| Returns the cosine of a `FLOAT`. - -| xref::functions/mathematical-trigonometric.adoc#functions-cot[cot()] -| Trigonometric -| Returns the cotangent of a `FLOAT`. - -| xref::functions/aggregating.adoc#functions-count[count()] -| Aggregating -| Returns the number of values or rows. - -| xref::functions/temporal/index.adoc#functions-date-current[date()] -| Temporal -| Returns the current `DATE`. - -| xref::functions/temporal/index.adoc#functions-date-calendar[date({year [, month, day\]})] -| Temporal -| Returns a calendar (Year-Month-Day) `DATE`. - -| xref::functions/temporal/index.adoc#functions-date-week[date({year [, week, dayOfWeek\]})] -| Temporal -| Returns a week (Year-Week-Day) `DATE`. - -| xref::functions/temporal/index.adoc#functions-date-quarter[date({year [, quarter, dayOfQuarter\]})] -| Temporal -| Returns a quarter (Year-Quarter-Day) `DATE`. - -| xref::functions/temporal/index.adoc#functions-date-ordinal[date({year [, ordinalDay\]})] -| Temporal -| Returns an ordinal (Year-Day) `DATE`. - -| xref::functions/temporal/index.adoc#functions-date-create-string[date(string)] -| Temporal -| Returns a `DATE` by parsing a `STRING`. - -| xref::functions/temporal/index.adoc#functions-date-temporal[+date({map})+] -| Temporal -| Returns a `DATE` from a map of another temporal value's components. - -| xref::functions/temporal/index.adoc#functions-date-realtime[date.realtime()] -| Temporal -| Returns the current `DATE` using the `realtime` clock. - -| xref::functions/temporal/index.adoc#functions-date-statement[date.statement()] -| Temporal -| Returns the current `DATE` using the `statement` clock. - -| xref::functions/temporal/index.adoc#functions-date-transaction[date.transaction()] -| Temporal -| Returns the current `DATE` using the `transaction` clock. - -| xref::functions/temporal/index.adoc#functions-date-truncate[date.truncate()] -| Temporal -| Returns a `DATE` obtained by truncating a value at a specific component boundary. xref::functions/temporal/index.adoc#functions-temporal-truncate-overview[Truncation summary]. - -| xref::functions/temporal/index.adoc#functions-datetime-current[datetime()] -| Temporal -| Returns the current `ZONED DATETIME`. - -| xref::functions/temporal/index.adoc#functions-datetime-calendar[datetime({year [, month, day, ...\]})] -| Temporal -| Returns a calendar (Year-Month-Day) `ZONED DATETIME`. - -| xref::functions/temporal/index.adoc#functions-datetime-week[datetime({year [, week, dayOfWeek, ...\]})] -| Temporal -| Returns a week (Year-Week-Day) `ZONED DATETIME`. - -| xref::functions/temporal/index.adoc#functions-datetime-quarter[datetime({year [, quarter, dayOfQuarter, ...\]})] -| Temporal -| Returns a quarter (Year-Quarter-Day) `ZONED DATETIME`. - -| xref::functions/temporal/index.adoc#functions-datetime-ordinal[datetime({year [, ordinalDay, ...\]})] -| Temporal -| Returns an ordinal (Year-Day) `ZONED DATETIME`. - -| xref::functions/temporal/index.adoc#functions-datetime-create-string[datetime(string)] -| Temporal -| Returns a `ZONED DATETIME` by parsing a `STRING`. - -| xref::functions/temporal/index.adoc#functions-datetime-temporal[+datetime({map})+] -| Temporal -| Returns a `ZONED DATETIME` from a map of another temporal value's components. - -| xref::functions/temporal/index.adoc#functions-datetime-timestamp[+datetime({epochSeconds})+] -| Temporal -| Returns a `ZONED DATETIME` from a timestamp. - -| xref::functions/temporal/index.adoc#functions-datetime-realtime[datetime.realtime()] -| Temporal -| Returns the current `ZONED DATETIME` using the `realtime` clock. - -| xref::functions/temporal/index.adoc#functions-datetime-statement[datetime.statement()] -| Temporal -| Returns the current `ZONED DATETIME` using the `statement` clock. - -| xref::functions/temporal/index.adoc#functions-datetime-transaction[datetime.transaction()] -| Temporal -| Returns the current `ZONED DATETIME` using the `transaction` clock. - -| xref::functions/temporal/index.adoc#functions-datetime-truncate[datetime.truncate()] -| Temporal -| -Returns a `ZONED DATETIME` obtained by truncating a value at a specific component boundary. -xref::functions/temporal/index.adoc#functions-temporal-truncate-overview[Truncation summary]. - -| xref::functions/mathematical-trigonometric.adoc#functions-degrees[degrees()] -| Trigonometric -| Converts radians to degrees. - -| xref::functions/temporal/duration.adoc#functions-duration[+duration({map})+] -| Temporal -| Returns a `DURATION` from a map of its components. - -| xref::functions/temporal/duration.adoc#functions-duration-create-string[duration(string)] -| Temporal -| Returns a `DURATION` by parsing a `STRING`. - -| xref::functions/temporal/duration.adoc#functions-duration-between[duration.between()] -| Temporal -| Returns a `DURATION` equal to the difference between two given instants. - -| xref::functions/temporal/duration.adoc#functions-duration-indays[duration.inDays()] -| Temporal -| Returns a `DURATION` equal to the difference in whole days or weeks between two given instants. - -| xref::functions/temporal/duration.adoc#functions-duration-inmonths[duration.inMonths()] -| Temporal -| Returns a `DURATION` equal to the difference in whole months, quarters or years between two given instants. - -| xref::functions/temporal/duration.adoc#functions-duration-inseconds[duration.inSeconds()] -| Temporal -| Returns a `DURATION` equal to the difference in seconds and fractions of seconds, or minutes or hours, between two given instants. - -| xref::functions/mathematical-logarithmic.adoc#functions-e[e()] -| Logarithmic -| Returns the base of the natural logarithm, `e`. - -| xref::functions/scalar.adoc#functions-endnode[endNode()] -| Scalar -| Returns the end `NODE` of a `RELATIONSHIP`. - -| xref::functions/predicate.adoc#functions-exists[exists()] -| Predicate -| Returns `true` if a match for the pattern exists in the graph. - -| xref::functions/mathematical-logarithmic.adoc#functions-exp[exp()] -| Logarithmic -| Returns `e^n`, where `e` is the base of the natural logarithm, and `n` is the value of the argument expression. - -| xref::functions/mathematical-numeric.adoc#functions-floor[floor()] -| Numeric -| Returns the largest `FLOAT` that is less than or equal to a number and equal to an `INTEGER`. - -| xref::functions/mathematical-trigonometric.adoc#functions-haversin[haversin()] -| Trigonometric -| Returns half the versine of a number. - -| xref::functions/scalar.adoc#functions-head[head()] -| Scalar -| Returns the first element in a `LIST`. - -| xref::functions/scalar.adoc#functions-id[id()] -| Scalar -| Returns the id of a `RELATIONSHIP` or `NODE`. - -| xref::functions/predicate.adoc#functions-isempty[isEmpty()] -| Predicate -| Returns true if the given `LIST` or `MAP` contains no elements or if the given `STRING` contains no characters. - -| xref::functions/mathematical-numeric.adoc#functions-isnan[isNaN()] -| Numeric -| Returns `true` if the given numeric value is `NaN` (Not a Number). - -| xref::functions/list.adoc#functions-keys[keys()] -| List -| Returns a `LIST` containing the `STRING` representations for all the property names of a `NODE`, `RELATIONSHIP`, or `MAP`. - -| xref::functions/list.adoc#functions-labels[labels()] -| List -| Returns a `LIST` containing the `STRING` representations for all the labels of a `NODE`. - -| xref::functions/scalar.adoc#functions-last[last()] -| Scalar -| Returns the last element in a `LIST`. - -| xref::functions/string.adoc#functions-left[left()] -| String -| Returns a `STRING` containing the specified number (`INTEGER`) of leftmost characters in the given `STRING`. - -| xref::functions/scalar.adoc#functions-length[length()] -| Scalar -| Returns the length of a `PATH`. - -| xref::functions/temporal/index.adoc#functions-localdatetime-current[localdatetime()] -| Temporal -| Returns the current `LOCAL DATETIME`. - -| xref::functions/temporal/index.adoc#functions-localdatetime-calendar[localdatetime({year [, month, day, ...\]})] -| Temporal -| Returns a calendar (Year-Month-Day) `LOCAL DATETIME`. - -| xref::functions/temporal/index.adoc#functions-localdatetime-week[localdatetime({year [, week, dayOfWeek, ...\]})] -| Temporal -| Returns a week (Year-Week-Day) `LOCAL DATETIME`. - -| xref::functions/temporal/index.adoc#functions-localdatetime-quarter[localdatetime({year [, quarter, dayOfQuarter, ...\]})] -| Temporal -| Returns a quarter (Year-Quarter-Day) `ZONED DATETIME`. - -| xref::functions/temporal/index.adoc#functions-localdatetime-ordinal[localdatetime({year [, ordinalDay, ...\]})] -| Temporal -| Returns an ordinal (Year-Day) `LOCAL DATETIME`. - -| xref::functions/temporal/index.adoc#functions-localdatetime-create-string[localdatetime(string)] -| Temporal -| Returns a `LOCAL DATETIME` by parsing a `STRING`. - -| xref::functions/temporal/index.adoc#functions-localdatetime-temporal[localdatetime(+{map}+)] -| Temporal -| Returns a `LOCAL DATETIME` from a map of another temporal value's components. - -| xref::functions/temporal/index.adoc#functions-localdatetime-realtime[localdatetime.realtime()] -| Temporal -| Returns the current `LOCAL DATETIME` using the `realtime` clock. - -| xref::functions/temporal/index.adoc#functions-localdatetime-statement[localdatetime.statement()] -| Temporal -| Returns the current `LOCAL DATETIME` using the `statement` clock. - -| xref::functions/temporal/index.adoc#functions-localdatetime-transaction[localdatetime.transaction()] -| Temporal -| Returns the current `LOCAL DATETIME` using the `transaction` clock. - -| xref::functions/temporal/index.adoc#functions-localdatetime-truncate[localdatetime.truncate()] -| Temporal -| -Returns a `LOCAL DATETIME` obtained by truncating a value at a specific component boundary. -xref::functions/temporal/index.adoc#functions-temporal-truncate-overview[Truncation summary]. - -| xref::functions/temporal/index.adoc#functions-localtime-current[localtime()] -| Temporal -| Returns the current `LOCAL TIME`. - -| xref::functions/temporal/index.adoc#functions-localtime-create[localtime({hour [, minute, second, ...\]})] -| Temporal -| Returns a `LOCAL TIME` with the specified component values. - -| xref::functions/temporal/index.adoc#functions-localtime-create-string[localtime(string)] -| Temporal -| Returns a `LOCAL TIME` by parsing a `STRING`. - -| xref::functions/temporal/index.adoc#functions-localtime-temporal[localtime({time [, hour, ...\]})] -| Temporal -| Returns a `LOCAL TIME` from a map of another temporal value's components. - -| xref::functions/temporal/index.adoc#functions-localtime-realtime[localtime.realtime()] -| Temporal -| Returns the current `LOCAL TIME` using the `realtime` clock. - -| xref::functions/temporal/index.adoc#functions-localtime-statement[localtime.statement()] -| Temporal -| Returns the current `LOCAL TIME` using the `statement` clock. - -| xref::functions/temporal/index.adoc#functions-localtime-transaction[localtime.transaction()] -| Temporal -| Returns the current `LOCAL TIME` using the `transaction` clock. - -| xref::functions/temporal/index.adoc#functions-localtime-truncate[localtime.truncate()] -| Temporal -| -Returns a `LOCAL TIME` obtained by truncating a value at a specific component boundary. -xref::functions/temporal/index.adoc#functions-temporal-truncate-overview[Truncation summary]. - -| xref::functions/mathematical-logarithmic.adoc#functions-log[log()] -| Logarithmic -| Returns the natural logarithm of a `FLOAT`. - -| xref::functions/mathematical-logarithmic.adoc#functions-log10[log10()] -| Logarithmic -| Returns the common logarithm (base 10) of a `FLOAT`. - -| xref::functions/string.adoc#functions-ltrim[lTrim()] -| String -| Returns the given `STRING` with leading whitespace removed. - -| xref::functions/aggregating.adoc#functions-max[max()] -| Aggregating -| Returns the maximum value in a set of values. - -| xref::functions/aggregating.adoc#functions-min[min()] -| Aggregating -| Returns the minimum value in a set of values. - -| xref::functions/list.adoc#functions-nodes[nodes()] -| List -| Returns a `LIST` containing all the `NODE` values in a `PATH`. - -| xref::functions/predicate.adoc#functions-none[none()] -| Predicate -| Returns true if the predicate holds for no element in the given `LIST`. - -| xref::functions/aggregating.adoc#functions-percentilecont[percentileCont()] -| Aggregating -| Returns the percentile of the given value over a group using linear interpolation. - -| xref::functions/aggregating.adoc#functions-percentiledisc[percentileDisc()] -| Aggregating -| Returns the nearest value to the given percentile over a group using a rounding method. - -| xref::functions/mathematical-trigonometric.adoc#functions-pi[pi()] -| Trigonometric -| Returns the mathematical constant _pi_. - -| xref::functions/spatial.adoc#functions-point-cartesian-2d[point() - Cartesian 2D] -| Spatial -| Returns a 2D `POINT` object, given two coordinate values in the Cartesian coordinate system. - -| xref::functions/spatial.adoc#functions-point-cartesian-3d[point() - Cartesian 3D] -| Spatial -| Returns a 3D `POINT` object, given three coordinate values in the Cartesian coordinate system. - -| xref::functions/spatial.adoc#functions-point-wgs84-2d[point() - WGS 84 2D] -| Spatial -| Returns a 2D `POINT` object, given two coordinate values in the WGS 84 coordinate system. - -| xref::functions/spatial.adoc#functions-point-wgs84-3d[point() - WGS 84 3D] -| Spatial -| Returns a 3D `POINT` object, given three coordinate values in the WGS 84 coordinate system. - -| xref::functions/spatial.adoc#functions-distance[point.distance()] -| Spatial -| Returns true if the provided `POINT` is within the bounding box defined by the two provided points. - -| xref::functions/spatial.adoc#functions-distance[point.withinBBox()] -| Spatial -| Returns a `FLOAT` representing the geodesic distance between any two points in the same CRS. - -| xref::functions/scalar.adoc#functions-properties[properties()] -| Scalar -| Returns a `MAP` containing all the properties of a `NODE` or `RELATIONSHIP`. - -| xref::functions/mathematical-trigonometric.adoc#functions-radians[radians()] -| Trigonometric -| Converts degrees to radians. - -| xref::functions/mathematical-numeric.adoc#functions-rand[rand()] -| Numeric -| Returns a random `FLOAT` in the range from 0 (inclusive) to 1 (exclusive); i.e. `[0, 1)`. - -| xref::functions/scalar.adoc#functions-randomuuid[randomUUID()] -| Scalar -| Returns a `STRING` value corresponding to a randomly-generated UUID. - -| xref::functions/list.adoc#functions-range[range()] -| List -| Returns a `LIST` comprising all `INTEGER` values within a specified range. - -| xref::functions/list.adoc#functions-reduce[reduce()] -| List -| Runs an expression against individual elements of a `LIST`, storing the result of the expression in an accumulator. - -| xref::functions/list.adoc#functions-relationships[relationships()] -| List -| Returns a `LIST` containing all the `RELATIONSHIP` values in a `PATH`. - -| xref::functions/string.adoc#functions-replace[replace()] -| String -| Returns a `STRING` in which all occurrences of a specified string in the given `STRING` have been replaced by another (specified) `STRING`. - -| xref::functions/list.adoc#functions-reverse-list[reverse()] -| List -| Returns a `LIST` in which the order of all elements in the given `LIST` have been reversed. - -| xref::functions/string.adoc#functions-reverse[reverse()] -| String -| Returns a `STRING` in which the order of all characters in the given `STRING` have been reversed. - -| xref::functions/string.adoc#functions-right[right()] -| String -| Returns a `STRING` containing the specified number of rightmost characters in the given `STRING`. - -| xref::functions/mathematical-numeric.adoc#functions-round[round()] -| Numeric -| Returns the `FLOAT` of the given number rounded to the nearest mathematical `INTEGER`, with half-way values always rounded up. - -| xref::functions/mathematical-numeric.adoc#functions-round2[round(), with precision] -| Numeric -| Returns the `FLOAT` of the given number rounded with the specified precision, with half-values always being rounded up. - -| xref::functions/mathematical-numeric.adoc#functions-round3[round(), with precision and rounding mode] -| Numeric -| Returns the `FLOAT` of the given number rounded with the specified precision and the specified rounding mode. - -| xref::functions/string.adoc#functions-rtrim[rTrim()] -| String -| Returns the given `STRING` with trailing whitespace removed. - -| xref::functions/mathematical-numeric.adoc#functions-sign[sign()] -| Numeric -| Returns the signum of a number: `0` if the number is `0`, `-1` for any negative number, and `1` for any positive number. - -| xref::functions/mathematical-trigonometric.adoc#functions-sin[sin()] -| Trigonometric -| Returns the sine of a `FLOAT`. - -| xref::functions/predicate.adoc#functions-single[single()] -| Predicate -| Returns true if the predicate holds for exactly one of the elements in the given `LIST`. - -| xref::functions/scalar.adoc#functions-size[size()] -| Scalar -| Returns the number of items in a `LIST`. - -| xref::functions/scalar.adoc#functions-size-of-pattern-comprehension[size() applied to pattern comprehension] -| Scalar -| Returns the number of paths matching the pattern comprehension. - -| xref::functions/scalar.adoc#functions-size-of-string[size() applied to string] -| Scalar -| Returns the number of Unicode characters in a `STRING`. - -| xref::functions/string.adoc#functions-split[split()] -| String -| Returns a `LIST` resulting from the splitting of the given `STRING` around matches of the given delimiter. - -| xref::functions/mathematical-logarithmic.adoc#functions-sqrt[sqrt()] -| Logarithmic -| Returns the square root of a `FLOAT`. - -| xref::functions/scalar.adoc#functions-startnode[startNode()] -| Scalar -| Returns the start `NODE` of a `RELATIONSHIP`. - -| xref::functions/aggregating.adoc#functions-stdev[stDev()] -| Aggregating -| Returns the standard deviation for the given value over a group for a sample of a population. - -| xref::functions/aggregating.adoc#functions-stdevp[stDevP()] -| Aggregating -| Returns the standard deviation for the given value over a group for an entire population. - -| xref::functions/string.adoc#functions-substring[substring()] -| String -| Returns a substring of the given `STRING`, beginning with a 0-based index start and length. - -| xref::functions/aggregating.adoc#functions-sum[sum()] -| Aggregating -| Returns the sum of a set of numeric values. - -| xref::functions/list.adoc#functions-tail[tail()] -| List -| Returns all but the first element in a `LIST`. - -| xref::functions/mathematical-trigonometric.adoc#functions-tan[tan()] -| Trigonometric -| Returns the tangent of a `FLOAT`. - -| xref::functions/temporal/index.adoc#functions-time-current[time()] -| Temporal -| Returns the current `ZONED TIME`. - -| xref::functions/temporal/index.adoc#functions-time-create[time({hour [, minute, ...\]})] -| Temporal -| Returns a `ZONED TIME` with the specified component values. - -| xref::functions/temporal/index.adoc#functions-time-create-string[time(string)] -| Temporal -| Returns a `ZONED TIME` by parsing a `STRING`. - -| xref::functions/temporal/index.adoc#functions-time-temporal[time({time [, hour, ..., timezone\]})] -| Temporal -| Returns a `ZONED TIME` from a map of another temporal value's components. - -| xref::functions/temporal/index.adoc#functions-time-realtime[time.realtime()] -| Temporal -| Returns the current `ZONED TIME` using the `realtime` clock. - -| xref::functions/temporal/index.adoc#functions-time-statement[time.statement()] -| Temporal -| Returns the current `ZONED TIME` using the `statement` clock. - -| xref::functions/temporal/index.adoc#functions-time-transaction[time.transaction()] -| Temporal -| Returns the current `ZONED TIME` using the `transaction` clock. - -| xref::functions/temporal/index.adoc#functions-time-truncate[time.truncate()] -| Temporal -| -Returns a `ZONED TIME` obtained by truncating a value at a specific component boundary. -xref::functions/temporal/index.adoc#functions-temporal-truncate-overview[Truncation summary]. - -| xref::functions/scalar.adoc#functions-timestamp[timestamp()] -| Scalar -| Returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. - -| xref::functions/scalar.adoc#functions-toboolean[toBoolean()] -| Scalar -| Converts a `STRING` value to a `BOOLEAN` value. - -| xref::functions/scalar.adoc#functions-tofloat[toFloat()] -| Scalar -| Converts an `INTEGER` or `STRING` value to a `FLOAT`. - -| xref::functions/scalar.adoc#functions-tointeger[toInteger()] -| Scalar -| Converts a `FLOAT` or `STRING` value to an `INTEGER` value. - -| xref::functions/string.adoc#functions-tolower[toLower()] -| String -| Returns the given `STRING` in lowercase. - -| xref::functions/string.adoc#functions-tostring[toString()] -| String -| Converts an `INTEGER`, `FLOAT`, `BOOLEAN` or temporal (i.e. `DATE`, `ZONED TIME`, `LOCAL TIME`, `ZONED DATETIME`, `LOCAL DATETIME` or `DURATION`) value to a `STRING`. - -| xref::functions/string.adoc#functions-toupper[toUpper()] -| String -| Returns the given `STRING` in uppercase. - -| xref::functions/string.adoc#functions-trim[trim()] -| String -| Returns the given `STRING` with leading and trailing whitespace removed. - -| xref::functions/scalar.adoc#functions-type[type()] -| Scalar -| Returns a `STRING` representation of the `RELATIONSHIP` type. - -|=== - - -[[glossary-expressions]] -== Expressions - -[options="header"] -|=== -| Name | Description - -| xref::queries/case.adoc[CASE] -| A generic conditional expression, similar to if/else statements available in other languages. - -| xref:subqueries/collect.adoc[COLLECT {...}] -| Creates a list with the rows returned by a subquery. - -| xref:subqueries/count.adoc[COUNT {...}] -| Computes the number of results of a subquery. - -| xref:subqueries/existential.adoc[EXISTS {...}] -| Evaluates the existence of a subquery. - -| xref:values-and-types/type-predicate.adoc#[IS :: `type`] -| Verifies that an expression is of a certain type. -|=== - - -[[glossary-cypher-query-options]] -== Cypher query options - -[options="header"] -|=== -| Name | Type | Description - -//// -Removed in 5.0 -| xref::query-tuning/query-options.adoc#cypher-version[CYPHER $version query] -| Version -| -This will force `'query'` to use Neo4j Cypher `$version`. -//// - -| xref::query-tuning/query-options.adoc#cypher-runtime[CYPHER runtime=interpreted query] -| Runtime -| -This will force the query planner to use the interpreted runtime. -This is the only option in Neo4j Community Edition. - -| xref::query-tuning/query-options.adoc#cypher-runtime[CYPHER runtime=slotted query] -| Runtime -| -This will cause the query planner to use the slotted runtime. -This is only available in Neo4j Enterprise Edition. - -| xref::query-tuning/query-options.adoc#cypher-runtime[CYPHER runtime=pipelined query] -| Runtime -| -This will cause the query planner to use the pipelined runtime if it supports `'query'`. -This is only available in Neo4j Enterprise Edition. - -|=== - - -[[glossary-admin-commands]] -== Administrative commands - -The following commands are only executable against the `system` database: - -[options="header"] -|=== -| Command | Admin category | Description - -| xref::administration/aliases.adoc#alias-management-alter-database-alias[ALTER ALIAS ... [IF EXISTS\] SET DATABASE ...] -| Database alias -| Modifies a database alias. - -| xref::administration/access-control/manage-users.adoc#access-control-alter-password[ALTER CURRENT USER SET PASSWORD FROM ... TO] -| User and role -| Change the password of the user that is currently logged in. - -| xref:administration/databases.adoc#administration-databases-alter-database[ALTER DATABASE ... [IF EXISTS\] [SET ACCESS {READ ONLY \| READ WRITE}\] [SET TOPOLOGY n PRIMAR{Y\|IES} [m SECONDAR{Y\|IES}\]\] [WAIT [n [SEC[OND[S\]\]\]\]\|NOWAIT\]] -| Database -| Modifies the database access mode and / or topology. - -| xref::administration/servers.adoc#server-management-syntax[ALTER SERVER ... [SET OPTIONS\] {...}] -| Server management -| Modifies the options for a server. - -| xref::administration/access-control/manage-users.adoc#access-control-alter-users[ALTER USER ... [IF EXISTS\] [SET [PLAINTEXT \| ENCRYPTED\] PASSWORD {password [CHANGE [NOT\] REQUIRED\] \| CHANGE [NOT\] REQUIRED}\] [SET STATUS {ACTIVE \| SUSPENDED}\] [SET HOME DATABASE name\] [REMOVE HOME DATABASE\]] -| User and role -| -Changes a user account. -Changes can include setting a new password, setting the account status, setting or removing home database and enabling that the user should change the password upon next login. - -| xref::administration/aliases.adoc#alias-management-create-database-alias[CREATE [OR REPLACE\] ALIAS ... [IF NOT EXISTS\] FOR DATABASE ...] -| Database alias -| Creates a new database alias. - -| xref::administration/databases.adoc#administration-databases-create-composite-database[CREATE [OR REPLACE\] COMPOSITE DATABASE ... [IF NOT EXISTS\] [OPTIONS {}\] [WAIT [n [SEC[OND[S\]\]\]\]\|NOWAIT\]] -| Database -| Creates a new composite database. - -| xref:administration/databases.adoc#administration-databases-create-database[CREATE [OR REPLACE\] DATABASE ... [IF NOT EXISTS\] [TOPOLOGY n PRIMAR{Y\|IES} [m SECONDAR{Y\|IES}\]\] [OPTIONS {optionKey: optionValue[, ...\]}\] [WAIT [n [SEC[OND[S\]\]\]\]\|NOWAIT\]] -| Database -| Creates a new database. - -| xref::administration/access-control/manage-roles.adoc#access-control-create-roles[CREATE [OR REPLACE\] ROLE ... [IF NOT EXISTS\] [AS COPY OF\]] -| User and role -| Creates new roles. - -| xref::administration/access-control/manage-users.adoc#access-control-create-users[CREATE [OR REPLACE\] USER ... [IF NOT EXISTS\] SET [PLAINTEXT \| ENCRYPTED\] PASSWORD ... [[SET PASSWORD\] CHANGE [NOT\] REQUIRED\] [SET STATUS {ACTIVE \| SUSPENDED}\] [SET HOME DATABASE name\]] -| User and role -| -Creates a new user and sets the password for the new account. -Optionally the account status and home database can also be set and if the user should change the password upon first login. - -| xref::administration/servers.adoc#server-management-deallocate[DEALLOCATE DATABASE(S) FROM SERVER(S) ...] -| Server management -| Removes databases from the specified servers. - -| xref:administration/access-control/database-administration.adoc[DENY [IMMUTABLE\] ... ON DATABASE ... TO] -| Privilege -| Denies a database or schema privilege to one or multiple roles. - -| xref:administration/access-control/dbms-administration.adoc[DENY [IMMUTABLE\] ... ON DBMS TO] -| Privilege -| Denies a DBMS privilege to one or multiple roles. - -| xref:administration/access-control/manage-privileges.adoc#access-control-graph-privileges[DENY [IMMUTABLE\] ... ON GRAPH ... [NODES \| RELATIONSHIPS \| ELEMENTS\] ... TO] -| Privilege -| Denies a graph privilege for one or multiple specified elements to one or multiple roles. - -| xref::administration/aliases.adoc#alias-management-drop-database-alias[DROP ALIAS ... [IF EXISTS\] FOR DATABASE] -| Database alias -| Deletes a specified database alias. - -| xref::administration/databases.adoc#administration-databases-drop-database[DROP COMPOSITE DATABASE ... [IF EXISTS\] [DUMP DATA \| DESTROY DATA\] [WAIT [n [SEC[OND[S\]\]\]\]\|NOWAIT\]] -| Database -| Deletes a specified composite database. - -| xref::administration/databases.adoc#administration-databases-drop-database[DROP DATABASE ... [IF EXISTS\] [DUMP DATA \| DESTROY DATA\]] -| Database -| Deletes a specified database (either standard or composite). - -| xref::administration/access-control/manage-roles.adoc#access-control-drop-roles[DROP ROLE ... [IF EXISTS\]] -| User and role -| Deletes a specified role. - -| xref::administration/servers.adoc#server-management-drop-server[DROP SERVER ...] -| Server management -| Removes a specified server. - -| xref::administration/access-control/manage-users.adoc#access-control-drop-users[DROP USER ... [IF EXISTS\]] -| User and role -| Deletes a specified user. - -| xref::administration/servers.adoc#server-management-enable-server[ENABLE SERVER [OPTIONS\]] -| Server management -| Enables a specified server. - -| xref:administration/access-control/database-administration.adoc[GRANT [IMMUTABLE\] ... ON DATABASE ... TO] -| Privilege -| Assigns a database or schema privilege to one or multiple roles. - -| xref:administration/access-control/dbms-administration.adoc[GRANT [IMMUTABLE\] ... ON DBMS TO] -| Privilege -| Assigns a DBMS privilege to one or multiple roles. - -| xref:administration/access-control/manage-privileges.adoc#access-control-graph-privileges[GRANT [IMMUTABLE\] ... ON GRAPH ... [NODES \| RELATIONSHIPS \| ELEMENTS\] ... TO] -| Privilege -| Assigns a graph privilege for one or multiple specified elements to one or multiple roles. - -| xref:administration/access-control/manage-roles.adoc#access-control-assign-roles[GRANT [IMMUTABLE\] ROLE[S\] ... TO] -| User and role -| Assigns one or multiple roles to one or multiple users. - -| xref::administration/servers.adoc#server-management-reallocate[REALLOCATE DATABASE(S)] -| Server management -| Re-balance databases among all servers. - -| xref::administration/access-control/manage-roles.adoc#access-control-rename-roles[RENAME ROLE ... [IF EXISTS\] TO ...] -| User and role -| Changes the name of a role. - -| xref::administration/access-control/manage-users.adoc#access-control-rename-users[RENAME USER ... [IF EXISTS\] TO ...] -| User and role -| Changes the name of a user. - -| xref:administration/access-control/database-administration.adoc[REVOKE [IMMUTABLE\] [GRANT \| DENY\] ... ON DATABASE ... FROM] -| Privilege -| Removes a database or schema privilege from one or multiple roles. - -| xref:administration/access-control/dbms-administration.adoc[REVOKE [IMMUTABLE\] [GRANT \| DENY\] ... ON DBMS FROM] -| Privilege -| Removes a DBMS privilege from one or multiple roles. - -| xref:administration/access-control/manage-privileges.adoc#access-control-revoke-privileges[REVOKE [IMMUTABLE\] [GRANT \| DENY\] ... ON GRAPH ... [NODES \| RELATIONSHIPS \| ELEMENTS\] ... FROM] -| Privilege -| Removes a graph privilege for one or multiple specified elements from one or multiple roles. - -| xref::administration/access-control/manage-roles.adoc#access-control-revoke-roles[REVOKE ROLE[S\] ... FROM] -| User and role -| Removes one or multiple roles from one or multiple users. - -| xref::administration/aliases.adoc#alias-management-show-alias[SHOW ALIASES FOR DATABASE] -| Database alias -| Returns information about all aliases, optionally including driver settings. - -| xref::administration/access-control/manage-roles.adoc#access-control-list-roles[SHOW [ALL \| POPULATED\] ROLES [WITH USERS\]] -| User and role -| Returns information about all or populated roles, optionally including the assigned users. - -| xref::administration/databases.adoc#administration-databases-show-databases[SHOW DATABASE] -| Database -| Returns information about a specified database. - -| xref::administration/databases.adoc#administration-databases-show-databases[SHOW DATABASES] -| Database -| Returns information about all databases. - -| xref::administration/servers.adoc#server-management-show-servers[SHOW SERVERS] -| Server management -| Returns information about all servers. - -| xref::administration/databases.adoc#administration-databases-show-databases[SHOW DEFAULT DATABASE] -| Database -| Returns information about the default database. - -| xref::administration/databases.adoc#administration-databases-show-databases[SHOW HOME DATABASE] -| Database -| Returns information about the current users home database. - -| xref::administration/access-control/manage-privileges.adoc#access-control-list-supported-privileges[SHOW SUPPORTED PRIVILEGES] -| Privilege -| Returns information about supported privileges. - -| xref::administration/access-control/manage-roles.adoc#access-control-list-roles[SHOW [ROLE ... \| USER ... \| ALL \] PRIVILEGES [AS [REVOKE\] COMMAND[S\]\]] -| Privilege -| Returns information about role, user or all privileges. - -| xref::administration/access-control/manage-users.adoc#access-control-list-users[SHOW USERS] -| User and role -| Returns information about all users. - -| xref::administration/databases.adoc#administration-databases-start-database[START DATABASE] -| Database -| Starts up a specified database. - -| xref::administration/databases.adoc#administration-databases-stop-database[STOP DATABASE] -| Database -| Stops a specified database. - -|=== - - -[[glossary-privileges]] -== Privilege Actions - -[options="header"] -|=== -| Name | Category | Description - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-access[ACCESS] -| Database -| Determines whether a user can access a specific database. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-all[ALL DATABASE PRIVILEGES] -| Database and schema -| Determines whether a user is allowed to access, create, drop, and list indexes and constraints, create new labels, types and property names on a specific database. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-all[ALL DBMS PRIVILEGES] -| DBMS -| Determines whether a user is allowed to perform role, user, database and privilege management. - -| xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-all[ALL GRAPH PRIVILEGES] -| GRAPH -| Determines whether a user is allowed to perform reads and writes. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[ALTER ALIAS] -| DBMS -| Determines whether the user can modify aliases. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[ALTER DATABASE] -| DBMS -| Determines whether the user can modify databases and aliases. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[ALTER USER] -| DBMS -| Determines whether the user can modify users. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[ASSIGN PRIVILEGE] -| DBMS -| Determines whether the user can assign privileges using the `GRANT` and `DENY` commands. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[ASSIGN ROLE] -| DBMS -| Determines whether the user can grant roles. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[COMPOSITE DATABASE MANAGEMENT] -| DBMS -| Determines whether the user can create and delete composite databases. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-constraints[CONSTRAINT MANAGEMENT] -| Schema -| Determines whether a user is allowed to create, drop, and list constraints on a specific database. - -| xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-create[CREATE] -| GRAPH -| Determines whether the user can create a new element (node, relationship or both). - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[CREATE ALIAS] -| DBMS -| Determines whether the user can create new aliases. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[CREATE COMPOSITE DATABASE] -| DBMS -| Determines whether the user can create new composite databases. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-constraints[CREATE CONSTRAINT] -| Schema -| Determines whether a user is allowed to create constraints on a specific database. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[CREATE DATABASE] -| DBMS -| Determines whether the user can create new databases and aliases. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[CREATE INDEX] -| Schema -| Determines whether a user is allowed to create indexes on a specific database. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW NODE LABEL] -| Schema -| Determines whether a user is allowed to create new node labels on a specific database. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW PROPERTY NAME] -| Schema -| Determines whether a user is allowed to create new property names on a specific database. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[CREATE NEW RELATIONSHIP TYPE] -| Schema -| Determines whether a user is allowed to create new relationship types on a specific database. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[CREATE ROLE] -| DBMS -| Determines whether the user can create new roles. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[CREATE USER] -| DBMS -| Determines whether the user can create new users. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[ALIAS MANAGEMENT] -| DBMS -| Determines whether the user can create, delete, modify and list aliases. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[DATABASE MANAGEMENT] -| DBMS -| Determines whether the user can create, delete, and modify databases and aliases. - -| xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-delete[DELETE] -| GRAPH -| Determines whether the user can delete an element (node, relationship or both). - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[DROP ALIAS] -| DBMS -| Determines whether the user can delete aliases. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[DROP COMPOSITE DATABASE] -| DBMS -| Determines whether the user can delete composite databases. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-constraints[DROP CONSTRAINT] -| Schema -| Determines whether a user is allowed to drop constraints on a specific database. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[DROP DATABASE] -| DBMS -| Determines whether the user can delete databases and aliases. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[DROP INDEX] -| Schema -| Determines whether a user is allowed to drop indexes on a specific database. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DROP ROLE] -| DBMS -| Determines whether the user can delete roles. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DROP USER] -| DBMS -| Determines whether the user can delete users. - -| xref::administration/access-control/dbms-administration.adoc#access-control-admin-procedure[EXECUTE ADMIN PROCEDURE] -| DBMS -| Determines whether the user can execute admin procedures. - -| xref::administration/access-control/dbms-administration.adoc#access-control-execute-boosted-user-defined-function[EXECUTE BOOSTED FUNCTION] -| DBMS -| Determines whether the user gets elevated privileges when executing functions. - -| xref::administration/access-control/dbms-administration.adoc#access-control-execute-boosted-procedure[EXECUTE BOOSTED PROCEDURE] -| DBMS -| Determines whether the user gets elevated privileges when executing procedures. - -| xref::administration/access-control/dbms-administration.adoc#access-control-execute-user-defined-function[EXECUTE FUNCTION] -| DBMS -| Determines whether the user can execute functions. - -| xref::administration/access-control/dbms-administration.adoc#access-control-execute-procedure[EXECUTE PROCEDURE] -| DBMS -| Determines whether the user can execute procedures. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-impersonation[IMPERSONATE] -| DBMS -| Determines whether a user can impersonate another one and assume their privileges. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[INDEX MANAGEMENT] -| Schema -| Determines whether a user is allowed to create, drop, and list indexes on a specific database. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[MATCH] -| GRAPH -| Determines whether the properties of an element (node, relationship or both) can be read and the element can be found and traversed while executing queries on the specified graph. - -| xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-merge[MERGE] -| GRAPH -| Determines whether the user can find, read, create and set properties on an element (node, relationship or both). - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-tokens[NAME MANAGEMENT] -| Schema -| Determines whether a user is allowed to create new labels, types and property names on a specific database. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[PRIVILEGE MANAGEMENT] -| DBMS -| Determines whether the user can show, assign and remove privileges. - -| xref::administration/access-control/privileges-reads.adoc#access-control-privileges-reads-read[READ] -| GRAPH -| Determines whether the properties of an element (node, relationship or both) can be read while executing queries on the specified graph. - -| xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-remove-label[REMOVE LABEL] -| GRAPH -| Determines whether the user can remove a label from a node using the `REMOVE` clause. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[REMOVE PRIVILEGE] -| DBMS -| Determines whether the user can remove privileges using the `REVOKE` command. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[REMOVE ROLE] -| DBMS -| Determines whether the user can revoke roles. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[RENAME ROLE] -| DBMS -| Determines whether the user can rename roles. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[RENAME USER] -| DBMS -| Determines whether the user can rename users. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[ROLE MANAGEMENT] -| DBMS -| Determines whether the user can create, drop, grant, revoke and show roles. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-server-management[SERVER MANAGEMENT] -| DBMS -| Determines whether the user can enable, alter, rename, reallocate, deallocate, drop, and show servers. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-database-management[SET DATABASE ACCESS] -| DBMS -| Determines whether the user can modify the database access mode. - -| xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-set-label[SET LABEL] -| GRAPH -| Determines whether the user can set a label to a node using the SET clause. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[SET PASSWORDS] -| DBMS -| Determines whether the user can modify users' passwords and whether those passwords must be changed upon first login. - -| xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-set-property[SET PROPERTY] -| GRAPH -| Determines whether the user can set a property to an element (node, relationship or both) using the SET clause. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[SET USER HOME DATABASE] -| DBMS -| Determines whether the user can modify the home database of users. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[SET USER STATUS] -| DBMS -| Determines whether the user can modify the account status of users. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-alias-management[SHOW ALIAS] -| DBMS -| Determines whether the user is allowed to list aliases. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-constraints[SHOW CONSTRAINT] -| Schema -| Determines whether the user is allowed to list constraints. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-index[SHOW INDEX] -| Schema -| Determines whether the user is allowed to list indexes. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SHOW PRIVILEGE] -| DBMS -| Determines whether the user can get information about privileges assigned to users and roles. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[SHOW ROLE] -| DBMS -| Determines whether the user can get information about existing and assigned roles. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-server-management[SHOW SERVERS] -| DBMS -| Determines whether the user can get information about servers. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-setting[SHOW SETTINGS] -| DBMS -| Determines whether the user can get information about configuration settings. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-transaction[SHOW TRANSACTION] -| Database -| Determines whether a user is allowed to list transactions and queries. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[SHOW USER] -| DBMS -| Determines whether the user can get information about existing users. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-startstop[START] -| Database -| Determines whether a user can start up a specific database. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-startstop[STOP] -| Database -| Determines whether a user can stop a specific running database. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-transaction[TERMINATE TRANSACTION] -| Database -| Determines whether a user is allowed to end running transactions and queries. - -| xref::administration/access-control/database-administration.adoc#access-control-database-administration-transaction[TRANSACTION MANAGEMENT] -| Database -| Determines whether a user is allowed to list and end running transactions and queries. - -| xref::administration/access-control/privileges-reads.adoc#access-control-privileges-reads-traverse[TRAVERSE] -| GRAPH -| Determines whether an element (node, relationship or both) can be found and traversed while executing queries on the specified graph. - -| xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[USER MANAGEMENT] -| DBMS -| Determines whether the user can create, drop, modify and show users. - -| xref::administration/access-control/privileges-writes.adoc#access-control-privileges-writes-write[WRITE] -| GRAPH -| Determines whether the user can execute write operations on the specified graph. - -|=== - diff --git a/modules/ROOT/pages/patterns/concepts.adoc b/modules/ROOT/pages/patterns/concepts.adoc index e9d69a590..24ea0a0e2 100644 --- a/modules/ROOT/pages/patterns/concepts.adoc +++ b/modules/ROOT/pages/patterns/concepts.adoc @@ -836,7 +836,7 @@ RETURN [n in nodes(p) | n.name] AS stops |=== On a large, highly connected graph, this can be very time consuming. -See the section on xref::execution-plans/shortestpath-planning.adoc[shortest path planning] for more information. +See the section on xref::appendix/tutorials/shortestpath-planning.adoc[shortest path planning] for more information. [[shortest-path-all-shortest-paths]] === All shortest paths diff --git a/modules/ROOT/pages/planning-and-tuning/execution-plans.adoc b/modules/ROOT/pages/planning-and-tuning/execution-plans.adoc new file mode 100644 index 000000000..9b7b6e3e8 --- /dev/null +++ b/modules/ROOT/pages/planning-and-tuning/execution-plans.adoc @@ -0,0 +1,159 @@ +:description: This page describes how to understand a Cypher execution plan. += Understanding execution plans + +This page describes how to understand the execution plans produced by the Cypher planner. +It begins by explaining the lifecycle of a Cypher query, before giving a step-by-step breakdown of a particular query and the execution plan it uses. +It then explains the difference between lazy and eager query evaluation. + +== The lifecycle of a Cypher query + +A Cypher query begins as a declarative query represented as a string, describing the graph pattern to match in a database. +After parsing, the query string goes through the query optimizer (also known as the planner), which produces an imperative plan, known as the logical plan, to determine the most efficient way of executing the query given the current state of the database.footnote:[The relevant information about the current state of the database includes which indexes and constraints are available, as well as various statistics maintained by the database. +The Cypher planner uses this information to determine which access patterns will produce the best execution plan.] +In the final phase, this logical plan is turned into an executable physical plan, which actually runs the query against the database. +Executing this physical plan is the task of the xref:planning-and-tuning/runtimes/index.adoc[Cypher runtime]. + +image::runtimes_cypher_lifecycle.svg[width="400", role="middle"] + +[[runtimes-example-graph]] +== Example graph + +To explain how to understand a Cypher execution plan, a graph based on the UK national rail network is used. +The data in the graph is taken from link:https://www.raildeliverygroup.com/our-services/rail-data/fares-timetable-data.html[publically available datasets]. + +image::patterns_qpp_calling_points.svg[width="700",role="middle"] + +The graph contains two types of nodes: `Stop` and `Station`. +Each `Stop` on a train service `CALLS_AT` one `Station`, and has the properties `arrives` and `departs` that give the times the train is at the `Station`. +Following the `NEXT` relationship of a `Stop` will give the next `Stop` of a service. + +To recreate the graph, run the following query against an empty Neo4j database: + +.Query +[source, cypher, role=test-setup] +---- +CREATE (pmr:Station {name: 'Peckham Rye'}), + (dmk:Station {name: 'Denmark Hill'}), + (clp:Station {name: 'Clapham High Street'}), + (wwr:Station {name: 'Wandsworth Road'}), + (clj:Station {name: 'Clapham Junction'}), + (s1:Stop {arrives: time('17:19'), departs: time('17:20')}), + (s2:Stop {arrives: time('17:12'), departs: time('17:13')}), + (s3:Stop {arrives: time('17:10'), departs: time('17:11')}), + (s4:Stop {arrives: time('17:06'), departs: time('17:07')}), + (s5:Stop {arrives: time('16:58'), departs: time('17:01')}), + (s6:Stop {arrives: time('17:17'), departs: time('17:20')}), + (s7:Stop {arrives: time('17:08'), departs: time('17:10')}), + (clj)<-[:CALLS_AT]-(s1), (wwr)<-[:CALLS_AT]-(s2), + (clp)<-[:CALLS_AT]-(s3), (dmk)<-[:CALLS_AT]-(s4), + (pmr)<-[:CALLS_AT]-(s5), (clj)<-[:CALLS_AT]-(s6), + (dmk)<-[:CALLS_AT]-(s7), + (s5)-[:NEXT {distance: 1.2}]->(s4),(s4)-[:NEXT {distance: 0.34}]->(s3), + (s3)-[:NEXT {distance: 0.76}]->(s2), (s2)-[:NEXT {distance: 0.3}]->(s1), + (s7)-[:NEXT {distance: 1.4}]->(s6) +---- + +The example query uses a xref:patterns/concepts.adoc#quantified-path-pattern[quantified path pattern] to count the number of possible path patterns between the start `Station`, `Denmark Hill`, and the end `Station`, `Clapham Junction`: + +.Query +[source, cypher] +---- +MATCH (:Station { name: 'Denmark Hill' })<-[:CALLS_AT]-(d:Stop) + ((:Stop)-[:NEXT]->(:Stop))+ + (a:Stop)-[:CALLS_AT]->(:Station { name: 'Clapham Junction' }) +RETURN count(*) +---- + +As can be seen from the graph, two such patterns exist (one with a service departing `Denmark Hill` at `17:07` which stops at the Stations `Clapham High Street` and `Wandsworth Road`, and one direct service departing `Denmark Hill` at `17:10`): + +image::patterns_qpp_solutions.svg[width="700",role="middle"] + +For the purposes of understanding Cypher execution plans, however, the query result is less interesting than the planning that produces it. + +[[runtimes-reading-execution-plans]] +== Reading execution plans + +The Cypher planner produces logical plans which describe how a particular query is going to be executed. +This execution plan is essentially a binary tree of operators. +An operator is, in turn, a specialized execution module that is responsible for some type of transformation to the data before passing it on to the next operator, until the desired graph pattern has been matched. +The execution plans produced by the planner thus decide which operators will be used and in what order they will be applied to achieve the aim declared in the original query. + +In order to view the plan of a query, prepend the query with `EXPLAIN` - this will not run the query, but only show the tree of operators used to find the desired result. + +.Query +[source, cypher, role=test-skip] +---- +EXPLAIN +MATCH (:Station { name: 'Denmark Hill' })<-[:CALLS_AT]-(d:Stop) + ((:Stop)-[:NEXT]->(:Stop))+ + (a:Stop)-[:CALLS_AT]->(:Station { name: 'Clapham Junction' }) +RETURN count(*) +---- + +This is the resulting execution plan (produced by the xref:planning-and-tuning/runtimes/concepts.adoc#runtimes-slotted-runtime[slotted runtime], the default for Neo4j Community Edition)footnote:[The format of the execution plans displayed in this section are those generated when using link:{neo4j-docs-base-uri}/operations-manual/{page-version}/tools/cypher-shell[Cypher Shell]. +The execution plans generated by link:{neo4j-docs-base-uri}/browser-manual/current[Neo4j Browser] use a different format.]: + +[role="queryplan"] +---- ++-------------------+----+------------------------------------------------------------------------+----------------+ +| Operator | Id | Details | Estimated Rows | ++-------------------+----+------------------------------------------------------------------------+----------------+ +| +ProduceResults | 0 | `count(*)` | 1 | +| | +----+------------------------------------------------------------------------+----------------+ +| +EagerAggregation | 1 | count(*) AS `count(*)` | 1 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Filter | 2 | not anon_1 = anon_5 AND anon_0.name = $autostring_0 AND anon_0:Station | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Expand(All) | 3 | (d)-[anon_1:CALLS_AT]->(anon_0) | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Filter | 4 | d:Stop | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Repeat(Trail) | 5 | (a) (...){1, *} (d) | 0 | +| |\ +----+------------------------------------------------------------------------+----------------+ +| | +Filter | 6 | isRepeatTrailUnique(anon_7) AND anon_2:Stop | 6 | +| | | +----+------------------------------------------------------------------------+----------------+ +| | +Expand(All) | 7 | (anon_4)<-[anon_7:NEXT]-(anon_2) | 6 | +| | | +----+------------------------------------------------------------------------+----------------+ +| | +Filter | 8 | anon_4:Stop | 11 | +| | | +----+------------------------------------------------------------------------+----------------+ +| | +Argument | 9 | anon_4 | 13 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Filter | 10 | a:Stop | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Expand(All) | 11 | (anon_6)<-[anon_5:CALLS_AT]-(a) | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Filter | 12 | anon_6.name = $autostring_1 | 1 | +| | +----+------------------------------------------------------------------------+----------------+ +| +NodeByLabelScan | 13 | anon_6:Station | 10 | ++-------------------+----+------------------------------------------------------------------------+----------------+ +---- + +The operators can be seen in the leftmost column of the results table. +The most important thing to remember when reading execution plans is that they are read from the bottom up. +To follow the execution of this query it is, therefore, necessary to start from the bottom or leaf operator, xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-by-label-scan[NodeByLabelScan] (which fetches all nodes with a specific label from the node label index) and move step-by-step up the operator tree to see how the data in the graph is gradually refined until the final, root operator, xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-produce-results[ProduceResults], generates readable results for the user. + +To read more about the specific role played by operators used in this example, and many others, see the section on xref::planning-and-tuning/operators/index.adoc[]. + +The `id` column specifies a unique ID assigned to each operator. +There are no guarantees about the order of the ids, although they will usually start with 0 at the root operator, and will increase until the leaf operator is reached at the beginning of the operator tree. + +The `Details` column in the middle of the execution plan describes what task is performed by each operator. +For example, the details column of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-repeat[Repeat(Trail)] operator in the middle of the execution plan (`id 5`), specifies that the operator traverses a quantified path pattern without an upward limit. + +Finally, the `Estimated Rows` column in the rightmost column of the execution plan details the number of rows that are expected to be produced by each operator. +This estimate is an approximate number based on the available statistical information and the planner uses it to choose a suitable execution plan.footnote:[The statistical information maintained by Neo4j includes the following: the number of nodes having a certain label, the number of relationships by type, selectivity per index, and the number of relationships by type, ending with or starting from a node with a specific label.] + +The execution plans produced by the xref:planning-and-tuning/runtimes/concepts.adoc#runtimes-pipelined-runtime[pipelined runtime] and xref:planning-and-tuning/runtimes/concepts.adoc#runtimes-parallel-runtimes[parallel runtime] runtimes contain more information about how a query is executed. +For details about how the different runtimes changes a particular execution plan, see xref:planning-and-tuning/runtimes/concepts.adoc[]. + +[[lazy-eager-evaluation]] +== Lazy and eager query evaluation + +In general, query evaluation is _lazy_. +This means that most operators pipe their output rows to their parent operators as soon as they are produced. +In other words, a child operator may not be fully exhausted before the parent operator starts consuming the input rows produced by the child. + +However, some operators, such as those used for aggregation and sorting, need to aggregate all their rows before they can produce output. +These operators are called eager operators (see the xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-eager-aggregation[EagerAggregation] operator in the above table (`id 1`) for an example). +Such operators need to complete execution in its entirety before any rows are sent to their parents as input, and are sometimes required to enforce correct Cypher semantics. +For more information about the row-by-row processing of Cypher queries, see the section on xref:clauses/clause_composition.adoc[]. diff --git a/modules/ROOT/pages/planning-and-tuning/index.adoc b/modules/ROOT/pages/planning-and-tuning/index.adoc new file mode 100644 index 000000000..c52566ed2 --- /dev/null +++ b/modules/ROOT/pages/planning-and-tuning/index.adoc @@ -0,0 +1,26 @@ += Execution plans and query tuning + +Cypher queries are executed according to a particular execution plan. +The execution plan consists of a binary tree of operators, with information about the step-by-step execution of a query, and it may differ depending on which runtime the query uses. +Apart from selecting a different runtime, there are numerous other ways in which a query can be tuned. + +More information about each of these topics can be found in the following sections: + +* xref:planning-and-tuning/execution-plans.adoc[] +* xref:planning-and-tuning/operators/index.adoc[] +* xref:planning-and-tuning/runtimes/index.adoc[] +* xref:planning-and-tuning/query-tuning/index.adoc[] + +== Note on `PROFILE` and `EXPLAIN` + +The queries in this section are often prepended with either `PROFILE` or `EXPLAIN`. +Both produce an execution plan, but there are important differences: + +`EXPLAIN`:: +If you want to see the execution plan but not run the query, prepend your Cypher statement with `EXPLAIN`. +The statement will always return an empty result and make no changes to the database. + +`PROFILE`:: +If you want to run the query and see which operators are doing most of the work, use `PROFILE`. +This will run your query and keep track of how many rows pass through each operator, and how much each operator needs to interact with the storage layer to retrieve the necessary data. +Note that _profiling your query uses more resources,_ so you should not profile unless you are actively working on a query. diff --git a/modules/ROOT/pages/planning-and-tuning/operators/index.adoc b/modules/ROOT/pages/planning-and-tuning/operators/index.adoc new file mode 100644 index 000000000..484ad1c63 --- /dev/null +++ b/modules/ROOT/pages/planning-and-tuning/operators/index.adoc @@ -0,0 +1,792 @@ +:description: Overview page for the Cypher operators. += Operators + +This page provides an overview of the available operators in Cypher. +An operator is a specialized execution module that is responsible for some type of transformation to the data in a query execution plan before passing it on to the next operator, until the desired graph pattern has been matched. + +For information about how to understand execution plans (and the role operators play in them), see xref:planning-and-tuning/execution-plans.adoc[]. + +For more information about each operator, see xref:planning-and-tuning/operators/operators-detail.adoc[]. + +== Summary of operators + +This table comprises all the execution plan operators ordered lexicographically. + +* _Leaf_ operators, in most cases, locate the starting nodes and relationships required in order to execute the query. + +* _Updating_ operators are used in queries that update the graph. + +* _Eager_ operators xref::planning-and-tuning/execution-plans.adoc#lazy-eager-evaluation[accumulate all their rows] before piping them to the next operator. + +[cols="35a,35a,6,10,14", options="header"] +|=== +| Name | Description | Leaf? | Updating? | Considerations + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[AllNodesScan] +| Reads all nodes from the node store. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-anti[Anti] +| Tests for the absence of a pattern. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-anti-semi-apply[AntiSemiApply] +a| +Performs a nested loop. +Tests for the absence of a pattern predicate. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] +| Performs a nested loop. Yields rows from both the left-hand and right-hand side operators. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-argument[Argument] +| Indicates the variable to be used as an argument to the right-hand side of an `Apply` operator. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-assert-same-node[AssertSameNode] +| Ensures that no node property uniqueness constraints are violated. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-assert-same-relationship[AssertSameRelationship] +| Ensures that no relationship property uniqueness constraints are violated. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-asserting-multi-node-index-seek[AssertingMultiNodeIndexSeek] +| Used to ensure that no property uniqueness constraints are violated. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-cache-properties[CacheProperties] +| Reads node or relationship properties and caches them. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-cartesian-product[CartesianProduct] +| Produces a cartesian product of the inputs from the left-hand and right-hand operators. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-create[Create] +| Creates nodes and relationships. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-create-index[CreateIndex] +| Creates an index for either nodes or relationships. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-create-constraint[CreateConstraint] +| Creates a constraint for either nodes or relationships. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-delete[Delete] +| Deletes a node or relationship. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-detach-delete[DetachDelete] +| Deletes a node and its relationships. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-directed-all-relationships-scan[DirectedAllRelationshipsScan] +| Fetches all relationships and their start and end nodes in the database. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-directed-relationship-by-id-seek[DirectedRelationshipByIdSeek] +| Reads one or more relationships by id from the relationship store. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-directed-relationship-index-contains-scan[DirectedRelationshipIndexContainsScan] +| Examines all values stored in an index, searching for entries containing a specific string; for example, in queries including `CONTAINS`. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-directed-relationship-index-ends-with-scan[DirectedRelationshipIndexEndsWithScan] +| Examines all values stored in an index, searching for entries ending in a specific string; for example, in queries containing `ENDS WITH`. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-directed-relationship-index-scan[DirectedRelationshipIndexScan] +| Examines all values stored in an index, returning all relationships and their start and end nodes with a particular relationship type and a specified property. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-directed-relationship-index-seek[DirectedRelationshipIndexSeek] +| Finds relationships and their start and end nodes using an index seek. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-directed-relationship-index-seek-by-range[DirectedRelationshipIndexSeekByRange] +| Finds relationships and their start and end nodes using an index seek where the value of the property matches a given prefix string. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-directed-relationship-type-scan[DirectedRelationshipTypeScan] +| Fetches all relationships and their start and end nodes with a specific type from the relationship type index. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-directed-union-relationship-types-scan[DirectedUnionRelationshipTypesScan] +| Fetches all relationships and their start and end nodes with at least one of the provided types from the relationship type index. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-distinct[Distinct] +| Drops duplicate rows from the incoming stream of rows. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-do-nothing-if-exists-constraint[DoNothingIfExists(CONSTRAINT)] +| Checks if a constraint already exists, if it does then it stops the execution, if not it continues. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-do-nothing-if-exists-index[DoNothingIfExists(INDEX)] +| Checks if an index already exists, if it does then it stops the execution, if not it continues. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-drop-constraint[DropConstraint] +| Drops a constraint using its name. +| label:yes[] +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-drop-index[DropIndex] +| Drops an index using its name. +| label:yes[] +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-eager[Eager] +| For isolation purposes, `Eager` ensures that operations affecting subsequent operations are executed fully for the whole dataset before continuing execution. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-eager-aggregation[EagerAggregation] +| Evaluates a grouping expression. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-empty-result[EmptyResult] +| Eagerly loads all incoming data and discards it. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-empty-row[EmptyRow] +| Returns a single row with no columns. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-exhaustive-limit[ExhaustiveLimit] +a| +The `ExhaustiveLimit` operator is similar to the `Limit` operator, but always exhausts the input. +Used when combining `LIMIT` and updates. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-expand-all[Expand(All)] +| Traverses incoming or outgoing relationships from a given node. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-expand-into[Expand(Into)] +| Finds all relationships between two nodes. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-filter[Filter] +| Filters each row coming from the child operator, only passing through rows that evaluate the predicates to `true`. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-foreach[Foreach] +a| +Performs a nested loop. +Yields rows from the left-hand operator and discards rows from the right-hand operator. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-intersection-node-by-labels-scan[IntersectionNodeByLabelsScan] +| Fetches all nodes that have all of the provided labels from the node label index. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-let-anti-semi-apply[LetAntiSemiApply] +a| +Performs a nested loop. +Tests for the absence of a pattern predicate in queries containing multiple pattern predicates. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-let-select-or-anti-semi-apply[LetSelectOrAntiSemiApply] +a| +Performs a nested loop. +Tests for the absence of a pattern predicate that is combined with other predicates. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-let-select-or-semi-apply[LetSelectOrSemiApply] +a| +Performs a nested loop. +Tests for the presence of a pattern predicate that is combined with other predicates. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-let-semi-apply[LetSemiApply] +a| +Performs a nested loop. +Tests for the presence of a pattern predicate in queries containing multiple pattern predicates. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-limit[Limit] +| Returns the first `+n+` rows from the incoming input. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-load-csv[LoadCSV] +| Loads data from a CSV source into the query. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-locking-merge[LockingMerge] +| Similar to the `Merge` operator but will lock the start and end node when creating a relationship if necessary. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-merge[Merge] +| The `Merge` operator will either read or create nodes and/or relationships. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-multi-node-index-seek[MultiNodeIndexSeek] +| Finds nodes using multiple index seeks. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-by-elementid-seek[NodeByElementIdSeek] +| Reads one or more nodes by ID from the node store, specified via the function xref::functions/scalar.adoc#functions-elementid[elementId()]. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-by-id-seek[NodeByIdSeek] +| Reads one or more nodes by ID from the node store, specified via the function xref::functions/scalar.adoc#functions-id[id()]. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-by-label-scan[NodeByLabelScan] +| Fetches all nodes with a specific label from the node label index. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-count-from-count-store[NodeCountFromCountStore] +| Uses the count store to answer questions about node counts. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-hash-join[NodeHashJoin] +| Executes a hash join on node ID. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-index-contains-scan[NodeIndexContainsScan] +| Examines all values stored in an index, searching for entries containing a specific string. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-index-ends-with-scan[NodeIndexEndsWithScan] +| Examines all values stored in an index, searching for entries ending in a specific string. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-index-scan[NodeIndexScan] +| Examines all values stored in an index, returning all nodes with a particular label with a specified property. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-index-seek[NodeIndexSeek] +| Finds nodes using an index seek. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-index-seek-by-range[NodeIndexSeekByRange] +| Finds nodes using an index seek where the value of the property matches the given prefix string. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-left-right-outer-hash-join[NodeLeftOuterHashJoin] +| Executes a left outer hash join. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-left-right-outer-hash-join[NodeRightOuterHashJoin] +| Executes a right outer hash join. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-unique-index-seek[NodeUniqueIndexSeek] +| Finds nodes using an index seek within a unique index. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-unique-index-seek-by-range[NodeUniqueIndexSeekByRange] +| Finds nodes using an index seek within a unique index where the value of the property matches the given prefix string. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-optional[Optional] +| Yields a single row with all columns set to `null` if no data is returned by its source. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-optional-expand-all[OptionalExpand(All)] +| Traverses relationships from a given node, producing a single row with the relationship and end node set to `null` if the predicates are not fulfilled. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-optional-expand-into[OptionalExpand(Into)] +| Traverses all relationships between two nodes, producing a single row with the relationship and end node set to `null` if no matching relationships are found (the start node is the node with the smallest degree). +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-ordered-aggregation[OrderedAggregation] +a| +Like `EagerAggregation` but relies on the ordering of incoming rows. +Is not eager. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-ordered-distinct[OrderedDistinct] +| Like `Distinct` but relies on the ordering of incoming rows. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-partial-sort[PartialSort] +| Sorts a row by multiple columns if there is already an ordering. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-partial-top[PartialTop] +| Returns the first `+n+` rows sorted by multiple columns if there is already an ordering. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-procedure-call[ProcedureCall] +| Calls a procedure. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-produce-results[ProduceResults] +| Prepares the result so that it is consumable by the user. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-project-endpoints[ProjectEndpoints] +| Projects the start and end node of a relationship. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-projection[Projection] +| Evaluates a set of expressions, producing a row with the results thereof. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-relationship-count-from-count-store[RelationshipCountFromCountStore] +| Uses the count store to answer questions about relationship counts. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-repeat[Repeat(Trail)] +| Solves quantified path patterns. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-remove-labels[RemoveLabels] +| Deletes labels from a node. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-roll-up-apply[RollUpApply] +a| +Performs a nested loop. +Executes a pattern expression or pattern comprehension. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-select-or-anti-semi-apply[SelectOrAntiSemiApply] +a| +Performs a nested loop. +Tests for the absence of a pattern predicate if an expression predicate evaluates to `false`. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-select-or-semi-apply[SelectOrSemiApply] +| Performs a nested loop. Tests for the presence of a pattern predicate if an expression predicate evaluates to `false`. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-semi-apply[SemiApply] +| Performs a nested loop. Tests for the presence of a pattern predicate. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-set-labels[SetLabels] +| Sets labels on a node. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-set-node-properties-from-map[SetNodePropertiesFromMap] +| Sets properties from a map on a node. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-set-property[SetProperty] +| Sets a property on a node or relationship. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-set-relationship-properties-from-map[SetRelationshipPropertiesFromMap] +| Sets properties from a map on a relationship. +| +| label:yes[] +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-shortest-path[ShortestPath] +| Finds one or all shortest paths between two previously matches node variables. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-show-constraints[ShowConstraints] +| Lists the available constraints. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-show-functions[ShowFunctions] +| Lists the available functions. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-show-indexes[ShowIndexes] +| Lists the available indexes. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-show-procedures[ShowProcedures] +| Lists the available procedures. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-show-settings[ShowSettings] +| Lists the available configuration settings. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-show-transactions[ShowTransactions] +| Lists the available transactions on the current server. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-skip[Skip] +| Skips `+n+` rows from the incoming rows. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-sort[Sort] +| Sorts rows by a provided key. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-terminate-transactions[TerminateTransactions] +| Terminate transactions with the given IDs. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-top[Top] +| Returns the first 'n' rows sorted by a provided key. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-triadic-build[TriadicBuild] +| The `TriadicBuild` operator is used in conjunction with `TriadicFilter` to solve triangular queries. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-triadic-filter[TriadicFilter] +| The `TriadicFilter` operator is used in conjunction with `TriadicBuild` to solve triangular queries. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-triadic-selection[TriadicSelection] +| Solves triangular queries, such as the very common 'find my friend-of-friends that are not already my friend'. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-undirected-all-relationships-scan[UndirectedAllRelationshipsScan] +| Fetches all relationships and their start and end nodes in the database. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-undirected-relationship-by-id-seek[UndirectedRelationshipByIdSeek] +| Reads one or more relationships by ID from the relationship store. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-undirected-relationship-index-contains-scan[UndirectedRelationshipIndexContainsScan] +| Examines all values stored in an index, searching for entries containing a specific string; for example, in queries including `CONTAINS`. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-undirected-relationship-index-ends-with-scan[UndirectedRelationshipIndexEndsWithScan] +| Examines all values stored in an index, searching for entries ending in a specific string; for example, in queries containing `ENDS WITH`. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-undirected-relationship-index-scan[UndirectedRelationshipIndexScan] +| Examines all values stored in an index, returning all relationships and their start and end nodes with a particular relationship type and a specified property. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-undirected-relationship-index-seek[UndirectedRelationshipIndexSeek] +| Finds relationships and their start and end nodes using an index seek. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-undirected-relationship-index-seek-by-range[UndirectedRelationshipIndexSeekByRange] +| Finds relationships and their start and end nodes using an index seek where the value of the property matches a given prefix string. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-undirected-relationship-type-scan[UndirectedRelationshipTypeScan] +| Fetches all relationships and their start and end nodes with a specific type from the relationship type index. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-undirected-union-relationship-types-scan[UndirectedUnionRelationshipTypesScan] +| Fetches all relationships and their start and end nodes with at least one of the provided types from the relationship type index. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-union[Union] +| Concatenates the results from the right-hand operator with the results from the left-hand operator. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-union-node-by-labels-scan[UnionNodeByLabelsScan] +| Fetches all nodes that have at least one of the provided labels from the node label index. +| label:yes[] +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-unwind[Unwind] +| Returns one row per item in a list. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-value-hash-join[ValueHashJoin] +| Executes a hash join on arbitrary values. +| +| +| label:eager[] + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-varlength-expand-all[VarLengthExpand(All)] +| Traverses variable-length relationships from a given node. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-varlength-expand-into[VarLengthExpand(Into)] +| Finds all variable-length relationships between two nodes. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-varlength-expand-pruning[VarLengthExpand(Pruning)] +| Traverses variable-length relationships from a given node and only returns unique end nodes. +| +| +| + +| xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-varlength-expand-pruning-bfs[VarLengthExpand(Pruning,BFS)] +| Traverses variable-length relationships from a given node and only returns unique end nodes. +| +| +| + +|=== + + +[[operators-dbhits]] +== Database hits + +Each operator will send a request to the storage engine to do work such as retrieving or updating data. +A _database hit_ (DBHits) is an abstract unit of this storage engine work. + +These are all the actions that trigger one or more database hits: + +* **Create actions** +** Create a node. +** Create a relationship. +** Create a new node label. +** Create a new relationship type. +** Create a new ID for property keys with the same name. + +* **Delete actions** +** Delete a node. +** Delete a relationship. + +* **Update actions** +** Set one or more labels on a node. +** Remove one or more labels from a node. + +* **Node-specific actions** +** Get a node by its ID. +** Get the degree of a node. +** Determine whether a node is dense. +** Determine whether a label is set on a node. +** Get the labels of a node. +** Get a property of a node. +** Get an existing node label. +** Get the name of a label by its ID, or its ID by its name. + +* **Relationship-specific actions** +** Get a relationship by its ID. +** Get a property of a relationship. +** Get an existing relationship type. +** Get a relationship type name by its ID, or its ID by its name. + +* **General actions** +** Get the name of a property key by its ID, or its ID by the key name. +** Find a node or relationship through an index seek or index scan. +** Find a path in a variable-length expand. +** Find a shortest path. +** Ask the count store for a value. + +* **Schema actions** +** Add an index. +** Drop an index. +** Get the reference of an index. +** Create a constraint. +** Drop a constraint. + +* Call a procedure. +* Call a user-defined function. diff --git a/modules/ROOT/pages/execution-plans/operators.adoc b/modules/ROOT/pages/planning-and-tuning/operators/operators-detail.adoc similarity index 98% rename from modules/ROOT/pages/execution-plans/operators.adoc rename to modules/ROOT/pages/planning-and-tuning/operators/operators-detail.adoc index b3ce228fa..563cfac13 100644 --- a/modules/ROOT/pages/execution-plans/operators.adoc +++ b/modules/ROOT/pages/planning-and-tuning/operators/operators-detail.adoc @@ -1,11 +1,10 @@ -:description: Execution plan operators. +:description: This page contains information about each Cypher operator. += Operators in detail -[[execution-plans-operators]] -= Execution plan operators in detail +This page contains details and an example query for all operators available in Cypher. +The operators are grouped by the similarity of their characteristics. -This page lists all execution plan operators, grouped by the similarity of their characteristics. - -Certain operators are only used by a subset of the xref::query-tuning/index.adoc#cypher-runtime[runtimes] that Cypher can choose from. +Certain operators are only used by a subset of the xref::planning-and-tuning/runtimes/concepts.adoc[runtimes] that Cypher can choose from. If that is the case, the example queries will be prefixed with an option to choose one of these runtimes. //// @@ -1162,7 +1161,7 @@ CREATE RANGE INDEX range_location_name FOR (l:Location) ON (l.name) The `NodeIndexSeek` operator finds nodes using an index seek. The node variable and the index used are shown in the arguments of the operator. -If the index is a unique index, the operator is instead called xref::execution-plans/operators.adoc#query-plan-node-unique-index-seek[NodeUniqueIndexSeek]. +If the index is a unique index, the operator is instead called xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-unique-index-seek[NodeUniqueIndexSeek]. .NodeIndexSeek @@ -1214,7 +1213,7 @@ CREATE CONSTRAINT team_name IF NOT EXISTS FOR (t:Team) REQUIRE (t.name) IS UNIQU The `NodeUniqueIndexSeek` operator finds nodes using an index seek within a unique index. The node variable and the index used are shown in the arguments of the operator. -If the index is not unique, the operator is instead called xref::execution-plans/operators.adoc#query-plan-node-index-seek[NodeIndexSeek]. +If the index is not unique, the operator is instead called xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-index-seek[NodeIndexSeek]. If the index seek is used to solve a xref::clauses/merge.adoc[MERGE] clause, it will also be marked with `(Locking)`. This makes it clear that any nodes returned from the index will be locked in order to prevent concurrent conflicting updates. @@ -1610,7 +1609,7 @@ Total database accesses: 11, total allocated memory: 184 == Apply // Apply -All the different `Apply` operators (listed below) share the same basic functionality: they perform a nested loop by taking a single row from the left-hand side, and using the xref::execution-plans/operators.adoc#query-plan-argument[Argument] operator on the right-hand side, execute the operator tree on the right-hand side. +All the different `Apply` operators (listed below) share the same basic functionality: they perform a nested loop by taking a single row from the left-hand side, and using the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-argument[Argument] operator on the right-hand side, execute the operator tree on the right-hand side. The versions of the `Apply` operators differ in how the results are managed. The `Apply` operator (i.e. the standard version) takes the row produced by the right-hand side -- which at this point contains data from both the left-hand and right-hand sides -- and yields it. @@ -1660,7 +1659,7 @@ Total database accesses: 2, total allocated memory: 2216 == Semi Apply // SemiApply -The `SemiApply` operator tests for the presence of a pattern predicate, and is a variation of the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +The `SemiApply` operator tests for the presence of a pattern predicate, and is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. If the right-hand side operator yields at least one row, the row from the left-hand side operator is yielded by the `SemiApply` operator. This makes `SemiApply` a filtering operator, used mostly for pattern predicates in queries. @@ -1715,7 +1714,7 @@ Total database accesses: 142, total allocated memory: 64 == Anti Semi Apply // AntiSemiApply -The `AntiSemiApply` operator tests for the absence of a pattern, and is a variation of the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +The `AntiSemiApply` operator tests for the absence of a pattern, and is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. If the right-hand side operator yields no rows, the row from the left-hand side operator is yielded by the `AntiSemiApply` operator. This makes `AntiSemiApply` a filtering operator, used for pattern predicates in queries. @@ -1838,7 +1837,7 @@ Total database accesses: 178, total allocated memory: 6744 == Let Semi Apply // LetSemiApply -The `LetSemiApply` operator tests for the presence of a pattern predicate, and is a variation of the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +The `LetSemiApply` operator tests for the presence of a pattern predicate, and is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. When a query contains multiple pattern predicates separated with `OR`, `LetSemiApply` will be used to evaluate the first of these. It will record the result of evaluating the predicate but will leave any filtering to another operator. In the example, `LetSemiApply` will be used to check for the presence of the `FRIENDS_WITH` relationship from each person. @@ -1902,7 +1901,7 @@ Total database accesses: 165, total allocated memory: 64 == Let Anti Semi Apply // LetAntiSemiApply -The `LetAntiSemiApply` operator tests for the absence of a pattern, and is a variation of the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +The `LetAntiSemiApply` operator tests for the absence of a pattern, and is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. When a query contains multiple negated pattern predicates -- i.e. predicates separated with `OR`, where at least one predicate contains `NOT` -- `LetAntiSemiApply` will be used to evaluate the first of these. It will record the result of evaluating the predicate but will leave any filtering to another operator. In the example, `LetAntiSemiApply` will be used to check for the absence of the `FRIENDS_WITH` relationship from each person. @@ -1966,7 +1965,7 @@ Total database accesses: 142, total allocated memory: 64 // SelectOrSemiApply The `SelectOrSemiApply` operator tests for the presence of a pattern predicate and evaluates a predicate, -and is a variation of the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +and is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. This operator allows for the mixing of normal predicates and pattern predicates that check for the presence of a pattern. First, the normal expression predicate is evaluated, and, only if it returns `false`, is the costly pattern predicate evaluated. @@ -2024,7 +2023,7 @@ Total database accesses: 148, total allocated memory: 2952 == Select Or Anti Semi Apply // SelectOrAntiSemiApply -The `SelectOrAntiSemiApply` operator is used to evaluate `OR` between a predicate and a negative pattern predicate (i.e. a pattern predicate preceded with `NOT`), and is a variation of the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +The `SelectOrAntiSemiApply` operator is used to evaluate `OR` between a predicate and a negative pattern predicate (i.e. a pattern predicate preceded with `NOT`), and is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. If the predicate returns `true`, the pattern predicate is not tested. If the predicate returns `false` or `null`, `SelectOrAntiSemiApply` will instead test the pattern predicate. @@ -2085,7 +2084,7 @@ Total database accesses: 136, total allocated memory: 4208 // LetSelectOrSemiApply The `LetSelectOrSemiApply` operator is planned for pattern predicates that are combined with other predicates using `OR`. -This is a variation of the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +This is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. .LetSelectOrSemiApply @@ -2147,7 +2146,7 @@ Total database accesses: 179, total allocated memory: 64 // LetSelectOrAntiSemiApply The `LetSelectOrAntiSemiApply` operator is planned for negated pattern predicates -- i.e. pattern predicates preceded with `NOT` -- that are combined with other predicates using `OR`. -This operator is a variation of the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +This operator is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. .LetSelectOrAntiSemiApply @@ -2316,7 +2315,7 @@ Total database accesses: 15, total allocated memory: 2232 // RollUpApply The `RollUpApply` operator is used to execute an expression which takes as input a pattern, and returns a list with content from the matched pattern; for example, when using a pattern expression or pattern comprehension in a query. -This operator is a variation of the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +This operator is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. .RollUpApply @@ -2368,7 +2367,7 @@ Total database accesses: 153, total allocated memory: 64 == Argument // Argument -The `Argument` operator indicates the variable to be used as an argument to the right-hand side of an xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator. +The `Argument` operator indicates the variable to be used as an argument to the right-hand side of an xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator. .Argument @@ -2520,7 +2519,7 @@ Total database accesses: 13, total allocated memory: 976 == Optional Expand All // OptionalExpand(All) -The `OptionalExpand(All)` operator is analogous to xref::execution-plans/operators.adoc#query-plan-expand-all[Expand(All)], apart from when no relationships match the direction, type and property predicates. +The `OptionalExpand(All)` operator is analogous to xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-expand-all[Expand(All)], apart from when no relationships match the direction, type and property predicates. In this situation, `OptionalExpand(all)` will return a single row with the relationship and end node set to `null`. @@ -2568,7 +2567,7 @@ Total database accesses: 125, total allocated memory: 184 == Optional Expand Into // OptionalExpand(Into) -The `OptionalExpand(Into)` operator is analogous to xref::execution-plans/operators.adoc#query-plan-expand-into[Expand(Into)], apart from when no matching relationships are found. +The `OptionalExpand(Into)` operator is analogous to xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-expand-into[Expand(Into)], apart from when no matching relationships are found. In this situation, `OptionalExpand(Into)` will return a single row with the relationship and end node set to `null`. As both the start and end node of the relationship are already in scope, the node with the smallest degree will be used. This can make a noticeable difference when dense nodes appear as end points. @@ -2712,7 +2711,7 @@ Total database accesses: 222, total allocated memory: 192 == VarLength Expand Pruning // VarLengthExpand(Pruning) -Given a start node, the `VarLengthExpand(Pruning)` operator will traverse variable-length and quantified relationships much like the xref::execution-plans/operators.adoc#query-plan-varlength-expand-all[`VarLengthExpand(All)`] operator. +Given a start node, the `VarLengthExpand(Pruning)` operator will traverse variable-length and quantified relationships much like the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-varlength-expand-all[`VarLengthExpand(All)`] operator. However, as an optimization, some paths will not be explored if they are guaranteed to produce an end node that has already been found (by means of a previous path traversal). This kind of expand is only planned when: @@ -2769,7 +2768,7 @@ Total database accesses: 30, total allocated memory: 480 // VarLengthExpand(Pruning,BFS) // New in 5.0 -Given a start node, the `VarLengthExpand(Pruning,BFS)` operator traverses variable-length and quantified relationships much like the xref::execution-plans/operators.adoc#query-plan-varlength-expand-all[`VarLengthExpand(All)`] operator. +Given a start node, the `VarLengthExpand(Pruning,BFS)` operator traverses variable-length and quantified relationships much like the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-varlength-expand-all[`VarLengthExpand(All)`] operator. However, as an optimization, it instead performs a breadth-first search (BFS) and while expanding, some paths are not explored if they are guaranteed to produce an end node that has already been found (by means of a previous path traversal). This is only used in cases where the individual paths are not of interest. @@ -2821,8 +2820,8 @@ Total database accesses: 1, total allocated memory: 200 // Repeat(Trail) _This feature was introduced in Neo4j 5.9._ -Given a start node, the `Repeat(Trail)` operator will traverse xref::patterns/concepts.adoc#quantified-path-patterns[quantified path patterns] that cannot be solved with the xref::execution-plans/operators.adoc#query-plan-varlength-expand-all[`VarLengthExpand(All)`] operator. -Similar to an xref::execution-plans/operators.adoc#query-plan-apply[`Apply`] operator, it takes a single row from the left-hand side and applies the operators on the right-hand side. +Given a start node, the `Repeat(Trail)` operator will traverse xref::patterns/concepts.adoc#quantified-path-patterns[quantified path patterns] that cannot be solved with the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-varlength-expand-all[`VarLengthExpand(All)`] operator. +Similar to an xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[`Apply`] operator, it takes a single row from the left-hand side and applies the operators on the right-hand side. In contrast to `Apply`, however, it repeatedly applies these operators in accordance with the quantifiers on the quantified path pattern. In the following example, the operator will repeat twice and produce rows for both repetitions. @@ -3125,17 +3124,17 @@ In query plans, the build input is always the left operator, and the probe input There are four hash join operators: -* xref::execution-plans/operators.adoc#query-plan-node-hash-join[NodeHashJoin] -* xref::execution-plans/operators.adoc#query-plan-value-hash-join[ValueHashJoin] -* xref::execution-plans/operators.adoc#query-plan-node-left-right-outer-hash-join[NodeLeftOuterHashJoin] -* xref::execution-plans/operators.adoc#query-plan-node-left-right-outer-hash-join[NodeRightOuterHashJoin] +* xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-hash-join[NodeHashJoin] +* xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-value-hash-join[ValueHashJoin] +* xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-left-right-outer-hash-join[NodeLeftOuterHashJoin] +* xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-node-left-right-outer-hash-join[NodeRightOuterHashJoin] [[query-plan-node-hash-join]] == Node Hash Join // NodeHashJoin -The `NodeHashJoin` operator is a variation of the xref::execution-plans/operators.adoc#execution-plans-operators-hash-join-general[hash join]. +The `NodeHashJoin` operator is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#execution-plans-operators-hash-join-general[hash join]. `NodeHashJoin` executes the hash join on node ids. As primitive types and arrays can be used, it can be done very efficiently. @@ -3192,7 +3191,7 @@ Total database accesses: 7, total allocated memory: 3888 == Value Hash Join // ValueHashJoin -The `ValueHashJoin` operator is a variation of the xref::execution-plans/operators.adoc#execution-plans-operators-hash-join-general[hash join]. +The `ValueHashJoin` operator is a variation of the xref::planning-and-tuning/operators/operators-detail.adoc#execution-plans-operators-hash-join-general[hash join]. This operator allows for arbitrary values to be used as the join key. It is most frequently used to solve predicates of the form: `n.prop1 = m.prop2` (i.e. equality predicates between two property columns). @@ -3245,7 +3244,7 @@ Total database accesses: 71, total allocated memory: 664 // NodeLeftOuterHashJoin // NodeRightOuterHashJoin -The `NodeLeftOuterHashJoin` and `NodeRightOuterHashJoin` operators are variations of the xref::execution-plans/operators.adoc#execution-plans-operators-hash-join-general[hash join]. +The `NodeLeftOuterHashJoin` and `NodeRightOuterHashJoin` operators are variations of the xref::planning-and-tuning/operators/operators-detail.adoc#execution-plans-operators-hash-join-general[hash join]. The query below can be planned with either a left or a right outer join. The decision depends on the cardinalities of the left-hand and right-hand sides; i.e. how many rows would be returned, respectively, for `(a:Person)` and `(a)-->(b:Person)`. If `(a:Person)` returns fewer results than `(a)-->(b:Person)`, a left outer join -- indicated by `NodeLeftOuterHashJoin` -- is planned. @@ -3543,7 +3542,7 @@ Total database accesses: 142, total allocated memory: 1816 // Foreach The `Foreach` operator executes a nested loop between the left child operator and the right child operator. -In an analogous manner to the xref::execution-plans/operators.adoc#query-plan-apply[Apply] operator, it takes a row from the left-hand side and, using the xref::execution-plans/operators.adoc#query-plan-argument[Argument] operator, provides it to the operator tree on the right-hand side. +In an analogous manner to the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-apply[Apply] operator, it takes a row from the left-hand side and, using the xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-argument[Argument] operator, provides it to the operator tree on the right-hand side. `Foreach` will yield all the rows coming in from the left-hand side; all results from the right-hand side are pulled in and discarded. @@ -4541,7 +4540,6 @@ Batch size 128 | | +----+------------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+ | +Create | 6 | (n), (m), (n)-[p:KNOWS]->(m) | 1 | 1 | 3 | | | | Fused in Pipeline 0 | +---------------------+----+------------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+ - Total database accesses: 5, total allocated memory: 4936 ---- @@ -4727,7 +4725,7 @@ Batch size 128 | | +-----------------------------------+----------------+------+---------+----------------+------------------------+-----------+ | | | +Sort | label ASC | 10 | 4 | 0 | 536 | 0/0 | 0.178 | label ASC | In Pipeline 1 | | | +-----------------------------------+----------------+------+---------+----------------+------------------------+-----------+------------+---------------------+ -| +ProcedureCall | db.labels() :: (label :: STRING?) | 10 | 4 | | | | | | Fused in Pipeline 0 | +| +ProcedureCall | db.labels() :: (label :: STRING) | 10 | 4 | | | | | | Fused in Pipeline 0 | +-----------------+-----------------------------------+----------------+------+---------+----------------+------------------------+-----------+------------+---------------------+ Total database accesses: ?, total allocated memory: 600 diff --git a/modules/ROOT/pages/query-tuning/index.adoc b/modules/ROOT/pages/planning-and-tuning/query-tuning/index.adoc similarity index 50% rename from modules/ROOT/pages/query-tuning/index.adoc rename to modules/ROOT/pages/planning-and-tuning/query-tuning/index.adoc index bd6b3aaa6..0a64acc03 100644 --- a/modules/ROOT/pages/query-tuning/index.adoc +++ b/modules/ROOT/pages/planning-and-tuning/query-tuning/index.adoc @@ -1,20 +1,29 @@ :description: Query tuning for the Cypher query language. - [[query-tuning]] = Query tuning Neo4j aims to execute queries as fast as possible. - However, when optimizing for maximum query execution performance, it may be helpful to rephrase queries using knowledge about the domain and the application. +This section contains information about how to tune queries using different strategies. + +* xref:planning-and-tuning/query-tuning/indexes.adoc[] +* xref:planning-and-tuning/query-tuning/using.adoc[] +* xref:planning-and-tuning/query-tuning/query-options.adoc[] + +For information about changing the runtime of a query, see the page about xref:planning-and-tuning/runtimes/concepts.adoc[Cypher runtime concepts]. + +== General recommendations + The overall goal of manual query performance optimization is to ensure that only necessary data is retrieved from the graph. -At the very least, data should get filtered out as early as possible in order to reduce the amount of work that has to be done in the later stages of query execution. + +Queries should aim to filter data as early as possible in order to reduce the amount of work that has to be done in the later stages of query execution. This also applies to what gets returned: returning whole nodes and relationships ought to be avoided in favour of selecting and returning only the data that is needed. You should also make sure to set an upper limit on variable length patterns, so they don't cover larger portions of the dataset than needed. -Each Cypher query gets optimized and transformed into an xref::execution-plans/index.adoc#execution-plan-introduction[execution plan] by the Cypher query planner. +Each Cypher query gets optimized and transformed into an xref::planning-and-tuning/execution-plans.adoc[execution plan] by the Cypher query planner. To minimize the resources used for this, try to use parameters instead of literals when possible. -This allows Cypher to re-use your queries instead of having to parse and build new execution plans. +This allows Cypher to re-use queries instead of having to parse and build new execution plans. -To read more about the execution plan operators mentioned in this section, see xref::execution-plans/index.adoc[]. +To read more about the execution plan operators mentioned in this section, see xref::planning-and-tuning/operators/index.adoc[]. diff --git a/modules/ROOT/pages/query-tuning/indexes.adoc b/modules/ROOT/pages/planning-and-tuning/query-tuning/indexes.adoc similarity index 94% rename from modules/ROOT/pages/query-tuning/indexes.adoc rename to modules/ROOT/pages/planning-and-tuning/query-tuning/indexes.adoc index 1bbf221fd..7de1cbf7d 100644 --- a/modules/ROOT/pages/query-tuning/indexes.adoc +++ b/modules/ROOT/pages/planning-and-tuning/query-tuning/indexes.adoc @@ -1,5 +1,4 @@ :description: The query plans when indexes are used in various scenarios. - [[query-tuning-indexes]] = The use of indexes @@ -11,7 +10,6 @@ Therefore, node and relationship indexes are used interchangeably in this sectio For instructions on how to create and maintain indexes, refer to xref::indexes-for-search-performance.adoc[]. - == Index types and predicate compatibility Generally, an index solves some combination of a label/relationship type predicate and property predicates at the same time. @@ -168,10 +166,9 @@ point.distance(n.prop, center) < = distance [NOTE] ==== As of Neo4j 5.11, the above set of predicates can be extended with the use of type constraints. -For more information, see xref::query-tuning/indexes.adoc#extending-index-compatibility-with-type-constraints[Extending index compatibility with type constraints]. +For more information, see xref::planning-and-tuning/query-tuning/indexes.adoc#extending-index-compatibility-with-type-constraints[Extending index compatibility with type constraints]. ==== - == TEXT indexes In combination with node label and relationship type predicates, `TEXT` indexes only solve predicates operating on strings. @@ -235,7 +232,7 @@ CONTAINS [NOTE] ==== -As of Neo4j 5.11, the above set of predicates can be extended with the use of type constraints, see xref::query-tuning/indexes.adoc#extending-index-compatibility-with-type-constraints[Extending index compatibility with type constraints]. +As of Neo4j 5.11, the above set of predicates can be extended with the use of type constraints, see xref::planning-and-tuning/query-tuning/indexes.adoc#extending-index-compatibility-with-type-constraints[Extending index compatibility with type constraints]. ==== In some cases, the system cannot determine whether an expression is of type string. @@ -253,7 +250,7 @@ Depending on how values that are not of type string should be treated, there are `MATCH (n:Label) WHERE $param STARTS WITH '' AND n.prop = $param` * If expressions which are not of type string should be converted to string, then wrapping these in `toString()` is the right choice: `MATCH (n:Label) WHERE n.prop = toString($param)` -* If it is known that the property is always of type `STRING`, then it's also possible to xref::query-tuning/indexes.adoc#extending-index-compatibility-with-type-constraints[add a type constraint to help the planner]. +* If it is known that the property is always of type `STRING`, then it's also possible to xref::planning-and-tuning/query-tuning/indexes.adoc#extending-index-compatibility-with-type-constraints[add a type constraint to help the planner]. [[extending-index-compatibility-with-type-constraints]] == Extending index compatibility with type constraints @@ -286,31 +283,31 @@ It is defined as such: *Examples:* -* xref::query-tuning/indexes.adoc#administration-indexes-node-label-lookup-index-example[] -* xref::query-tuning/indexes.adoc#administration-indexes-relationship-type-lookup-index-example[] -* xref::query-tuning/indexes.adoc#administration-indexes-node-range-index-example[] -* xref::query-tuning/indexes.adoc#administration-indexes-relationship-range-index-example[] -* xref::query-tuning/indexes.adoc#administration-indexes-node-text-index-example[] -* xref::query-tuning/indexes.adoc#administration-indexes-relationship-text-index-example[] -* xref::query-tuning/indexes.adoc#administration-indexes-multiple-available-index-types[] -* xref::query-tuning/indexes.adoc#administration-indexes-equality-check-using-where-single-property-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-equality-check-using-where-composite-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-range-comparisons-using-where-single-property-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-range-comparisons-using-where-composite-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-multiple-range-comparisons-using-where-single-property-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-multiple-range-comparisons-using-where-composite-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-list-membership-check-using-in-single-property-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-list-membership-check-using-in-composite-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-prefix-search-using-starts-with-single-property-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-prefix-search-using-starts-with-composite-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-suffix-search-using-ends-with-single-property-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-suffix-search-using-ends-with-composite-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-substring-search-using-contains-single-property-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-substring-search-using-contains-composite-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-existence-check-using-is-not-null-single-property-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-existence-check-using-is-not-null-composite-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-spatial-distance-searches-single-property-index[] -* xref::query-tuning/indexes.adoc#administration-indexes-spatial-bounding-box-searches-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-node-label-lookup-index-example[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-relationship-type-lookup-index-example[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-node-range-index-example[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-relationship-range-index-example[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-node-text-index-example[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-relationship-text-index-example[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-multiple-available-index-types[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-equality-check-using-where-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-equality-check-using-where-composite-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-range-comparisons-using-where-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-range-comparisons-using-where-composite-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-multiple-range-comparisons-using-where-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-multiple-range-comparisons-using-where-composite-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-list-membership-check-using-in-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-list-membership-check-using-in-composite-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-prefix-search-using-starts-with-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-prefix-search-using-starts-with-composite-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-suffix-search-using-ends-with-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-suffix-search-using-ends-with-composite-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-substring-search-using-contains-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-substring-search-using-contains-composite-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-existence-check-using-is-not-null-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-existence-check-using-is-not-null-composite-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-spatial-distance-searches-single-property-index[] +* xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-spatial-bounding-box-searches-single-property-index[] [discrete] @@ -909,7 +906,7 @@ Total database accesses: 2, total allocated memory: 184 [[administration-indexes-list-membership-check-using-in-single-property-index]] === List membership check using `IN` (single-property index) -The `IN` predicate on `r.lastMetIn` in the following query will use the single-property index `KNOWS(lastMetIn)` if it exists. +The `IN` predicate on `r.since` in the following query will use the single-property index `KNOWS(lastMetIn)` if it exists. //// [source, cypher, role=test-setup] diff --git a/modules/ROOT/pages/query-tuning/query-options.adoc b/modules/ROOT/pages/planning-and-tuning/query-tuning/query-options.adoc similarity index 78% rename from modules/ROOT/pages/query-tuning/query-options.adoc rename to modules/ROOT/pages/planning-and-tuning/query-tuning/query-options.adoc index 8e657f513..1d8e15cba 100644 --- a/modules/ROOT/pages/query-tuning/query-options.adoc +++ b/modules/ROOT/pages/planning-and-tuning/query-tuning/query-options.adoc @@ -1,8 +1,7 @@ -[[cypher-query-options]] -= Cypher query options +[[query-tuning-options]] += Query options :description: Query options available in Cypher. - Query execution can be fine-tuned through the use of query options. In order to use one or more of these options, the query must be prepended with `CYPHER`, followed by the query option(s), as exemplified thus: @@ -12,41 +11,7 @@ In order to use one or more of these options, the query must be prepended with ` CYPHER query-option [further-query-options] query ---- - -[[cypher-runtime]] -== Cypher runtime - -The Cypher _runtime_ runs queries and returns records based on an execution plan. -Depending on the Neo4j edition, there are two different runtimes available: - -Slotted:: -In the _slotted_ runtime, the operators in the execution plan are chained together in a tree, where each non-leaf operator feeds from one or two child operators. -The tree comprises nested iterators, which stream records from the top iterator, which pulls from the next iterator, and so on. -Each variable in the query gets a dedicated "slot" or offset, which the runtime uses for accessing (e.g., `slotRow[0]`). + -The slotted runtime covers all operators and queries. + -In Neo4j 5, it is the default for Community Edition. - -[enterprise-edition]#Pipelined#:: -In the _pipelined_ runtime, the operators are grouped into pipelines in the execution plan to generate new combinations and orders of execution, which are optimized for performance and memory usage. + -The pipelined runtime covers most operators and queries. -If the `pipelined` runtime does not support a query, the planner falls back to the `slotted` runtime. + -It is the default for Enterprise Edition. - -[options="header",cols="2m,2a,^1a"] -|=== -|Option -|Description -|Default - -|runtime=slotted -|Forces the Cypher query planner to use the _slotted_ runtime. -|Default for Community Edition. - -|[enterprise-edition]#runtime=pipelined# -| Forces the Cypher query planner to use the _pipelined_ runtime. -| Default for Enterprise Edition. -|=== - +For information about the various runtimes available in Cypher, see xref:planning-and-tuning/runtimes/index.adoc[]. [[cypher-planner]] == Cypher planner @@ -168,8 +133,6 @@ The possible values are: | Always compile expressions and use the _compiled_ expression engine. -Cannot be used together with `runtime=interpreted`. - | |=== @@ -198,7 +161,7 @@ The possible values are: | Always attempt to generate _compiled_ operators. -Cannot be used together with `runtime=interpreted` or `runtime=slotted`. +Cannot be used together with `runtime=slotted`. | @@ -224,7 +187,7 @@ The available options are: | If the plan contains any operators not supported by the pipelined runtime then another runtime is chosen to execute the entire plan. -Cannot be used together with `runtime=interpreted` or `runtime=slotted`. +Cannot be used together with `runtime=slotted`. | @@ -233,7 +196,7 @@ Cannot be used together with `runtime=interpreted` or `runtime=slotted`. Parts of the execution plan can be executed on another runtime. Only certain operators are allowed to execute on another runtime. -Cannot be used together with `runtime=interpreted` or `runtime=slotted`. +Cannot be used together with `runtime=slotted`. | @@ -243,7 +206,7 @@ Parts of the execution plan may be executed on another runtime. Any operator is allowed to execute on another runtime. Queries with this option set might produce incorrect results, or fail. -Cannot be used together with `runtime=interpreted` or `runtime=slotted`. +Cannot be used together with or `runtime=slotted`. [WARNING] ==== @@ -264,7 +227,7 @@ Cypher replanning occurs in the following circumstances: This can either be when the server is first started or restarted, if the cache has recently been cleared, or if link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_server.db.query_cache_size[server.db.query_cache_size] was exceeded. * When the time has past the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.cypher.min_replan_interval[dbms.cypher.min_replan_interval] value, and the database statistics have changed more than the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/configuration-settings#config_dbms.cypher.statistics_divergence_threshold[dbms.cypher.statistics_divergence_threshold] value. -There may be situations where xref::execution-plans/index.adoc[Cypher query planning] can occur at a non-ideal time. +There may be situations where xref::planning-and-tuning/execution-plans.adoc[Cypher query planning] can occur at a non-ideal time. For example, when a query must be as fast as possible and a valid plan is already in place. [NOTE] diff --git a/modules/ROOT/pages/query-tuning/using.adoc b/modules/ROOT/pages/planning-and-tuning/query-tuning/using.adoc similarity index 99% rename from modules/ROOT/pages/query-tuning/using.adoc rename to modules/ROOT/pages/planning-and-tuning/query-tuning/using.adoc index 32864e424..c1a798d13 100644 --- a/modules/ROOT/pages/query-tuning/using.adoc +++ b/modules/ROOT/pages/planning-and-tuning/query-tuning/using.adoc @@ -23,9 +23,9 @@ This is called giving a planner hint. There are three types of planner hints: -* Index hints. -* Scan hints. -* Join hints. +* xref:planning-and-tuning/query-tuning/using.adoc#query-using-index-hint[Index hints]. +* xref:planning-and-tuning/query-tuning/using.adoc#query-using-scan-hint[Scan hints]. +* xref:planning-and-tuning/query-tuning/using.adoc#query-using-join-hint[Join hints]. //// [source, cypher, role=test-setup] @@ -142,7 +142,7 @@ When no index type is specified, the hint can be fulfilled by any index types. ==== Using a hint must never change the result of a query. Therefore, a hint with a specified index type is only fulfillable when the planner knows that using an index of the specified type does not change the results. -Please refer to xref::query-tuning/indexes.adoc[The use of indexes] for more details. +Please refer to xref::planning-and-tuning/query-tuning/indexes.adoc[The use of indexes] for more details. ==== It is possible to supply several index hints, but keep in mind that several starting points diff --git a/modules/ROOT/pages/planning-and-tuning/runtimes/concepts.adoc b/modules/ROOT/pages/planning-and-tuning/runtimes/concepts.adoc new file mode 100644 index 000000000..813ecaf95 --- /dev/null +++ b/modules/ROOT/pages/planning-and-tuning/runtimes/concepts.adoc @@ -0,0 +1,401 @@ +:description: information about the concepts behind slotted, pipelined, and parallel runtime. + +[[runtimes-concepts]] += Runtime concepts + +In Cypher, there are three types of runtimes: slotted, pipelined, and parallel. +In general, the default runtimes (the pipelined runtime in Enterprise Edition) provide the best query performance. +However, each runtime offers advantages and disadvantages, and there are scenarios when deciding which runtime to use is an important step in maximizing the efficiency of queries. + +This is a step-by-step guide to the concepts behind each of the three available Cypher runtimes. +For readers not familiar with reading the execution plans produced by Cypher queries, it is recommended to first read the section on xref:planning-and-tuning/execution-plans.adoc[]. + +[[runtimes-example-graph]] +== Example graph + +The following graph is used for the queries on this page: + +image::patterns_qpp_calling_points.svg[width="700",role="middle"] + +The graph contains two types of nodes: `Stop` and `Station`. +Each `Stop` on a train service `CALLS_AT` one `Station`, and has the properties `arrives` and `departs` that give the times the train is at the `Station`. +Following the `NEXT` relationship of a `Stop` will give the next `Stop` of a service. + +To recreate the graph, run the following query against an empty Neo4j database: + +.Query +[source, cypher, role=test-setup] +---- +CREATE (pmr:Station {name: 'Peckham Rye'}), + (dmk:Station {name: 'Denmark Hill'}), + (clp:Station {name: 'Clapham High Street'}), + (wwr:Station {name: 'Wandsworth Road'}), + (clj:Station {name: 'Clapham Junction'}), + (s1:Stop {arrives: time('17:19'), departs: time('17:20')}), + (s2:Stop {arrives: time('17:12'), departs: time('17:13')}), + (s3:Stop {arrives: time('17:10'), departs: time('17:11')}), + (s4:Stop {arrives: time('17:06'), departs: time('17:07')}), + (s5:Stop {arrives: time('16:58'), departs: time('17:01')}), + (s6:Stop {arrives: time('17:17'), departs: time('17:20')}), + (s7:Stop {arrives: time('17:08'), departs: time('17:10')}), + (clj)<-[:CALLS_AT]-(s1), (wwr)<-[:CALLS_AT]-(s2), + (clp)<-[:CALLS_AT]-(s3), (dmk)<-[:CALLS_AT]-(s4), + (pmr)<-[:CALLS_AT]-(s5), (clj)<-[:CALLS_AT]-(s6), + (dmk)<-[:CALLS_AT]-(s7), + (s5)-[:NEXT {distance: 1.2}]->(s4),(s4)-[:NEXT {distance: 0.34}]->(s3), + (s3)-[:NEXT {distance: 0.76}]->(s2), (s2)-[:NEXT {distance: 0.3}]->(s1), + (s7)-[:NEXT {distance: 1.4}]->(s6) +---- + +[[runtimes-slotted-runtime]] +== Slotted runtime + +The slotted runtime is the default runtime for Neo4j Community Edition. +Users of Neo4j Enterprise Edition must prepend their query with `CYPHER runtime = slotted` in order for a query to run with slotted runtime. +For example: + +.Query +[source, cypher] +---- +EXPLAIN +CYPHER runtime = slotted +MATCH (:Station { name: 'Denmark Hill' })<-[:CALLS_AT]-(d:Stop) + ((:Stop)-[:NEXT]->(:Stop))+ + (a:Stop)-[:CALLS_AT]->(:Station { name: 'Clapham Junction' }) +RETURN count(*) +---- + +This query will generate the following execution plan: + +[role="queryplan", subs="attributes+"] +---- +Planner COST + +Runtime SLOTTED + +Runtime version {neo4j-version-minor} + ++-------------------+----+------------------------------------------------------------------------+----------------+ +| Operator | Id | Details | Estimated Rows | ++-------------------+----+------------------------------------------------------------------------+----------------+ +| +ProduceResults | 0 | `count(*)` | 1 | +| | +----+------------------------------------------------------------------------+----------------+ +| +EagerAggregation | 1 | count(*) AS `count(*)` | 1 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Filter | 2 | not anon_1 = anon_5 AND anon_0.name = $autostring_0 AND anon_0:Station | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Expand(All) | 3 | (d)-[anon_1:CALLS_AT]->(anon_0) | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Filter | 4 | d:Stop | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Repeat(Trail) | 5 | (a) (...){1, *} (d) | 0 | +| |\ +----+------------------------------------------------------------------------+----------------+ +| | +Filter | 6 | isRepeatTrailUnique(anon_7) AND anon_2:Stop | 6 | +| | | +----+------------------------------------------------------------------------+----------------+ +| | +Expand(All) | 7 | (anon_4)<-[anon_7:NEXT]-(anon_2) | 6 | +| | | +----+------------------------------------------------------------------------+----------------+ +| | +Filter | 8 | anon_4:Stop | 11 | +| | | +----+------------------------------------------------------------------------+----------------+ +| | +Argument | 9 | anon_4 | 13 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Filter | 10 | a:Stop | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Expand(All) | 11 | (anon_6)<-[anon_5:CALLS_AT]-(a) | 0 | +| | +----+------------------------------------------------------------------------+----------------+ +| +Filter | 12 | anon_6.name = $autostring_1 | 1 | +| | +----+------------------------------------------------------------------------+----------------+ +| +NodeByLabelScan | 13 | anon_6:Station | 10 | ++-------------------+----+------------------------------------------------------------------------+----------------+ +---- + +The physical plan produced by slotted runtimes is a one-to-one mapping from the logical plan, where each logical operator maps to a corresponding physical operator, and where the operators are processed row-by-row. +When using slotted runtime, each variable in the query gets a dedicated “slot”, which the runtime uses for accessing the data mapped to the given variable, hence the name “slotted”. + +The slotted runtime uses the traditional execution model of most databases known as the iterator or “Volcano” model. +This is a pull-based process where each operator in the tree “pulls” rows of data from its child operator by using a virtual call function. +In this way, data is pulled up from the bottom of the execution plan to the top, generating an eruption-like flow of data. + +[[runtimes-slotted-runtime-considerations]] +=== Considerations + +The slotted runtime is the first high-performance runtime introduced in Neo4j, replacing the original (and slower) interpreted runtime, which is now retired. + +The slotted runtime is an interpreted runtime, meaning that it interprets the logical plan sent by the planner operator-by-operator. +In general, this is a convenient and flexible approach capable of handling all operators and queries. +The slotted runtime is conceptually similar to interpreted programming languages, in that it has a shorter planning phase because it does not need to generate all the code for the query before execution (unlike compiled runtimes - discussed in more detail xref::planning-and-tuning/runtimes/concepts.adoc#pipelined-runtime-considerations.adoc[below]).footnote:[The classification of a runtime as interpreted or compiled is not entirely accurate. +Most runtime implementations are not fully interpreted or fully compiled but are rather a blend of the two styles. +For example, when the slotted runtime is run in Neo4j Enterprise Edition, code is generated for the expressions included in the query. +Nevertheless, the slotted runtime is considered interpreted, since that is the predominant method of implementation.] + +In general, users of Neo4j Enterprise Edition should not have to use slotted runtime. +However, there are scenarios where the fast planning phase of the slotted runtime may be useful. + For example, if you are using an application that generates short queries that are not cached (i.e. never, or very rarely, repeated), then the slotted runtime may be preferable because of its faster planning time. + +There are, however, limitations to the slotted runtime. +The continuous calling of virtual functions between each operator uses CPU cycles which results in slower query execution. +Furthermore, the iterator model can lead to poor data locality, which can cause a slower query execution. +This is because the process of individual rows being pulled from different operators makes it difficult to make efficient use of CPU caches. + +[role=enterprise-edition] +[[runtimes-pipelined-runtime]] +== Pipelined runtime + +The pipelined runtime is the default runtime for Neo4j Enterprise Edition. +This means that unless users of Neo4j Enterprise Edition specify a different runtime, queries will be run using the pipelined runtime. + +To specify that a query should use the pipelined runtime, prepend the query with `CYPHER runtime = pipelined`. +For example: + +.Query +[source, cypher] +---- +EXPLAIN +CYPHER runtime = pipelined +MATCH (:Station { name: 'Denmark Hill' })<-[:CALLS_AT]-(d:Stop) + ((:Stop)-[:NEXT]->(:Stop))+ + (a:Stop)-[:CALLS_AT]->(:Station { name: 'Clapham Junction' }) +RETURN count(*) +---- + +The resulting execution plan contains notable differences from the one produced by slotted runtime: + +[role="queryplan", subs="attributes+"] +---- +Planner COST + +Runtime PIPELINED + +Runtime version {neo4j-version-minor} + +Batch size 128 + ++-------------------+----+------------------------------------------------------------------------+----------------+---------------------+ +| Operator | Id | Details | Estimated Rows | Pipeline | ++-------------------+----+------------------------------------------------------------------------+----------------+---------------------+ +| +ProduceResults | 0 | `count(*)` | 1 | In Pipeline 3 | +| | +----+------------------------------------------------------------------------+----------------+---------------------+ +| +EagerAggregation | 1 | count(*) AS `count(*)` | 1 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Filter | 2 | not anon_1 = anon_5 AND anon_0.name = $autostring_0 AND anon_0:Station | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Expand(All) | 3 | (d)-[anon_1:CALLS_AT]->(anon_0) | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Filter | 4 | d:Stop | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +NullifyMetadata | 14 | | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Repeat(Trail) | 5 | (a) (...){1, *} (d) | 0 | Fused in Pipeline 2 | +| |\ +----+------------------------------------------------------------------------+----------------+---------------------+ +| | +Filter | 6 | isRepeatTrailUnique(anon_7) AND anon_2:Stop | 6 | | +| | | +----+------------------------------------------------------------------------+----------------+ | +| | +Expand(All) | 7 | (anon_4)<-[anon_7:NEXT]-(anon_2) | 6 | | +| | | +----+------------------------------------------------------------------------+----------------+ | +| | +Filter | 8 | anon_4:Stop | 11 | | +| | | +----+------------------------------------------------------------------------+----------------+ | +| | +Argument | 9 | anon_4 | 13 | Fused in Pipeline 1 | +| | +----+------------------------------------------------------------------------+----------------+---------------------+ +| +Filter | 10 | a:Stop | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Expand(All) | 11 | (anon_6)<-[anon_5:CALLS_AT]-(a) | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Filter | 12 | anon_6.name = $autostring_1 | 1 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +NodeByLabelScan | 13 | anon_6:Station | 10 | Fused in Pipeline 0 | ++-------------------+----+------------------------------------------------------------------------+----------------+---------------------+ +---- + +The rightmost column of the plan shows that it has been divided into four different *pipelines*. +In order to understand what pipelines are, it is first necessary to understand that queries using pipelined runtime are, unlike those run in slotted runtime, not executed one row at a time. +Rather, the pipelined runtime allows the physical operators to consume and produce *batches* of between roughly 100 and 1000 rows each (referred to as *morsels*), which are written into *buffers* containing data and tasks for a pipeline. +A pipeline can, in turn, be defined as a sequence of operators which have been fused into one another so that they may be executed together in the same task by the runtime. + +The logical operators are thus not mapped to a corresponding physical operator when using the pipelined runtime. +Instead, the logical operator tree is transformed into an execution graph containing pipelines and buffers: + +image::runtimes_execution_graph1.svg[width="700",role="middle"] + +In this execution graph, query execution starts at `pipeline 0` which will eventually produce a morsel to be written into the buffer of `pipeline 1`. +Once there is data for `pipeline 1` to process, it can begin executing and in turn write data for the next pipeline to process, and so on. +In this way, data is being pushed along the execution graph. + +[[runtimes-pipelined-runtime-considerations]] +=== Considerations + +The pipelined runtime is a push-based execution model, where data is pushed from the leaf operator to its parent operators. +Unlike pull-based models (which the slotted runtime uses), data can be kept in local variables when using push-based execution models, and this has several benefits; it enables direct use of CPU registers, improves the use of CPU caches, and avoids the costly virtual function calls used in pull-based models. + +The pipelined runtime is ideal for transactional use cases, with a large number of queries running in parallel on the system. +This covers most usage scenarios, and for this reason, it is the default Neo4j runtime. + +The pipelined runtime is a combined model, that can either use an interpreted or compiled runtime. +However, because it predominantly uses the latter, it is considered a compiled runtime. +Unlike interpreted runtimes, compiled runtimes have a code generation phase followed by an execution phase, and this typically causes a longer query planning time, but a shorter execution time. + +As stated xref::planning-and-tuning/runtimes/concepts.adoc#runtimes-slotted-runtime-considerations[above], there are rare scenarios in which users of Neo4j Enterprise Edition may benefit from not using the pipelined runtime for their queries. +However, for most queries, the pipelined runtime is a more efficient runtime capable of handling all operators and queries. + +[role=enterprise-edition] +[[runtimes-parallel-runtime]] +== Parallel runtime + +_This feature was introduced in Neo4j 5.13._ + +Both the slotted and pipelined runtimes execute queries in a single thread assigned to one CPU core. +It is still possible to achieve parallelism (broadly defined as when two or more sets of operations can be processed concurrently within a single database environment) when using these two runtimes by running multiple queries in separate CPU threads concurrently. +This is the typical scenario in OLTP (Online Transaction Processing) use cases. + +However, there are scenarios, principally when performing graph analytics, where it is beneficial for a single query to use several cores to boost its performance. +This can be achieved by using parallel runtime, which is multi-threaded and allows queries to potentially utilize all available cores on the server running Neo4j. + +To specify that a query should use the parallel runtime, prepend it with `CYPHER runtime = parallel`. +For example: + +.Query +[source, cypher] +---- +EXPLAIN +CYPHER runtime = parallel +MATCH (:Station { name: 'Denmark Hill' })<-[:CALLS_AT]-(d:Stop) + ((:Stop)-[:NEXT]->(:Stop))+ + (a:Stop)-[:CALLS_AT]->(:Station { name: 'Clapham Junction' }) +RETURN count(*) +---- + +This is the resulting execution plan: + +[role="queryplan", subs="attributes+"] +---- +Planner COST + +Runtime PARALLEL + +Runtime version {neo4j-version-minor} + +Batch size 128 + ++-------------------+----+------------------------------------------------------------------------+----------------+---------------------+ +| Operator | Id | Details | Estimated Rows | Pipeline | ++-------------------+----+------------------------------------------------------------------------+----------------+---------------------+ +| +ProduceResults | 0 | `count(*)` | 1 | In Pipeline 6 | +| | +----+------------------------------------------------------------------------+----------------+---------------------+ +| +EagerAggregation | 1 | count(*) AS `count(*)` | 1 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Filter | 2 | not anon_1 = anon_5 AND anon_0.name = $autostring_0 AND anon_0:Station | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Expand(All) | 3 | (d)-[anon_1:CALLS_AT]->(anon_0) | 0 | Fused in Pipeline 5 | +| | +----+------------------------------------------------------------------------+----------------+---------------------+ +| +Filter | 4 | d:Stop | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +NullifyMetadata | 14 | | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Repeat(Trail) | 5 | (a) (...){1, *} (d) | 0 | Fused in Pipeline 4 | +| |\ +----+------------------------------------------------------------------------+----------------+---------------------+ +| | +Filter | 6 | isRepeatTrailUnique(anon_7) AND anon_2:Stop | 6 | | +| | | +----+------------------------------------------------------------------------+----------------+ | +| | +Expand(All) | 7 | (anon_4)<-[anon_7:NEXT]-(anon_2) | 6 | Fused in Pipeline 3 | +| | | +----+------------------------------------------------------------------------+----------------+---------------------+ +| | +Filter | 8 | anon_4:Stop | 11 | | +| | | +----+------------------------------------------------------------------------+----------------+ | +| | +Argument | 9 | anon_4 | 13 | Fused in Pipeline 2 | +| | +----+------------------------------------------------------------------------+----------------+---------------------+ +| +Filter | 10 | a:Stop | 0 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +Expand(All) | 11 | (anon_6)<-[anon_5:CALLS_AT]-(a) | 0 | Fused in Pipeline 1 | +| | +----+------------------------------------------------------------------------+----------------+---------------------+ +| +Filter | 12 | anon_6.name = $autostring_1 | 1 | | +| | +----+------------------------------------------------------------------------+----------------+ | +| +NodeByLabelScan | 13 | anon_6:Station | 10 | Fused in Pipeline 0 | ++-------------------+----+------------------------------------------------------------------------+----------------+---------------------+ +---- + +A key difference between the physical plans produced by the parallel runtime compared to those generated by pipelined runtime is that, in general, more pipelines are produced when using the parallel runtime (in this case, seven instead of the four produced by the same query being run on pipelined runtime). +This is because, when executing a query in the parallel runtime, it is more efficient to have more tasks that can be run in parallel, whereas when running a single-threaded execution in the pipelined runtime it is more efficient to fuse several pipelines together. + +The parallel runtime shares the same architecture as the pipelined runtime, meaning that it will transform the logical plan into the same type of execution graph as described above. +However, when using parallel runtime, each pipeline task can be executed in a separate thread. +Another similarity with pipelined runtime is that queries run on the parallel runtime will begin by generating the first pipeline which eventually will produce a morsel in the input buffer of the subsequent pipeline. +But, whereas only one pipeline can progress at a time when using the pipelined runtime, parallel runtime allows pipelines to concurrently produce morsels. +Therefore, as each task finishes, more and more input morsels will be made available for the tasks which means that more and more workers can be utilized to execute the query. + +To further explain how parallel runtime works, a set of new terms need to be defined: + +* *Worker*: a thread that executes work units to evaluate incoming queries. +* *Task*: a unit of work. +A task executes one pipeline on one input morsel and produces one output morsel. +If any condition prevents a task from completing, it can be rescheduled as a Continuation to resume at a later time. +* *Continuation*: a task that did not finish execution and must be scheduled again. +* *Scheduler*: responsible for deciding which unit of work to process next. +Scheduling is decentralized, and each worker has its own scheduler instance. + +Consider the execution graph below, based on the same example query: + +image::runtimes_execution_graph2.svg[width="900",role="middle"] + +The execution graph shows that execution starts at `pipeline 0`, which consists of the operator `NodeByLabelScan` and can be executed simultaneously on all available threads working on different morsels of data. +Once pipeline `0` has produced at least one full morsel of data, any thread can then start executing `pipeline 1`, while other threads may continue to execute `pipeline 0`. +More specifically, once there is data from a pipeline, the scheduler can proceed to the next pipeline while concurrently executing earlier pipelines. +In this case, `pipeline 5` ends with an aggregation (performed by the EagerAggregation operator), which means that the last pipeline (6) cannot start until all preceding pipelines are completely finished for all the preceding morsels of data. + +[[runtimes-parallel-runtime-considerations]] +=== Considerations + +.When to use the parallel runtime + +In most situations where multiple CPU cores are available, long-running queries can be expected to run significantly faster on the parallel runtime. +While it is not possible to define the exact duration at which a query would benefit from being run on the parallel runtime (as this depends on the data model, the query structure, the load of the system, and the number of cores available), it can be assumed as a general rule that any query that takes longer than approximately 500 milliseconds would be a good candidate. + +This means that the parallel runtime is suitable for *analytical*, *graph-global* queries. +These queries are often not anchored to a particular start node and therefore process a large section of the graph in order to gain valuable insights from it. + +However, queries that start with anchoring a specific node may benefit from being run on the parallel runtime, if either of the following is true: + +* The anchored starting node is a densely connected node or super node. +* The query proceeds to expand from the anchored node to a large section of the graph. + +There is, therefore, no fixed rule as to when a query should be run with the parallel runtime, but these guidelines provide some useful information about the scenarios when users would very likely benefit from trying to use it. + +.When not to use the parallel runtime + +Unlike the pipelined runtime, which was designed as the most efficient method for most queries to be planned, the use cases for the parallel runtime are more specific, and there are situations where it is not possible or beneficial to use it. +Most notably, the parallel runtime *only supports read queries*. +It also does not support procedures functions that are not considered thread-safe (i.e. not safe to run from multiple threads). + +Moreover, not all queries will run faster by using the parallel runtime. +For example, a *graph-local* query that starts with anchoring a node and proceeds to only match a small portion of the graph will probably not run any faster on the parallel runtime (it may even run slower when executed with the parallel runtime, because of its scheduling and the additional book-keeping required for executing a query on multiple threads). +As a general rule of thumb, the parallel runtime is probably not beneficial for queries which take less than half a second to complete. + +The parallel runtime may also perform worse than the pipelined runtime for queries that contain subclauses where xref:clauses/order-by.adoc[] is used to order a property that is indexed. +This is because the parallel runtime is unable to take advantage of property indexes for ordering, and therefore must re-sort the aggregated results on the selected properties before returning any results. + +Finally, though individual queries may run faster when running the parallel runtime, the overall throughput of the database may decrease as a result of running many concurrent queries. + +The parallel runtime is accordingly not suitable for transactional processing queries with high throughput workloads. +It is, however, ideal for analytical use cases where the database runs relatively few, but demanding read queries. + +[[runtimes-parallel-runtime-overview]] +==== Overview + +In general, the parallel runtime should be considered if the following conditions are met: + +* Graph-global read-queries are constructed to target a large section of a graph. +* The speed of queries is important. +* The server has many CPUs and enough memory. +* There is a low concurrency workload on the database. + +For more information about the parallel runtime, including more details about queries, procedures, functions, configuration settings, and using the parallel runtime on Aura, see the xref:planning-and-tuning/runtimes/reference.adoc[] page. + +[[runtimes-summary]] +== Summary + +The below table summarizes the most important distinctions between the three different runtimes available in Cypher: + +|=== +| | *Slotted* | *Pipelined* | *Parallel* + +| *Execution model* | Pull | Push | Push +| *Physical operator consumption* | Row-by-row | Batched | Batched +| *Processor threads* | Single-threaded | Single-threaded | Multi-threaded +| *Runtime type* | Interpreted | Compiled or interpreted | Compiled or interpreted +| *Supported query type* | Read and write | Read and write | Read only + +|=== diff --git a/modules/ROOT/pages/planning-and-tuning/runtimes/index.adoc b/modules/ROOT/pages/planning-and-tuning/runtimes/index.adoc new file mode 100644 index 000000000..4212c16d5 --- /dev/null +++ b/modules/ROOT/pages/planning-and-tuning/runtimes/index.adoc @@ -0,0 +1,13 @@ +:description: Overview page for the Cypher runtimes chapter += Cypher runtimes + +The runtime is the final step of a Cypher query, where query plans received from the planner are executed as quickly and efficiently as possible. + +Cypher has three available runtimes: slotted, pipelined, and parallel. +Though the default runtime generally provides the best performance, there are situations when deciding which runtime to use is an important part of maximizing the efficiency of queries. +It is, therefore, important for advanced users to understand the different runtimes offered by Neo4j. + +This chapter contains the following sections: + +* xref::planning-and-tuning/runtimes/concepts.adoc[] - a deep-dive into the concepts behind Cypher runtimes. +* xref::planning-and-tuning/runtimes/reference.adoc[] - information about queries, configuration settings, and using the parallel runtime on Aura. \ No newline at end of file diff --git a/modules/ROOT/pages/planning-and-tuning/runtimes/reference.adoc b/modules/ROOT/pages/planning-and-tuning/runtimes/reference.adoc new file mode 100644 index 000000000..bf4d8ffdd --- /dev/null +++ b/modules/ROOT/pages/planning-and-tuning/runtimes/reference.adoc @@ -0,0 +1,236 @@ +:description: reference material for the parallel runtime. += Parallel runtime: reference + +_The parallel runtime was introduced in Neo4j 5.13._ + +The parallel runtime behaves differently compared to the slotted and pipelined runtimes in several regards. +This page explains the relevant configuration settings for the parallel runtime and the scenarios in which it is either not supported or considered thread-safe. +It also includes relevant information for Neo4j Aura users. + +Readers not familiar with the parallel runtime are encouraged to read about the xref:planning-and-tuning/runtimes/concepts.adoc#runtimes-parallel-runtime[parallel runtime concepts] before reading this page. + +[[updating-queries]] +== Updating queries + +The parallel runtime will throw an error if a query attempts to update the graph. +For example, any query run on the parallel runtime which uses the `CREATE` clause, will throw the following error: + +.Error message +[source, error] +---- +The parallel runtime does not support updating queries. Please use another runtime. +---- + +For a full list of all available Cypher write clauses, see the xref:clauses/index.adoc#writing-clauses[Clauses overview page]. + +[[transactions]] +== Transactions + +It is not possible to use the parallel runtime if a change has been made to the state of a transaction. + +For example, the following transaction (initiated on link:{neo4j-docs-base-uri}/operations-manual/{page-version}/tools/cypher-shell[Cypher Shell]) will be rolled back, because executing a Cypher query will make changes to the state of a transaction. + +.Step 1: Initiate a new transaction and change its state by creating a node +[source, cypher, role=test-skip] +---- +:begin +CREATE (n:Person) +---- + +.Step 2: Attempt to execute a Cypher query with the parallel runtime on the existing transaction +[source, cypher, role=test-fail] +---- +CYPHER runtime = parallel +RETURN 42 +---- + +.Error message +[source, error] +---- +An error occurred while in an open transaction. The transaction will be rolled back and terminated. Error: The parallel runtime is not supported if there are changes in the transaction state. Use another runtime. +---- + +For more information about transactions in Neo4j, see the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-internals/transaction-management[Operations Manual -> Transaction management]. + +[[configuration-settings]] +== Configuration settings + +The following setting can be configured to modify the behavior of the parallel runtime: + +.server.cypher.parallel.worker_limit +[frame="topbot", stripes=odd, grid="cols", cols="<1s,<4", role=noheader] +|=== +|Description +a|Number of threads to allocate to Cypher worker threads for the parallel runtime. +If set to a positive number, that number of workers will be started. +If set to `0`, one worker will be started for every logical processor available to the Java Virtual Machine. + +If set to a negative number we will subtract the value from the number of logical processors available; for example, say Neo4j is running on a server with 16 available processors, using `server.cypher.parallel.worker_limit = -1` would then mean that 15 threads are available for the parallel runtime. +|Valid values +a| Integer +|Default value +m| 0 +|=== + +Setting `server.cypher.parallel.worker_limit` to a negative number `-n` where `n` is greater than the total number of cores will disable the parallel runtime. + +For more information about configuration settings in Neo4j, see the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration[Operations Manual -> Configuration.] + +[[aura]] +== Aura + +The parallel runtime can only be run on Aura instances with 3 or more CPUs. +This means that the parallel runtime is not available to users to users of AuraDB Free. +Nor is it available on instances of AuraDB Professional and AuraDB Enterprise with 2 or fewer CPUs. + +Attempting to run a query with the parallel runtime on instances with 2 or fewer CPUs will generate the following error message: + +.Error message +[source,error] +---- +Parallel runtime has been disabled, please enable it or upgrade to a bigger Aura instance. +---- + +[TIP] +==== +Users of AuraDB Professional and AuraDB Enterprise select the number of available CPUs when creating an instance. +More information about the various tiers of AuraDB can be found on the link:https://neo4j.com/pricing/[Neo4j Pricing page]. +==== + +[[procedures-and-functions]] +== Procedures and functions + +Procedures and functions that read the database are supported by the parallel runtime. +Apart from this, there are two categories of procedures and functions to keep in mind when using the parallel runtime. + +The first can be categorized as _updating procedures_. +These are procedures that update the graph with write queries, such as the Neo4j procedures link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_createlabel[db.createLabel] and link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_createproperty[db.createProperty]. +If such procedures are called in a query run on the parallel runtime, the query will fail. + +The second can be categorized as _non-thread-safe_ procedures and functions. +These are procedures and functions which perform tasks that are not protected against multiple worker threads concurrently interacting with the targeted data. +This includes procedures and functions that perform either of the following tasks: + +* Executes a Cypher query (because that will start a new transaction, which is not supported by the parallel runtime). +* Starts a new transaction (because this is not supported by the parallel runtime). + +Calling procedures which perform any of these tasks in a query run on the parallel runtime will not fail the query. +Instead the query will automatically run on the pipelined runtime. + +[[neo4j-procedures]] +=== Neo4j procedures + +The following Neo4j procedures are not considered thread-safe and cannot be run on the parallel runtime. +Trying to call them in a query run on the parallel runtime will not fail the query. +Instead the query will automatically run on the pipelined runtime. + +.Non-thread-safe Neo4j procedures +[cols="1", options="header", cols="1m"] +|=== + +| Procedure + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_awaitindex[db.awaitIndex] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_awaitindexes[db.awaitIndexes] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_checkpoint[db.checkpoint] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_info[db.info] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_labels[db.labels] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_listlocks[db.listLocks] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_ping[db.ping] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_propertykeys[db.propertyKeys] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_prepareforreplanning[db.prepareForReplanning] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_relationshiptypes[db.relationshipTypes] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_resampleindex[db.resampleIndex] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_resampleoutdatedindexes[db.resampleOutdatedIndexes] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_schema_nodetypeproperties[db.schema.nodeTypeProperties] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_schema_reltypeproperties[db.schema.relTypeProperties] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_db_schema_visualization[db.schema.visualization] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_dbms_checkconfigvalue[dbms.checkConfigValue] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_dbms_listactivelocks[dbms.listActiveLocks] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_dbms_listpools[dbms.listPools] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_dbms_scheduler_failedjobs[dbms.scheduler.failedJobs] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_dbms_scheduler_groups[dbms.scheduler.groups] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_dbms_scheduler_jobs[dbms.scheduler.jobs] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_dbms_upgrade[dbms.upgrade] + +| link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/#procedure_dbms_upgradestatus[dbms.upgradeStatus] + +|=== + +[[apoc]] +=== APOC + +The link:{neo4j-docs-base-uri}/apoc/{page-version}/[APOC library] contains procedures and functions which extend the use of Cypher. +There are a number of APOC procedures and functions that are not considered thread-safe, and *cannot* be run on the parallel runtime. +For information about these, refer to the pages of the individual link:{neo4j-docs-base-uri}/apoc/{page-version}/overview/[procedures and functions] in the APOC Manual. + +[[user-defined-functions]] +=== User-defined functions + +User-defined functions are simpler forms of procedures that return a single value and are read-only. +To learn more about user-defined functions in Neo4j, see the link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/functions/[Java Reference Manual -> User-defined functions]. + +Similar to Neo4j and APOC procedures, any user-defined function that starts a new transaction by executing a Cypher query is not considered thread-safe and will not be supported by the parallel runtime (this includes all user-defined aggregating functions). + +For example, consider the two following user-defined functions: + +[source,java] +---- +class MyFunctions { + @Context + public Transaction transaction; + + @UserFunction("examples.return42") + public long return42() { + return 42L; + } + + @UserFunction("examples.return42ViaCypher") + public long return42ViaCypher() { + return (long) transaction.execute("RETURN 42 AS res").next().get("n); + } +} +---- + +Running `examples.return42()` will succeed with the parallel runtime, whereas `examples.return42ViaCypher()` will fail because executing a new Cypher query will start a new transaction. + +However, if `@NotThreadSafe` is added to the method, then the query will automatically not run on the parallel runtime. The query will instead default to the single-threaded pipelined runtime and generate a notification. + +Calling the below user-defined function would, therefore, not fail with the parallel runtime. +Instead, the Cypher query would automatically be run on the pipelined runtime. + +[source,java] +---- +class MyFunctions { + @Context + public Transaction transaction; + + @UserFunction("examples.return42ViaCypher") + @NotThreadSafe + public long return42ViaCypher() { + return (long) transaction.execute("RETURN 42 AS res").next().get("n); + } +} +---- + diff --git a/modules/ROOT/pages/query-tuning/query-profile.adoc b/modules/ROOT/pages/query-tuning/query-profile.adoc deleted file mode 100644 index 5dbf48eb4..000000000 --- a/modules/ROOT/pages/query-tuning/query-profile.adoc +++ /dev/null @@ -1,25 +0,0 @@ -:description: Profile a query; analyze a query by looking at its execution plan. - -[[profile-a-query]] -= Profile a query - -There are two options to choose from when you want to analyze a query by looking at its execution plan: - -`EXPLAIN`:: -If you want to see the execution plan but not run the statement, prepend your Cypher statement with `EXPLAIN`. -The statement will always return an empty result and make no changes to the database. - -`PROFILE`:: -If you want to run the statement and see which operators are doing most of the work, use `PROFILE`. -This will run your statement and keep track of how many rows pass through each operator, and how much each operator needs to interact with the storage layer to retrieve the necessary data. -Note that _profiling your query uses more resources,_ so you should not profile unless you are actively working on a query. - -See xref::execution-plans/index.adoc[] for a detailed explanation of each of the operators contained in an execution plan. - -[TIP] -==== -Being explicit about what types and labels you expect relationships and nodes to have in your query helps Neo4j use the best possible statistical information, which leads to better execution plans. -This means that when you know that a relationship can only be of a certain type, you should add that to the query. -The same goes for labels, where declaring labels on both the start and end nodes of a relationship helps Neo4j find the best way to execute the statement. -==== - diff --git a/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc b/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc index 7f5278b31..f4f52b5e5 100644 --- a/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc +++ b/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc @@ -73,9 +73,8 @@ For more details, see xref::values-and-types/working-with-null.adoc[working with The table below shows the types and their syntactic synonyms. -These types (and their synonyms) can be used in xref::syntax/expressions.adoc#type-predicate-expressions[type predicate expressions] and in xref::constraints/examples.adoc#constraints-examples-node-property-type[node] and xref::constraints/examples.adoc#constraints-examples-relationship-property-type[relationship] property type constraints. +These types (and their synonyms) can be used in xref::values-and-types/type-predicate.adoc[type predicate expressions] and in xref::constraints/examples.adoc#constraints-examples-node-property-type[node] and xref::constraints/examples.adoc#constraints-examples-relationship-property-type[relationship] property type constraints. They are also returned as a `STRING` value when using the xref::functions/scalar.adoc#functions-valueType[valueType()] function. - However, not all types can be used in all places. [.synonyms, opts="header", cols="2a,2a"] @@ -107,6 +106,59 @@ However, not all types can be used in all places. All Cypher types contain the `null` value. To make them not nullable, `NOT NULL` can be appended to the end of the type (e.g. `BOOLEAN NOT NULL`, `LIST`). Note that closed dynamic types (`INNER_TYPE_1 | INNER_TYPE_2...`) cannot be appended with `NOT NULL`: all inner types must be nullable, or all appended with `NOT NULL`. +[[type-normalization]] +== Type Normalization + +Cypher runs a normalization algorithm on all input types, simplifying the given type to a deterministic representation for equivalent types. +Types are simplified to their default name (e.g. `BOOL` is simplified to `BOOLEAN`). +Encompassing types are absorbed (e.g. `LIST | LIST` is normalized to `LIST`). +Types are also xref:values-and-types/property-structural-constructed.adoc#ordering-of-types[ordered]. + +The type `PROPERTY VALUE` is expanded to a closed dynamic union of all valid property types, and if all types are represented, then the normalization would simplify to `ANY`. + +For example, given the closed dynamic type `BOOL | LIST | BOOLEAN | LIST`, the normalized type would be: `BOOLEAN | LIST`. + +This normalization is run on types used in xref::values-and-types/type-predicate.adoc[type predicate expressions], and in xref::constraints/examples.adoc#constraints-examples-node-property-type[node] and xref::constraints/examples.adoc#constraints-examples-relationship-property-type[relationship] property type constraints. +Type normalization is also used to ensure the consistency of the output for the xref::functions/scalar.adoc#functions-valueType[valueType()] function. + +[[ordering-of-types]] +=== Ordering of types +The ordering of types is as follows: + + * Predefined types + ** `NOTHING` + ** `NULL` + ** `BOOLEAN` + ** `STRING` + ** `INTEGER` + ** `FLOAT` + ** `DATE` + ** `LOCAL TIME` + ** `ZONED TIME` + ** `LOCAL DATETIME` + ** `ZONED DATETIME` + ** `DURATION` + ** `POINT` + ** `NODE` + ** `RELATIONSHIP` + * Constructed types + ** `MAP` + ** `LIST` (ordered by the inner type) + ** `PATH` + * Dynamic union types + ** `INNER_TYPE_1 \| INNER_TYPE_2...` (ordered by specific rules for closed dynamic union type) + ** `ANY` + +Subtypes are always ordered before any enclosing types (e.g. `LIST` is ordered before `LIST`). +This also means that the `NOT NULL` variants of each type comes before the nullable variant. + +The order between two closed dynamic unions `A` and `B` is determined as followed: + + * If `A` has fewer inner types than `B`, `A` is ordered first. + * If `A` and `B` have the same number of inner types, they are ordered according to the order of the first inner type that differ (lexicographic order). + +The resulting order is deterministic. + == Property type details The below table provides more detailed information about the various property types that Cypher supports. diff --git a/modules/ROOT/pages/values-and-types/spatial.adoc b/modules/ROOT/pages/values-and-types/spatial.adoc index 243f7e5d7..efe24e20a 100644 --- a/modules/ROOT/pages/values-and-types/spatial.adoc +++ b/modules/ROOT/pages/values-and-types/spatial.adoc @@ -255,9 +255,9 @@ RETURN If there is a RANGE or POINT index on a particular node or relationship property, and a spatial point is assigned to that property on a node or relationship, the node or relationship will be indexed. -In a POINT index, Neo4j uses space filling curves in 2D or 3D over an underlying generalized B+Tree. This index has support for xref::query-tuning/indexes.adoc#administration-indexes-equality-check-using-where-single-property-index[equality], xref::query-tuning/indexes.adoc#administration-indexes-spatial-distance-searches-single-property-index[distance], and xref::query-tuning/indexes.adoc#administration-indexes-spatial-bounding-box-searches-single-property-index[bounding box] queries. +In a POINT index, Neo4j uses space filling curves in 2D or 3D over an underlying generalized B+Tree. This index has support for xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-equality-check-using-where-single-property-index[equality], xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-spatial-distance-searches-single-property-index[distance], and xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-spatial-bounding-box-searches-single-property-index[bounding box] queries. -In a RANGE index, the points will be sorted according to their lexicographic ordering per coordinate reference system. For point values, this index has support for xref::query-tuning/indexes.adoc#administration-indexes-equality-check-using-where-single-property-index[equality]. +In a RANGE index, the points will be sorted according to their lexicographic ordering per coordinate reference system. For point values, this index has support for xref::planning-and-tuning/query-tuning/indexes.adoc#administration-indexes-equality-check-using-where-single-property-index[equality]. [[spatial-values-comparability-orderability]] == Comparability and orderability