DOC-8371 -- page changes (#467)

(cherry picked from commit 1087ba6766446844bfeff89f3ca308df637d9e0f)
(cherry picked from commit 9cca374)

Author: ibsoln

modules/ROOT/pages/_partials/_attributes-local.adoc

@@ -129,6 +129,8 @@ endif::[]
 :url-cb-blog: https://blog.couchbase.com/
 :url-cb-blog-replication: {url-cb-blog}data-replication-couchbase-mobile/[Introducing the Data Replication Protocol^]
 :url-cb-blog-cert-pinning: {url-cb-blog}certificate-pinning-android-with-couchbase-mobile/[Certificate Pinning with Couchbase Mobile^]
+:url-cb-blog-query-interface: {url-cb-blog}sql-for-json-query-interface-couchbase-mobile/[Introducing the Query Interface in Couchbase Mobile^]
+
 :url-cb-blog-link: {url-cb-blog}[The Couchbase Blog]
 
 // BEGIN -- download urls
@@ -184,6 +186,15 @@ endif::[]
 :url-issues-objc: {url-github-cbl}-ios/issues
 :url-issues-swift: {url-github-cbl}-ios/issues
 
+
+
+
+:url-tutorials: https://docs.couchbase.com/tutorials/
+
+:url-tutorial-mobile-workshop: {url-tutorials}mobile-travel-sample/introduction.html[Couchbase Mobile Workshop]
+
+
+
 // END URLs
 
 
@@ -204,6 +215,7 @@ endif::[]
 :objc-examples: {lang-mod-objc}:example$
 :swift-examples: {lang-mod-swift}:example$
 
+:snippets-android-docsnippets: example$docsnippets/app/src/main/java/com/example/docsnippets/
 :snippets-pfx--android: example$snippets/app/src/main/
 :snippets-pfx--android-kt: {snippets-pfx--android}kotlin/com/couchbase/code_snippets/
 :snippets-pfx--android-java: {snippets-pfx--android}java/com/couchbase/code_snippets/
@@ -230,6 +242,17 @@ endif::[]
 :xref-pg-sgw-gs-install: {xref-pfx-sgw}:{pg-sgw-gs-install}[Install Sync Gateway]
 
 
+// BEGIN -- SET SNIPPET HEADERS
+:gen-subs: +attributes, +macros
+:bash-snippet: pass:q,a[source, bash, subs="{gen-subs}"]
+// :code-snippet: pass:q,a[source, {source-language}, subs="{gen-subs}"]
+:json-snippet: pass:q,a[source, json, subs="{gen-subs}"]
+:text-snippet: pass:q,a[source, text, subs="{gen-subs}"]
+
+// END -- SET SNIPPET HEADERS
+
+
+
 // Couchbase Lite Pages
 
 :component-mob-status: {_page-status-gamma}

modules/ROOT/pages/_partials/_page-index.adoc

@@ -21,4 +21,8 @@ include::ROOT:partial$_glossary-links.adoc[]
 // sets a flag to indicate what platform is on
 include::{root-partials}_set-platform.adoc[]
 
+// Set common code snippet header
+:code-snippet: source, {source-language}, subs="{gen-subs}"
+
+
 // END -- inclusion -- _std-cbl-hdr.adoc -- Standard page initialization

modules/ROOT/pages/_partials/_std-cbl-hdr.adoc

@@ -0,0 +1,198 @@
+// BEGIN -- inclusion -- common-query-resultsets.adoc
+//  Purpose -- describes the use of the query's resultset
+//
+// // BEGIN::REQUIRED EXTERNALS
+// :this-module: {par-module}
+// :this-lang-title: {par-lang-title}
+// :this-packageNm: {par-packageNm}
+// :this-source-language: {par-source-language}
+// snippet: {par-snippet}
+//:this-url-issues: {par-url-issues}
+// END::REQUIRED EXTERNALS
+
+// BEGIN::Local page attributes
+:blank-field: ____
+
+// END::Local page attributes
+
+
+== Query Execution
+The execution of a Couchbase Lite for {param-title}'s database query returns an array of results, a result set.
+
+Each row of the result set represents the data returned from a document that met the conditions defined by the `WHERE` statement of your query.
+The composition of each row is determined by the `SelectResult` expressions provided in the `SELECT` statement.
+
+
+[#lbl-rtnd-res]
+== Returned Results
+<<lbl-rtn-all>>
+| <<lbl-rtn-id>>
+| <<lbl-rtn-specific>>
+
+The types of SelectResult formats you may encounter include those generated by :
+
+* SelectResult.all -- <<lbl-rtn-all,Using All>>
+* SelectResult.expression(meta.id) -- <<lbl-rtn-id, Using Doc Id>> Metadata such as the `_id`
+* SelectResult.expression(property("name")) -- <<lbl-rtn-specific, Using Specific Properties>>
+
+
+[#lbl-rtn-all]
+=== Return All Document Properties
+The SelectResult returned by `SelectResult.all` is a dictionary object, with the database name as the key and the document properties as an array of key-value pairs
+
+--
+.Returning All Properties
+[#ex-result-id]
+====
+[{json-snippet}]
+----
+
+include::{root-examples}query-snippets.adoc[tags=query-result-format-all]
+
+----
+====
+--
+
+
+[#lbl-rtn-id]
+=== Return Document Id Only
+The SelectResult returned by queries using a SelectResult expression of the form `SelectResult.expression(meta.id)` comprises a dictionary object with `ID` as the key and the ID value as the value.
+
+--
+.Returning Meta Properties -- Document ID
+[#ex-result-id]
+====
+[{json-snippet}]
+----
+
+include::{root-examples}query-snippets.adoc[tags=query-result-format-id]
+
+----
+====
+--
+
+
+[#lbl-rtn-specific]
+=== Return Specific Properties Only
+The SelectResult returned by queries using one or more SelectResult expressions of the form `SelectResult.expression(property("name")) )` comprises a key-value pair for each SelectResult expression in the query.
+The key being the property name.
+
+--
+.Returning Specific Properties
+[#ex-result-props]
+====
+[{json-snippet}]
+----
+
+include::{root-examples}query-snippets.adoc[tags=query-result-format-props]
+
+----
+====
+--
+
+
+[#lbl-process-resultset]
+== Processing Results
+<<lbl-acc-all>>
+| <<lbl-acc-id>>
+| <<lbl-acc-specific>>
+
+To retrieve the results of your query,  you need to execute it using `Query.execute`.
+
+The output from the execution is an array, with each array element representing the data from a document that matched your search criteria.
+
+To unpack the results you need to iterate through this array.
+
+
+[#lbl-acc-all]
+=== Access Document Properties - All Properties
+Here we look at how to access document properties when you have used SelectResult.all.
+
+In this case each array element is a dictionary structure with the database name as its key.
+The properties are presented in the value as an array of key-value pairs (property name/property value).
+
+You access the retrieved document properties by converting each row's value, in turn, to a dictionary -- as shown in <<ex-acc-all>>.
+
+[#ex-acc-all]
+.Access All Properties
+====
+[{code-snippet}]
+----
+let yourQuery = QueryBuilder.select(SelectResult.all)
+            .from(DataSource.database(yourDb))
+
+for dataRow in try yourQuery.execute() {
+  if let yourDoc = dict[dataRow.toDictionary()] as? [String:Any] {
+      let docid = yourDoc["id"]
+      let name = yourDoc["name"]
+      let type = yourDoc["type"]
+      let city = yourDoc["city"]
+  }
+}
+
+----
+====
+
+
+[#lbl-acc-id]
+=== Access Document Properties - ID
+Here we look at how to access document properties when you have returned only the document IDs for documents that matched your selection criteria.
+
+This is something you may do when retrieval of the properties directly by the query may consume excessive amounts of memory and-or processing time.
+
+In this case each array element is a dictionary structure where `ID` is the key and the required document ID is the value.
+
+Access the required document properties by retrieving the document from the database using its document ID -- as shown in <<ex-acc-all>>.
+
+[#ex-acc-id]
+.Access Properties using Doc ID
+====
+[{code-snippet}]
+----
+let yourQuery = QueryBuilder.select(SelectResult.expression(Meta.id))
+            .from(DataSource.database(yourDb))
+
+for dataRow in try yourQuery.execute() {
+  if let yourDocID = dict[dataRow["id"] {
+      let yourDoc = try yourDb.document(withID: yourDocId)
+      let name = yourDoc.name
+      let type = yourDoc.type
+      let city = yourDoc.city
+  }
+}
+
+----
+====
+
+
+[#lbl-acc-specific]
+=== Access Document Properties - Selected Properties
+Here we look at how to access properties when you have used SelectResult to get a specific subset of properties.
+
+In this case each array element is an array of key value pairs (property name/property value).
+
+Access the retrieved properties by converting each row into a dictionary -- as shown in <<ex-acc-all>>.
+
+[#ex-acc-all]
+.Access All Properties
+====
+[{code-snippet}]
+----
+let yoursearchQuery = QueryBuilder
+            .select(SelectResult.expression(Meta.id),
+                    SelectResult.expression(Expression.property("name")),
+                    SelectResult.expression(Expression.property("city")),
+                    SelectResult.expression(Expression.property("type")))
+            .from(DataSource.database(yourDb))
+
+for dataRow in try yourQuery.execute() {
+  if let yourDoc = dict[dataRow.toDictionary()] as? [String:Any] {
+      let docid = yourDoc["id"]
+      let name = yourDoc["name"]
+      let type = yourDoc["type"]
+  }
+}
+
+----
+====
+// END -- inclusion -- common-query-resultsets.adoc