v9 (current) v8
Edit Page

Reading Documents

RESTHeart Cloud

This page covers everything you need to know about querying MongoDB data through RESTHeart’s REST API.

What You’ll Learn

  • Pagination - Control how many documents are returned

  • Filtering - Select documents based on criteria

  • Projection - Choose which fields to include

  • Sorting - Order results by any field

  • Counting - Get document counts (exact or estimated) without retrieving data

  • Advanced queries - Text search, indexes, and nested properties

Start with the basics and work your way through, or jump to a specific section using the page navigation. This page demonstrates how to query MongoDB collections through RESTHeart’s REST API using the GET method.

🔧 Configuration

▼
Sets localhost:8080 with admin:secret
Values are saved in your browser

⚡ Setup Guide

▼

To run the examples on this page, you need a RESTHeart instance.

Option 1: Use RESTHeart Cloud (Recommended)

The fastest way to get started is with RESTHeart Cloud. Create a free service in minutes:

  1. Sign up at cloud.restheart.com

  2. Create a free API service

  3. Set up your root user following the Root User Setup guide

  4. Use the configuration panel above to set your service URL and credentials

Tip
 All code examples on this page will automatically use your configured RESTHeart Cloud credentials.

Option 2: Run RESTHeart Locally

If you prefer local development, follow the Setup Guide to install RESTHeart on your machine.

Note
 Local instances run at http://localhost:8080 with default credentials admin:secret

Create the Inventory Collection

The example requests on this page use the inventory collection. If not already created, run the following:

cURL

curl -i -X PUT [INSTANCE-URL]/inventory -H "Authorization: Basic [BASIC-AUTH]"

curl -i -X POST [INSTANCE-URL]/inventory?wm=upsert -H "Authorization: Basic [BASIC-AUTH]" \
  -d '[
    { "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" }
  ]'

HTTPie

http PUT [INSTANCE-URL]/inventory Authorization:"Basic [BASIC-AUTH]"

echo '[
   { "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" }
]' | http POST [INSTANCE-URL]/inventory wm==upsert Authorization:"Basic [BASIC-AUTH]"

JavaScript

const data = [
   { "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" }
];

await fetch('[INSTANCE-URL]/inventory', {
  method: 'PUT',
  headers: { 'Authorization': 'Basic [BASIC-AUTH]' }
});

await fetch('[INSTANCE-URL]/inventory?wm=upsert', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: { 'Authorization': 'Basic [BASIC-AUTH]' }
});

Basic Document Retrieval

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

cURL

curl -i -X GET [RESTHEART-URL]/inventory \
  -H "Authorization: Basic [BASIC-AUTH]"

HTTPie

http GET [RESTHEART-URL]/inventory \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[RESTHEART-URL]/inventory', {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

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:

cURL

curl -i -X GET [RESTHEART-URL]/inventory?page=2&pagesize=3 \
  -H "Authorization: Basic [BASIC-AUTH]"

HTTPie

http GET [RESTHEART-URL]/inventory \
  Authorization:"Basic [BASIC-AUTH]" \
  page==2 \
  pagesize==3

JavaScript

fetch('[RESTHEART-URL]/inventory?page=2&pagesize=3', {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

Filtering Documents

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

cURL

curl -i -X GET "[RESTHEART-URL]/inventory" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode 'filter={"qty":{"$gt":50}}'

HTTPie

http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  filter=="{\"qty\":{\"\$gt\":50}}"

JavaScript

const filter = encodeURIComponent('{"qty":{"$gt":50}}');
fetch(`[RESTHEART-URL]/inventory?filter=${filter}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

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

Complex Filters

Combine multiple conditions using MongoDB operators like $and:

cURL

curl -i -X GET "[RESTHEART-URL]/inventory" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode 'filter={"$and":[{"qty":{"$gt":75}},{"status":"D"}]}'

HTTPie

http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  filter=="{\"\$and\":[{\"qty\":{\"\$gt\":75}},{\"status\":\"D\"}]}"

JavaScript

const filter = encodeURIComponent('{"$and":[{"qty":{"$gt":75}},{"status":"D"}]}');
fetch(`[RESTHEART-URL]/inventory?filter=${filter}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

Alternatively, you can use multiple filter parameters:

cURL

curl -i -X GET "[RESTHEART-URL]/inventory" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode 'filter={"qty":{"$gt":75}}' \
  --data-urlencode 'filter={"status":"D"}'

HTTPie

http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  filter=="{\"qty\":{\"\$gt\":75}}" \
  filter=="{\"status\":\"D\"}"

JavaScript

fetch('[RESTHEART-URL]/inventory?filter={"qty":{"$gt":75}}&filter={"status":"D"}', {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

Counting Documents

Use this rule:

  • Use _size when you only need a count.

  • Use count on GET /<coll> when you need documents and count metadata in the same response (for example pagination UIs).

You need Use

only the total number of matching documents

GET /<coll>/_size

a page of documents + total size / total pages

GET /<coll>?count&page=…​&pagesize=…​

Count-only request (_size):

cURL

curl -i -X GET "[RESTHEART-URL]/inventory/_size" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode 'filter={"status":"A"}'

HTTPie

http GET "[RESTHEART-URL]/inventory/_size" \
  Authorization:"Basic [BASIC-AUTH]" \
  filter=="{\"status\":\"A\"}"

JavaScript

const filter = encodeURIComponent('{"status":"A"}');
fetch(`[RESTHEART-URL]/inventory/_size?filter=${filter}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

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

If you also need the documents in the same response, request the collection with count:

cURL (docs + count metadata)

curl -i -X GET "[RESTHEART-URL]/inventory?count&page=1&pagesize=10" \
  -H "Authorization: Basic [BASIC-AUTH]"

With count, RESTHeart includes count metadata (such as _size and _total_pages) together with the returned documents.

Concrete examples:

Example 1: collection GET with count (documents + metadata)

Request:

GET /mydb/people?page=1&pagesize=2&count

Possible response body:

{
  "_size": 5,
  "_total_pages": 3,
  "_returned": 2,
  "_embedded": {
    "rh:doc": [
      { "_id": "1", "name": "Alice" },
      { "_id": "2", "name": "Bob" }
    ]
  }
}

Possible response header:

X-Count-Strategy: exact

Example 2: collection GET with count=estimated (no filter)

Request:

GET /mydb/people?page=1&pagesize=2&count=estimated

Possible response body:

{
  "_size": 5,
  "_total_pages": 3,
  "_returned": 2,
  "_embedded": {
    "rh:doc": [
      { "_id": "1", "name": "Alice" },
      { "_id": "2", "name": "Bob" }
    ]
  }
}

Possible response header:

X-Count-Strategy: estimated

Example 3: _size endpoint (count-only)

Request:

GET /mydb/people/_size?count=estimated

Possible response body:

{ "_size": 5 }

Possible response header:

X-Count-Strategy: estimated

Estimated Counts (Fast Counting on Large Collections)

By default _size runs MongoDB’s countDocuments, which scans every document matching the filter. On very large collections (millions of documents) or with filters on multikey arrays this can be slow or time out.

Adding count=estimated opts in to a metadata-based count using estimatedDocumentCount (O(1), no I/O on the data files):

Note

Using /_size already means "count-only request".

  • /<coll>/_size and /<coll>/_size?count produce the same result (exact count).

  • Adding count is redundant on /_size.

  • Use count=estimated only when you want metadata-based counting (no filter).

  • If filter is present with count=estimated, RESTHeart automatically falls back to exact counting.

  • The X-Count-Strategy response header always reports what was actually used: estimated or exact.

 
curl -i -X GET "[RESTHEART-URL]/inventory/_size?count=estimated" \
  -H "Authorization: Basic [BASIC-AUTH]"

Sample response:

HTTP/1.1 200 OK
X-Count-Strategy: estimated
Content-Type: application/json

{ "_size": 9876543 }

estimatedDocumentCount cannot apply a filter, so when both count=estimated and filter are provided RESTHeart automatically falls back to the exact countDocuments. The X-Count-Strategy response header reports which strategy was actually used so callers can detect the fallback.

Request Behavior X-Count-Strategy

/<coll>/_size

Exact count

exact

/<coll>/_size?count

Same as /_size (count is redundant)

exact

/<coll>/_size?count=estimated

Metadata-based count (no filter)

estimated

/<coll>/_size?count=estimated&filter={…​}

Automatic fallback to exact count

exact

?count=estimated works on the collection list endpoint as well — GET /<coll>?count=estimated returns documents together with the metadata count. This remains estimated as long as no filter is provided. If filter is present, strategy is exact by design. In all cases, verify X-Count-Strategy; only estimated confirms metadata-based counting.

/collection?count=estimated and /collection/_size?count=estimated do not behave the same way:

  • /collection?count=estimated returns documents plus count metadata.

  • /collection/_size?count=estimated returns only _size.

  • If filter is present, count=estimated falls back to exact counting for correctness.

Note
 The estimated count is read from collection metadata; it can drift slightly from the exact value after unclean shutdowns until the metadata is revalidated. Use it where speed matters more than precision.

Projection (Selecting Fields)

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

Include only specific fields

cURL
curl -i -X GET "[RESTHEART-URL]/inventory" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode "keys={'item':1}"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  keys=="{'item':1}"
JavaScript
const keys = encodeURIComponent("{'item':1}");
fetch(`[RESTHEART-URL]/inventory?keys=${keys}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

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

Exclude specific fields

cURL
curl -i -X GET "[RESTHEART-URL]/inventory" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode "keys={'item':0}"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  keys=="{'item':0}"
JavaScript
const keys = encodeURIComponent("{'item':0}");
fetch(`[RESTHEART-URL]/inventory?keys=${keys}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

This returns all fields except item for each document.

Include multiple specific fields

cURL
curl -i -X GET "[RESTHEART-URL]/inventory" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode "keys={'item':1}" \
  -G --data-urlencode "keys={'qty':1}"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  keys=="{'item':1}" \
  keys=="{'qty':1}"
JavaScript
fetch('[RESTHEART-URL]/inventory?keys={"item":1}&keys={"qty":1}', {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

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:

cURL
curl -i -X GET "[RESTHEART-URL]/inventory?sort=status" \
  -H "Authorization: Basic [BASIC-AUTH]"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  sort==status
JavaScript
fetch('[RESTHEART-URL]/inventory?sort=status', {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

This sorts documents by status in ascending order.

For descending order:

cURL
curl -i -X GET "[RESTHEART-URL]/inventory?sort=-status" \
  -H "Authorization: Basic [BASIC-AUTH]"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  sort==-status
JavaScript
fetch('[RESTHEART-URL]/inventory?sort=-status', {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

Multiple Fields Sorting

Use multiple sort parameters to sort by multiple fields:

cURL
curl -i -X GET "[RESTHEART-URL]/inventory?sort=status&sort=-qty" \
  -H "Authorization: Basic [BASIC-AUTH]"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  sort==status \
  sort==-qty
JavaScript
fetch('[RESTHEART-URL]/inventory?sort=status&sort=-qty', {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

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

JSON Expression Format

You can also use MongoDB’s sort expression format:

cURL
curl -i -X GET "[RESTHEART-URL]/inventory" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode 'sort={"status":1,"qty":-1}'
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  sort=="{\"status\":1,\"qty\":-1}"
JavaScript
const sort = encodeURIComponent('{"status":1,"qty":-1}');
fetch(`[RESTHEART-URL]/inventory?sort=${sort}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

Accessing Nested Properties

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

cURL

curl -i -X GET "[RESTHEART-URL]/inventory" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode "keys={'size.h':1}" \
  -G --data-urlencode "sort={'size.uom':1}"

HTTPie

http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  keys=="{'size.h':1}" \
  sort=="{'size.uom':1}"

JavaScript

const keys = encodeURIComponent("{'size.h':1}");
const sort = encodeURIComponent("{'size.uom':1}");
fetch(`[RESTHEART-URL]/inventory?keys=${keys}&sort=${sort}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

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:

cURL
curl -i -X PUT "[RESTHEART-URL]/inventory/_indexes/item" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{"keys": {"item": 1}}'
HTTPie
echo '{"keys": {"item": 1}}' | \
http PUT "[RESTHEART-URL]/inventory/_indexes/item" \
  Authorization:"Basic [BASIC-AUTH]" \
  Content-Type:application/json
JavaScript
fetch('[RESTHEART-URL]/inventory/_indexes/item', {
  method: 'PUT',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"keys": {"item": 1}})
})
.then(response => {
  if (response.ok) {
    console.log('Write request executed successfully');
  } else {
    console.error('Write request failed:', response.status);
  }
})
.catch(error => console.error('Error:', error));
cURL
curl -i -X PUT "[RESTHEART-URL]/inventory/_indexes/status" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{"keys":{"status": 1}}'
HTTPie
echo '{"keys":{"status": 1}}' | \
http PUT "[RESTHEART-URL]/inventory/_indexes/status" \
  Authorization:"Basic [BASIC-AUTH]" \
  Content-Type:application/json
JavaScript
fetch('[RESTHEART-URL]/inventory/_indexes/status', {
  method: 'PUT',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"keys":{"status": 1}})
})
.then(response => {
  if (response.ok) {
    console.log('Write request executed successfully');
  } else {
    console.error('Write request failed:', response.status);
  }
})
.catch(error => console.error('Error:', error));

Using Hint

Specify which index to use:

cURL
curl -i -X GET "[RESTHEART-URL]/inventory" \
  -G --data-urlencode "hint={'item':1}" \
  -H "Authorization: Basic [BASIC-AUTH]"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  hint=="{'item':1}"
JavaScript
const hint = encodeURIComponent("{'item':1}");
fetch(`[RESTHEART-URL]/inventory?hint=${hint}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

Or use the compact string format:

cURL
curl -i -X GET "[RESTHEART-URL]/inventory?hint=%2Bitem&hint=-status" \
  -H "Authorization: Basic [BASIC-AUTH]"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  hint=="+item" \
  hint=="-status"
JavaScript
fetch('[RESTHEART-URL]/inventory?hint=%2Bitem&hint=-status', {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));
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:

cURL
curl -i -X GET "[RESTHEART-URL]/inventory" \
  -G --data-urlencode "hint={'$natural':1}" \
  -H "Authorization: Basic [BASIC-AUTH]"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  hint=="{'%24natural':1}"
JavaScript
const hint = encodeURIComponent("{'$natural':1}");
fetch(`[RESTHEART-URL]/inventory?hint=${hint}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

For a reverse collection scan:

cURL
curl -i -X GET "[RESTHEART-URL]/inventory" \
  -G --data-urlencode "hint={'$natural':-1}" \
  -H "Authorization: Basic [BASIC-AUTH]"
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  hint=="{'%24natural':-1}"
JavaScript
const hint = encodeURIComponent("{'$natural':-1}");
fetch(`[RESTHEART-URL]/inventory?hint=${hint}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));

Text Search

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

First, create the text index:

cURL
curl -i -X PUT "[RESTHEART-URL]/inventory/_indexes/text" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{"keys": {"item": "text"}}'
HTTPie
echo '{"keys": {"item": "text"}}' | \
http PUT "[RESTHEART-URL]/inventory/_indexes/text" \
  Authorization:"Basic [BASIC-AUTH]" \
  Content-Type:application/json
JavaScript
fetch('[RESTHEART-URL]/inventory/_indexes/text', {
  method: 'PUT',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"keys": {"item": "text"}})
})
.then(response => {
  if (response.ok) {
    console.log('Write request executed successfully');
  } else {
    console.error('Write request failed:', response.status);
  }
})
.catch(error => console.error('Error:', error));

Then search and sort by relevance score:

cURL
curl -i -X GET "[RESTHEART-URL]/inventory" \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -G --data-urlencode 'filter={"$text":{"$search":"paper"}}' \
  -G --data-urlencode 'keys={"item":1,"score":{"$meta":"textScore"}}' \
  -G --data-urlencode 'sort={"score":{"$meta":"textScore"}}'
HTTPie
http GET "[RESTHEART-URL]/inventory" \
  Authorization:"Basic [BASIC-AUTH]" \
  filter=="{\"\$text\":{\"\$search\":\"paper\"}}" \
  keys=="{\"item\":1,\"score\":{\"\$meta\":\"textScore\"}}" \
  sort=="{\"score\":{\"\$meta\":\"textScore\"}}"
JavaScript
const filter = encodeURIComponent('{"$text":{"$search":"paper"}}');
const keys = encodeURIComponent('{"item":1,"score":{"$meta":"textScore"}}');
const sort = encodeURIComponent('{"score":{"$meta":"textScore"}}');
fetch(`[RESTHEART-URL]/inventory?filter=${filter}&keys=${keys}&sort=${sort}`, {
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved data:', data);
})
.catch(error => console.error('Error:', error));