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 POST
Request
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 GET
Request
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 GET
Request
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, ... ]