v8 v7 v6 v5 v4 v3
Edit Page

Reading Documents

This page demonstrates how to query MongoDB collections through RESTHeart’s REST API using the GET method.

Basic Document Retrieval

To retrieve documents from a collection, send a GET request to the collection URI:

Request Execute with restninja 
GET /inventory HTTP/1.1

This returns all documents in the collection, subject to pagination limits.

Pagination

RESTHeart always paginates results to prevent performance issues with large collections. By default, only 100 documents are returned per request.

Control pagination with these query parameters:

  • page: Which page of results to return (starting from 1)

  • pagesize: Number of documents per page (1-1000, default is 100)

Example - get the second page with 3 documents per page:

Request Execute with restninja 
GET /inventory?page=2&pagesize=3 HTTP/1.1

Filtering Documents

Use the filter parameter to specify which documents to return using MongoDB query syntax:

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

This returns only documents where the quantity is greater than 50.

Complex Filters

Combine multiple conditions using MongoDB operators like $and:

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

Alternatively, you can use multiple filter parameters:

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

Counting Documents

Instead of retrieving documents, you can count them by appending _size to the collection URI:

Request Execute with restninja 
GET /inventory/_size?filter={"status":"A"} HTTP/1.1

This returns the count of documents with status "A".

Projection (Selecting Fields)

Use the keys parameter to specify which fields to include or exclude from the results:

Include only specific fields

Request Execute with restninja 
GET /inventory?keys={'item':1} HTTP/1.1

This returns only the _id and item fields for each document.

Exclude specific fields

Request Execute with restninja 
GET /inventory?keys={'item':0} HTTP/1.1

This returns all fields except item for each document.

Include multiple specific fields

Request Execute with restninja 
GET /inventory?keys={'item':1}&keys={'qty':1} HTTP/1.1

This returns only the _id, item, and qty fields.

Sorting Results

Control the order of results with the sort parameter:

Simple Format

For simple sorting, use sort=fieldname for ascending order or sort=-fieldname for descending order:

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

This sorts documents by status in ascending order.

For descending order:

Request Execute with restninja 
GET /inventory?sort=-status HTTP/1.1

Multiple Fields Sorting

Use multiple sort parameters to sort by multiple fields:

Request Execute with restninja 
GET /inventory?sort=status&sort=-qty HTTP/1.1

This sorts first by status (ascending) and then by quantity (descending).

JSON Expression Format

You can also use MongoDB’s sort expression format:

Request Execute with restninja 
GET /inventory?sort={"status":1,"qty":-1} HTTP/1.1

Accessing Nested Properties

Use dot notation to access nested document fields or array elements:

GET /inventory?keys={'size.h':1}&sort={'size.uom':1} HTTP/1.1

This returns only the height field from the size subdocument and sorts by the unit of measure.

Using Indexes with Hint

Override MongoDB’s default index selection with the hint parameter:

Create Indexes First

Before using hints, create the 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 }}

Using Hint

Specify which index to use:

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

Or use the compact string format:

Request Execute with restninja 
GET /inventory?hint=+item&hint=-status HTTP/1.1
Note
 When using the + sign in URLs, encode it as %2B to prevent it being interpreted as a space.

Special Query Operations

Collection Scan

Force a collection scan instead of using indexes:

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

For a reverse collection scan:

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

Text Search

If you have a text index, you can perform text searches:

First, create the text index:

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

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

Then search and sort by relevance score:

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