# Query Objects

## Queries

This function allows you to retrieve a list of objects matching specified criteria.

<table><thead><tr><th width="508">Relative URL</th><th>HTTP Request Method</th></tr></thead><tbody><tr><td><code>/api/v4/</code><em><code>backend-deployment-id</code></em><code>/objects/</code><em><code>model</code></em><code>.json?query[</code><em><code>field</code></em><code>]=</code><em><code>value</code></em></td><td>GET</td></tr><tr><td><code>/api/v4/</code><em><code>backend-deployment-id</code></em><code>/objects/</code><em><code>model</code></em><code>.json?q[</code><em><code>field</code></em><code>]=</code><em><code>value</code></em></td><td>GET</td></tr><tr><td><code>/api/v4/</code><em><code>backend-deployment-id</code></em><code>/objects/</code><em><code>model</code></em><code>.json?query[</code><em><code>field</code></em><code>]=</code><em><code>value1</code></em><code>&#x26;query[</code><em><code>other_field</code></em><code>]=</code><em><code>value2</code></em></td><td>GET</td></tr></tbody></table>

{% hint style="info" %}

* Replace *`model`* with the type of object that you wish to retrieve (as defined in your app's Data Model), for example `person`, `job` or `asset`.
* Multiple query criteria can be specified.
* Certain "hidden" fields are prefixed with an underscore, for example: to query on the `updated_at` hidden field, use `_updated_at`.
  {% endhint %}

### Parameters

Query parameters are specified as a URL-encoded `query` or `q` hash. Valid keys for this hash are the names of the fields in that model. The format for the values is the same as for creating objects. Please refer to the same section at [Creating a New Object.](https://docs.journeyapps.com/reference/backend-api/create-a-new-object#parameters)

You can specify your criteria with logic such as 'equals', 'not equal to', 'greater than', 'less than', etc. as follows:

<table><thead><tr><th width="185">Comparison</th><th width="334.3333333333333">Syntax</th><th>Allowed Values</th></tr></thead><tbody><tr><td>Equals</td><td><strong><code>query[</code></strong><em><strong><code>field</code></strong></em><strong><code>]=</code></strong><em><strong><code>value</code></strong></em></td><td></td></tr><tr><td>is Not Equal To</td><td><strong><code>query[</code></strong><em><strong><code>field</code></strong></em><strong><code>.ne]=</code></strong><em><strong><code>value</code></strong></em></td><td></td></tr><tr><td>is Less Than</td><td><strong><code>query[</code></strong><em><strong><code>field</code></strong></em><strong><code>.lt]=</code></strong><em><strong><code>value</code></strong></em></td><td></td></tr><tr><td>is Less Than or Equal To</td><td><strong><code>query[</code></strong><em><strong><code>field</code></strong></em><strong><code>.lte]=</code></strong><em><strong><code>value</code></strong></em></td><td></td></tr><tr><td>is Greater Than</td><td><strong><code>query[</code></strong><em><strong><code>field</code></strong></em><strong><code>.gt]=</code></strong><em><strong><code>value</code></strong></em></td><td></td></tr><tr><td>is Greater Than or Equal To</td><td><strong><code>query[</code></strong><em><strong><code>field</code></strong></em><strong><code>.gte]=</code></strong><em><strong><code>value</code></strong></em></td><td></td></tr><tr><td>Contains</td><td><strong><code>query[</code></strong><em><strong><code>field</code></strong></em><strong><code>.contains]=</code></strong><em><strong><code>value</code></strong></em></td><td></td></tr><tr><td>is Null (or Not Null)</td><td><strong><code>query[</code></strong><em><strong><code>field</code></strong></em><strong><code>.null]=</code></strong><em><strong><code>value</code></strong></em></td><td>Specify <code>true</code> for the <em>value</em> to check for "Is Null" or <code>false</code> to check for "Is Not Null"</td></tr></tbody></table>

{% hint style="info" %}
The `contains` operator is case-sensitive.
{% endhint %}

### Response

The response includes a list of all the objects of the given type which match all of the query criteria. The format of the objects is the same as for listing all objects (please refer to the [Retrieve All Objects](https://docs.journeyapps.com/reference/backend-api/api-reference/retrieve-all-objects) section.)

### Examples

{% hint style="info" %}
**BASE-URL**

The below examples contain a `BASE-URL` placeholder. Please refer to the [HTTP Endpoints](https://docs.journeyapps.com/reference/introduction#http-endpoints) section to get the base URL relevant to your deployment.
{% endhint %}

{% hint style="success" %}
When using curl with queries you have to either escape the square brackets with a backslash `\` or add the `-g` option to turn off curl's globbing functionality.
{% endhint %}

#### Match a text field:

{% tabs %}
{% tab title="HTTP" %}

```http
GET BASE-URL/api/v4/533bda53027894f69b001055/objects/assets.json?q[serial_number]=123456
```

{% endtab %}

{% tab title="curl" %}

```shell
curl "BASE-URL/api/v4/533bda53027894f69b001055/objects/assets.json?q[serial_number]=123456" \
    -g -u "533bda53027894f69b001055:7Ajj5htRY1uzw7b4w23V"l
```

{% endtab %}

{% tab title="ruby" %}

```ruby
require 'rest-client'
journey = RestClient::Resource.new "BASE-URL/api/v4", "533bda53027894f69b001055", "7Ajj5htRY1uzw7b4w23V"
journey["533bda53027894f69b001055/objects/assets.json"].get :params => {:q=>{:serial_number=>"123456"}}
```

{% endtab %}
{% endtabs %}

#### Match multiple fields, including human-readable dates:

{% tabs %}
{% tab title="HTTP" %}

```http
GET BASE-URL/api/v4/533bda53027894f69b001055/objects/assets.json?q[make]=Acme&q[registration_date]=2012-09-19
```

{% endtab %}

{% tab title="curl" %}

```shell
curl "BASE-URL/api/v4/533bda53027894f69b001055/objects/assets.json?q[make]=Acme&q[registration_date]=2012-09-19" \
    -g -u "533bda53027894f69b001055:7Ajj5htRY1uzw7b4w23V"
```

{% endtab %}

{% tab title="ruby" %}

```ruby
require 'rest-client'
journey = RestClient::Resource.new "BASE-URL/api/v4", "533bda53027894f69b001055", "7Ajj5htRY1uzw7b4w23V"
journey["533bda53027894f69b001055/objects/assets.json"].get :params => {:q=>{:make=>"Acme", :registration_date=>"2012-09-19"}}
```

{% endtab %}
{% endtabs %}

#### Query with `datetime` in ISO8601 format:

{% tabs %}
{% tab title="HTTP" %}

```http
GET BASE-URL/api/v4/533bda53027894f69b001055/objects/assets.json?q[updated_at]=2012-09-18T10%3A27%3A46Z
```

{% endtab %}

{% tab title="curl" %}

```shell
curl "BASE-URL/api/v4/533bda53027894f69b001055/objects/assets.json?q[updated_at]=2012-09-18T10%3A27%3A46Z" \
    -g -u "533bda53027894f69b001055:7Ajj5htRY1uzw7b4w23V"
```

{% endtab %}

{% tab title="ruby" %}

```ruby
require 'rest-client'
journey = RestClient::Resource.new "BASE-URL/api/v4", "533bda53027894f69b001055", "7Ajj5htRY1uzw7b4w23V"
journey["533bda53027894f69b001055/objects/assets.json"].get :params => {:q=>{:updated_at=>"2012-09-18T10:27:46Z"}}
```

{% endtab %}
{% endtabs %}

#### Match a value (as a string) from a [single-choice field](https://docs.journeyapps.com/reference/build/data-model-configuration/model/field):&#x20;

{% tabs %}
{% tab title="HTTP" %}

```http
GET BASE-URL/api/v4/533bda53027894f69b001055/objects/assets.json?q[make]=Acme&q[verified]=no
```

{% endtab %}

{% tab title="curl" %}

```shell
curl "BASE-URL/api/v4/533bda53027894f69b001055/objects/assets.json?q[make]=Acme&q[verified]=no" \
    -g -u "533bda53027894f69b001055:7Ajj5htRY1uzw7b4w23V"
```

{% endtab %}

{% tab title="ruby" %}

```ruby
require 'rest-client'
journey = RestClient::Resource.new "BASE-URL/api/v4", "533bda53027894f69b001055", "7Ajj5htRY1uzw7b4w23V"
journey["533bda53027894f69b001055/objects/assets.json"].get :params => {:q=>{:make=>"Acme", :verified=>"no"}}
```

{% endtab %}
{% endtabs %}

#### Query on a relationship - Find all assets related to the specified room:

{% tabs %}
{% tab title="HTTP" %}

```http
GET BASE-URL/api/v4/533bda53027894f69b001055/objects/assets.json?q[room_id]=8af9f570-017b-11e2-84c8-b88d120322de
```

{% endtab %}

{% tab title="curl" %}

```shell
curl "https://run-testing-us.journeyapps.com/api/v4/533bda53027894f69b001055/objects/assets.json?q[room_id]=8af9f570-017b-11e2-84c8-b88d120322de" \
    -g -u "533bda53027894f69b001055:7Ajj5htRY1uzw7b4w23V"
```

{% endtab %}

{% tab title="ruby" %}

```ruby
require 'rest-client'
journey = RestClient::Resource.new "https://run-testing-us.journeyapps.com/api/v4", "533bda53027894f69b001055", "7Ajj5htRY1uzw7b4w23V"
journey["533bda53027894f69b001055/objects/assets.json"].get :params => {:q=>{:room_id=>"8af9f570-017b-11e2-84c8-b88d120322de"}}
```

{% endtab %}
{% endtabs %}

## Searching Across All Fields

You can also search through all the fields of all objects of a given type for a partial text match. This can be useful for implementing basic search functions.

| Relative URL                                                          | HTTP Request Method |
| --------------------------------------------------------------------- | ------------------- |
| `/api/v4/`*`backend-deployment-id`*`/objects/`*`model`*`/search.json` | POST                |

### Parameters

The search text must be specified as a URL-encoded parameter named `query`.

### Example

{% hint style="info" %}
**BASE-URL**

The below examples contain a `BASE-URL` placeholder. Please refer to the [HTTP Endpoints](https://docs.journeyapps.com/reference/introduction#http-endpoints) section to get the base URL relevant to your deployment.
{% endhint %}

#### Search `task` objects for the text "site":

{% tabs %}
{% tab title="HTTP" %}

```http
POST BASE-URL/api/v4/533bda53027894f69b001055/objects/tasks/search.json
query=site
```

{% endtab %}

{% tab title="curl" %}

```shell
curl "BASE-URL/api/v4/533bda53027894f69b001055/objects/tasks/search.json" \
    -u "533bda53027894f69b001055:7Ajj5htRY1uzw7b4w23V" \
    -d "query=site"
```

{% endtab %}

{% tab title="ruby" %}

```ruby
journey = RestClient::Resource.new "BASE-URL/api/v4", "533bda53027894f69b001055", "7Ajj5htRY1uzw7b4w23V"
journey["533bda53027894f69b001055/objects/tasks/search.json"].post :query=>"site"
```

{% endtab %}
{% endtabs %}

#### Response:

{% code title="json" %}

```json
{
    "objects": [
      {
          "id": "7b44dcf4-b02d-11e4-b450-001e6733fe3c",
          "type": "task",
          "updated_at": "2015-02-09T07:30:11Z",
          "display": "Confirm that site rules are documented and distributed",
          "name": "Confirm that site rules are documented and distributed",
          "instructions": null,
          "status": {
            "key": 1,
            "display": "Closed"
          },
          "category_id": null
        },
        {
          "id": "fd3b75e2-b02d-11e4-a034-001e6733fe3c",
          "type": "task",
          "updated_at": "2015-02-09T07:33:49Z",
          "display": "Confirm that supervisor is on site",
          "name": "Confirm that supervisor is on site",
          "instructions": null,
          "status": {
            "key": 1,
            "display": "Closed"
          },
          "category_id": null
        },
    ],
    "count": 2,
    "total": 2,
    "more": false
}
```

{% endcode %}