{NOTE: }
-
Use this endpoint with the
PUTmethod to upload a new document to the database, or update an existing one:
<server URL>/databases/<database name>/docs -
In this page:
{NOTE/}
{PANEL: Examples}
These are cURL requests to a database named "Example" on our playground server to store and then modify a document.
{CODE-BLOCK: bash} curl -X PUT "http://live-test.ravendb.net/databases/Example/docs?id=person/1-A" -d "{ "FirstName":"Jane", "LastName":"Doe", "Age":42, "@metadata":{ "@collection":"People" } }" {CODE-BLOCK/} Linebreaks are added for clarity.
Response:
{CODE-BLOCK: Http} HTTP/1.1 201 status: 201 Server: nginx Date: Tue, 27 Aug 2019 10:58:28 GMT Content-Type: application/json; charset=utf-8 Transfer-Encoding: chunked Connection: keep-alive Content-Encoding: gzip Vary: Accept-Encoding Raven-Server-Version: 4.2.3.42
{ "Id":"person/1-A", "ChangeVector":"A:1" } {CODE-BLOCK/}
{CODE-BLOCK: bash} curl -X PUT "http://live-test.ravendb.net/databases/Example/docs?id=person/1-A" --header "If-Match: A:1-L8hp6eYcA02dkVIEifGfKg" -d "{ "FirstName":"John", "LastName":"Smith", "Age":24, "@metadata":{ "@collection": "People" } }" {CODE-BLOCK/}
The response is the same as the previous response except for the updated change vector:
{CODE-BLOCK: Http} HTTP/1.1 201 status: 201 Server: nginx Date: Tue, 27 Aug 2019 10:59:54 GMT Content-Type: application/json; charset=utf-8 Transfer-Encoding: chunked Connection: keep-alive Content-Encoding: gzip Vary: Accept-Encoding Raven-Server-Version: 4.2.3.42
{ "Id":"person/1-A", "ChangeVector":"A:3" }
{CODE-BLOCK/}
{PANEL/}
{PANEL: Request Format}
This is the general format of the cURL request:
{CODE-BLOCK: bash} curl -X PUT "/databases//docs?id=" --header "If-Match: " -d "" {CODE-BLOCK/}
| Parameter | Description | Required |
|---|---|---|
| id | Unique ID under which the new document will be stored, or the ID of an existing document to be updated | Yes |
| Header | Description | Required |
|---|---|---|
| If-Match | When updating an existing document, this header passes the document's expected change vector. If this change vector doesn't match the document's server-side change vector, a concurrency exception is thrown. | No |
The body contains a JSON document. This will replace the existing document with the specified ID if one exists. Otherwise, it will become a new document with the specified ID.
{CODE-BLOCK: powershell}
{
"": "",
...
"@metadata": {
"@collection": "",
...
}
}
{CODE-BLOCK/}
Depending on the shell you're using to run cURL, you will probably need to escape all double quotes within the request body
using a backslash: " -> \".
When updating an existing document, you'll need to include its collection
name in the metadata or an exception will be thrown. Exceptions to this rule are documents in the collection @empty -
i.e. not in any collection. A document's collection cannot be modified.
Another way to make this request is to save your document as a file (such as a .txt), and pass the path to that file in
the request body:
{CODE-BLOCK: batch} curl -X PUT "/databases//docs?id=" -d "<@path/to/yourDocument.txt>" {CODE-BLOCK/}
{PANEL/}
{PANEL: Response Format}
The response body is JSON and contains the document ID and current change vector:
{CODE-BLOCK: javascript} { "Id": "", "ChangeVector": "" } {CODE-BLOCK/}
| Header | Description |
|---|---|
| Content-Type | MIME media type and character encoding. This should always be: application/json; charset=utf-8. |
| Raven-Server-Version | Version of RavenDB the responding server is running |
| HTTP Status Code | Description |
|---|---|
201 |
The document was successfully stored / updated |
409 |
The change vector submitted did not match the server-side change vector. A concurrency exception is thrown. |
500 |
Server error, e.g. when the submitted document's collection tag did not match the specified document's collection tag. |
{PANEL/}
- Get All Documents
- Get Documents by ID
- Get Documents by Prefix
- Delete a Document
- Batch Commands
- What is a Collection
### Server