Looking for Cloud Services or Professional Support? Check restheart.com

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:

PUT / HTTP/1.1

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

PUT /inventory HTTP/1.1

To populate the inventory collection, run the following:

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:

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

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

GET /inventory?filter={"qty":{"$gt":50}} HTTP/1.1

Return documents whose quantity is more than 25 and with status set to "D" value

GET /inventory?filter={"$and":[{"qty":{"$gt":75}},{"status":"D"}]} HTTP/1.1

or equivalently:

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

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

GET /inventory?sort=status HTTP/1.1

or equivalently:

GET /inventory?sort={"status":1} HTTP/1.1

Sort by status descending

GET /inventory?sort=-status HTTP/1.1

or equivalently:

GET /inventory?sort={"status":-1} HTTP/1.1

Sort by status ascending and qty descending

GET /inventory?sort=status&sort=-qty HTTP/1.1

or equivalently:

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

PUT /inventory/_indexes/text HTTP/1.1

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

sort by score

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

GET /inventory?keys={'item':1} HTTP/1.1

Return all but the property item

GET /inventory?keys={'item':0} HTTP/1.1

Only return the properties item and qty

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 by the index specification document, either using a json document or the compact string representation; specifying the index by name is not supported.

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

Hint Examples

Before running the following examples create the following indexes:

PUT /inventory/_indexes/item HTTP/1.1

{"keys": {"item": 1}}
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.

GET /inventory?hint={'item':1} HTTP/1.1

Use the compound index on age and timestamp fields using the compact string format

The following example returns the documents using the compound index on the item and reverse status fields.

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.

GET /inventory?hint={'$natural':1} HTTP/1.1

Perform a reverse collection scan

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

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