# Data Lake

## Searching data with OpenGate API

The searching API lets you retrieve provisioned and collected information from the entities registered on the platform.

Using search API, you can manage many situations in which you need to get information, collected by OpenGate, about your remote devices.

Some examples of questions you can answer using the searching API are:

- Where is my lost truck?
- Is my vending machine connected to Internet?
- What is the software version of this smart meter which is rebooting all the time?
- How is the signal strength of this weather station which is off-line most of the time?
- What are the latest operations launched over different devices and their current status?
- What are the latest raised alarms associated with my in-field resources?
- What is the latest value and history of different sensors and machine parameters?

## Searching Features

Where are the `FROM` and `WHERE`?

Well, if you’re still thinking in SQL, then you’ll expect to find the word `FROM` anywhere. Remember, OpenGate exposes its API through a REST interface, so in this case the word `FROM` is in the URL suffix.

That suffix is the resource you are querying, and every available one is listed in
[What you can query](../what_you_can_query/). The `WHERE` — and the `ORDER BY`, the `SELECT` and the
`GROUP BY` — is the JSON body described below.

In all response cases, you must POST a valid JSON query and you’ll get an array with the matched specific resources. The query could have next main objects:

- `filter`: Allows to select the resources that meets with desired information, see Filtering
- `limit`: Allows paginating the response, see Pagination
- `sort`: Allows sorting the results, see Sorting
- `select`: Allows selecting only the parameters you need, see Selecting
- `group`: Allows grouping the results, see Grouping

```json
{
  "filter": {}, // filter document omitted
  "limit": {}, // limit document omitted
  "sort": {}, // sort document omitted
  "select": {}, // select document omitted
  "group": {} // group document omitted
}
```

## Procedure

Searching in OpenGate platform is pretty easy. You have to send a HTTP request to the API using the `POST` method, the prefix always is **/north/v80/search**. Optionally you can attach a JSON file (in the HTTP body) if you need to use paging, sorting, selecting, grouping or filtering features.

You can use the URL above for searching information. So for the impatient, let’s suppose you’re trying to search over your previously provisioned device list, and you’re thinking in a SQL `WHERE` clause like that:

```sql
name like 'device_name' AND (
    serialNumber like '82A75D494B0EBF7A95587285AE78E83F' OR
    serialNumber like '08D83B1864A1F9CFED76DAF426EB04D7')
```

in this case you must use **<https://api.opengate.es/north/v80/search/devices>** URL and POST a JSON payload like that:

```json
{
  "filter": {
    "and": [
      {
        "like": {
          "device.name": "device_name"
        }
      },
      {
        "or": [
          {
            "like": {
              "device.serialNumber": "82A75D494B0EBF7A95587285AE78E83F"
            }
          },
          {
            "like": {
              "device.serialNumber": "08D83B1864A1F9CFED76DAF426EB04D7"
            }
          }
        ]
      }
    ]
  },
  "limit": {
    "start": 26,
    "size": 50
  }
}
```

Requesting with curl:

```bash
curl --request POST \
     --data-binary @search-query.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     https://[your_opengate_address]/north/v80/search/devices \
     -H "Content-type: application/json"
```

Then you’ll receive the device list matching with your query, the response body should be something like that.

```json
{
  "devices": [
    {}, // device body omitted
    {}, // device body omitted
    // a number of other devices
    {}
  ]
}
```

## Where to go next

The clauses above are documented one page each, below. Two things live outside this section:

- **Which URL to POST to**: [What you can query](../what_you_can_query/) indexes every search endpoint.
- **Where the clauses behave differently**: [time series](../time_series/) and [data sets](../data_sets/)
  accept the same syntax with stricter rules and a different response shape. The differences are collected
  in [Query dialects](../query_dialects/).