--- title: Querying: HTTP (Legacy) slug: cloud/legacy/legacy-querying-http docTags: createdAt: 2023-09-25T18:51:35.608Z --- 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. :::hint{type="info"} For a high-level overview of Ditto `create`, `read`, `update`, and `delete` (CRUD) operations, see *Ditto Basics *> [CRUD Fundamentals](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 *> [Query Syntax](docId\:ESQ8nYEK3msPdw9-EcDh1) and *Platform Manual* > [Querying Techniques](docId\:g_GgvGMMo5JzO4zrEMOrD). :::hint{type="info"} 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 [Finding by Document ID](docId\:S17oRCPLO9WUy13BWER8H). :::CodeblockTabs cURL ```curl curl -X POST 'https:///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: :::CodeblockTabs cuRL ```curl curl -X POST 'https:///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: :::hint{type="info"} 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](docId\:GKV_uASgEMDpmarvU1r8N). ::: :::CodeblockTabs ```none 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`: :::CodeblockTabs cURL ```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: :::hint{type="warning"} 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](docId\:vQQYFkwDVy-LseZ89-Qur). ::: :::CodeblockTabs ```none 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: ::::WorkflowBlock :::WorkflowBlockItem Send a `find` request to fetch the documents. ::: :::WorkflowBlockItem 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. :::hint{type="info"} 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. :::CodeblockTabs cURL ```curl curl -X POST 'https:///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`: :::CodeblockTabs cURL ```curl curl -X POST 'https:///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: :::CodeblockTabs cURL ```curl curl -X POST 'https:///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: :::CodeblockTabs JSON ```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: :::CodeblockTabs JSON ```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: ::::WorkflowBlock :::WorkflowBlockItem Send a `find` request to fetch the documents. ::: :::WorkflowBlockItem 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: :::CodeblockTabs ```none https://{app_id}.cloud.ditto.live/api/v4/store/count ``` ::: :::hint{type="info"} 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 *> [Querying Dynamic Data Using $args](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`: :::CodeblockTabs cURL ```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\'" }' ``` :::