diff --git a/antora.yml b/antora.yml index a4d5049ed..67e3512a8 100644 --- a/antora.yml +++ b/antora.yml @@ -7,5 +7,5 @@ nav: asciidoc: attributes: neo4j-version: '5' - neo4j-version-minor: '5.5' - neo4j-version-exact: '5.5.0' + neo4j-version-minor: '5.6' + neo4j-version-exact: '5.6.0' diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index e3a260fbd..a2063f57c 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -6,6 +6,7 @@ ** xref:introduction/transactions.adoc[] ** xref:introduction/uniqueness.adoc[] ** xref:introduction/clause_composition.adoc[] +** xref:introduction/aura.adoc[] * xref:syntax/index.adoc[] ** xref:syntax/values.adoc[] @@ -46,6 +47,7 @@ ** xref:clauses/load-csv.adoc[] ** xref:clauses/listing-functions.adoc[] ** xref:clauses/listing-procedures.adoc[] +** xref:clauses/listing-settings.adoc[] ** xref:clauses/transaction-clauses.adoc#query-listing-transactions[SHOW TRANSACTIONS] ** xref:clauses/transaction-clauses.adoc#query-terminate-transactions[TERMINATE TRANSACTIONS] diff --git a/modules/ROOT/images/graph_expression_subqueries.svg b/modules/ROOT/images/graph_expression_subqueries.svg index b037298a9..0b116c781 100644 --- a/modules/ROOT/images/graph_expression_subqueries.svg +++ b/modules/ROOT/images/graph_expression_subqueries.svg @@ -3,117 +3,119 @@ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> - - - -L - + + + +H + Andy - -Swedish, Person - -age = 36 -name = 'Andy' + +Swedish, Person + +age = 36 + name = 'Andy' - + -DogAndy - -Dog - -name = 'Andy' +AndyDog + +Dog + +name = 'Andy' - + -Andy->DogAndy - - -  HAS_DOG -since = 2016 +Andy->AndyDog + + +HAS_DOG +  since = 2016 Timothy - -Person - -age = 25 -name = 'Timothy' + +Person + +age = 25 + name = 'Timothy' + nickname = 'Tim' - + Mittens - -Cat - -name = 'Mittens' + +Cat + +name = 'Mittens' - + Timothy->Mittens - - -  HAS_CAT -since = 2019 + + +HAS_CAT +  since = 2019 Peter - -Person - -age = 35 -name = 'Peter' + +Person + +age = 25 + name = 'Peter' + nickname = 'Pete' - + Ozzy - -Dog - -name = 'Ozzy' + +Dog + +name = 'Ozzy' - + Peter->Ozzy - - -  HAS_DOG -since = 2018 + + +HAS_DOG +  since = 2018 - + Fido - -Dog - -name = 'Fido' + +Dog + +name = 'Fido' - + Peter->Fido - - -  HAS_DOG -since = 2010 + + +HAS_DOG +  since = 2010 - + Banana - -Toy - -name = 'Banana' + +Toy + +name = 'Banana' - + Fido->Banana - - -  HAS_TOY + + +  HAS_TOY diff --git a/modules/ROOT/images/privileges_grant_and_deny_syntax.png b/modules/ROOT/images/privileges_grant_and_deny_syntax.png deleted file mode 100644 index 6482f2d84..000000000 Binary files a/modules/ROOT/images/privileges_grant_and_deny_syntax.png and /dev/null differ diff --git a/modules/ROOT/images/privileges_grant_and_deny_syntax_database_privileges.png b/modules/ROOT/images/privileges_grant_and_deny_syntax_database_privileges.png deleted file mode 100644 index 9f9d72486..000000000 Binary files a/modules/ROOT/images/privileges_grant_and_deny_syntax_database_privileges.png and /dev/null differ diff --git a/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.png b/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.png deleted file mode 100644 index 6f55e7829..000000000 Binary files a/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.png and /dev/null differ diff --git a/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.svg b/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.svg index 63e06b2a5..b929a580d 100644 --- a/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.svg +++ b/modules/ROOT/images/privileges_grant_and_deny_syntax_dbms_privileges.svg @@ -1,9 +1 @@ - - - - - - - - - + \ No newline at end of file diff --git a/modules/ROOT/images/privileges_hierarchy.png b/modules/ROOT/images/privileges_hierarchy.png deleted file mode 100644 index 3d6db6187..000000000 Binary files a/modules/ROOT/images/privileges_hierarchy.png and /dev/null differ diff --git a/modules/ROOT/images/privileges_hierarchy_database.png b/modules/ROOT/images/privileges_hierarchy_database.png deleted file mode 100644 index 554f25334..000000000 Binary files a/modules/ROOT/images/privileges_hierarchy_database.png and /dev/null differ diff --git a/modules/ROOT/images/privileges_hierarchy_dbms.png b/modules/ROOT/images/privileges_hierarchy_dbms.png deleted file mode 100644 index 0f7d2a7a5..000000000 Binary files a/modules/ROOT/images/privileges_hierarchy_dbms.png and /dev/null differ diff --git a/modules/ROOT/images/privileges_hierarchy_dbms.svg b/modules/ROOT/images/privileges_hierarchy_dbms.svg index 3cffcbd45..705c3fd5d 100644 --- a/modules/ROOT/images/privileges_hierarchy_dbms.svg +++ b/modules/ROOT/images/privileges_hierarchy_dbms.svg @@ -1,14 +1 @@ - - - - - - - - - - - - - - + \ No newline at end of file diff --git a/modules/ROOT/images/privileges_on_graph_syntax.png b/modules/ROOT/images/privileges_on_graph_syntax.png deleted file mode 100644 index c70792be2..000000000 Binary files a/modules/ROOT/images/privileges_on_graph_syntax.png and /dev/null differ diff --git a/modules/ROOT/pages/access-control/dbms-administration.adoc b/modules/ROOT/pages/access-control/dbms-administration.adoc index 4c1964a63..65f15513d 100644 --- a/modules/ROOT/pages/access-control/dbms-administration.adoc +++ b/modules/ROOT/pages/access-control/dbms-administration.adoc @@ -55,6 +55,8 @@ 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; ---- //// @@ -1953,82 +1955,88 @@ a|Rows: 2 |=== ====== -[[access-control-name-globbing]] -=== Procedure and user-defined function name-globbing -The name-globbing for procedure and user defined function 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. +[[access-control-dbms-administration-setting]] +== The DBMS `SETTING` privileges + +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::access-control/dbms-administration.adoc#access-control-name-globbing[name-globbing]. + [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%`++` but not `++mine.procedure`With%`++`. -It is also good to keep in mind that wildcard characters behave as wildcards even when escaped. -As an example, using `++`*`++` is equivalent to using `+*+`, and thus allows executing all functions or procedures and not only the procedure or function named `+*+`. +The syntax descriptions use xref:access-control/index.adoc#access-control-syntax[the style] from access control. ==== -The examples below only use procedures, but the same rules apply to user defined function names: - -* `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` +.Setting privileges command syntax +[options="header", width="100%", cols="3a,2"] +|=== +| Command +| Description -[source, cypher, role=noplay] ----- -GRANT EXECUTE PROCEDURE * ON DBMS TO globbing1 ----- +| [source, syntax, role=noheader] +GRANT [IMMUTABLE] SHOW SETTING[S] name-globbing[, ...] + ON DBMS + TO role[, ...] +| Enables the specified roles to query given configuration settings. +|=== -Users with the role `globbing1` can thus run all the procedures. +The following query shows an example of how to grant this privilege: [source, cypher, role=noplay] ---- -GRANT EXECUTE PROCEDURE mine.*.exampleProcedure ON DBMS TO globbing2 +GRANT SHOW SETTING server.bolt.* ON DBMS TO configurationViewer ---- -Users with the role `globbing2` can thus run procedures `mine.public.exampleProcedure` and `mine.private.exampleProcedure`, but none of the others. +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] ---- -GRANT EXECUTE PROCEDURE mine.*.exampleProcedure? ON DBMS TO globbing3 +SHOW ROLE configurationViewer PRIVILEGES AS COMMANDS ---- -Users with the role `globbing3` can thus run procedures `mine.public.exampleProcedure1`, `mine.private.exampleProcedure1` and `mine.private.exampleProcedure2`, but none of the others. +.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 EXECUTE PROCEDURE *.exampleProcedure ON DBMS TO globbing4 +GRANT SHOW SETTINGS * ON DBMS TO deniedConfigurationViewer ---- -Users with the role `globbing4` can thus run procedures `your.exampleProcedure`, `mine.public.exampleProcedure` and `mine.private.exampleProcedure`, but none of the others. - [source, cypher, role=noplay] ---- -GRANT EXECUTE PROCEDURE mine.public.exampleProcedure* ON DBMS TO globbing5 +DENY SHOW SETTING dbms.security* ON DBMS TO deniedConfigurationViewer ---- -Users with the role `globbing5` can thus run procedures `mine.public.exampleProcedure`, `mine.public.exampleProcedure1` and `mine.public.exampleProcedure42`, but none of the others. +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] ---- -GRANT EXECUTE PROCEDURE `mine.public.with#*§Characters`, mine.private.`with#Spec???§Characters` ON DBMS TO globbing6 +SHOW ROLE deniedConfigurationViewer PRIVILEGES AS COMMANDS ---- -Users with the role `globbing6` can thus run procedures `mine.public.with#Special§Characters` and `mine.private.with#Special§Characters`, but none of the others. +.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 +|=== -[NOTE] -==== -The name-globbing may be fully or partially escaped. -Both `+*+` and `+?+` are interpreted as wildcards either way. -==== +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]] @@ -2043,6 +2051,7 @@ The right to perform the following privileges can be achieved with a single comm * Show, assign, and remove privileges. * Execute all procedures with elevated privileges. * Execute all user defined functions with elevated privileges. +* Show all configuration settings. [NOTE] ==== @@ -2077,3 +2086,85 @@ SHOW ROLE dbmsManager PRIVILEGES AS COMMANDS |"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/access-control/manage-servers.adoc b/modules/ROOT/pages/access-control/manage-servers.adoc index eda562dd9..1a87b8ec6 100644 --- a/modules/ROOT/pages/access-control/manage-servers.adoc +++ b/modules/ROOT/pages/access-control/manage-servers.adoc @@ -319,6 +319,10 @@ This may not be specified in combination with `deniedDatabases`. | list of database names | 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 +| List of server tags used during database allocation and for load balancing and routing policies. |=== [NOTE] @@ -327,6 +331,11 @@ 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 @@ -356,6 +365,10 @@ This may not be specified in combination with `deniedDatabases`. | list of database names | 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 +| List of server tags used during database allocation and for load balancing and routing policies. |=== [NOTE] @@ -364,6 +377,12 @@ 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 diff --git a/modules/ROOT/pages/clauses/index.adoc b/modules/ROOT/pages/clauses/index.adoc index 723b6a99b..2bcb03ad5 100644 --- a/modules/ROOT/pages/clauses/index.adoc +++ b/modules/ROOT/pages/clauses/index.adoc @@ -32,6 +32,17 @@ m| xref::constraints/syntax.adoc[CREATE \| DROP CONSTRAINT] |=== +[[configuration-commands]] +== Configuration Commands + +[options="header"] +|=== +| Clause | Description + +m| xref:clauses/listing-settings.adoc[SHOW SETTINGS] +| List configuration settings. + +|=== [[importing-clauses]] == Importing data @@ -247,7 +258,6 @@ m| xref:clauses/transaction-clauses.adoc#query-terminate-transactions[TERMINATE |=== - [[writing-clauses]] == Writing clauses diff --git a/modules/ROOT/pages/clauses/listing-settings.adoc b/modules/ROOT/pages/clauses/listing-settings.adoc new file mode 100644 index 000000000..16c51d2a6 --- /dev/null +++ b/modules/ROOT/pages/clauses/listing-settings.adoc @@ -0,0 +1,271 @@ +:description: This section explains the `SHOW SETTINGS` command. + +[[query-listing-settings]] += SHOW SETTINGS + +[abstract] +-- +This section explains the `SHOW SETTINGS` command. +-- + +Listing the configuration settings on a server can be done with `SHOW SETTINGS`. + +[NOTE] +==== +The command `SHOW SETTINGS` returns settings on the executing server only. +To retrieve settings on a specific server, you need to directly connect to it using `bolt` scheme. +==== + +[NOTE] +==== +The command `SHOW SETTINGS` returns only the default output. +For a full output use the optional `YIELD` command. +Full output: `SHOW SETTINGS YIELD *`. +==== + +The `SHOW SETTINGS` command will produce a table with the following columns: + + +.Show settings output +[options="header", cols="4,6"] +|=== +| Column | Description + +m| name +a| The name of the setting. label:default-output[] + +m| value +a| The current value of the setting. label:default-output[] + +m| isDynamic +a| +Whether the value of the setting can be updated dynamically, without restarting the server. +For dynamically updating a setting value, see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/dynamic-settings/[Update dynamic settings]. +label:default-output[] + +m| defaultValue +a| The default value of the setting. label:default-output[] + +m| description +a| The setting description. label:default-output[] + +m| startupValue +a| The value of the setting at last startup. + +m| isExplicitlySet +a| Whether the value of the setting is explicitly set by the user, either through configuration or dynamically. + +m| validValues +a| A description of valid values for the setting. + +|=== + + +== Syntax + +[NOTE] +==== +The syntax descriptions use xref:access-control/index.adoc#access-control-syntax[the style] from access control. +==== + +List settings:: + +[source, syntax, role="noheader"] +---- +SHOW SETTING[S] [setting-name[,...]] +[YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] +[WHERE expression] +[RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] +---- + +Setting names must be supplied as one or more comma-separated quoted strings or as an expression resolving to a string or a list of strings. + +[NOTE] +==== +When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. +==== + +== Listing all settings + +To list all settings with the default output columns, the `SHOW SETTINGS` command can be used. +If all columns are required, use `SHOW SETTINGS YIELD *`. + + +.Query +[source, cypher, role=test-result-skip] +---- +SHOW SETTINGS +---- + +.Result +[role="queryresult",options="header,footer",cols="2m,1m,1m,1m,3m"] +|=== +| +name+ | +value+ | +isDynamic+ | +defaultValue+ | +description+ + +| +"browser.allow_outgoing_connections"+ +| +"true"+ +| +false+ +| +"true"+ +| +"Configure the policy for outgoing Neo4j Browser connections."+ + +| +"browser.credential_timeout"+ +| +"0s"+ +| +false+ +| +"0s"+ +| +"Configure the Neo4j Browser to time out logged in users after this idle period. Setting this to 0 indicates no limit."+ + +| +"browser.post_connect_cmd"+ +| +""+ +| +false+ +| +""+ +| +"Commands to be run when Neo4j Browser successfully connects to this server. Separate multiple commands with semi-colon."+ + +| +"browser.remote_content_hostname_whitelist"+ +| +"guides.neo4j.com,localhost"+ +| +false+ +| +"guides.neo4j.com,localhost"+ +| +"Whitelist of hosts for the Neo4j Browser to be allowed to fetch content from."+ + +| +"browser.retain_connection_credentials"+ +| +"true"+ +| +false+ +| +"true"+ +| +"Configure the Neo4j Browser to store or not store user credentials."+ + +| +"browser.retain_editor_history"+ +| +"true"+ +| +false+ +| +"true"+ +| +"Configure the Neo4j Browser to store or not store user editor history."+ + +| +"client.allow_telemetry"+ +| +"true"+ +| +false+ +| +"true"+ +| +"Configure client applications such as Browser and Bloom to send Product Analytics data."+ + +| +"db.checkpoint"+ +| +"PERIODIC"+ +| +false+ +| +"PERIODIC"+ +| +"Configures the general policy for when check-points should occur. The default policy is the 'periodic' check-point policy, as specified by the 'db.checkpoint.interval.tx' and 'db.checkpoint.interval.time' settings. The Neo4j Enterprise Edition provides two alternative policies: The first is the 'continuous' check-point policy, which will ignore those settings and run the check-point process all the time. The second is the 'volumetric' check-point policy, which makes a best-effort at check-pointing often enough so that the database doesn't get too far behind on deleting old transaction logs in accordance with the 'db.tx_log.rotation.retention_policy' setting."+ + +| +"db.checkpoint.interval.time"+ +| +"15m"+ +| +false+ +| +"15m"+ +| +"Configures the time interval between check-points. The database will not check-point more often than this (unless check pointing is triggered by a different event), but might check-point less often than this interval, if performing a check-point takes longer time than the configured interval. A check-point is a point in the transaction logs, which recovery would start from. Longer check-point intervals typically mean that recovery will take longer to complete in case of a crash. On the other hand, a longer check-point interval can also reduce the I/O load that the database places on the system, as each check-point implies a flushing and forcing of all the store files."+ + +| +"db.checkpoint.interval.tx"+ +| +"100000"+ +| +false+ +| +"100000"+ +| +"Configures the transaction interval between check-points. The database will not check-point more often than this (unless check pointing is triggered by a different event), but might check-point less often than this interval, if performing a check-point takes longer time than the configured interval. A check-point is a point in the transaction logs, which recovery would start from. Longer check-point intervals typically mean that recovery will take longer to complete in case of a crash. On the other hand, a longer check-point interval can also reduce the I/O load that the database places on the system, as each check-point implies a flushing and forcing of all the store files. The default is '100000' for a check-point every 100000 transactions."+ + +5+d|Rows: 10 +|=== + +The above table only displays the first 10 results of the query. +For a full list of all available settings in Neo4j, refer to link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/configuration-settings[Configuration settings]. + + +== Listing settings with filtering on output columns + +The listed settings can be filtered by using the `WHERE` clause. +For example, the following query returns the name, value, and description of all settings starting with 'dbms': + +.Query +[source, cypher] +---- +SHOW SETTINGS YIELD name, value, description +WHERE name STARTS WITH 'dbms' +RETURN name, value, description +LIMIT 10 +---- + +.Result +[role="queryresult",options="header,footer",cols="2m,1m,3m"] +|=== +| +name+ | +value+ | +description+ + +| +"dbms.cluster.catchup.client_inactivity_timeout"+ +| +"10m"+ +| +"The catch up protocol times out if the given duration elapses with no network activity. Every message received by the client from the server extends the time out duration."+ + +| +"dbms.cluster.discovery.endpoints"+ +| +"No Value"+ +| +"A comma-separated list of endpoints which a server should contact in order to discover other cluster members."+ + +| +"dbms.cluster.discovery.log_level"+ +| +"WARN"+ +| +"The level of middleware logging"+ + +| +"dbms.cluster.discovery.type"+ +| +"LIST"+ +| +"Configure the discovery type used for cluster name resolution"+ + +| +"dbms.cluster.minimum_initial_system_primaries_count"+ +| +"3"+ +| +"This setting has been moved to Cluster Base Settings"+ + +| +"dbms.cluster.network.handshake_timeout"+ +| +"20s"+ +| +"Time out for protocol negotiation handshake."+ + +| +"dbms.cluster.network.max_chunk_size"+ +| +"32768"+ +| +"Maximum chunk size allowable across network by clustering machinery."+ + +| +"dbms.cluster.network.supported_compression_algos"+ +| +""+ +| +"Network compression algorithms that this instance will allow in negotiation as a comma-separated list. Listed in descending order of preference for incoming connections. An empty list implies no compression. For outgoing connections this merely specifies the allowed set of algorithms and the preference of the remote peer will be used for making the decision. Allowable values: [Gzip, Snappy, Snappy_validating, LZ4, LZ4_high_compression, LZ_validating, LZ4_high_compression_validating]"+ + +| +"dbms.cluster.raft.binding_timeout"+ +| +"1d"+ +| +"The time allowed for a database on a Neo4j server to either join a cluster or form a new cluster with at least the quorum of the members available. The members are provided by `dbms.cluster.discovery.endpoints` for the system database and by the topology graph for user databases."+ + +| +"dbms.cluster.raft.client.max_channels"+ +| +"8"+ +| +"The maximum number of TCP channels between two nodes to operate the raft protocol. Each database gets allocated one channel, but a single channel can be used by more than one database."+ + +3+d|Rows: 10 +|=== + + + +== Listing specific settings + +It is possible to specify which settings to return in the list by setting names. + +.Query +[source, cypher] +---- +SHOW SETTINGS "server.bolt.enabled", "server.bolt.advertised_address", "server.bolt.listen_address" +---- + +.Result +[role="queryresult",options="header,footer",cols="2m,1m,1m,1m,3m"] +|=== +| +name+ | +value+ | +isDynamic+ | +defaultValue+ | +description+ + +| +"server.bolt.advertised_address"+ +| +"localhost:7687"+ +| +false+ +| +":7687"+ +| +"Advertised address for this connector"+ + +| +"server.bolt.enabled"+ +| +"true"+ +| +false+ +| +"true"+ +| +"Enable the bolt connector"+ + +| +"server.bolt.listen_address"+ +| +"localhost:7687"+ +| +false+ +| +":7687"+ +| +"Address the connector should bind to"+ + +5+d|Rows: 3 +|=== + diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index a1494ea62..f832259e2 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -10,6 +10,63 @@ 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.6]] +== Version 5.6 + + +=== New features + +[cols="2", options="header"] +|=== +| Feature +| Details + +a| +label:functionality[] +label:added[] +[source, cypher, role="noheader"] +---- +COLLECT { + ... +} +---- +a| + +New expression which returns the results of a subquery collected in a list. + + +a| +label:functionality[] +label:new[] +[source, cypher, role="noheader"] +---- +SHOW SETTING[S] [setting-name[,...]] +[YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] +[WHERE expression] +[RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] + +---- +a| + +List configuration settings on the current server. + +The `setting-name` is either a comma-separated list of one or more quoted strings or a single expression resolving to a string or a list of strings. + +a| +label:functionality[] +label:new[] + +New privilege: +[source, cypher, role="noheader"] +---- +SHOW SETTING[S] name-globbing[,...] +---- +a| + +New privilege that controls a user's access to desired configuration settings. + +|=== + + [[cypher-deprecations-additions-removals-5.5]] == Version 5.5 diff --git a/modules/ROOT/pages/execution-plans/operator-summary.adoc b/modules/ROOT/pages/execution-plans/operator-summary.adoc index 06762ad46..b7336675b 100644 --- a/modules/ROOT/pages/execution-plans/operator-summary.adoc +++ b/modules/ROOT/pages/execution-plans/operator-summary.adoc @@ -556,6 +556,12 @@ Tests for the absence of a pattern predicate if an expression predicate evaluate | | +| 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[] diff --git a/modules/ROOT/pages/execution-plans/operators.adoc b/modules/ROOT/pages/execution-plans/operators.adoc index f3ffb715e..ad876773f 100644 --- a/modules/ROOT/pages/execution-plans/operators.adoc +++ b/modules/ROOT/pages/execution-plans/operators.adoc @@ -5434,6 +5434,43 @@ Total database accesses: 0, total allocated memory: 64 ====== +[[query-plan-show-settings]] +== Show Settings +// ShowSettings + +The `ShowSettings` operator lists configuration settings. + +.ShowSettings +====== + +.Query +[source, cypher] +---- +PROFILE +SHOW SETTINGS +---- + +.Query Plan +[role="queryplan", subs="attributes+"] +---- +Planner COST + +Runtime SLOTTED + +Runtime version {neo4j-version-minor} + ++-----------------+---------------------------------------------------+----------------+------+---------+------------------------+ +| Operator | Details | Estimated Rows | Rows | DB Hits | Page Cache Hits/Misses | ++-----------------+---------------------------------------------------+----------------+------+---------+------------------------+ +| +ProduceResults | name, value, isDynamic, defaultValue, description | 10 | 264 | 0 | 0/0 | +| | +---------------------------------------------------+----------------+------+---------+------------------------+ +| +ShowSettings | allSettings, defaultColumns | 10 | 264 | 0 | 0/0 | ++-----------------+---------------------------------------------------+----------------+------+---------+------------------------+ + +Total database accesses: 0, total allocated memory: 64 +---- + +====== [[query-plan-show-transactions]] == Show Transactions diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 4db5dac8b..0eb155bf2 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -63,6 +63,12 @@ The ability to yield and filter the output from `TERMINATE TRANSACTIONS` has bee + For more information, see xref:deprecations-additions-removals-compatibility.adoc#_updated_features[Updated features list]. +* `SHOW SETTINGS` clause. ++ +You can now query configuration settings using `SHOW SETTINGS` clause. ++ +For more information, see xref:clauses/listing-settings.adoc[SHOW SETTINGS]. + * Changes to Neo4j indexes: + ** The B-tree index type has been removed. diff --git a/modules/ROOT/pages/introduction/aura.adoc b/modules/ROOT/pages/introduction/aura.adoc new file mode 100644 index 000000000..449df071e --- /dev/null +++ b/modules/ROOT/pages/introduction/aura.adoc @@ -0,0 +1,52 @@ += Aura and Cypher + +== Introduction + +Aura is Neo4j's fully managed cloud service. +It consists of AuraDB and AuraDS. +AuraDB is a graph database service for developers building intelligent applications, and AuraDS is a Graph Data Science (GDS) service for data scientists building predictive models and analytics workflows. + +AuraDB is available on the following tiers: + +* AuraDB Free +* AuraDB Pro +* AuraDB Enterprise + +For more information, see link:{neo4j-docs-base-uri}/aura/auradb[Aura docs - Neo4j AuraDB overview]. + +AuraDS is available on the following tiers: + +* AuraDS Pro +* AuraDS Enterprise + +For more information, see link:{neo4j-docs-base-uri}/aura/aurads[Aura docs - Neo4j AuraDS overview] + +== Using Cypher on Aura + +Most Cypher features are available on all tiers of Aura. +There are, however, some features which are not available to Aura instances. +For example, it is not possible to create, alter, or drop databases using Aura, nor is it possible to alter or drop servers. + +There are also certain Cypher features which are only available on AuraDB Enterprise instances. +These can be categorized as the role-based access-control features of Cypher. +For example, it is not possible to create, alter, or drop roles using AuraDB Free, AuraDB Pro, AuraDS Pro, or AuraDS Enterprise, but it is possible using AuraDB Enterprise. + +The Cypher Manual uses two different labels to differentiate this distinction: + +[options="header,cols=""2a,2a"] +|=== +| Label | Description +| label:not-on-aura[] | Cypher feature not available on any tier of Aura. +| label:aura-db-enterprise[] | Cypher feature only available on AuraDB Enterprise. +|=== + +//// +TODO: remove comment blocks once Aura Cheat Sheet has been published. + +== Aura and the Cypher Cheat Sheet + +Each different tier of Aura has a customized version of the Cypher Cheat Sheet which only shows the features of Cypher available for the chosen tier. + +The Aura Cheat Sheet can be accessed here: //Add url when available +Note that the default tier is AuraDB Enterprise. +//// diff --git a/modules/ROOT/pages/introduction/uniqueness.adoc b/modules/ROOT/pages/introduction/uniqueness.adoc index f25ebc999..bca12046c 100644 --- a/modules/ROOT/pages/introduction/uniqueness.adoc +++ b/modules/ROOT/pages/introduction/uniqueness.adoc @@ -8,7 +8,7 @@ Cypher path matching uses relationship isomorphism, the same relationship cannot be returned more than once in the same result record. -- -**Neo4j Cypher** makes use of **relationship isomorphism** for path matching and is a very effective way of reducing the result set size and preventing infinite traversals. +**Neo4j Cypher** makes use of **relationship isomorphism** for path matching, which is a very effective way of reducing the result set size and preventing infinite traversals. [NOTE] ==== diff --git a/modules/ROOT/pages/keyword-glossary.adoc b/modules/ROOT/pages/keyword-glossary.adoc index 32b98c840..e5dd0f0a9 100644 --- a/modules/ROOT/pages/keyword-glossary.adoc +++ b/modules/ROOT/pages/keyword-glossary.adoc @@ -205,6 +205,12 @@ Also allows `WHERE` and `YIELD` clauses. 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 | @@ -1508,6 +1514,10 @@ Optionally the account status and home database can also be set and if the user | DBMS | Determines whether the user can get information about servers. +| xref::access-control/dbms-administration.adoc#access-control-dbms-administration-setting[SHOW SETTINGS] +| DBMS +| Determines whether the user can get information about configuration settings. + | xref::access-control/database-administration.adoc#access-control-database-administration-transaction[SHOW TRANSACTION] | Database | Determines whether a user is allowed to list transactions and queries. diff --git a/modules/ROOT/pages/syntax/expressions.adoc b/modules/ROOT/pages/syntax/expressions.adoc index e6a3a16d9..f86089eeb 100644 --- a/modules/ROOT/pages/syntax/expressions.adoc +++ b/modules/ROOT/pages/syntax/expressions.adoc @@ -378,8 +378,8 @@ The following graph is used for the examples below: MATCH (n:A|B|C|D|E) DETACH DELETE n; CREATE (andy:Swedish:Person {name: 'Andy', age: 36}), -(timothy:Person {name: 'Timothy', age: 25}), -(peter:Person {name: 'Peter', age: 35}), +(timothy:Person {name: 'Timothy', nickname: 'Tim', age: 25}), +(peter:Person {name: 'Peter', nickname: 'Pete', age: 35}), (andy)-[:HAS_DOG {since: 2016}]->(:Dog {name:'Andy'}), (timothy)-[:HAS_CAT {since: 2019}]->(:Cat {name:'Mittens'}), (fido:Dog {name:'Fido'})<-[:HAS_DOG {since: 2010}]-(peter)-[:HAS_DOG {since: 2018}]->(:Dog {name:'Ozzy'}), @@ -863,6 +863,317 @@ RETURN person.name AS name |=== +[[collect-subqueries]] +=== `COLLECT` subqueries + +A `COLLECT` subquery expression can be used to create a list with the rows returned by a given subquery. + +Any non-writing query is allowed. +`COLLECT` subqueries differ from `COUNT` and `EXISTS` subqueries in that the final `RETURN` clause is mandatory. +The `RETURN` clause must return exactly one column. + +[[collect-subquery-simple-case]] +==== Simple `COLLECT` subquery + +Variables introduced by the outside scope can be used in the `COLLECT` subquery without importing them. +In this regard, `COLLECT` subqueries are different from `CALL` subqueries, xref::clauses/call-subquery.adoc#subquery-correlated-importing[which do require importing]. +The following query exemplifies this and outputs the owners of the dog named `Ozzy`: + +.Query +[source, cypher] +---- +MATCH (person:Person) +WHERE 'Ozzy' IN COLLECT { MATCH (person)-[:HAS_DOG]->(dog:Dog) RETURN dog.name } +RETURN person.name AS name +---- + +.Result +[role="queryresult",options="header,footer",cols="1*(dog:Dog) + WHERE r.since > 2017 + RETURN dog.name +} as youngDogs +---- + +.Result +[role="queryresult",options="header,footer",cols="2*(dog:Dog) + RETURN dog.name AS petName + UNION + MATCH (person)-[:HAS_CAT]->(cat:Cat) + RETURN cat.name AS petName + } AS petNames +---- + +.Result +[role="queryresult",options="header,footer",cols="2*(d:Dog {name: name}) + RETURN d.name +} as dogsOfTheYear +---- + +.Error message +[source, output, role="noheader"] +---- +The variable `name` is shadowing a variable with the same name from the outer scope and needs to be renamed (line 4, column 20 (offset: 92)) +---- + +New variables can be introduced into the subquery, as long as they use a different identifier. +In the below example, a `WITH` clause introduces a new variable. +Note that the outer scope variable `person` referenced in the main query is still available after the `WITH` clause. + +.Query +[source, cypher] +---- +MATCH (person:Person) +RETURN person.name AS name, COLLECT { + WITH 2018 AS yearOfTheDog + MATCH (person)-[r:HAS_DOG]->(d:Dog) + WHERE r.since = yearOfTheDog + RETURN d.name +} as dogsOfTheYear +---- + +.Result +[role="queryresult",options="header,footer",cols="2*(d:Dog) + MATCH (d)-[:HAS_TOY]->(t:Toy) + RETURN t.name + } as toyNames +---- + +.Result +[role="queryresult",options="header,footer",cols="2*(d:Dog) RETURN d.name } +RETURN person.dogNames as dogNames +---- + +.Result +[role="queryresult",options="header,footer",cols="1*(d:Dog) RETURN d.name } = [] THEN "No Dogs " + person.name + ELSE person.name + END AS result +---- + +.Result +[role="queryresult",options="header,footer",cols="1*(d:Dog) RETURN d.name } AS dogNames, + avg(person.age) AS averageAge + ORDER BY dogNames +---- + +.Result +[role="queryresult",options="header,footer",cols="2*()<--(c) ---- +=== Equijoins + +If a node variable is declared more than once in the query, this is called an _equijoin_. +This is an operation that requires each node pattern with the same node variable to be bound to the same node. +For example, the following pattern refers to the same node twice with the variable `a`, forming a cycle: +[source, role=noplay, indent=0] +---- +(a)-->(b)-->(c)-->(a) +---- + +The following pattern refers twice to the same node with the variable `b`, forming a T-shaped pattern: +[source, role=noplay, indent=0] +---- +(a)-->(b)-->(c), (b)-->(e) +---- [[cypher-pattern-label]] == Patterns for labels @@ -180,14 +195,20 @@ As with nodes, the name of the relationship can always be omitted, as exemplifie (a)-[:REL_TYPE]->(b) ---- -It is not possible to use the same name for a relationship multiple times within a pattern due to xref::introduction/uniqueness.adoc#relationship-isomorphism[relationship isomorphism]. +To specify additional constraints, introduce a xref::clauses/where.adoc#relationship-pattern-predicates[relationship pattern predicate]. + +=== Equijoins + +Similar to nodes, it is possible to use the same name for a relationship multiple times within a pattern. +However, due to xref::introduction/uniqueness.adoc#relationship-isomorphism[relationship isomorphism], this will not yield any results if done in the same pattern. +It can be useful across separate `MATCH` statements, though. .Relationship isomorphism ====== -Using the same variable name for relationships multiple times within a pattern is not allowed. +Using the same variable name for relationships multiple times in a query would require that particular relationship to be traversed several times. -The following example is therefore not allowed. +Therefore, the following example will lead to no results: [source, syntax] ---- @@ -196,8 +217,16 @@ The following example is therefore not allowed. ====== -You can specify additional constraints by introducing a xref::clauses/where.adoc#relationship-pattern-predicates[relationship pattern predicate]. +If, on the other hand, the two relationships are spread over two `MATCH`-clauses, then the relationship isomorphism does not pose an obstacle any longer. +The following query would, therefore, return results: +[source, syntax] +---- +MATCH ()-[r:REL_TYPE]-() +MATCH ()-[r:REL_TYPE]-() +---- + +Note, that the two instances of `r` refer to the same relationship. [[cypher-pattern-varlength]] == Variable-length pattern matching @@ -296,8 +325,71 @@ This is a typical example of finding first and second degree friends. Note that variable length relationships cannot be used with `CREATE` and `MERGE`. -Under certain circumstances variable length relationships can be planned with an optimisation, see xref::execution-plans/operators.adoc#query-plan-varlength-expand-pruning[VarLength Expand Pruning] query plan. +Under certain circumstances, variable-length relationships can be planned with an optimisation, see xref::execution-plans/operators.adoc#query-plan-varlength-expand-pruning[VarLength Expand Pruning] query plan. + +=== Equijoins + +Like simple relationships, the variable of variable-length relationships can be used more than once to refer to the same variable-length relationship. Just as with simple relationships, this yields no results if used in the same `MATCH` statement. + +In addition, the results must observe the bounds of both declarations of that variable. +In the following example, the bounds of `r` require it to be of length 2 and therefore only `'Anders'` is returned: + +.Query +[source, cypher, indent=0] +---- +MATCH (me {name: 'Filipa'})-[r:KNOWS*1..2]-(remote_friend) +MATCH ()-[r:KNOWS*2..3]-() +RETURN remote_friend.name +---- + +.Result +[role="queryresult",options="header,footer",cols="1*(me) +RETURN remote_friend.name +---- + +.Result +[role="queryresult",options="header,footer",cols="1*(me) +RETURN remote_friend.name +---- + +.Result +[role="queryresult",options="header,footer",cols="1*