For a high-level overview of Ditto
create
, read
, update
, and delete
(CRUD) operations, see Ditto Basics CRUD Fundamentals.Creating Queries
Ditto’s query language is similar to what you’d write in mostif
statements. In addition, you can use intuitive query condition operators. For more information, see Ditto Basics Query Syntax and Platform Manual > Querying Techniques.
If you want to receive detailed information about the types of data being returned, specify the key
serializedAs: latestValuesAndTypes
in your request.cURL
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
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 Identifiers.
people
collection with the document ID of 123abc
:
cURL
Finding Documents by Criteria
Thefind
method fetches the current version of multiple documents from Ditto Server:
Do not include a
find
query within a write
command in a single operation. Instead, perform each as separate API calls. For instructions, see Performing Find and Write Operations.Performing Find and Write Operations
Do not include afind
query within a write
command in a single operation. Instead, perform each operation as separate API calls:
1
Send a
find
request to fetch the documents.2
Once you’ve received a response, send a separate
write
request to create or modify documents.Sorting Results
Unless you explicitly specify asort
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 documents with
name
field property set to ascending (asc
) order. - Sort documents with the
age
field property set to descending (desc
) order.
cURL
Limiting Results
Limit the number of results that a query returns by calling thelimit
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
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 Ditto Server, perform an index test by including thedescribe
field set to true
in the JSON body of your request.
For example:
cURL
"index_scan"
response:
JSON
"full_scan"
response:
JSON
Performing Find and Write Operations
Do not include afind
query within a write
command in a single operation. Instead, perform the following as separate API calls:
1
Send a
find
request to fetch the documents.2
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 Ditto Server or evaluate and test the amount of data that a subscription will sync to Small Peers, use thecount
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:
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]().count
the number of documents within the people
collection with the field property of name
set to the value of John
:
cURL