You are currently browsing legacy 5.2 version of documentation. Click here to switch to the newest 6.2 version.
    We can help you with migration to the latest RavenDB
    Contact Us Now
    See on GitHub

    Get Documents by ID

    Basic Example

    This is a cURL request to retrieve one document named "products/48-A" from a database named "Example" on our playground server: 

    curl -X GET "http://live-test.ravendb.net/databases/Example/docs?id=products/48-A"

    Response: 

    HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 10:33:04 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:285-k50KTOC5G0mfVXKjomTNFQ"
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
    "Results": [
        {
            "Name": "Chocolade",
            "Supplier": "suppliers/22-A",
            "Category": "categories/3-A",
            "QuantityPerUnit": "10 pkgs.",
            "PricePerUnit": 12.7500,
            "UnitsInStock": 22,
            "UnitsOnOrder": 15,
            "Discontinued": false,
            "ReorderLevel": 25,
            "@metadata": {
                "@collection": "Products",
                "@change-vector": "A:285-k50KTOC5G0mfVXKjomTNFQ",
                "@id": "products/48-A",
                "@last-modified": "2018-07-27T12:11:53.0300420Z"
            }
        }
    ],
    "Includes": {}
}

    Request Format

    This is the general format of a cURL request that uses all parameters: 

    curl -X GET "<server URL>/databases/<database name>/docs?
            id=<document ID>
            &include=<path>
            &counter=<counter name>
            &metadataOnly=<boolean>"
--header "If-None-Match:<hash>"
    Linebreaks are added for clarity.

    Query String Parameters

    Parameter Description Required / #
    id ID of a document to retrieve.
    If no IDs are specified, all the documents in the database are retrieved in descending order of their change vectors.    		 Yes;
    Can be used more than once
    include Path to a field containing the ID of another, 'related' document. See: How to Handle Document Relationships. No;
    Can be used more than once
    counter Name of a counter to retrieve. Set this parameter to @all_counters to retrieve all counters of the specified documents. Counters of included documents, however, will not be retrieved. No;
    Can be used more than once
    metadataOnly Set this parameter to true to retrieve only the metadata of each document. This does not apply to included documents which are retrieved with their complete contents. No;
    Used once

    Headers

    Header Description Required
    If-None-Match This header takes a hash representing the previous results of an identical request. The hash is found in the response header ETag. If the results were not modified since the previous request, the server responds with http status code 304 and the requested documents are retrieved from a local cache rather than over the network. No

    Response Format

    Http Status Codes

    Code Description
    200 Results are successfully retrieved. If a requested document could not be found, the result returned is null.
    304 In response to an If-None-Match check: none of the requested documents were modified since they were last loaded, so they were not retrieved from the server.
    404 No document with the specified ID was found. This code is only sent when one document was requested. Otherwise, see status code 200.

    Headers

    Header Description
    Content-Type MIME media type and character encoding. This should always be: application/json; charset=utf-8.
    ETag Hash representing the state of these results. If another, identical request is made, this hash can be sent in the If-None-Match header to check whether the retrieved documents have been modified since the last response. If none were modified, they are not retrieved.
    Raven-Server-Version Version of RavenDB that the responding server is running.

    Body

    A retrieved document is identical in contents and format to the document stored on the server (unless the metadataOnly parameter is set to true).

    This is the general JSON format of the response body: 

    {
    "Results": [ 
        { 
            <document contents>
        },
        { },
        ...
    ],
    "Includes":
        "<document ID>": {
            <document contents>
        },
        "<document ID>": { },
        ...
    }
    "CounterIncludes": {
        "<document ID>": [
            {
                "DocumentId": "<document ID>",
                "CounterName": "<counter name>",
                "TotalValue": <integer>
            },
            { },
            ...
        ],
        "<document ID>": [ ],
        ...
    }
}
    Linebreaks are added for clarity.

    More Examples

    About Northwind, the database used in our examples.

    In this section:

    Get Multiple Documents

    Example cURL request: 

    curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
            id=shippers/1-A
            &id=shippers/2-A"
    Linebreaks are added for clarity.

    Response: 

    HTTP/1.1 200 OK
Server: nginx
Date: Thu, 12 Sep 2019 09:23:49 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "Hash-auWLG9xq3imTfRdJvlKIL32LhEM0IwJ20eiibWse0X8="
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
    "Results": [
        {
            "Name": "Speedy Express",
            "Phone": "(503) 555-9831",
            "@metadata": {
                "@collection": "Shippers",
                "@change-vector": "A:349-k50KTOC5G0mfVXKjomTNFQ",
                "@id": "shippers/1-A",
                "@last-modified": "2018-07-27T12:11:53.0317375Z"
            }
        },
        {
            "Name": "United Package",
            "Phone": "(503) 555-3199",
            "@metadata": {
                "@collection": "Shippers",
                "@change-vector": "A:351-k50KTOC5G0mfVXKjomTNFQ",
                "@id": "shippers/2-A",
                "@last-modified": "2018-07-27T12:11:53.0317596Z"
            }
        }
    ],
    "Includes": {}
}

    Example cURL request: 

    curl -X GET "http://live-test.ravendb.net/databases/Demo/docs?
            id=products/48-A
            &include=Supplier
            &include=Category"
    Linebreaks are added for clarity.

    Response: 

    HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 10:40:27 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "Hash-9oK1ZcWmNa9SD9hP8m0vT355ztQuFnF/vKD5ILyI/KY="
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
    "Results": [
        {
            "Name": "Chocolade",
            "Supplier": "suppliers/22-A",
            "Category": "categories/3-A",
            "QuantityPerUnit": "10 pkgs.",
            "PricePerUnit": 12.7500,
            "UnitsInStock": 22,
            "UnitsOnOrder": 15,
            "Discontinued": false,
            "ReorderLevel": 25,
            "@metadata": {
                "@collection": "Products",
                "@change-vector": "A:285-k50KTOC5G0mfVXKjomTNFQ",
                "@id": "products/48-A",
                "@last-modified": "2018-07-27T12:11:53.0300420Z"
            }
        }
    ],
    "Includes": {
        "suppliers/22-A": {
            "Contact": {
                "Name": "Dirk Luchte",
                "Title": "Accounting Manager"
            },
            "Name": "Zaanse Snoepfabriek",
            "Address": {
                "Line1": "Verkoop Rijnweg 22",
                "Line2": null,
                "City": "Zaandam",
                "Region": null,
                "PostalCode": "9999 ZZ",
                "Country": "Netherlands",
                "Location": null
            },
            "Phone": "(12345) 1212",
            "Fax": "(12345) 1210",
            "HomePage": null,
            "@metadata": {
                "@collection": "Suppliers",
                "@change-vector": "A:399-k50KTOC5G0mfVXKjomTNFQ",
                "@id": "suppliers/22-A",
                "@last-modified": "2018-07-27T12:11:53.0335729Z"
            }
        },
        "categories/3-A": {
            "Name": "Confections",
            "Description": "Desserts, candies, and sweet breads",
            "@metadata": {
                "@attachments": [
                    {
                        "Name": "image.jpg",
                        "Hash": "1QxSMa3tBr+y8wQYNre7E9UJFFVTNWGjVoC+IC+gSSs=",
                        "ContentType": "image/jpeg",
                        "Size": 47955
                    }
                ],
                "@collection": "Categories",
                "@change-vector": "A:2092-k50KTOC5G0mfVXKjomTNFQ",
                "@flags": "HasAttachments",
                "@id": "categories/3-A",
                "@last-modified": "2018-07-27T12:16:44.1738714Z"
            }
        }
    }
}

    Get Document Metadata Only

    Example cURL request:

    curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
            id=orders/19-A
            &metadataOnly=true"
    Linebreaks are added for clarity.

    Response:

    HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 10:52:28 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:453-k50KTOC5G0mfVXKjomTNFQ"
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
    "Results": [
        {
            "@metadata": {
                "@collection": "Orders",
                "@change-vector": "A:453-k50KTOC5G0mfVXKjomTNFQ",
                "@flags": "HasRevisions",
                "@id": "orders/19-A",
                "@last-modified": "2018-07-27T12:11:53.0476121Z"
            }
        }
    ],
    "Includes": {}
}

    Get Document Counters

    Example cURL request:

    curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
            id=products/48-A
            &counter=MoLtUaE"
    Linebreaks are added for clarity.

    Response:

    HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 12:26:04 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:5957-k50KTOC5G0mfVXKjomTNFQ"
Vary: Accept-Encoding
Raven-Server-Version: 4.2.4.42

{
    "Results": [
        {
            "Name": "Chocolade",
            "Supplier": "suppliers/22-A",
            "Category": "categories/3-A",
            "QuantityPerUnit": "10 pkgs.",
            "PricePerUnit": 12.7500,
            "UnitsInStock": 22,
            "UnitsOnOrder": 15,
            "Discontinued": false,
            "ReorderLevel": 25,
            "@metadata": {
                "@collection": "Products",
                "@counters": [
                    "#OfCounters",
                    "MoLtUaE"
                ],
                "@change-vector": "A:285-k50KTOC5G0mfVXKjomTNFQ",
                "@id": "products/48-A",
                "@flags": "HasRevisions, HasCounters",
                "@last-modified": "2019-09-10T12:25:44.1759382Z"
            }
        }
    ],
    "Includes": {},
    "CounterIncludes": {
        "orders/19-A": [
            {
                "DocumentId": "orders/19-A",
                "CounterName": "MoLtUaE",
                "TotalValue": 42
            }
        ]
    }
}

    (Note that the standard Northwind data does not contain any counters when it is generated in the studio - counters were added to "products/48-A" for this example)

    related articlesRelated Articles

    Getting Started

    Client API

    Commands
    REST API

    Server

    Home / Docs / Client Api / Rest Api / Document Commands / Get Documents By Id