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

    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"
            }
        }
    ]
}

    see on GitHub

    related articlesRelated Articles

    Getting Started

    Client API

    Commands
    REST API
    Home / Docs / Client Api / Rest Api / Document Commands / Get Documents By Prefix