Skip to main content
V5 - Java Server DocumentationThese docs are for Java Server V5 Only. For all other languages and platforms, continue using SDK v4 until V5 support is available.
See Document Model for more information on documents in Ditto. Just like with conventional database querying, you execute query operations to fetch one or more documents that satisfy specific criteria and conditions. To perform a single execution query on the Ditto store, call the execute API method on the store namespace as follows: 
// try-with-resources block auto-closes DittoQueryResult
try (DittoQueryResult result = ditto.getStore().execute(
        "SELECT * FROM cars"
    ).toCompletableFuture().join()) {
    ...
}

​
Using args to Query Dynamic Values

When dealing with data that may change dynamically during runtime, instead of defining the changing values directly in the query string, encapsulate them in a top-level args object you can use to reference the values in your queries. To pass an argument to the execute function, use the :[argument] syntax with DQL where the [argument] maps to the field in the provided args object. For example, here color is passed as an argument to the execute function, and, within the query string, :color placeholder references the color defined in a top-level args object. 
import static com.ditto.java.serialization.DittoCborSerializable.buildDictionary;

try (DittoQueryResult result = ditto.getStore().execute(
        "SELECT * FROM cars WHERE color = :color",
        buildDictionary().put("color", "blue").build()
    ).toCompletableFuture().join()) {
    ...
}
Once the previous example operation executes, the query becomes SELECT * FROM cars WHERE color = blue.

​
Managing Query Results

After executing a query, the result object that is returned includes both the overall content retrieved and individual items. Each item is encapsulated in independent QueryResultItem objects that you can use to access them either directly or as raw CBOR or JSON data. Rather than retrieving the items as part of the query execution and making them available immediately after execution, each item is lazy loaded. Lazy loading involves postponing fetching and storing in memory until requested on-demand or accessed later. Here is an example query execution to select all documents from the cars collection. The result is stored in the variable result. Then, each item is lazy loaded from the result object and stored in the items: 
try (DittoQueryResult result = ditto.getStore().execute(
        "SELECT * FROM cars"
    ).toCompletableFuture().join()) {
    List<DittoQueryResultItem> items = result.getItems();
}

​
Working with a QueryResultItem

The result items object is a collection ofQueryResultItem. Each item’s value can be independently managed to meet the needs of your scenario.

​
Value

To retrieve the value, call the value property on an item: 
import com.ditto.java.serialization.DittoCborSerializable;

try (DittoQueryResult result = ditto.getStore().execute(
        "SELECT * FROM cars"
    ).toCompletableFuture().join()) {
    DittoQueryResultItem item = result.getItems().get(0);
    DittoCborSerializable.Dictionary itemValue = item.getValue();
    String itemValueColor = itemValue.get("color").getString();
}

​
Materializing the Value

To help manage memory usage more efficiently, content associated with an item is lazily loaded, meaning it materializes — loads into memory — only upon the initial call to value. To load the item’s value into memory, use any of the following methods as appropriate: 
// Returns `true` if value is currently held materialized in memory, otherwise returns `false`
item.isMaterialized

// Loads the item's value into memory
item.materialize()

// Release item's value from memory
item.dematerialize()

​
Raw CBOR Value

To access the result items as CBOR data:
The result of this method call is not cached.
try (DittoQueryResult result = ditto.getStore().execute(
        "SELECT * FROM cars"
    ).toCompletableFuture().join()) {
    byte[] cborItem = result.getItems().get(0).cborData();
}

​
Raw JSON Value

To access the result items as a JSON-string:
The result of this method call is not cached.
try (DittoQueryResult result = ditto.getStore().execute(
        "SELECT * FROM cars"
    ).toCompletableFuture().join()) {
    String jsonItem = result.getItems().get(0).jsonString();
}