Subclauses CIP

cip/1.accepted/CIP2017-03-01-LIMIT-subclause.adoc

@@ -0,0 +1,120 @@
+= CIP2017-03-01 - LIMIT subclause
+:numbered:
+:toc:
+:toc-placement: macro
+:source-highlighter: codemirror
+
+*Author:* Mats Rydberg <[email protected]>
+
+toc::[]
+
+== Background
+
+This CIP is a proposal in response to link:https://github.com/opencypher/openCypher/issues/194[CIR-2017-194].
+
+== Proposal
+
+The `LIMIT` subclause is used to constrain the cardinality of its parent clause by providing an upper limit.
+This can be useful for data exploration, or verifying partial results of expensive queries.
+
+=== Syntax
+
+.Syntax overview:
+[source, ebnf]
+----
+clause-with-limit = read-only-clause, [ limit ] ;
+read-only-clause  = match
+                  | with
+                  | unwind
+                  | return
+                  ;
+limit             = "LIMIT", expr ;
+----
+
+=== Semantics
+
+The `LIMIT` subclause prevents records passing through its parent clause after the specified amount of rows, as determined by the expression used as the argument to `LIMIT`, has been processed.
+For these semantics to be well defined, the limit expression must be constant over the query lifetime, such as parameters or literals.
+In other words, arbitrary expressions or variables are not valid, as the values of these may change across records, and it would not be clear which value should be used by the `LIMIT`.
+
+.Parameters and literals are global constants, and may be used as arguments to `LIMIT`:
+[source, cypher]
+----
+MATCH (a:Label)
+LIMIT $matchLimit
+RETURN a.prop
+LIMIT 100
+----
+
+.Variables and expressions involving variables are (in general) not constant, and may not be used as arguments to `LIMIT`:
+[source, cypher]
+----
+MATCH (a:Label)
+LIMIT a.prop // not guaranteed to be constant -- error!
+RETURN a.prop
+LIMIT size((a)-->()) // not guaranteed to be constant -- error!
+----
+
+==== Updating queries
+
+The use of `LIMIT` opens up the possibility for certain performance optimisations.
+Clauses appearing earlier in the query only need to be evaluated until the limit is reached, as opposed to evaluating the entire dataset.
+These optimisations are however not always applicable in combination with updating clauses.
+Semantics between clauses is defined such that _all_ of a previous clause is processed (logically) before _any_ of a subsequent clause is processed.
+This means that _all_ side effects must happen before a `LIMIT` is allowed to terminate the processing of records in preceding clauses.
+
+Consider the following query:
+
+.Create a producer for each item, returning the first 100 product ids.
+[source, cypher]
+----
+MATCH (i:Item)
+CREATE (i)-[:PRODUCED_BY]->(:Producer)
+RETURN i.productId
+LIMIT 100
+----
+
+This query must execute its `CREATE` clause once for every `:Item` node, even though only 100 records are to be returned.
+
+If the user intention is to only do a partial update of the graph, the query must be rewritten:
+
+.Create a producer for the top 100 items, and return their product ids.
+[source, cypher]
+----
+MATCH (i:Item)
+LIMIT 100
+CREATE (i)-[:PRODUCED_BY]->(:Producer)
+RETURN i.productId
+----
+
+=== Examples
+
+.Limiting a pattern match:
+[source, cypher]
+----
+MATCH (a:Person)
+WHERE a.name STARTS WITH 'And'
+LIMIT $limit
+RETURN a.age, a.name
+----
+
+.Limiting between query parts:
+[source, cypher]
+----
+MATCH (a:Person)
+WHERE a.age < 18
+SET a.child = true
+WITH a
+LIMIT 100
+MATCH (a)<-[:PARENT_OF]-(p)
+RETURN p.age, p.name
+----
+
+.Limiting the query result:
+[source, cypher]
+----
+MATCH (a:Person)
+WHERE a.age > 18
+RETURN p.age, p.name
+LIMIT 100
+----