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:

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:

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:

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:

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

Alternatively, you can use multiple filter parameters:

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:

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

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

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

Exclude specific fields

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

This returns all fields except item for each document.

Include multiple specific fields

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:

GET /inventory?sort=status HTTP/1.1

This sorts documents by status in ascending order.

For descending order:

GET /inventory?sort=-status HTTP/1.1

Multiple Fields Sorting

Use multiple sort parameters to sort by multiple fields:

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:

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:

PUT /inventory/_indexes/item HTTP/1.1

{"keys": {"item": 1}}
PUT /inventory/_indexes/status HTTP/1.1

{"keys":{"status": 1 }}

Using Hint

Specify which index to use:

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

Or use the compact string format:

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:

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

For a reverse collection scan:

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

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

First, create the text index:

PUT /inventory/_indexes/text HTTP/1.1

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

Then search and sort by relevance score:

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