# Array

An `Array` is used to contain zero or more other values (representable using fields) in the form of a numerically indexed list.

#### Import

`from marrow.mongo.field import Array`

#### Inherits

`marrow.mongo:`**`Field`**

## Attributes

This field type inherits all [`Field` attributes](https://github.com/marrow/mongo/tree/128b1ec81ec6a48e05a95c32b636deede377854b/reference/field/field.md#attributes). As a complex type, the first positional argument is always the nested field instance, other positional ordering is unaffected.

#### `kind`

A `Field` subclass instance, or an instance of `Field` itself if the type is dynamic.

Required

## Usage

Instantiate and assign an instance of this class during construction of a new `Document` subclass, passing another `Field` instance representing the type to embed as the first positional parameter. Accessing as a class attribute will return a Queryable allowing array-like filtering operations, and access as an instance attribute will return a `list` subclass containing cast values.

To reduce boilerplate when costructing new document instances utilizing `Array` fields, if the `assign` attribute is truthy and no default is otherwise assigned, an empty list will be assumed and assigned, eliminating the need for armour against None or non-existant conditions.

## Examples

### Arrays of Scalar Values

Tags are a very, very common storage pattern, modelled here using an `Array` of free-form `String` values. Foreign references are also common, though MongoDB itself provides no referential integrity validation.

```python
class Record(Document):
    tags = Array(String(), assign=True)
    actors = Array(Reference('Account'))
```

### Array of Embedded Documents

Another principal pattern is that of an array of embedded documents, for example, an invoice with line items.

```python
class Invoice(Document):
    class Item(Document):
        ...

    items = Array(Embed(Item), assign=True)
```

## See Also

* [`Embed`](https://mongo.webcore.io/reference/fields/broken-reference)
* [`Reference`](https://mongo.webcore.io/reference/fields/broken-reference)