|
| 1 | +// BEGIN -- inclusion -- common-query-resultsets.adoc |
| 2 | +// Purpose -- describes the use of the query's resultset |
| 3 | +// |
| 4 | +// // BEGIN::REQUIRED EXTERNALS |
| 5 | +// :this-module: {par-module} |
| 6 | +// :this-lang-title: {par-lang-title} |
| 7 | +// :this-packageNm: {par-packageNm} |
| 8 | +// :this-source-language: {par-source-language} |
| 9 | +// snippet: {par-snippet} |
| 10 | +//:this-url-issues: {par-url-issues} |
| 11 | +// END::REQUIRED EXTERNALS |
| 12 | + |
| 13 | +// BEGIN::Local page attributes |
| 14 | +:blank-field: ____ |
| 15 | + |
| 16 | +// END::Local page attributes |
| 17 | + |
| 18 | + |
| 19 | +== Query Execution |
| 20 | +The execution of a Couchbase Lite for {param-title}'s database query returns an array of results, a result set. |
| 21 | + |
| 22 | +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. |
| 23 | +The composition of each row is determined by the `SelectResult` expressions provided in the `SELECT` statement. |
| 24 | + |
| 25 | + |
| 26 | +[#lbl-rtnd-res] |
| 27 | +== Returned Results |
| 28 | +<<lbl-rtn-all>> |
| 29 | +| <<lbl-rtn-id>> |
| 30 | +| <<lbl-rtn-specific>> |
| 31 | + |
| 32 | +The types of SelectResult formats you may encounter include those generated by : |
| 33 | + |
| 34 | +* SelectResult.all -- <<lbl-rtn-all,Using All>> |
| 35 | +* SelectResult.expression(meta.id) -- <<lbl-rtn-id, Using Doc Id>> Metadata such as the `_id` |
| 36 | +* SelectResult.expression(property("name")) -- <<lbl-rtn-specific, Using Specific Properties>> |
| 37 | + |
| 38 | + |
| 39 | +[#lbl-rtn-all] |
| 40 | +=== Return All Document Properties |
| 41 | +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 |
| 42 | + |
| 43 | +-- |
| 44 | +.Returning All Properties |
| 45 | +[#ex-result-id] |
| 46 | +==== |
| 47 | +[{json-snippet}] |
| 48 | +---- |
| 49 | +
|
| 50 | +include::{root-examples}query-snippets.adoc[tags=query-result-format-all] |
| 51 | +
|
| 52 | +---- |
| 53 | +==== |
| 54 | +-- |
| 55 | + |
| 56 | + |
| 57 | +[#lbl-rtn-id] |
| 58 | +=== Return Document Id Only |
| 59 | +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. |
| 60 | + |
| 61 | +-- |
| 62 | +.Returning Meta Properties -- Document ID |
| 63 | +[#ex-result-id] |
| 64 | +==== |
| 65 | +[{json-snippet}] |
| 66 | +---- |
| 67 | +
|
| 68 | +include::{root-examples}query-snippets.adoc[tags=query-result-format-id] |
| 69 | +
|
| 70 | +---- |
| 71 | +==== |
| 72 | +-- |
| 73 | + |
| 74 | + |
| 75 | +[#lbl-rtn-specific] |
| 76 | +=== Return Specific Properties Only |
| 77 | +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. |
| 78 | +The key being the property name. |
| 79 | + |
| 80 | +-- |
| 81 | +.Returning Specific Properties |
| 82 | +[#ex-result-props] |
| 83 | +==== |
| 84 | +[{json-snippet}] |
| 85 | +---- |
| 86 | +
|
| 87 | +include::{root-examples}query-snippets.adoc[tags=query-result-format-props] |
| 88 | +
|
| 89 | +---- |
| 90 | +==== |
| 91 | +-- |
| 92 | + |
| 93 | + |
| 94 | +[#lbl-process-resultset] |
| 95 | +== Processing Results |
| 96 | +<<lbl-acc-all>> |
| 97 | +| <<lbl-acc-id>> |
| 98 | +| <<lbl-acc-specific>> |
| 99 | + |
| 100 | +To retrieve the results of your query, you need to execute it using `Query.execute`. |
| 101 | + |
| 102 | +The output from the execution is an array, with each array element representing the data from a document that matched your search criteria. |
| 103 | + |
| 104 | +To unpack the results you need to iterate through this array. |
| 105 | + |
| 106 | + |
| 107 | +[#lbl-acc-all] |
| 108 | +=== Access Document Properties - All Properties |
| 109 | +Here we look at how to access document properties when you have used SelectResult.all. |
| 110 | + |
| 111 | +In this case each array element is a dictionary structure with the database name as its key. |
| 112 | +The properties are presented in the value as an array of key-value pairs (property name/property value). |
| 113 | + |
| 114 | +You access the retrieved document properties by converting each row's value, in turn, to a dictionary -- as shown in <<ex-acc-all>>. |
| 115 | + |
| 116 | +[#ex-acc-all] |
| 117 | +.Access All Properties |
| 118 | +==== |
| 119 | +[{code-snippet}] |
| 120 | +---- |
| 121 | +let yourQuery = QueryBuilder.select(SelectResult.all) |
| 122 | + .from(DataSource.database(yourDb)) |
| 123 | +
|
| 124 | +for dataRow in try yourQuery.execute() { |
| 125 | + if let yourDoc = dict[dataRow.toDictionary()] as? [String:Any] { |
| 126 | + let docid = yourDoc["id"] |
| 127 | + let name = yourDoc["name"] |
| 128 | + let type = yourDoc["type"] |
| 129 | + let city = yourDoc["city"] |
| 130 | + } |
| 131 | +} |
| 132 | +
|
| 133 | +---- |
| 134 | +==== |
| 135 | + |
| 136 | + |
| 137 | +[#lbl-acc-id] |
| 138 | +=== Access Document Properties - ID |
| 139 | +Here we look at how to access document properties when you have returned only the document IDs for documents that matched your selection criteria. |
| 140 | + |
| 141 | +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. |
| 142 | + |
| 143 | +In this case each array element is a dictionary structure where `ID` is the key and the required document ID is the value. |
| 144 | + |
| 145 | +Access the required document properties by retrieving the document from the database using its document ID -- as shown in <<ex-acc-all>>. |
| 146 | + |
| 147 | +[#ex-acc-id] |
| 148 | +.Access Properties using Doc ID |
| 149 | +==== |
| 150 | +[{code-snippet}] |
| 151 | +---- |
| 152 | +let yourQuery = QueryBuilder.select(SelectResult.expression(Meta.id)) |
| 153 | + .from(DataSource.database(yourDb)) |
| 154 | +
|
| 155 | +for dataRow in try yourQuery.execute() { |
| 156 | + if let yourDocID = dict[dataRow["id"] { |
| 157 | + let yourDoc = try yourDb.document(withID: yourDocId) |
| 158 | + let name = yourDoc.name |
| 159 | + let type = yourDoc.type |
| 160 | + let city = yourDoc.city |
| 161 | + } |
| 162 | +} |
| 163 | +
|
| 164 | +---- |
| 165 | +==== |
| 166 | + |
| 167 | + |
| 168 | +[#lbl-acc-specific] |
| 169 | +=== Access Document Properties - Selected Properties |
| 170 | +Here we look at how to access properties when you have used SelectResult to get a specific subset of properties. |
| 171 | + |
| 172 | +In this case each array element is an array of key value pairs (property name/property value). |
| 173 | + |
| 174 | +Access the retrieved properties by converting each row into a dictionary -- as shown in <<ex-acc-all>>. |
| 175 | + |
| 176 | +[#ex-acc-all] |
| 177 | +.Access All Properties |
| 178 | +==== |
| 179 | +[{code-snippet}] |
| 180 | +---- |
| 181 | +let yoursearchQuery = QueryBuilder |
| 182 | + .select(SelectResult.expression(Meta.id), |
| 183 | + SelectResult.expression(Expression.property("name")), |
| 184 | + SelectResult.expression(Expression.property("city")), |
| 185 | + SelectResult.expression(Expression.property("type"))) |
| 186 | + .from(DataSource.database(yourDb)) |
| 187 | +
|
| 188 | +for dataRow in try yourQuery.execute() { |
| 189 | + if let yourDoc = dict[dataRow.toDictionary()] as? [String:Any] { |
| 190 | + let docid = yourDoc["id"] |
| 191 | + let name = yourDoc["name"] |
| 192 | + let type = yourDoc["type"] |
| 193 | + } |
| 194 | +} |
| 195 | +
|
| 196 | +---- |
| 197 | +==== |
| 198 | +// END -- inclusion -- common-query-resultsets.adoc |
0 commit comments