--- title: Result Sets description: How to use Couchbase Lite Query's Result Sets pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbase/docs-couchbase-lite/edit/release/3.3/modules/java/pages/query-resultsets.adoc xref: xref:3.3@couchbase-lite:java:query-resultsets.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/couchbase-lite/3.3/java/query-resultsets.html) # Result Sets > Description — _How to use Couchbase Lite Query's Result Sets_ > Related Content — [QueryBuilder](querybuilder.md) | [SQL++ for Mobile](query-n1ql-mobile.md) | [Predictive Queries](querybuilder.md#lbl-predquery) | [Live Queries](query-live.md) | [Indexing](indexing.md) ## [](#query-execution)Query Execution The execution of a Couchbase Lite for Java'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 [Return All Document Properties](#lbl-rtn-all)| [Return Document Id Only](#lbl-rtn-id)| [Return Specific Properties Only](#lbl-rtn-specific) The types of SelectResult formats you may encounter include those generated by : * `QueryBuilder.select(SelectResult.all())` — [Using All](#lbl-rtn-all) * `QueryBuilder.select(SelectResult.expression(Meta.id))` — [Using Doc Id](#lbl-rtn-id) Metadata such as the `_id` * `QueryBuilder.select(SelectResult.property("myProp"))` — [Using Specific Properties](#lbl-rtn-specific) ### [](#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 Example 1\. Returning All Properties ```json [ { "travel-sample": { (1) "callsign": "MILE-AIR", "country": "United States", "iata": "Q5", "icao": "MLA", "id": 10, "name": "40-Mile Air", "type": "airline" } }, { "travel-sample": { (2) "callsign": "ALASKAN-AIR", "country": "United States", "iata": "AA", "icao": "AAA", "id": 10, "name": "Alaskan Airways", "type": "airline" } } ] ``` ### [](#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. Example 2\. Returning Meta Properties — Document ID ```json [ { "id": "hotel123" }, { "id": "hotel456" }, ] ``` ### [](#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. Example 3\. Returning Specific Properties ```json [ { (1) "id": "hotel123", "type": "hotel", "name": "Hotel Ghia" }, { (2) "id": "hotel456", "type": "hotel", "name": "Hotel Deluxe", } ] ``` ## [](#lbl-process-resultset)Processing Results [Access Document Properties - All Properties](#lbl-acc-all)| [Access Document Properties - ID](#lbl-acc-id)| [Access Document Properties - Selected Properties](#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. Alternatively, you can convert the result to a JSON string — see: ### [](#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 [Example 4](#ex-acc-all). Example 4\. Access All Properties ```Java Map hotels = new HashMap<>(); try (ResultSet resultSet = listQuery.execute()) { for (Result result: resultSet) { // get the k-v pairs from the 'hotel' key's value into a dictionary Dictionary docsProp = result.getDictionary(0); (1) String docsId = docsProp.getString("id"); String docsName = docsProp.getString("Name"); String docsType = docsProp.getString("Type"); String docsCity = docsProp.getString("City"); // Alternatively, access results value dictionary directly final Hotel hotel = new Hotel(); hotel.setId(result.getDictionary(0).getString("id")); (2) hotel.setType(result.getDictionary(0).getString("Type")); hotel.setName(result.getDictionary(0).getString("Name")); hotel.setCity(result.getDictionary(0).getString("City")); hotel.setCountry(result.getDictionary(0).getString("Country")); hotel.setDescription(result.getDictionary(0).getString("Description")); hotels.put(hotel.getId(), hotel); } } ``` | **1** | Here we get the dictionary of document properties using the database name as the key. You can add this dictionary to an array of returned matches, for processing elsewhere in the app. | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **2** | Alternatively, you can access the document properties here, by using the property names as keys to the dictionary object. | ### [](#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 [Example 5](#ex-acc-id). Example 5\. Access by ID ```Java try (ResultSet rs = listQuery.execute()) { for (Result result: rs.allResults()) { // get the ID form the result's k-v pair array String thisDocsId = result.getString("metaID"); (1) // Get document from DB using retrieved ID Document thisDoc = collection.getDocument(thisDocsId); // Process document as required String thisDocsName = thisDoc.getString("Name"); } } ``` | **1** | Extract the Id value from the dictionary and use it to get the document from the database | | ----- | ----------------------------------------------------------------------------------------- | ### [](#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-specific\]](#ex-acc-specific). ```Java HashMap hotels = new HashMap<>(); try (ResultSet resultSet = listQuery.execute()) { for (Result result: resultSet) { // get data direct from result k-v pairs final Hotel hotel = new Hotel(); hotel.setId(result.getString("id")); hotel.setType(result.getString("Type")); hotel.setName(result.getString("Name")); hotel.setCity(result.getString("City")); // Store created hotel object in a hashmap of hotels hotels.put(hotel.getId(), hotel); // Get result k-v pairs into a 'dictionary' object Map thisDocsProps = result.toMap(); String docId = thisDocsProps.getOrDefault("id", null).toString(); String docName = thisDocsProps.getOrDefault("Name", null).toString(); String docType = thisDocsProps.getOrDefault("Type", null).toString(); String docCity = thisDocsProps.getOrDefault("City", null).toString(); } } ``` ## [](#json-result-sets)JSON Result Sets Example 6\. Using JSON Results Use [Result.toJSON()](https://docs.couchbase.com/mobile/3.3.4/couchbase-lite-java/com/couchbase/lite/Result.html#toJSON--) to transform your result string into a JSON string, which can easily be serialized or used as required in your application. See [Example 6](#ex-json) for a working example. ```Java // Uses Jackson JSON processor ObjectMapper mapper = new ObjectMapper(); List hotels = new ArrayList<>(); try (ResultSet rs = listQuery.execute()) { for (Result result: rs) { String json = result.toJSON(); Map dictFromJSONstring = mapper.readValue(json, HashMap.class); String hotelId = dictFromJSONstring.get("id"); String hotelType = dictFromJSONstring.get("type"); String hotelname = dictFromJSONstring.get("name"); // Get custom object from JSON string Hotel thisHotel = mapper.readValue(json, Hotel.class); hotels.add(thisHotel); } } ``` JSON String Format If your query selects ALL then the JSON format will be: ```JSON { database-name: { key1: "value1", keyx: "valuex" } } ``` If your query selects a sub-set of available properties then the JSON format will be: ```JSON { key1: "value1", keyx: "valuex" } ``` ## [](#related-content)Related Content ###### [](#) How to . . . * [Prerequisites](gs-prereqs.md) * [Install](gs-install.md) * [Build and Run](gs-build.md) . ###### [](#-2) Learn more . . . * [Databases](database.md) * [Documents](document.md) * [Blobs](blob.md) * [Remote Sync Gateway](replication.md) * [Handling Data Conflicts](conflict.md) . ###### [](#-3) Dive Deeper . . . [Mobile Forum](https://forums.couchbase.com/c/mobile/14) | [Blog](https://blog.couchbase.com/) | [Tutorials](https://docs.couchbase.com/tutorials/) .