# Операторы фильтрации

Используются в параметре `filter` для таких API репозитория, как `find`, `findOne`, `findAndCount`, `count`:

```ts
const repository = db.getRepository('books');

repository.find({
  filter: {
    title: {
      $eq: '春秋',
    },
  },
});
```

Для поддержки JSON-сериализации NocoBase обозначает операторы запросов строками с префиксом `$`.

Кроме того, NocoBase предоставляет API для расширения операторов. Подробнее см. в [`db.registerOperators()`](../database#registeroperators).

## Общие операторы

### `$eq`

Проверяет, равно ли значение поля указанному значению. Эквивалентно SQL-оператору `=`.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $eq: '春秋',
    },
  },
});
```

Эквивалентно `title: '春秋'`.

### `$ne`

Проверяет, не равно ли значение поля указанному значению. Эквивалентно SQL-оператору `!=`.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $ne: '春秋',
    },
  },
});
```

### `$is`

Проверяет, является ли значение поля указанным значением. Эквивалентно SQL-оператору `IS`.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $is: null,
    },
  },
});
```

### `$not`

Проверяет, не является ли значение поля указанным значением. Эквивалентно SQL-оператору `IS NOT`.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $not: null,
    },
  },
});
```

### `$col`

Проверяет, равно ли значение поля значению другого поля. Эквивалентно SQL-оператору `=`.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $col: 'name',
    },
  },
});
```

### `$in`

Проверяет, содержится ли значение поля в указанном массиве. Эквивалентно SQL-оператору `IN`.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $in: ['春秋', '战国'],
    },
  },
});
```

### `$notIn`

Проверяет, не содержится ли значение поля в указанном массиве. Эквивалентно SQL-оператору `NOT IN`.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $notIn: ['春秋', '战国'],
    },
  },
});
```

### `$empty`

Проверяет, пусто ли поле. Для строкового поля это означает пустую строку, для поля-массива — пустой массив.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $empty: true,
    },
  },
});
```

### `$notEmpty`

Проверяет, не пусто ли поле. Для строкового поля это означает непустую строку, для поля-массива — непустой массив.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $notEmpty: true,
    },
  },
});
```

## Логические операторы

### `$and`

Логическое И. Эквивалентно SQL-оператору `AND`.

**Пример**

```ts
repository.find({
  filter: {
    $and: [{ title: '诗经' }, { isbn: '1234567890' }],
  },
});
```

### `$or`

Логическое ИЛИ. Эквивалентно SQL-оператору `OR`.

**Пример**

```ts
repository.find({
  filter: {
    $or: [{ title: '诗经' }, { publishedAt: { $lt: '0000-00-00T00:00:00Z' } }],
  },
});
```

## Операторы для полей булева типа

Используются для полей булева типа (type: 'boolean').

### `$isFalsy`

Проверяет, является ли значение булева поля ложным (falsy). Значения поля `false`, `0` и `NULL` считаются ложными.

**Пример**

```ts
repository.find({
  filter: {
    isPublished: {
      $isFalsy: true,
    },
  },
});
```

### `$isTruly`

Проверяет, является ли значение булева поля истинным (truly). Значения поля `true` и `1` считаются истинными.

**Пример**

```ts
repository.find({
  filter: {
    isPublished: {
      $isTruly: true,
    },
  },
});
```

## Операторы для числовых полей

Используются для числовых полей, включая:

- `type: 'integer'`
- `type: 'float'`
- `type: 'double'`
- `type: 'real'`
- `type: 'decimal'`

### `$gt`

Проверяет, больше ли значение поля указанного значения. Эквивалентно SQL-оператору `>`.

**Пример**

```ts
repository.find({
  filter: {
    price: {
      $gt: 100,
    },
  },
});
```

### `$gte`

Проверяет, больше или равно ли значение поля указанному значению. Эквивалентно SQL-оператору `>=`.

**Пример**

```ts
repository.find({
  filter: {
    price: {
      $gte: 100,
    },
  },
});
```

### `$lt`

Проверяет, меньше ли значение поля указанного значения. Эквивалентно SQL-оператору `<`.

**Пример**

```ts
repository.find({
  filter: {
    price: {
      $lt: 100,
    },
  },
});
```

### `$lte`

Проверяет, меньше или равно ли значение поля указанному значению. Эквивалентно SQL-оператору `<=`.

**Пример**

```ts
repository.find({
  filter: {
    price: {
      $lte: 100,
    },
  },
});
```

### `$between`

Проверяет, находится ли значение поля между двумя указанными значениями. Эквивалентно SQL-оператору `BETWEEN`.

**Пример**

```ts
repository.find({
  filter: {
    price: {
      $between: [100, 200],
    },
  },
});
```

### `$notBetween`

Проверяет, не находится ли значение поля между двумя указанными значениями. Эквивалентно SQL-оператору `NOT BETWEEN`.

**Пример**

```ts
repository.find({
  filter: {
    price: {
      $notBetween: [100, 200],
    },
  },
});
```

## Операторы для строковых полей

Используются для строковых полей (type: 'string').

### `$includes`

Проверяет, содержит ли строковое поле указанную подстроку.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $includes: '三字经',
    },
  },
});
```

### `$notIncludes`

Проверяет, не содержит ли строковое поле указанную подстроку.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $notIncludes: '三字经',
    },
  },
});
```

### `$startsWith`

Проверяет, начинается ли строковое поле с указанной подстроки.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $startsWith: '三字经',
    },
  },
});
```

### `$notStartsWith`

Проверяет, не начинается ли строковое поле с указанной подстроки.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $notStatsWith: '三字经',
    },
  },
});
```

### `$endsWith`

Проверяет, заканчивается ли строковое поле указанной подстрокой.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $endsWith: '三字经',
    },
  },
});
```

### `$notEndsWith`

Проверяет, не заканчивается ли строковое поле указанной подстрокой.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $notEndsWith: '三字经',
    },
  },
});
```

### `$like`

Проверяет, содержит ли значение поля указанную строку. Эквивалентно SQL-оператору `LIKE`.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $like: '计算机',
    },
  },
});
```

### `$notLike`

Проверяет, не содержит ли значение поля указанную строку. Эквивалентно SQL-оператору `NOT LIKE`.

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $notLike: '计算机',
    },
  },
});
```

### `$iLike`

Проверяет, содержит ли значение поля указанную строку без учета регистра. Эквивалентно SQL-оператору `ILIKE` (только для PostgreSQL).

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $iLike: 'Computer',
    },
  },
});
```

### `$notILike`

Проверяет, не содержит ли значение поля указанную строку без учета регистра. Эквивалентно SQL-оператору `NOT ILIKE` (только для PostgreSQL).

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $notILike: 'Computer',
    },
  },
});
```

### `$regexp`

Проверяет, соответствует ли значение поля указанному регулярному выражению. Эквивалентно SQL-оператору `REGEXP` (только для PostgreSQL).

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $regexp: '^计算机',
    },
  },
});
```

### `$notRegexp`

Проверяет, не соответствует ли значение поля указанному регулярному выражению. Эквивалентно SQL-оператору `NOT REGEXP` (только для PostgreSQL).

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $notRegexp: '^计算机',
    },
  },
});
```

### `$iRegexp`

Проверяет, соответствует ли значение поля указанному регулярному выражению без учета регистра. Эквивалентно SQL-оператору `~*` (только для PostgreSQL).

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $iRegexp: '^COMPUTER',
    },
  },
});
```

### `$notIRegexp`

Проверяет, не соответствует ли значение поля указанному регулярному выражению без учета регистра. Эквивалентно SQL-оператору `!~*` (только для PostgreSQL).

**Пример**

```ts
repository.find({
  filter: {
    title: {
      $notIRegexp: '^COMPUTER',
    },
  },
});
```

## Операторы для полей типа "дата"

Используются для полей типа "дата" (type: 'date').

### `$dateOn`

Проверяет, приходится ли дата поля на указанный день.

**Пример**

```ts
repository.find({
  filter: {
    createdAt: {
      $dateOn: '2021-01-01',
    },
  },
});
```

### `$dateNotOn`

Проверяет, не приходится ли дата поля на указанный день.

**Пример**

```ts
repository.find({
  filter: {
    createdAt: {
      $dateNotOn: '2021-01-01',
    },
  },
});
```

### `$dateBefore`

Проверяет, предшествует ли дата поля указанному значению. Эквивалентно "меньше" переданного значения даты.

**Пример**

```ts
repository.find({
  filter: {
    createdAt: {
      $dateBefore: '2021-01-01T00:00:00.000Z',
    },
  },
});
```

### `$dateNotBefore`

Проверяет, не предшествует ли дата поля указанному значению. Эквивалентно "больше или равно" переданного значения даты.

**Пример**

```ts
repository.find({
  filter: {
    createdAt: {
      $dateNotBefore: '2021-01-01T00:00:00.000Z',
    },
  },
});
```

### `$dateAfter`

Проверяет, следует ли дата поля за указанным значением. Эквивалентно "больше" переданного значения даты.

**Пример**

```ts
repository.find({
  filter: {
    createdAt: {
      $dateAfter: '2021-01-01T00:00:00.000Z',
    },
  },
});
```

### `$dateNotAfter`

Проверяет, не следует ли дата поля за указанным значением. Эквивалентно "меньше или равно" переданного значения даты.

**Пример**

```ts
repository.find({
  filter: {
    createdAt: {
      $dateNotAfter: '2021-01-01T00:00:00.000Z',
    },
  },
});
```

## Операторы для полей типа "массив"

Используются для полей типа "массив" (type: 'array').

### `$match`

Проверяет, соответствует ли значение поля-массива значениям в указанном массиве.

**Пример**

```ts
repository.find({
  filter: {
    tags: {
      $match: ['文学', '历史'],
    },
  },
});
```

### `$notMatch`

Проверяет, не соответствует ли значение поля-массива значениям в указанном массиве.

**Пример**

```ts
repository.find({
  filter: {
    tags: {
      $notMatch: ['文学', '历史'],
    },
  },
});
```

### `$anyOf`

Проверяет, содержит ли значение поля-массива хотя бы одно из значений в указанном массиве.

**Пример**

```ts
repository.find({
  filter: {
    tags: {
      $anyOf: ['文学', '历史'],
    },
  },
});
```

### `$noneOf`

Проверяет, не содержит ли значение поля-массива ни одного из значений в указанном массиве.

**Пример**

```ts
repository.find({
  filter: {
    tags: {
      $noneOf: ['文学', '历史'],
    },
  },
});
```

### `$arrayEmpty`

Проверяет, пуст ли массив поля.

**Пример**

```ts
repository.find({
  filter: {
    tags: {
      $arrayEmpty: true,
    },
  },
});
```

### `$arrayNotEmpty`

Проверяет, не пуст ли массив поля.

**Пример**

```ts
repository.find({
  filter: {
    tags: {
      $arrayNotEmpty: true,
    },
  },
});
```

## Операторы для полей связей

Используются для проверки существования связи. Типы полей включают:

- `type: 'hasOne'`
- `type: 'hasMany'`
- `type: 'belongsTo'`
- `type: 'belongsToMany'`

### `$exists`

Проверяет наличие связанных данных.

**Пример**

```ts
repository.find({
  filter: {
    author: {
      $exists: true,
    },
  },
});
```

### `$notExists`

Проверяет отсутствие связанных данных.

**Пример**

```ts
repository.find({
  filter: {
    author: {
      $notExists: true,
    },
  },
});
```