Get Documents by Prefix



Basic Example

This is a cURL request to retrieve all documents whose IDs begin with the prefix "ship" from a database named "Example" on our playground server:

curl -X GET "http://live-test.ravendb.net/databases/Example/docs?startsWith=ship"

Response:

HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Sep 2019 15:25:34 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:2137-pIhs+72n6USJoZ5XIvTHvQ"
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"
            }
        },
        {
            "Name": "Federal Shipping",
            "Phone": "(503) 555-9931",
            "@metadata": {
                "@collection": "Shippers",
                "@change-vector": "A:353-k50KTOC5G0mfVXKjomTNFQ",
                "@id": "shippers/3-A",
                "@last-modified": "2018-07-27T12:11:53.0317858Z"
            }
        }
    ]
}

Request Format

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

curl -X GET "<server URL>/databases/<database name>/docs?
            startsWith=<prefix>
            &matches=<suffix>|<suffix>|...
            &exclude=<suffix>|<suffix>|...
            &startAfter=<document ID>
            &start=<integer>
            &pageSize=<integer>
            &metadataOnly=<boolean>"
--header "If-None-Match: <hash>"
Linebreaks are added for clarity.

Query String Parameters

Parameter Description Required
startsWith Retrieve all documents whose IDs begin with this string. If the value of this parameter is left empty, all documents in the database are retrieved. Yes
matches Retrieve documents whose IDs are exactly <startsWith>+<matches>. Accepts multiple values separated by a pipe character: ' | ' . Use ? to represent any single character, and * to represent any string. No
exclude Exclude documents whose IDs are exactly <startsWith>+<exclude>. Accepts multiple values separated by a pipe character: ' | ' . Use ? to represent any single character, and * to represent any string. No
startAfter Retrieve only the results after the first document ID that begins with this prefix. No
start Number of results to skip. No
pageSize Maximum number of results to retrieve. No
metadataOnly Set this parameter to true to retrieve only the document metadata from each result. No

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 were successfully retrieved. If no documents with the specified prefix could be found, the results array is empty.
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.

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.
Raven-Server-Version Version of RavenDB that the responding server is running

Body

Retrieved documents are sorted in ascending lexical order of their document IDs. A retrieved document is identical in contents and format to the document stored in the server - unless the metadataOnly parameter is set to true.

This is the general JSON format of the response body:

{
    "Results": [ 
        { 
            "<field>":"<value>",
            ...
            "@metadata":{
                ...
            }
        },
        { <document contents> },
        ...
    ]
}
Linebreaks are added for clarity.

More Examples

About Northwind, the database used in our examples.

In this section:


Get Using matches

cURL request:

curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
            startsWith=shipp
            &matches=ers/3-A|ers/1-A"
Linebreaks are added for clarity.

Response:

HTTP/1.1 200 OK
Server: nginx
Date: Thu, 12 Sep 2019 10:57:58 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:5972-k50KTOC5G0mfVXKjomTNFQ"
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": "Federal Shipping",
            "Phone": "(503) 555-9931",
            "@metadata": {
                "@collection": "Shippers",
                "@change-vector": "A:353-k50KTOC5G0mfVXKjomTNFQ",
                "@id": "shippers/3-A",
                "@last-modified": "2018-07-27T12:11:53.0317858Z"
            }
        }
    ]
}

Get Using matches and exclude

cURL request:

curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
            startsWith=shipp
            &matches=ers/3-A|ers/1-A
            &exclude=ers/3-A"
Linebreaks are added for clarity.

Response:

HTTP/1.1 200 OK
Server: nginx
Date: Thu, 12 Sep 2019 12:24:50 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
ETag: "A:5972-k50KTOC5G0mfVXKjomTNFQ"
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"
            }
        }
    ]
}

Get Using startAfter

cURL request:

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

Response:

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

{
    "Results": [
        {
            "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"
            }
        },
        {
            "Name": "Federal Shipping",
            "Phone": "(503) 555-9931",
            "@metadata": {
                "@collection": "Shippers",
                "@change-vector": "A:353-k50KTOC5G0mfVXKjomTNFQ",
                "@id": "shippers/3-A",
                "@last-modified": "2018-07-27T12:11:53.0317858Z"
            }
        }
    ]
}

Page Results

cURL request:

curl -X GET "http://live-test.ravendb.net/databases/Example/docs?
            startsWith=product
            &start=50
            &pageSize=2"
Linebreaks are added for clarity.

Response:

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

{
    "Results": [
        {
            "Name": "Pâté chinois",
            "Supplier": "suppliers/25-A",
            "Category": "categories/6-A",
            "QuantityPerUnit": "24 boxes x 2 pies",
            "PricePerUnit": 24.0000,
            "UnitsInStock": 25,
            "UnitsOnOrder": 115,
            "Discontinued": false,
            "ReorderLevel": 20,
            "@metadata": {
                "@collection": "Products",
                "@change-vector": "A:8170-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
                "@id": "products/55-A",
                "@last-modified": "2018-07-27T12:11:53.0303784Z"
            }
        },
        {
            "Name": "Gnocchi di nonna Alice",
            "Supplier": "suppliers/26-A",
            "Category": "categories/5-A",
            "QuantityPerUnit": "24 - 250 g pkgs.",
            "PricePerUnit": 38.0000,
            "UnitsInStock": 26,
            "UnitsOnOrder": 21,
            "Discontinued": false,
            "ReorderLevel": 30,
            "@metadata": {
                "@collection": "Products",
                "@change-vector": "A:8172-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
                "@id": "products/56-A",
                "@last-modified": "2018-07-27T12:11:53.0304385Z"
            }
        }
    ]
}

Note that the document ID numbers are 55 and 56 rather than the expected 51 and 52 because results are sorted in lexical order.


Get Document Metadata Only

cURL request:

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

Response:

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

{
    "Results": [
        {
            "@metadata": {
                "@collection": "Regions",
                "@change-vector": "A:9948-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
                "@id": "regions/1-A",
                "@last-modified": "2018-07-27T12:11:53.2016685Z"
            }
        },
        {
            "@metadata": {
                "@collection": "Regions",
                "@change-vector": "A:9954-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
                "@id": "regions/2-A",
                "@last-modified": "2018-07-27T12:11:53.2021826Z"
            }
        },
        {
            "@metadata": {
                "@collection": "Regions",
                "@change-vector": "A:9950-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
                "@id": "regions/3-A",
                "@last-modified": "2018-07-27T12:11:53.2018086Z"
            }
        },
        {
            "@metadata": {
                "@collection": "Regions",
                "@change-vector": "A:9952-k50KTOC5G0mfVXKjomTNFQ, A:1887-0N64iiIdYUKcO+yq1V0cPA, A:6214-xwmnvG1KBkSNXfl7/0yJ1A",
                "@id": "regions/4-A",
                "@last-modified": "2018-07-27T12:11:53.2019223Z"
            }
        }
    ]
}