Querying: HTTP (Legacy)

this article provides an overview on how to perform read operations in ditto, including how to construct your queries, use $args to query for dynamic data, sort and limit your results, and perform index testing for a high level overview of ditto create , read , update , and delete (crud) operations, see ditto basics > docid 1v 23t36jbqegsytqt1yu creating queries ditto's query language is similar to what you'd write in most if statements in addition, you can use intuitive query condition operators for more information, see ditto basics > docid\ esq8nyek3mspdw9 ecdh1 and platform manual > docid\ g ggvgmmo5jzo4zremord if you want to receive detailed information about the types of data being returned, specify the key serializedas latestvaluesandtypes in your request as demonstrated in the following snippet, you query documents by their collection, rather than by individual document however, if you need to find a specific document, you can query by its unique identifier for more information, see docid\ s17orcplo9wuy13bwer8h curl curl x post 'https //\<cloud endpoint>/api/v4/store/find' \\ \ header 'content type application/json' \\ \ data raw '{ "collection" "people", "query" "favoritebook title == 'the great gatsby'" }' using query variables with $args instead of building or interpolating query strings, you can query ditto using runtime variables through an $args map object curl curl x post 'https //\<cloud endpoint>/api/v4/store/find' \\ \ header 'content type application/json' \\ \ data raw '{ "args" { "name" "max", "age" 32 }, "collection" "people", "query" "name == $args name && age <= $args age" }' finding by document id to retrieve a single document by its unique identifier ( id ) or, if applicable, composite key, use the following endpoint if retrieving a document based on a composite key, make sure to provide all of the fields that make up the compound identifier for more information, see platform manual > docid\ gkv uasgemdpmarvu1r8n https //{app id} cloud ditto live/api/v4/store/findbyid for example, the following snippet shows how to construct a curl request to retrieve a document within the people collection with the document id of 123abc curl curl location request post 'https //{app id} cloud ditto live/api/v4/store/findbyid' \\ \ header 'content type application/json' \\ \ header 'authorization bearer $api key' \\ \ data raw '{ "collection" "people", "id" "123abc" }' finding documents by criteria the find method fetches the current version of multiple documents from the big peer do not include a find query within a write command in a single operation instead, perform each as separate api calls for instructions, see docid\ vqqyfkwdvy lsez89 qur https //{app id} cloud ditto live/api/v4/store/find performing find and write operations do not include a find query within a write command in a single operation instead, perform each operation as separate api calls send a find request to fetch the documents once you've received a response, send a separate write request to create or modify documents sorting results unless you explicitly specify a sort direction in your request, the documents are returned in an arbitrary order in previous versions of the http api, there was an implicit default sorting order; however, as of http api version 4, documents return in an arbitrary order by default if you want to maintain the same default sorting order as previous versions, add sort by id ascending in your request as follows "sort" \[ {"property" " id", "direction" "asc"} ] the following snippet provides an example of two sort operations sort documents with name field property set to ascending ( asc ) order sort documents with the age field property set to descending ( desc ) order curl curl x post 'https //\<cloud endpoint>/api/v4/store/find' \\ \ header 'content type application/json' \\ \ data raw '{ "collection" "people", "query" "favoritebook title == 'the great gatsby'", "sort" \[ {"property" "name", "direction" "asc"}, {"property" "age", "direction" "desc"} ] }' limiting results limit the number of results that a query returns by calling the limit method before executing your query for example, the following snippet demonstrates a limit of 100 results for documents within the people collection with a field property of color set to the value of red curl curl x post 'https //\<cloud endpoint>/api/v4/store/find' \\ \ header 'content type application/json' \\ \ data raw '{ "collection" "people", "query" "color == 'red'", "limit" 100 }' performing index testing query efficiency impacts the overall performance and scalability of your app to determine how the particular query interacts with an index on the big peer, perform an index test by including the describe field set to true in the json body of your request for example curl curl x post 'https //\<cloud endpoint>/api/v4/store/find' \\ \ header 'content type application/json' \\ \ data raw '{ "collection" "orders", "query" "status != 'finalized'", "limit" 100, "describe" true }' if the query successfully made use of an index, you'll receive the following "index scan" response json { "documents" \[ { "id" "query details", "fields" { "index scan" { "path" \[ "status" ] } } } ], "txnid" 221984002 } if the query failed to use an index, you'll receive the following "full scan" response json { "documents" \[ { "id" "query details", "fields" { "full scan" {} } } ], "txnid" 221983514 } performing find and write operations do not include a find query within a write command in a single operation instead, perform the following as separate api calls send a find request to fetch the documents once you've received a response, send a separate write request to create create or modify documents counting documents when you want to ensure whether documents have been successfully synced to the big peer or evaluate and test the amount of data that a subscription will sync to small peers, use the count command accessible using the following url endpoint, the count command determines the number of documents that match a specific query expression at a particular moment in time https //{app id} cloud ditto live/api/v4/store/count with the count command, you can write queries directly in your request or, if querying dynamic data, pass them as $args for more information about using $args, see the platform manual > docid\ kdwag uss1kgbdacdn16e for example, the following snippet illustrates how to count the number of documents within the people collection with the field property of name set to the value of john curl curl x post 'https //{app id} cloud ditto live/api/v4/store/count' \\ \ header 'authorization bearer $api key' \\ \ header 'content type application/json' \\ \ data raw '{ "collection" "people", "query" "name == \\'john\\'" }'