# Domain

Domains represent a set of records. A domain is a list of none or more clauses. A clause is a condition, which returns true or false. A record belongs to a domain, when the final result of the list of clauses returns true.

## Syntax

The definition of a simple domain with one clause is represented by this pattern:

    domain = [(<field name>, <operator>, <operand>)]

`field name`

  Is the name of a `fields` or a pyson statement, that evaluates to a string.

  A field of type `Many2One` or `Many2Many` or `One2Many` or `One2One` or `Reference` can be dereferenced to related models. This is illustrated by the following example:

      domain = [('country.name', '=', 'Japan')]

  The number of dots in a clause is not limited.

  Note

  Negative operators match records for which any of the field before the last dot is empty.

  Warning

  For `trytond.model.fields.Reference`, an extra ending clause is needed to define the target model to join, for example:

      domain = [('origin.party.name', '=', 'John Doe', 'sale.sale')]

  A field of type `Dict` can be searched by key also by using one dot. For example:

      domain = [('attributes.color', '=', 'yellow')]

  Warning

  Order comparison of `date` and `datetime` types is not supported.

`operator`

  Is an operator out of Domain Operators or a pyson statement, that evaluates to a domain operator string.

`operand`

  Is an operand or a pyson statement. The type of operand depends on the kind of <field name>.

The definition of an empty domain is:

    domain = []

An empty domain without clauses will always return all active records. A record is active, when its appropriate `Model` contains a `Boolean` field with name `active`, and set to true. When the appropriate `Model` does not contain a `Boolean` field with name `active` all records are returned.

A domain can be setup as a combination of clauses, like shown in this pattern:

    domain = [
        ('field name1', 'operator1', 'operand1'),
        ('field name2', 'operator2', 'operand2'),
        ('field name3', 'operator3', 'operand3'),
        ]

The single clauses are implicitly combined with a logical AND operation.

In the domain syntax it is possible to provide explicitly the combination operation of the clauses. These operations can be AND or OR. This is illustrated by the following pattern:

    domain = ['OR', [
                ('field name1', 'operator1', 'operand1'),
                ('field name2', 'operator2', 'operand2'),
            ], [
                ('field name3', 'operator3', 'operand3'),
            ],
        ]

Here the domain is evaluated like this: `((clause1 AND clause2) OR clause3)`. Please note that the `AND` operation is implicit assumed when no operator is given. While the `OR` operation must be given explicitly. The former pattern is equivalent to the following completely explicit domain definition:

    domain = ['OR',
                 ['AND', [
                         ('field name1', 'operator1', 'operand1'),
                     ], [
                         ('field name2', 'operator2', 'operand2'),
                     ],
                 ], [
                     ('field name3', 'operator3', 'operand3'),
             ],
        ]

Obviously the use of the implicit `AND` operation makes the code more readable.

## Domain Operators

The following operators are allowed in the domain syntax. `<field name>`, `<operator>` and `<operand>` are dereferenced to their values. The description of each operator follows this pattern, unless otherwise noted:

    (<field name>, <operator>, <operand>)

### `=`

> Is a parity operator. Returns true when `<field name>` equals to `<operand>`.

### `!=`

> Is an imparity operator. It is the negation of the = operator.

### `like`

> Is a pattern matching operator. Returns true when `<field name>` is contained in the pattern represented by `<operand>`.

> In `<operand>` an underscore (`_`) matches any single character, a percent sign (`%`) matches any string with zero or more characters. To use `_` or `%` as literal, use the backslash `\` to escape them. All matching is case sensitive.

### `not like`

> Is a pattern matching operator. It is the negation of the like operator.

### `ilike`

> Is a pattern matching operator. The same use as like operator, but matching is case insensitive.

### `not ilike`

> Is a pattern matching operator. The negation of the ilike operator.

### `in`

> Is a list member operator. Returns true when `<field name>` is in `<operand>` list.

### `not in`

> Is a list non-member operator. The negation of the in operator.

### `<`

> Is a less than operator. Returns true for type string of `<field name>` when `<field name>` is alphabetically sorted before `<operand>`.

> Returns true for type number of `<field name>` when `<field name>` is less than `<operand>`.

### `>`

> Is a greater than operator. Returns true for type string of `<field name>` when `<field name>` is alphabetically sorted after `<operand>`.

> Returns true for type number of `<field name>` when `<field name>` is greater `<operand>`.

### `<=`

> Is a less than or equal operator. Returns the same as using the < operator, but also returns true when `<field name>` is equal to `<operand>`.

### `>=`

> Is a greater than or equal operator. Returns the same as using the > operator, but also returns true when `<field name>` is equal to `<operand>`.

### `child_of`

> Is a parent child comparison operator. Returns true for records that are a child of `<operand>`. `<operand>` is a list of `ids` and `<field name>` must be a `Many2One` or a `Many2Many`. In case `<field name>` is not linked to itself, the clause pattern extends to:

>     (<field name>, ['child_of'|'not_child_of'], <operand>, <parent field>)

> Where `<parent field>` is the name of the field constituting the `Many2One` on the target model.

### `not child_of`

> Is a parent child comparison operator. It is the negation of the child_of operator.

### `parent_of`

> Is a parent child comparison operator. It is the same as child_of operator but if `<field name>` is a parent of `<operand>`.

### `not parent_of`

> Is a parent child comparison operator. It is the negation of this parent_of operator.

### `where`

> Is a `trytond.model.fields.One2Many` / `trytond.model.fields.Many2Many` domain operator. It returns true for every row of the target model that match the domain specified as `<operand>`.

### `not where`

> Is a `trytond.model.fields.One2Many` / `trytond.model.fields.Many2Many` domain operator. It returns true for every row of the target model that does not match the domain specified as `<operand>`.