# Querying in Truto API

> Source: https://truto.one/docs/api-reference/overview/querying/

This doc walks you through the various query parameter formats and conventions used in Truto API, both Admin and Unified APIs.

## Unified, Admin and SuperQuery APIs

The following query parameter formats and operators can be used in the Unified, Admin and SuperQuery APIs.

### Strings

If you are specifying a query parameter which accepts a string, then use the parameter name as is.

For example, if you are specifying a query parameter `name` with value `foo`, then the query parameters will be,

```http request
name=foo
```

```json
{
  "name": "foo"
}
```

### Numbers

If you are specifying a query parameter which accepts a number, then use the parameter name as is.

For example, if you are specifying a query parameter `limit` with value `10`, then the query parameters will be,

```http request
limit=10
```

```json
{
  "limit": 10
}
```

### Booleans

If you are specifying a query parameter which accepts a boolean, then use the parameter name as is.

For example, if you are specifying a query parameter `is_active` with value `true`, then the query parameters will be,

```http request
is_active=true
```

```json
{
  "is_active": true
}
```

### Objects

If you are specifying a query parameter which accepts an object, then use `[]` brackets to specify the attributes.

Assuming the following query in JSON,
```json
{
  "foo": {
    "bar": "baz",
    "bar1": {
      "bar2": "baz2"
    }
  }
}
```

The equivalent query parameters in HTTP request will be,
```http request
foo[bar]=baz&foo[bar1][bar2]=baz2
```

### Arrays

If you are specifying a query parameter which accepts an array, then use empty `[]` brackets to specify the items.

Assuming the following query in JSON,

```json
{
  "foo": [
    "bar",
    {
      "bar1": "baz1"
    }
  ]
}
```

The equivalent query parameters in HTTP will be,

```http request
foo[]=bar&foo[][bar1]=baz1
```

### Date and Time

Date and time query parameters are specified in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format regardless of the format the underlying third party API accepts. Truto handles the translation between the ISO 8601 format and the third party API format.

In all the Unified APIs we'll have the `created_at` and `updated_at` query parameters which can also use the `gt`, `gte`, `lt`, `lte` operators wherever the underlying API supports it.

:::callout{type="warning"}
The operators you can use are dependent on the underlying API and if the underlying API doesn't support the operator, then Truto will ignore it.
:::

For example, assuming you want to filter resources by `created_at` between `2021-01-01` and `2021-01-31`, the query parameters will be,

```http request
created_at[gte]=2021-01-01T00:00:00Z&created_at[lte]=2021-01-31T23:59:59Z
```

```json
{
  "created_at": {
    "gte": "2021-01-01T00:00:00Z",
    "lte": "2021-01-31T23:59:59Z"
  }
}
```

### Sort by

If you want to sort the resources by a specific attribute, then use the `sort_by` query parameter.

:::callout{type="warning"}
In case of Unified APIs, sorting will only work if the underlying API supports it and the attributes you can sort by is limited based on the underlying API.
:::

For example, if you want to sort the resources by `created_at` in ascending order, the query parameters will be,

```http request
sort_by[created_at]=asc
```

```json
{
  "sort_by": {
    "created_at": "asc"
  }
}
```

You can also sort by multiple attributes by specifying the `sort_by` query parameter multiple times.

For example, if you want to sort the resources by `created_at` in ascending order and then by `updated_at` in descending order, the query parameters will be,

```http request
sort_by[created_at]=asc&sort_by[updated_at]=desc
```

```json
{
  "sort_by": {
    "created_at": "asc",
    "updated_at": "desc"
  }
}
```

## Additional query operators in Admin and SuperQuery APIs

In the Admin and SuperQuery APIs, you can use the following additional query operators --

### ne

The `ne` operator is used to filter resources where the attribute is not equal to the specified value.

For example, if you want to filter resources where the `status` attribute is not equal to `closed`, the query parameters will be,

```http request
status[ne]=closed
```

```json
{
  "status": {
    "ne": "closed"
  }
}
```

### eq

The `eq` operator is used to filter resources where the attribute is equal to the specified value.

For example, if you want to filter resources where the `status` attribute is equal to `open`, the query parameters will be,

```http request
status[eq]=open
```

```json
{
  "status": {
    "eq": "open"
  }
}
```

### in

The `in` operator is used to filter resources where the attribute is in the specified list of values.

For example, if you want to filter resources where the `status` attribute is either `open` or `closed`, the query parameters will be,

```http request
status[in][]=open&status[in][]=closed
```

```json
{
  "status": {
    "in": ["open", "closed"]
  }
}
```

### nin

The `nin` operator is used to filter resources where the attribute is not in the specified list of values.

For example, if you want to filter resources where the `status` attribute is neither `open` nor `closed`, the query parameters will be,

```http request
status[nin][]=open&status[nin][]=closed
```

```json
{
  "status": {
    "nin": ["open", "closed"]
  }
}
```

### like

The `like` operator is used to filter resources where the attribute matches the specified pattern.

For example, if you want to filter resources where the `name` attribute starts with `foo`, the query parameters will be,

```http request
name[like]=foo%
```

```json
{
  "name": {
    "like": "foo%"
  }
}
```

### nlike

The `nlike` operator is used to filter resources where the attribute does not match the specified pattern.

For example, if you want to filter resources where the `name` attribute does not start with `foo`, the query parameters will be,

```http request
name[nlike]=foo%
```

```json
{
  "name": {
    "nlike": "foo%"
  }
}
```

### gt, gte, lt, lte

The `gt`, `gte`, `lt`, `lte` operators are used to filter resources where the attribute is greater than, greater than or equal to, less than, and less than or equal to the specified value respectively.

For example, if you want to filter resources where the `created_at` attribute is greater than `2021-01-01` and lesser than `2021-01-31`, the query parameters will be,

```http request
created_at[gt]=2021-01-01T00:00:00Z&created_at[lt]=2021-01-31T23:59:59Z
```

```json
{
  "created_at": {
    "gt": "2021-01-01T00:00:00Z",
    "lt": "2021-01-31T23:59:59Z"
  }
}
```

### or & and

The `or` and `and` operators are used to combine multiple query parameters.

For example, if you want to filter resources where the `status` attribute is `open` or `name` matches a pattern and the `created_at` attribute is greater than `2021-01-01`, the query parameters will be,

```http request
or[0][status]=open&or[1][and][0][name][like]=foo%&or[1][and][1][created_at][gt]=2021-01-01T00:00:00Z
```

```json
{
  "or": [
    {
      "status": "open"
    },
    {
      "and": [
        {
          "name": {
            "like": "foo%"
          }
        },
        {
          "created_at": {
            "gt": "2021-01-01T00:00:00Z"
          }
        }
      ]
    }
  ]
}
```

## In RapidBridge Sync Jobs

In RapidBridge Sync Jobs, query parameters can be specified in the `query` attribute of the `resources` array.

```json
{
  "resources": [
    {
        "resource": "knowledge-base/page-content",
        "method": "list",
        "depends_on": "knowledge-base/pages",
        "query": {
            "foo": {
              "bar": "baz"
            },
            "baz": ["foo", "bar"],
            "created_at": {
              "gt": "2021-01-01T00:00:00Z"
            },
            "page_id": "{{resources.knowledge-base.pages.id}}"
        }
    }
  ]
}
```

You can use the object format to specify the query parameters in RapidBridge Sync Jobs. In the example above, the query parameters sent to the `knowledge-base/page-content` endpoint will be,

```http request
foo[bar]=baz&baz[]=foo&baz[]=bar&created_at[gt]=2021-01-01T00:00:00Z&page_id=123
```

You can also use the placeholders to refer to the values of other resources in the Sync Job. In the example above, the `page_id` query parameter refers to the `id` attribute of the `knowledge-base/pages` resource.

## Remote Query Parameters

In Unified APIs, there are cases where you may need to pass query parameters to the underlying third-party API directly. In such cases, you can use the `remote_query` query parameter. The `remote_query` parameter is an object that contains the query parameters to be passed to the underlying third-party API. 

You can use this parameter with any other unified query parameters and they will merged together with remote query parameters taking precedence.

Imagine a scenario where you want to pass the query parameters `foo=bar` and `baz=foo` to the underlying third-party API. The query parameters will be,

```http request
remote_query[foo]=bar&remote_query[baz]=foo
```

```json
{
  "remote_query": {
    "foo": "bar",
    "baz": "foo"
  },
  //...any other unified query parameters
}
```

To specify this in the Truto Dashboards Try Unified API Modal, please check the `Use code editor for query parameters` checkbox and specify the query parameters in the code editor.

![Remote Query Parameters](https://docs-assets.truto.one/remote_query_parameters_truto_ui.png)