[DOC-10590] Add EXCLUDE clause to SELECT (#382)

Author: rakhi-prathap

modules/n1ql/assets/images/n1ql-language-reference/exclude-clause.png

@@ -5,6 +5,7 @@
 :page-topic-type: reference
 
 :expression: xref:n1ql-language-reference/index.adoc#N1QL_Expressions
+:string-expression: xref:n1ql-language-reference/literals.adoc#strings
 :hints: xref:n1ql-language-reference/optimizer-hints.adoc
 :conventions: xref:n1ql-language-reference/conventions.adoc
 :number: xref:n1ql-language-reference/literals.adoc#numbers
@@ -81,7 +82,7 @@ image::n1ql-language-reference/alias.png["Syntax diagram", align=left]
 
 [subs="normal"]
 ----
-select-clause ::= 'SELECT' {hints}[hint-comment]? <<projection>>
+select-clause ::= 'SELECT' {hints}[hint-comment]? <<projection>> <<exclude-clause>>? 
 ----
 
 image::n1ql-language-reference/select-clause.png["Syntax diagram", align=left]
@@ -109,6 +110,21 @@ path ::= {identifier}[identifier] ( '[' {expression}[expr] ']' )* ( '.' {identif
 
 image::n1ql-language-reference/path.png["Syntax diagram", align=left]
 
+[#exclude-clause,reftext="exclude-clause",subs="normal"]
+----
+exclude-clause ::= 'EXCLUDE' <<exclude-term>> ( ',' <<exclude-term>> )*
+----
+
+image::n1ql-language-reference/exclude-clause.png["Syntax diagram", align=left]
+
+[#exclude-term,reftext="exclude-term",subs="normal"]
+----
+exclude-term ::= {identifier}[identifier] | {string-expression}[string-expr] 
+----
+image::n1ql-language-reference/exclude-term.png["Syntax diagram", align=left]
+
+[#hints,reftext="hints",subs="normal"]
+
 [[from-clause,from-clause]]
 == FROM Clause
 

modules/n1ql/assets/images/n1ql-language-reference/exclude-term.png

@@ -34,6 +34,7 @@ image::n1ql-language-reference/select-clause.png["Syntax diagram", align=left]
 [horizontal.compact]
 hint-comment:: <<hint-comment>> icon:caret-down[]
 projection:: <<sec_Arguments>> icon:caret-down[]
+exclude-clause:: <<sec_ExcludeClause>> icon:caret-down[]
 
 [#hint-comment]
 === Optimizer Hints
@@ -155,6 +156,47 @@ If you do not explicitly give a field an alias, it is given an _implicit alias_.
 
 An implicit or explicit alias is returned in the result set, unless you suppress it using the <<raw-element-value,RAW keyword>>.
 
+[#sec_ExcludeClause]
+=== EXCLUDE Clause
+
+[source,ebnf]
+----
+include::partial$grammar/dql.ebnf[tag=exclude-clause]
+----
+image::n1ql-language-reference/exclude-clause.png["Syntax diagram", align=left]
+
+The EXCLUDE clause removes specific fields from your query's result set. 
+
+Instead of listing every field you want to include in the SELECT statement, use EXCLUDE to specify only the ones you want to omit.
+This is particularly useful when you use the star expression (`{asterisk}`) to select all fields, but want to exclude a few. 
+
+The clause consists of one or more <<exclude-term, EXCLUDE terms>>, separated by commas.
+
+[[exclude-term]]
+==== EXCLUDE Term
+[source,ebnf]
+----
+include::partial$grammar/dql.ebnf[tag=exclude-term]
+----
+image::n1ql-language-reference/exclude-term.png["Syntax diagram", align=left]
+
+An EXCLUDE term is a field that you want to exclude from the final projection.
+It must exactly match the field name or alias as it appears in the projection.
+Refer to <<ex-exclude-clause>>.
+
+An EXCLUDE term can be:
+
+* An identifier, such as `hotel.name`.
+* A string expression with one or more fields separated by commas, such as `"hotel.name, address"`.
+
+[NOTE]
+====
+* If the field has an alias, you must use the alias as the term. 
+* When your query includes only one FROM term, fields are automatically qualified with it.
+You can use the field name without the full identifier.
+For example, `name` instead of `hotel.name`.
+====
+
 [#sec_BestPractices]
 == Best Practices
 
@@ -632,6 +674,52 @@ FROM hotel LIMIT 5;
 <.> With a select expression, you may optionally include the keyspace name; in either case, the keyspace name is not added to the results.
 ====
 
+[[ex-exclude-clause]]
+.SELECT with an EXCLUDE clause
+====
+.Query
+[source,sqlpp]
+----
+SELECT * EXCLUDE reviews,h.public_likes,"geo,description" 
+FROM `travel-sample`.inventory.hotel h 
+ORDER BY meta().id LIMIT 1;
+----
+
+.Results
+[source,json]
+----
+[
+  {
+    "h": {
+      "address": "Capstone Road, ME7 3JE",
+      "alias": null,
+      "checkin": null,
+      "checkout": null,
+      "city": "Medway",
+      "country": "United Kingdom",
+      "directions": null,
+      "email": null,
+      "fax": null,
+      "free_breakfast": true,
+      "free_internet": false,
+      "free_parking": true,
+      "id": 10025,
+      "name": "Medway Youth Hostel",
+      "pets_ok": true,
+      "phone": "+44 870 770 5964",
+      "price": null,
+      "state": null,
+      "title": "Gillingham (Kent)",
+      "tollfree": null,
+      "type": "hotel",
+      "url": "http://www.yha.org.uk",
+      "vacancy": true
+    }
+  }
+]
+----
+====
+
 [#sec_RelatedLinks]
 == Related Links
 

modules/n1ql/assets/images/n1ql-language-reference/select-clause.png

@@ -71,10 +71,11 @@ anchor-select ::= select
 /* tag::recursive-select-term[] */
 recursive-select-term ::= select-term
 /* end::recursive-select-term[] */
+
 /* SELECT Clause */
 
 /* tag::select-clause[] */
-select-clause ::= 'SELECT' hint-comment? projection
+select-clause ::= 'SELECT' hint-comment? projection exclude-clause?
 /* end::select-clause[] */
 
 hint-comment ::= [https://github.com/couchbaselabs/docs-devex/blob/release/8.0/modules/n1ql/partials/grammar/hints.ebnf]
@@ -92,6 +93,13 @@ result-expr ::= ( path '.' )? '*' | expr ( 'AS'? alias )?
 path ::= identifier ( '[' expr ']' )* ( '.' identifier ( '[' expr ']' )* )*
 /* end::path[] */
 
+/* tag::exclude-clause[] */
+exclude-clause ::= 'EXCLUDE' exclude-term ( ',' exclude-term )*
+/* end::exclude-clause[] */
+
+/* tag::exclude-term[] */
+exclude-term ::= identifier | string-expression
+/* end::exclude-term[] */
 
 /* FROM Clause */