# Search for things

`POST /api/2/search/things`

This resource can be used to search for things.

* The parameter `filter` is not mandatory. If it is not set, the
  result contains all things which the logged in user is allowed to read.

* The search is case sensitive. In case you don't know how exactly the
  spelling of value of the namespace, name, attribute, feature etc. is, use the *like*
  notation instead of *eq* for filtering.

* The resource supports sorting and paging. If paging is not explicitly
  specified by means of the `size` option, a default count of `25`
  documents is returned.

* The internal search index is "eventually consistent".  Consistency with the latest
  thing updates should recover within milliseconds.

Authentication (security requirement alternatives):

```json
[
  {
    "OpenIDConnect": []
  },
  {
    "NginxBasic": []
  },
  {
    "Bearer": []
  }
]
```

- OpenIDConnect: openIdConnect. OpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.
- NginxBasic: http (basic). Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
- Bearer: http (bearer). A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.

Request body: application/x-www-form-urlencoded

Type: object

- `filter` (optional)
  Reference: [SearchFilterProperty](https://sourcey-ditto.pages.dev/http-api-doc/models/searchfilterproperty.md); Type: SearchFilterProperty
  
  
  #### Filter predicates:
  
  * ```eq({property},{value})```  (i.e. equal to the given value)
  
  * ```ne({property},{value})```  (i.e. not equal to the given value)
  
  * ```gt({property},{value})```  (i.e. greater than the given value)
  
  * ```ge({property},{value})```  (i.e. equal to the given value or greater than it)
  
  * ```lt({property},{value})```  (i.e. lower than the given value or equal to it)
  
  * ```le({property},{value})```  (i.e. lower than the given value)
  
  * ```in({property},{value},{value},...)```  (i.e. contains at least one of the values listed)
  
  * ```like({property},{value})```  (i.e. contains values similar to the expressions listed)
  
  * ```ilike({property},{value})```  (i.e. contains values similar and case insensitive to the expressions listed)
  
  * ```exists({property})```  (i.e. all things in which the given path exists)
  
  * ```empty({property})```  (i.e. all things in which the given path is absent, null, an empty array, an empty object or an empty string)
  
  
  Note: When using filter operations, only things with the specified properties are returned.
  For example, the filter `ne(attributes/owner, "SID123")` will only return things that do have
  the `owner` attribute.
  
  
  #### Logical operations:
  
  
  * ```and({query},{query},...)```
  
  * ```or({query},{query},...)```
  
  * ```not({query})```
  
  
  #### Examples:
  
  * ```eq(attributes/location,"kitchen")```
  
  * ```ge(thingId,"myThing1")```
  
  * ```gt(_created,"2020-08-05T12:17")```
  
  * ```exists(features/featureId)```
  
  * ```empty(attributes/tags)```
  
  * ```and(eq(attributes/location,"kitchen"),eq(attributes/color,"red"))```
  
  * ```or(eq(attributes/location,"kitchen"),eq(attributes/location,"living-room"))```
  
  * ```like(attributes/key1,"known-chars-at-start*")```
  
  * ```like(attributes/key1,"*known-chars-at-end")```
  
  * ```like(attributes/key1,"*known-chars-in-between*")```
  
  * ```like(attributes/key1,"just-som?-char?-unkn?wn")```
  
  The `like` filters with the wildcard `*` at the beginning can slow down your search request.

- `namespaces` (optional)
  Reference: [NamespaceProperty](https://sourcey-ditto.pages.dev/http-api-doc/models/namespaceproperty.md); Type: NamespaceProperty
  
  A comma-separated list of namespaces. This list is used to limit the query to things in the given namespaces
  only.
  
  
  #### Examples:
  
  * `?namespaces=com.example.namespace`
  
  * `?namespaces=com.example.namespace1,com.example.namespace2`

- `fields` (optional)
  Type: string
  
  Contains a comma-separated list of fields to be included in the returned
  JSON. attributes can be selected in the same manner.
  
  #### Selectable fields
  
  * `thingId`
  * `policyId`
  * `definition`
  * `attributes`
  
     Supports selecting arbitrary sub-fields by using a comma-separated list:
      * several attribute paths can be passed as a comma-separated list of JSON pointers (RFC-6901)
  
        For example:
          * `?fields=attributes/model` would select only `model` attribute value (if present)
          * `?fields=attributes/model,attributes/location` would select only `model` and
             `location` attribute values (if present)
  
    Supports selecting arbitrary sub-fields of objects by wrapping sub-fields inside parentheses `( )`:
      * a comma-separated list of sub-fields (a sub-field is a JSON pointer (RFC-6901)
        separated with `/`) to select
  
      * sub-selectors can be used to request only specific sub-fields by placing expressions
        in parentheses `( )` after a selected subfield
  
        For example:
         * `?fields=attributes(model,location)` would select only `model`
            and `location` attribute values (if present)
         * `?fields=attributes(coffeemaker/serialno)` would select the `serialno` value
            inside the `coffeemaker` object
         * `?fields=attributes/address/postal(city,street)` would select the `city` and
            `street` values inside the `postal` object inside the `address` object
  
  * `features`
  
    Supports selecting arbitrary fields in features similar to `attributes` (see also features documentation for more details)
  
  * `_namespace`
  
    Specifically selects the namespace also contained in the `thingId`
  
  * `_revision`
  
    Specifically selects the revision of the thing. The revision is a counter, which is incremented on each modification of a thing.
  
  * `_created`
  
    Specifically selects the created timestamp of the thing in ISO-8601 UTC format. The timestamp is set on creation of a thing.
  
  * `_modified`
  
    Specifically selects the modified timestamp of the thing in ISO-8601 UTC format. The timestamp is set on each modification of a thing.
  
  * `_metadata`
  
    Specifically selects the Metadata of the thing. The content is a JSON object having the Thing's JSON structure with the difference that the JSON leaves of the Thing are JSON objects containing the metadata.
  
  * `_policy`
  
    Specifically selects the content of the policy associated to the thing. (By default, only the policyId is returned.)
  
  #### Examples
  
  * `?fields=thingId,attributes,features`
  * `?fields=attributes(model,manufacturer),features`

- `option` (optional)
  Type: string
  
  Possible values for the parameter:
  
  #### Sort operations
  
  * ```sort([+|-]{property})```
  * ```sort([+|-]{property},[+|-]{property},...)```
  
  #### Paging operations
  
  * ```size({page-size})```  Maximum allowed page size is `200`. Default page size is `25`.
  * ```cursor({cursor-id})```  Start the search from the cursor location. Specify the cursor ID without
  quotation marks. Cursor IDs are given in search responses and mark the position after the last entry of
  the previous search. The meaning of cursor IDs is unspecified and may change without notice.
  
  The paging option `limit({offset},{count})` is deprecated.
  It may result in slow queries or timeouts and will be removed eventually.
  
  #### Examples:
  
  * ```sort(+thingId)```
  * ```sort(-attributes/manufacturer)```
  * ```sort(+thingId,-attributes/manufacturer)```
  * ```size(10)``` return 10 results
  * ```cursor(LOREMIPSUM)```  return results after the position of the cursor `LOREMIPSUM`.
  
  #### Combine:
  
  If you need to specify multiple options, when using the swagger UI just write each option in a new line.
  When using the plain REST API programmatically,
  you will need to separate the options using a comma (,) character.
  
  ```size(200),cursor(LOREMIPSUM)```
  
  The deprecated paging option `limit` may not be combined with the other paging options `size` and `cursor`.

- `condition` (optional)
  Type: string
  
  Similar to the `filter`, a `condition` may be passed to ensure strong consistency when querying things.
  
  This `condition` has the same syntax and semantics than the `filter` - it is however applied on the matched things
  selected by the `filter` - on their current state.
  
  So combining this together with `filter` can provide strong consistency when performing a search.

```json
{
  "filter": "and(like(definition,\"*test*\"))",
  "namespaces": "org.eclipse.ditto,foo.bar",
  "fields": "attributes/model,attributes/location",
  "option": "limit(0,5)"
}
```

Responses:

- 200: An array of the matching things.

Content type: application/json

Type: SearchResultThings

Schema: [SearchResultThings](https://sourcey-ditto.pages.dev/http-api-doc/models/searchresultthings.md)

- `items` (optional)
  Type: Array<Thing>
  
  Items:
    Reference: [Thing](https://sourcey-ditto.pages.dev/http-api-doc/models/thing.md); Type: Thing

- `cursor` (optional)
  Type: string

- 400: The request could not be completed. A provided parameter is in a
wrong format.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 401: The request could not be completed due to missing authentication.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 403: The request could not be completed due to an invalid authentication.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 504: The request ran out of time to execute on the the back-end. Optimize your query and try again.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

## Examples

### cURL

```bash
curl -X POST 'https://ditto.eclipseprojects.io/api/2/search/things' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'filter=and%28like%28definition%2C%22%2Atest%2A%22%29%29&namespaces=org.eclipse.ditto%2Cfoo.bar&fields=attributes%2Fmodel%2Cattributes%2Flocation&option=limit%280%2C5%29'
```

### JavaScript

```javascript
const response = await fetch('https://ditto.eclipseprojects.io/api/2/search/things', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'filter=and%28like%28definition%2C%22%2Atest%2A%22%29%29&namespaces=org.eclipse.ditto%2Cfoo.bar&fields=attributes%2Fmodel%2Cattributes%2Flocation&option=limit%280%2C5%29',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://ditto.eclipseprojects.io/api/2/search/things',
    data='filter=and%28like%28definition%2C%22%2Atest%2A%22%29%29&namespaces=org.eclipse.ditto%2Cfoo.bar&fields=attributes%2Fmodel%2Cattributes%2Flocation&option=limit%280%2C5%29'.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/x-www-form-urlencoded',
    },
)
print(response.text)
```