diff --git a/modules/n1ql/assets/images/n1ql-language-reference/exclude-clause.png b/modules/n1ql/assets/images/n1ql-language-reference/exclude-clause.png new file mode 100644 index 000000000..cb7a8b101 Binary files /dev/null and b/modules/n1ql/assets/images/n1ql-language-reference/exclude-clause.png differ diff --git a/modules/n1ql/assets/images/n1ql-language-reference/exclude-term.png b/modules/n1ql/assets/images/n1ql-language-reference/exclude-term.png new file mode 100644 index 000000000..526de6c4f Binary files /dev/null and b/modules/n1ql/assets/images/n1ql-language-reference/exclude-term.png differ diff --git a/modules/n1ql/assets/images/n1ql-language-reference/select-clause.png b/modules/n1ql/assets/images/n1ql-language-reference/select-clause.png index 187f34128..c0349054e 100644 Binary files a/modules/n1ql/assets/images/n1ql-language-reference/select-clause.png and b/modules/n1ql/assets/images/n1ql-language-reference/select-clause.png differ diff --git a/modules/n1ql/pages/n1ql-language-reference/select-syntax.adoc b/modules/n1ql/pages/n1ql-language-reference/select-syntax.adoc index d4e426eec..38e219f73 100644 --- a/modules/n1ql/pages/n1ql-language-reference/select-syntax.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/select-syntax.adoc @@ -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]? <> +select-clause ::= 'SELECT' {hints}[hint-comment]? <> <>? ---- 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' <> ( ',' <> )* +---- + +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 diff --git a/modules/n1ql/pages/n1ql-language-reference/selectclause.adoc b/modules/n1ql/pages/n1ql-language-reference/selectclause.adoc index 0080da7d4..dff382d14 100644 --- a/modules/n1ql/pages/n1ql-language-reference/selectclause.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/selectclause.adoc @@ -34,6 +34,7 @@ image::n1ql-language-reference/select-clause.png["Syntax diagram", align=left] [horizontal.compact] hint-comment:: <> icon:caret-down[] projection:: <> icon:caret-down[] +exclude-clause:: <> 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 <>. +[#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 <>, 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 <>. + +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 diff --git a/modules/n1ql/partials/grammar/dql.ebnf b/modules/n1ql/partials/grammar/dql.ebnf index 85e09ba7c..2a6a53964 100644 --- a/modules/n1ql/partials/grammar/dql.ebnf +++ b/modules/n1ql/partials/grammar/dql.ebnf @@ -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/7.6/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 */