v8 v7 v6 v5 v4 v3
Edit Page

Read Documents

Introduction

This page provides examples of query operations using the GET method.

You will learn how to get documents from a collection, optionally specifying a query, sort criteria, fields projections options and deal with pagination.

You will also learn hot to get a single document knowing its _id.

Before running the example requests

The following step by step tutorial assumes that RESTHeart is running on localhost with the default configuration: the database restheart is bound to / and the user admin exists with default password secret.

Tip
 To run RESTHeart refer to Setup section.

To create the restheart db, run the following:

Request Execute with restninja 
PUT / HTTP/1.1

The examples on this page use the inventory collection. To create the inventory collection, run the following:

Request Execute with restninja 
PUT /inventory HTTP/1.1

To populate the inventory collection, run the following:

Request Execute with restninja 
POST /inventory HTTP/1.1

[
   { "item": "journal", "qty": 25, "size": { "h": 14, "w": 21, "uom": "cm" }, "status": "A" },
   { "item": "notebook", "qty": 50, "size": { "h": 8.5, "w": 11, "uom": "in" }, "status": "A" },
   { "item": "paper", "qty": 100, "size": { "h": 8.5, "w": 11, "uom": "in" }, "status": "D" },
   { "item": "planner", "qty": 75, "size": { "h": 22.85, "w": 30, "uom": "cm" }, "status": "D" },
   { "item": "postcard", "qty": 45, "size": { "h": 10, "w": 15.25, "uom": "cm" }, "status": "A" }
]

GETting Documents from a Collection

To GET documents from a collection, run the following:

Request Execute with restninja 
GET /inventory HTTP/1.1

Paging

The response is paginated, i.e. only a subset of the collection’s document is returned in the response array.

The number of documents to return is controlled via the pagesize query parameter. Its default value is 100, maximum allowable size is 1000.

The page to return is specified with the page query parameter.

Paging Examples

Return documents of second page with 3 documents per page
Request Execute with restninja 
GET /inventory?page=2&pagesize=3 HTTP/1.1

Dot notation

It’s possible to use the "dot notation" to specify fields within an sub-document, for example:

GET /inventory?keys={'header.item':1}&sort={'header.status':1} HTTP/1.1

Filtering

The filter query parameter allows to specify conditions on the documents to be returned in the form of a mongodb query.

Filtering Examples

Return documents whose quantity is more than 50
Request Execute with restninja 
GET /inventory?filter={"qty":{"$gt":50}} HTTP/1.1
Return documents whose quantity is more than 25 and with status set to "D" value
Request Execute with restninja 
GET /inventory?filter={"$and":[{"qty":{"$gt":75}},{"status":"D"}]} HTTP/1.1

or equivalently:

Request Execute with restninja 
GET /inventory?filter={"qty":{"$gt":75}}&filter={"status":"D"} HTTP/1.1

Counting

Use _size keyword after the collection path to retrieve the number of documents that meets the filter condition (if present).

Counting Examples

Return the number of documents of "inventory" collection
Request Execute with restninja 
GET /inventory/_size?filter={"status":"A"} HTTP/1.1

Sorting

Sorting is controlled by the sort query parameter.

Sort simple format

The sort simplified format is :

sort=[ |-]<fieldname>
Note
 Specify multiple sort options using multiple sort query parameters 
GET /inventory?sort=qty&sort=-status HTTP/1.1

Sort JSON expression format

sort can also be a MongoDB sort expression.

sort={"field": 1}

Default sorting

The default sorting of the documents is by the id descending.

In the usual case, where the type of the ids of the documents is ObjectId, this makes the documents sorted by creation time by default (ObjectId have a timestamp in the most significant bits).

RESTHeart returns data in pages (default being 100) and it is stateless. This means that two requests use different db cursors. A default sorting makes sure that requests on different pages returns documents in a well defined order.

Tip
 Default sorting could impact performances for some use cases. To disable default sorting add the`sort={}` query parameter

Sorting Examples

Sort by status ascending
Request Execute with restninja 
GET /inventory?sort=status HTTP/1.1

or equivalently:

Request Execute with restninja 
GET /inventory?sort={"status":1} HTTP/1.1
Sort by status descending
Request Execute with restninja 
GET /inventory?sort=-status HTTP/1.1

or equivalently:

Request Execute with restninja 
GET /inventory?sort={"status":-1} HTTP/1.1
Sort by status ascending and qty descending
Request Execute with restninja 
GET /inventory?sort=status&sort=-qty HTTP/1.1

or equivalently:

Request Execute with restninja 
GET /inventory?sort={"status":1,"qty":-1} HTTP/1.1
Sort by search score
Note
 This is only possible with json expression format

create a text index

Request Execute with restninja 
PUT /inventory/_indexes/text HTTP/1.1

{"keys": {"item": "text" }}

sort by score

Request Execute with restninja 
GET /inventory?filter={"$text":{"$search":"paper"}}&keys={"item":1,"score":{"$meta":"textScore"}}&sort={"score":{"$meta":"textScore"}} HTTP/1.1

Projection

Projection limits the fields to return for all matching documents, specifying the inclusion or the exclusion of fields.

This is done via the keys query parameter.

Projection Examples

Only return the property item
Request Execute with restninja 
GET /inventory?keys={'item':1} HTTP/1.1
Return all but the property item
Request Execute with restninja 
GET /inventory?keys={'item':0} HTTP/1.1
Only return the properties item and qty
Request Execute with restninja 
GET /inventory?keys={'item':1}&keys={'qty':1} HTTP/1.1

Hint

Hint allows overriding MongoDB’s default index selection and query optimization process. See cursor hint on MongoDB documentation.

This is done via the hint query parameter.

Specify the index using an index specification document, either as a JSON object or a compact string representation (e.g., ?hint=+key or ?hint=-key). Starting from version 8.3, you can also specify the index by name (e.g., ?hint=indexName).

For version 8.3: Use the compact string representation by prefixing the field name with + or -. Note that the + sign must be URL-encoded as %2B; otherwise, it will be interpreted as a space. If the ?hint value does not start with + or -, it will be treated as an index name.

Use $natural to force the query to perform a forwards collection scan.

Hint Examples

Before running the following examples create the following indexes:

Request Execute with restninja 
PUT /inventory/_indexes/item HTTP/1.1

{"keys": {"item": 1}}
Request Execute with restninja 
PUT /inventory/_indexes/status HTTP/1.1

{"keys":{"status": 1 }}
Use the index on item field

The following example returns all documents in the collection named coll using the index on the item field.

Request Execute with restninja 
GET /inventory?hint={'item':1} HTTP/1.1
Use the index on item and status fields using the compact string format

The following example returns the documents using the indexes item and reverse status.

Request Execute with restninja 
GET /inventory?hint=+item&hint=-status HTTP/1.1
Perform a forwards collection scan

The following example returns the documents using a forwards collection scan.

Request Execute with restninja 
GET /inventory?hint={'$natural':1} HTTP/1.1
Perform a reverse collection scan

The following example returns the documents using a reverse collection scan.

Request Execute with restninja 
GET /inventory?hint={'$natural':-1} HTTP/1.1