Skip to Navigation
Commands: Documents: Get
There are few methods that allow you to retrieve documents from a database:
- Get
- Get - multiple documents
- GetDocuments
- StartsWith
Get
Get can be used to retrieve a single document.
Syntax
curl \
http://{serverUrl}/databases/{databaseName}/docs?id={key} \
-X GET \
--header "If-None-Match:{etag}"
curl \
http://{serverUrl}/databases/{databaseName}/docs/{key} \
-X GET \
--header "If-None-Match:{etag}"Request
| Query parameter | Required | Description |
|---|---|---|
| key | Yes | unique key under which document is stored |
| Header | Required | Description |
|---|---|---|
| If-None-Match | No | Used to pass document Etag |
Response
| Status code | Description |
|---|---|
200 |
OK |
404 |
Not found |
304 |
Not modified |
| Return Value | Description |
|---|---|
| payload | json representing document |
| Header | Description |
|---|---|
| ETag | document ETag |
| __document_id | Document id |
| Last-Modified | Date of last modification |
Example
Get document under key user/100.
curl -X GET http://localhost:8080/docs/user/100
< HTTP/1.1 200 OK
< Last-Modified: Thu, 06 Nov 2014 10:58:52 GMT
< ETag: "01000000-0000-0008-0000-00000000000A"
< __document_id: user/100
{ FirstName: 'Bob', LastName: 'Smith', Address: '5 Elm St' }
Get - multiple documents
Get can also be used to retrieve a list of documents.
Syntax
curl \
http://{serverUrl}/databases/{databaseName}/queries/? \
metadata-only={metadataOnly}& \
include={includePath}& \
transformer={transformerName}& \
tp-{param}={value}& \
id={documentKey} \
-X GET
curl \
http://{serverUrl}/databases/{databaseName}/queries/? \
metadata-only={metadataOnly}& \
include={includePath}& \
transformer={transformerName}& \
tp-{param}={value}& \
id={documentKey} \
-X POSTRequest
| Method | Description |
|---|---|
GET |
document ids length < 1024 |
PUT |
document ids length > 1024 (pass them as payload) |
| Query parameter | Required | Multiple allowed | Description |
|---|---|---|---|
| id | Yes | Yes | document id to load |
| include | No | Yes | include paths |
| transformer | No | No | transformerName to use |
| tp-{param} | No | Yes | Transformer parameter |
| metadata-only | No | No | Fetch only metadata |
Response
| Status code | Description |
|---|---|
200 |
OK |
| Return Value | Description |
|---|---|
| Results | List of requested documents |
| Includes | List of included documents |
Example I
Get documents with ids: products/1 and products/2.
curl -X GET "http://localhost:8080/databases/http/queries/?id=products%2F1&id=products%2F2"
< HTTP/1.1 200 OK
{
"Results":
[
{"Name":"orange","Price":0.0,"@metadata":...},
{"Name":"apple","Price":0.0, "@metadata":...}
],
"Includes":
[]
}Example II - using includes
Get documents with ids: products/1 and products/2. Include Category.
curl -X GET "http://localhost:8080/databases/NorthWind/queries/?include=Category&id=products%2F1&id=products%2F2"
< HTTP/1.1 200 OK
{"Results":[
{"Name":"Chai","Category":"categories/1", ... },
{"Name":"Chang","Category":"categories/1", ... }
],
"Includes":[
{"Name":"Beverages",...}
]
}Example III - missing documents
Assuming that products/9999 does not exist.
curl -X GET "http://localhost:8080/databases/NorthWind/queries/?&include=Category&id=products%2F1&id=products%2F9999&id=products%2F2"
< HTTP/1.1 200 OK
{"Results":[
{"Name":"Chai","Category":"categories/1", ... },
null,
{"Name":"Chang","Category":"categories/1", ... }
],
"Includes":[]
}
GetDocuments
GetDocuments can be used to retrieve multiple documents.
Syntax
curl \
http://{serverUrl}/databases/{databaseName}/docs? \
start={start}& \
pageSize={pageSize}& \
metadata-only={metadataOnly}
-X GETRequest
| Query parameter | Required | Description |
|---|---|---|
| start | No | number of documents that should be skipped |
| pageSize | No | maximum number of documents that will be retrieved |
| metadata-only | No | specifies if only document metadata should be returned |
Response
| Status code | Description |
|---|---|
200 |
OK |
| Return Value | Description |
|---|---|
| payload | List of json documents |
Example
curl -X GET "http://localhost:8080/databases/NorthWind/docs?start=0&pageSize=32"
< HTTP/1.1 200 OK
[ json, json, ... ]
StartsWith
StartsWith can be used to retrieve multiple documents for a specified key prefix.
Syntax
curl \
http://{serverName}/databases/{databaseName}/docs? \
startsWith={startsWith}& \
matches={matches}& \
exclude={exclude}& \
start={start}& \
pageSize={pageSize}& \
metadata-only={metadata}& \
skipAfter={skipAfter}& \
transformer={transformer}& \
tp-{param}={value} \
-X GETRequest
| Query parameter | Required | Multiple allowed | Description |
|---|---|---|---|
| startsWith | Yes | No | prefix for which documents should be returned |
| matches | No | No | separated values for which document keys (after 'keyPrefix') should be matched ('?' any single character, '*' any characters) |
| exclude | No | No | pipe ('|') separated values for which document keys (after 'keyPrefix') should not be matched ('?' any single character, '*' any characters) |
| start | No | No | number of documents that should be skipped |
| pageSize | No | No | maximum number of documents that will be retrieved |
| metadataOnly | No | No | specifies if only document metadata should be returned |
| skipAfter | No | No | skip document fetching until given key is found and return documents after that key (default: null) |
| transformer | No | No | name of a transformer that should be used to transform the results |
| tp-{param} | No | Yes | parameters that will be passed to transformer |
Response
| Status code | Description |
|---|---|
200 |
OK |
409 |
Conflict |
| Return Value | Description |
|---|---|
| payload | List of json documents |
Example I
Return up to 128 documents with key that starts with 'products'.
curl -X GET "http://localhost:8080/databases/NorthWind/docs?startsWith=products%2F&matches=&exclude=&start=0&pageSize=128"
< HTTP/1.1 200 OK
[ jsonDocument, jsonDocument, ... ]Example II
Return up to 128 documents with key that starts with 'products/' and rest of the key begins with "1" or "2" e.g. products/10, products/25
curl -X GET "http://localhost:8080/databases/NorthWind/docs?startsWith=products%2F&matches=1*%7C2*&exclude=&start=0&pageSize=128"
< HTTP/1.1 200 OK
[ jsonDocument, jsonDocument, ... ]Example III
Return up to 128 documents with key that starts with 'products/' and rest of the key have length of 3, begins and ends with "1" and contains any character at 2nd position e.g. products/101, products/1B1.
curl -X GET "http://localhost:8080/databases/NorthWind/docs?startsWith=products%2F&matches=1%3F1&exclude=&start=0&pageSize=128"
< HTTP/1.1 200 OK
[ jsonDocument, jsonDocument, ... ]
Related Articles