16min

Run a Query

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
|

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'.

Deprecation Announcement for the id field

On 1/17/2022, our Blueberry release will swap the id field to the _id field for the primary key on data documents within our service. When retrieving documents within your application or integration, any top-level id selectors will need to change to _id. more...ο»Ώ

[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
|

Query all movies released in 1984 or 1985.

Node.js
Curl
|

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 19 Apr 2022
Did this page help?
Yes
No