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
Text Search
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