Run a Query

10min

POST /{appname}/data/{servicename}/_query
Querying documents in your data service is a must requirement for any data service. With hyper cloud, we provide an agnostic way to query your documents so that we can handle several different datastore engines on the backend of the hyper service. This query syntax is the same syntax you will find in mongodb or couchdb.  Using JSON, you craft your query to filter and return only the documents in your datastore that match that selector.
Parameters
Path
appname - string - the name of your hyper cloud application. 
servicename - string - the name of your hyper cloud service.
See Parameters﻿﻿
value requirements 
must begin with a lowercase letter (a-z)
must be lowercase letters (a-z)
digits (0-9)
any of these characters _ $ + -
Request Body
When posting this request, you must send a JSON document as the request body, and in that JSON document you will need to specify the following properties: selector, fields, limit, use_index
JSON
|
{
    "selector": {...},
    "fields": [...],
    "limit": 100,
    "sort": [...],
    "use_index": "myindex"
}
{
    "selector": {...},
    "fields": [...],
    "limit": 100,
    "sort": [...],
    "use_index": "myindex"
}
﻿
Property
Type
Description
selector
object
This is the filter clause of your query, it will tell hyper what criteria must be met in order for the document to be returned in the set of documents. eg. { "selector": {"type": "movie"}} is telling hyper to only return documents that have a type property with the value 'movie'.
[fields]
array[string]
This set of strings tell the query command the actual document properties you would like returned. eg: "fields": ["title", "year"] would just return objects with title and year properties. This is valuable if you have large objects with a lot of properties. optional
[limit]
number
The number of documents you would like to return in your set. optional
[sort]
array[object]
The order you would like your results returned: eg "sort": [{"year": "DESC"}, {"title": "ASC"}]. optional
[use_index]
string
name of the index to use for this query. For more information about indexes, seeCreate an Index﻿  . optional
Examples
Don't forget!
Be sure to set your HYPER environment variable with the value of your hyper app's connection string.
Query all movies released after 1984:
Node.js
Curl
|
import { connect } from "hyper-connect";

const hyper = connect(process.env.HYPER);

const greaterThanQuery = { year: { $gt: '1984'}}

const result = await hyper.data.query(greaterThanQuery)

console.log(result)

/* =>
{
  ok: true,
  docs: [
    {
      _id: 'movie-5',
      title: 'Better Off Dead',
      type: 'movie',
      year: '1985'
    }
  ]
}
*/
import { connect } from "hyper-connect";

const hyper = connect(process.env.HYPER);

const greaterThanQuery = { year: { $gt: '1984'}}

const result = await hyper.data.query(greaterThanQuery)

console.log(result)

/* =>
{
  ok: true,
  docs: [
    {
      _id: 'movie-5',
      title: 'Better Off Dead',
      type: 'movie',
      year: '1985'
    }
  ]
}
*/
﻿
Query all movies released in 1984 or 1985.
Node.js
Curl
|
import { connect } from "hyper-connect";

const hyper = connect(process.env.HYPER);

const orQuery = { $or: [{year: '1984'}, {year: '1985'}]}

const result = await hyper.data.query(orQuery)

console.log(result)

/* => 
{
  ok: true,
  docs: [
    {
      _id: 'movie-5',
      title: 'Better Off Dead',
      type: 'movie',
      year: '1985'
    }
  ]
}
 */
import { connect } from "hyper-connect";

const hyper = connect(process.env.HYPER);

const orQuery = { $or: [{year: '1984'}, {year: '1985'}]}

const result = await hyper.data.query(orQuery)

console.log(result)

/* => 
{
  ok: true,
  docs: [
    {
      _id: 'movie-5',
      title: 'Better Off Dead',
      type: 'movie',
      year: '1985'
    }
  ]
}
 */
﻿
Responses
Status Code
Description
Example Response
200
Successfully returned results for your query
{"ok": true, "docs": [...]}
500
Error occured trying to run your query
{"ok": false, "msg": ""}
Need Help?
You can always reach out to our support team for any additional assistance on slack.
﻿

Updated 16 Aug 2022

Did this page help you?

TABLE OF CONTENTS

POST /{appname}/data/{servicename}/_query

Property	Type	Description
selector	object	This is the filter clause of your query, it will tell hyper what criteria must be met in order for the document to be returned in the set of documents. eg. { "selector": {"type": "movie"}} is telling hyper to only return documents that have a type property with the value 'movie'.
[fields]	array[string]	This set of strings tell the query command the actual document properties you would like returned. eg: "fields": ["title", "year"] would just return objects with title and year properties. This is valuable if you have large objects with a lot of properties. optional
[limit]	number	The number of documents you would like to return in your set. optional
[sort]	array[object]	The order you would like your results returned: eg "sort": [{"year": "DESC"}, {"title": "ASC"}]. optional
[use_index]	string	name of the index to use for this query. For more information about indexes, seeCreate an Index . optional

Status Code	Description	Example Response
200	Successfully returned results for your query	{"ok": true, "docs": [...]}
500	Error occured trying to run your query	{"ok": false, "msg": ""}