Ransack Query Parameter

Here we briefly describe how Ransack query parameter works and where it has been implemented. In this documentation you can find only some examples of how queries can be done, for complete information please consult search guide

In this guide we use a generic name resource as an example, and the Ransack query parameter can be used on following resources:

Ransack GET index

Ransack allows for complex search queries on resources from various building blocks. It is enabled on index actions, i.e. GET /api/v1/resources, and the query parameter to pass to the method is q. Example of a query parameter in a resource URL is GET /api/resources?q[field_eq]=fields-value.

Resource example scheme

Let’s assume, for the sake of further examples, that our resource has the following scheme:

{
  "id": "UUID",
  "name": "String",
  "value": "Integer",
  "flag": "Boolean"
}

GET methods

GET /api/resources?q[field_predicate]=value

Returns the resource whose field satisfy the predicate with respect to the value.

Example requests:

GET /api/resources?q[id_eq]=123 HTTP/1.1

Returns the resource whose id field is equal to the value 123.

GET /api/resources?q[name_cont]=machine HTTP/1.1

Returns the resource whose name field contains the value machine.

GET /api/resources?q[description_start]=Clean HTTP/1.1

Returns the resource whose description field starts with the value Clean.

GET /api/resources?q[value_lt]=15 HTTP/1.1

Returns the resource whose value field is less than 15.

GET /api/resources?q[flag_true]=1 HTTP/1.1

Returns the resource whose flag field is true.

GET /api/resources?q[name_null]=1 HTTP/1.1

Returns the resource whose name field is not set, i.e. equal to nil/false.

GET /api/resources?q[id_in][]=123&q[id_in][]=678 HTTP/1.1

Returns the resources with id equal to one of the values in array [123, 678].

Example Ransack Query

Here we briefly show how ransack can be used to obtain list of reports relevant to a specific machine. First we should obtain all the events relevant to the machine:

GET /api/v2/machines/:id/events HTTP/1.1

All the machine events should be put in an array that gets passed to the ransack query in order to get the reports with those specific event_id s:

GET /api/reports??q[event_id_in][]=:event_id_1&q[event_id_in][]=:event_id_2&q[event_id_in][]=:event_id_3 HTTP/1.1

This way we get reports that have as field values of event_id one of the following values [:event_id_1, :event_id_2, :event_id_3]