# Query Parameters

> The query params every read API of API Maker understands - find, skip, limit, sort, select, deep and getTotalCount, plus any column as a filter, upsert and returnDocument for updates - with the same keys in the body of the query APIs.

Source: https://docs.apimaker.dev/v1/docs/apis-all/query-params/query-params.html

The read APIs of a table ([get all](https://docs.apimaker.dev/v1/docs/apis-all/schema-apis/auto-generated-schema-based-get-all-api.html), [get all by stream](https://docs.apimaker.dev/v1/docs/apis-all/schema-apis/auto-generated-schema-based-get-all-by-stream-api.html), [get by id](https://docs.apimaker.dev/v1/docs/apis-all/schema-apis/auto-generated-schema-based-get-by-id-api.html), [distinct](https://docs.apimaker.dev/v1/docs/apis-all/schema-apis/auto-generated-schema-based-distinct-api.html)) take their options as query params of the URL. The [query](https://docs.apimaker.dev/v1/docs/apis-all/schema-apis/auto-generated-schema-based-query-for-get-data-api.html) APIs take the same keys in their JSON body, and the write APIs accept `select` and `deep` to shape their answer.

| customer_id | first_name | last_name | last_update           | pincode | isActive |
|-------------|------------|-----------|-----------------------|---------|----------|
| 1           | Bob        | lin       | 2022-11-14 04: 34: 58 | 382345  | 1        |
| 2           | Alice      | Page      | 2022-10-15 02: 10: 40 | 382346  | 1        |
| 3           | Mallory    | Brown     | 2022-09-13 03: 44: 05 | 382347  | 1        |
| 4           | Eve        | Mathly    | 2022-11-12 01: 59: 33 | 382348  | 1        |
| 5           | Eve        | Page      | 2022-11-12 01: 59: 33 | 382349  | 1        |

## The params

| Param | Example | What it does |
|---|---|---|
| [find](https://docs.apimaker.dev/v1/docs/apis-all/query-params/find.html) | `?find={first_name:'Bob',pincode:{$gte:382345}}` | Filter with the MongoDB operators, on every database, including fields of related tables. |
| any column | `?first_name=Bob,Alice&pincode>=382345` | A column name is a filter too, with `>`, `>=`, `<`, `<=`, `!=`, comma lists and regular expressions. |
| [skip](https://docs.apimaker.dev/v1/docs/apis-all/query-params/skip.html) | `?skip=20` | Leave out the first rows. |
| [limit](https://docs.apimaker.dev/v1/docs/apis-all/query-params/limit.html) | `?limit=10` | At most this many rows. Without it, every row. |
| [sort](https://docs.apimaker.dev/v1/docs/apis-all/query-params/sort.html) | `?sort=-last_update,first_name` | Order, `-` for descending, several columns. |
| [select](https://docs.apimaker.dev/v1/docs/apis-all/query-params/select.html) | `?select=first_name,last_name` or `?select=-password` | Only these fields, or everything but these. |
| [deep](https://docs.apimaker.dev/v1/docs/apis-all/query-params/deep.html) | `?deep=[{s_key:'customer_id',t_col:'orders',t_key:'customer_id',isMultiple:true}]` | Replace ids with the related rows, from any table, database or instance, any depth. |
| [getTotalCount](https://docs.apimaker.dev/v1/docs/apis-all/query-params/getTotalCount.html) | `?getTotalCount=true` | Add `totalCount` : the rows matching the filter before paging. |
| [upsert](https://docs.apimaker.dev/v1/docs/apis-all/query-params/upsert.html) | `?upsert=true` | Update by id and replace by id : insert when the id does not exist. |
| [returnDocument](https://docs.apimaker.dev/v1/docs/apis-all/query-params/returnDocument.html) | `?returnDocument=before` | Update by id and replace by id : answer with the row before the change. |
| throwErrorIfRecordNotFound | `?throwErrorIfRecordNotFound=true` | Update, replace and remove by id : `404` instead of `data: null` for an unknown id. |

## Writing them

- Values are **JSON5** : `find={first_name:'Bob'}` needs no quotes around keys and accepts single quotes. Strict JSON works too.
- URL encode the value when your client does not : `find=%7Bfirst_name%3A'Bob'%7D`. The API testing page and `g.sys.db` do it for you.
- Numbers, booleans and ISO dates in a column param are cast to their type before the query (`?pincode=382345` compares a number).
- The same keys go in the body of the query APIs, as JSON :

```json
{ "find": { "first_name": "Bob" }, "sort": "-customer_id", "skip": 0, "limit": 10, "select": "first_name,last_name", "deep": [ { "s_key": "customer_id", "t_col": "orders", "t_key": "customer_id" } ], "getTotalCount": true }
```

## From code

`g.sys.db.getAll({ instance, database, collection, queryParams: { find: {…}, sort: '-customer_id', limit: 10 } })` : `queryParams` takes the same keys, as objects rather than strings. See the [code examples](https://docs.apimaker.dev/v1/examples/sys/db/getAll.html).

## Schema or generated

The schema APIs convert the values of `find` to the types of the schema (`"8"` matches the number 8) and know the relations for `deep`. The generated APIs compare what you send as it is. See [All APIs at a glance](https://docs.apimaker.dev/v1/docs/apis-all/overview.html).