SURF-768 Documentation for cardinality function

modules/ROOT/pages/appendix/gql-conformance/index.adoc

@@ -1,8 +1,8 @@
 :description: Overview of Cypher's conformance to GQL.
 = GQL conformance
 
-*Last updated*: 30 April 2026 +
-*Neo4j version*: 2026.04
+*Last updated*: 1 June 2026 +
+*Neo4j version*: 2026.06
 
 GQL is the new link:https://www.iso.org/home.html[ISO] International Standard query language for graph databases.
 

modules/ROOT/pages/appendix/gql-conformance/supported-optional.adoc

@@ -212,6 +212,15 @@ In Cypher, `ln(0)` returns `-Infinity` and `ln(negative)` returns `NaN`.
 | In GQL, `TRIM()` removes only space characters.
 In Cypher, `trim()` removes any whitespace character.
 
+| GF12
+| `CARDINALITY` function
+| xref:functions/scalar.adoc#functions-cardinality[`cardinality()`]
+| Cypher supports `CARDINALITY` for `LIST<ANY>`, `MAP`, and `PATH` values.
+For a list, the element count is returned (equivalent to xref:functions/scalar.adoc#functions-size[`size()`]).
+For a map, the key count is returned (equivalent to `size(keys(map))`).
+For a path, the total number of nodes and relationships is returned; for a non-empty path, `cardinality(p) = 2 * length(p) + 1`.
+Binding table reference values are not supported in Cypher.
+
 | GG01
 | Graph with open graph type
 |

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

@@ -52,6 +52,27 @@ For more information, see xref:clauses/search.adoc#vector-search-filtering-predi
 
 |===
 
+=== New in Cypher 25
+
+[cols="2", options="header"]
+|===
+| Feature
+| Details
+
+a|
+label:functionality[]
+label:new[]
+[source, cypher, role="noheader"]
+----
+RETURN cardinality([1, 2, 3]);
+RETURN cardinality({a: 1, b: 2});
+MATCH p = (a)-[r]->(b) RETURN cardinality(p);
+----
+| Introduction of the xref:functions/scalar.adoc#functions-cardinality[`cardinality()`] function.
+It returns the number of keys in a `MAP`, the number of elements in a `LIST<ANY>`, or the number of nodes and relationships in a `PATH`.
+
+|===
+
 [[cypher-deprecations-additions-removals-2026.05]]
 == Neo4j 2026.05
 

modules/ROOT/pages/functions/index.adoc

@@ -479,6 +479,10 @@ These functions return a single value.
 |===
 | Function | Signature | Description
 
+1.1+| xref::functions/scalar.adoc#functions-cardinality[`cardinality()`]
+| `cardinality(input :: MAP \| LIST<ANY> \| PATH) :: INTEGER`
+| Returns the number of keys in a `MAP`, the number of elements in a `LIST<ANY>`, or the number of nodes and relationships in a `PATH`. label:cypher[Cypher 25 only] label:new[Introduced in Neo4j 2026.06]
+
 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`.
@@ -487,7 +491,6 @@ These functions return a single value.
 | `character_length(input :: STRING) :: INTEGER`
 | Returns the number of Unicode characters in a `STRING`.
 
-
 1.1+| xref::functions/scalar.adoc#functions-coalesce[`coalesce()`]
 | `coalesce(input :: ANY) :: ANY`
 | Returns the first non-null value in a list of expressions.

modules/ROOT/pages/functions/scalar.adoc

@@ -30,6 +30,113 @@ CREATE
   (bob)-[:MARRIED]->(eskil)
 ----
 
+[role=label--new-Neo4j-2026.06 label--cypher-25-only]
+[[functions-cardinality]]
+== cardinality()
+
+.Details
+|===
+| *Syntax* 3+| `cardinality(input)`
+| *Description* 3+| Returns the number of keys in a `MAP`, the number of elements in a `LIST<ANY>`, or the number of nodes and relationships in a `PATH`.
+.2+| *Arguments* | *Name* | *Type* | *Description*
+| `input` | `MAP \| LIST<ANY> \| PATH` | A list, path or map whose cardinality is to be calculated.
+| *Returns* 3+| `INTEGER`
+|===
+
+.Considerations
+|===
+
+| `cardinality(null)` returns `null`.
+| For a `MAP`, `cardinality()` returns the same result as `size(keys(map))`.
+| For a `LIST<ANY>`, `cardinality()` returns the same result as xref:functions/scalar.adoc#functions-size[`size()`].
+| For a `LIST<ANY>`, only top-level elements are counted; nested lists count as a single element.
+| For a non-empty path, `cardinality(p) = 2 * length(p) + 1`.
+
+|===
+
+[NOTE]
+To calculate the length of a `PATH` as a relationship count only, use xref:functions/scalar.adoc#functions-length[`length()`] or xref:functions/scalar.adoc#functions-path-length[`path_length()`].
+
+.+cardinality() applied to lists+
+======
+
+.Query
+// tag::functions_scalar_cardinality_list[]
+[source, cypher, indent=0, role=test-skip]
+----
+RETURN cardinality([1, 2, 3]) AS result
+----
+// end::functions_scalar_cardinality_list[]
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+
+| result
+| 3
+1+d|Rows: 1
+
+|===
+
+The number of elements in the list is returned.
+
+======
+
+
+.+cardinality() applied to maps+
+======
+
+.Query
+// tag::functions_scalar_cardinality_map[]
+[source, cypher, indent=0, role=test-skip]
+----
+RETURN cardinality({a: 1, b: 2}) AS result,
+       cardinality({a: 1, b: 2}) = size(keys({a: 1, b: 2})) AS sameAsSizeKeys
+----
+// end::functions_scalar_cardinality_map[]
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+
+| result | sameAsSizeKeys
+| 2 | true
+2+d|Rows: 1
+
+|===
+
+The number of keys in the map is returned.
+
+======
+
+
+.+cardinality() applied to paths+
+======
+
+.Query
+// tag::functions_scalar_cardinality_path[]
+[source, cypher, indent=0, role=test-skip]
+----
+MATCH p = (a:Developer)-[:KNOWS]->(b:Administrator)
+WHERE a.name = 'Alice' AND b.name = 'Bob'
+RETURN cardinality(p) AS cardinality, length(p) AS length
+----
+// end::functions_scalar_cardinality_path[]
+
+The cardinality of the returned path is `3` (2 nodes and 1 relationship), while its length is `1` (for the single relationship traversed).
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+
+| cardinality | length
+| 3 | 1
+2+d|Rows: 1
+
+|===
+
+======
+
 
 [[functions-char_length]]
 == char_length()

modules/cheat-sheet/pages/scalar-functions.adoc

@@ -1,6 +1,13 @@
 = link:{neo4j-docs-base-uri}/cypher-manual/{page-version}/functions/scalar/[Scalar functions^]
 
 
+====
+include::ROOT:functions/scalar.adoc[tag=functions_scalar_cardinality_list]
+
+[.description]
+The link:{neo4j-docs-base-uri}/cypher-manual/{page-version}/functions/scalar/#functions-cardinality[`cardinality()`^] function returns the number of keys in a `MAP`, the number of elements in a `LIST<ANY>`, or the number of nodes and relationships in a `PATH`.
+====
+
 ====
 include::ROOT:functions/scalar.adoc[tag=functions_scalar_char_length]