# How to Query

## **Sorting**

To sort data in a specified manner, you should add to your request:

* `_orderBy[fieldName]=asc` - Ascends by `fieldName`.
* `_orderBy[fieldName]=desc` - Descends by `fieldName`.

Note: Not all visible fields are sortable. If sorting is not specified in the request, data may be returned in any order.

## **Filtering**

For data filtering, you can use the parameter in the following format:

* `fieldName[OPERATOR]=value` allows for operation-based filtering.
* `fieldName=value` is equivalent to `fieldName[eq]=value`, applying an equality filter.

Filters can be combined as follows:

* `fieldName[OPERATOR]=value&fieldName2[OPERATOR]=value2`, with the filters connected by the logical AND operator.

This structure enables precise control over the data you retrieve, ensuring that the endpoint returns only the information relevant to your needs.

### Filtering by Custom Attributes

Some endpoints support filtering based on custom attributes. You can filter customers by specifying custom labels directly in your query. Here's how you can use this feature:

* **Basic Filtering:**\
  To find members with specific custom attributes, use the following request format:\
  `fieldName?labels=(label_key_1;label_value_1),(label_key_2;label_value_2)`<br>

  This query retrieves all objects that have either:

  * Custom attribute `label_key_1` with the value `label_value_1`
  * Custom attribute `label_key_2` with the value `label_value_2`
* **Filtering Without Specifying a Value:**\
  If you want to find objects that have a specific custom attribute, regardless of its value, you can omit the value like this:\
  `fieldName?labels=(label_key_1;)`

## Pagination

{% hint style="warning" %}
We are currently working on changing the Pagination mechanism to a more modern Scroll approach, that is more efficient and allows to pull large quantities of data more effectively.

You can find the details on how to apply the Scroll approach [here](https://help.openloyalty.io/technical-guide/api-fundamentals/scroll-mechanism-for-pages).
{% endhint %}

Open Loyalty provides mechanisms to limit data fetched per request and navigate through large datasets via pagination. Understanding these functionalities allows developers to integrate with the API more effectively, leading to optimized data handling and reduced system overhead.

#### Request Parameters

1. **\_itemsOnPage**: Limits the number of data items returned within a single request/page. The maximum value that can be specified is 50.

   Example: `_itemsOnPage=10`
2. **\_page**: Specifies the page number starting from 1. Providing a page number beyond the available limit returns a successful response with zero items.

   Example: `_page=2`

#### Combining Operations

Multiple parameters can be combined using the `&` operator. This allows for specifying pagination alongside filtering and sorting criteria in a single request.

Example:

```less
GET /api/DEFAULT/transaction?_page=1&_itemsOnPage=10&header:documentType[eq]=XY&customerData:email[eq]=ol@example.com&_orderBy[header:documentType]=asc
```

#### Response Structure

The structure of the returned data is consistently formatted to facilitate easy parsing and integration:

```json
{
  "items": [
    { /* item details */ },
    { /* item details */ }
  ],
  "total": {
    "all": 10026,
    "filtered": 0,
    "estimated": true
  }
}
```

* **items**: Contains search results that meet the specified filters, are sorted according to the specified field, and are limited by the pagination settings.
* **total**: Provides a summary of the results:
  * **all**: Total number of items available in the dataset (unfiltered).
  * **filtered**: Count of items that match the filter criteria (not just those returned).
  * **estimated**: Indicates whether the counts are approximate; critical decisions should not be based on these values.

***

## **Operators**

| Operator      | Description                                                       | Data Types        |
| ------------- | ----------------------------------------------------------------- | ----------------- |
| `eq`          | Equality (case sensitive)                                         | All               |
| `like`        | Substring occurrence (anywhere in the string) (case-insensitive)  | Text              |
| `hasValue`    | Checks if the value is defined (empty string counts as defined)   | All               |
| `notHasValue` | Checks if the value is undefined (empty string counts as defined) | All               |
| `lt`          | Less than                                                         | Numeric/Datetime  |
| `lte`         | Less than or equal                                                | Numeric/Datetime  |
| `gt`          | Greater than                                                      | Numeric/Datetime  |
| `gte`         | Greater than or equal                                             | Numeric/Datetime  |
| `in`          | Check in array                                                    | Some array fields |

### Using the 'IN' Operator

For fields that allow enumeration values, you can use the 'IN' operator to specify multiple possible values. Here's an example:

* **Filtering With 'IN' Operator:**

  `GET /api/{store}/redemption?status[in]=approved,issued`

  This query will return redemptions where the status is either `approved` or `issued`.

This feature allows you to effectively narrow down your search results to better target specific groups or conditions, enhancing your ability to manage and analyze your data.<br>

## Standard Responses

* **HTTP 200**: Indicates a successful operation. The associated resource is now available for modification and retrieval. Often, this response includes an identifier for the created or modified resource.

  Example:

  ```json
  {
    "customEventId": "00000000-0000-0000-0000-000000000000"
  }
  ```
* **HTTP 204**: Suggests a successful operation without any data in the response.
* **HTTP 202**: Indicates that the request has been accepted but processing may not start immediately.

####